Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
import { describe, expect, it } from "vitest";
import {
CPU,
arArchive,
fatImage,
machoImage,
} from "../apple/MachoImage.fixture.js";
import {
createArtifactEdges,
classifyArtifactContent,
createOccurrence,
indexDestinationOccurrencesByPath,
resolveOccurrenceParents,
} from "./ArtifactGraphConstruction.js";
import { createArtifactClassificationProbe } from "../ArtifactClassificationProbe.js";
import { artifactIdForContent } from "../../domain/artifactIdentity.js";
import type { ArtifactEntry } from "../ArtifactReader.js";
import { classifyArtifactBytesAtPath } from "../../../tests/fixtures/artifactClassification.js";
it("keeps an ambiguous DOS MZ inventory candidate unknown", () => {
const bytes = Buffer.alloc(128);
bytes.write("MZ", 0, "ascii");
bytes.writeUInt16LE(128, 2);
bytes.writeUInt16LE(1, 4);
bytes.writeUInt16LE(2, 6);
bytes.writeUInt16LE(4, 8);
bytes.writeUInt16LE(28, 24);
bytes.write("ABCD", 60, "ascii");
expect(classifyArtifactBytesAtPath("legacy.exe", bytes)).toEqual({
kind: "unknown",
format: "unknown",
});
});
const entry = (path: string, kind: ArtifactEntry["kind"]): ArtifactEntry => ({
path,
kind,
declaredSize: null,
compressedSize: null,
executable: false,
encrypted: false,
byteOffset: null,
declaredIntegrity: null,
unpacked: false,
limitations: [],
adapterKey: path,
});
describe("occurrence parent ownership", () => {
it("selects the nearest unique nested parent", () => {
const outer = createOccurrence(entry("a", "directory"), "a", null);
const inner = createOccurrence(entry("a/b", "directory"), "a/b", null);
const file = createOccurrence(entry("a/b/file", "file"), "a/b/file", null);
const occurrences = [outer, inner, file];
resolveOccurrenceParents(
occurrences,
indexDestinationOccurrencesByPath(occurrences),
new Set(),
);
expect(file.parent_occurrence_id).toBe(inner.occurrence_id);
});
it("leaves a child unparented when duplicate directories make ownership ambiguous", () => {
const first = createOccurrence(entry("a", "directory"), "a", null, 0);
const second = createOccurrence(entry("a", "directory"), "a", null, 1);
const file = createOccurrence(entry("a/file", "file"), "a/file", null);
const occurrences = [first, second, file];
const resolution = resolveOccurrenceParents(
occurrences,
indexDestinationOccurrencesByPath(occurrences),
new Set(),
);
expect(file.parent_occurrence_id).toBeNull();
expect(resolution.unknownParentOccurrences.has(file)).toBe(true);
expect(resolution.limitations).toContain(
'The parent occurrence for "a/file" is unknown because multiple observed directory or container occurrences share "a".',
);
expect([first, second].map(({ hash_status }) => hash_status)).toEqual([
"unavailable",
"unavailable",
]);
});
});
describe("source-map artifact relationships", () => {
const contentId = (digit: string): string =>
artifactIdForContent(digit.repeat(64));
it.each([
["missing target", [] as string[], "contains"],
["unread target", ["unread"] as string[], "contains"],
["unique identified target", ["identified"] as string[], "maps-source"],
["duplicate targets", ["identified", "identified"] as string[], "contains"],
] as const)(
"uses a truthful edge for a %s",
(_label, targetIdentities, relation) => {
const directory = createOccurrence(
entry("app", "directory"),
"app",
null,
);
directory.artifact_id = contentId("1");
const targets = targetIdentities.map((identity, index) => {
const target = createOccurrence(
entry("app/main.js", "file"),
"app/main.js",
directory.occurrence_id,
index,
);
target.artifact_id = identity === "unread" ? null : contentId("2");
return target;
});
const sourceMap = createOccurrence(
entry("app/main.js.map", "file"),
"app/main.js.map",
directory.occurrence_id,
);
sourceMap.artifact_id = contentId("3");
const result = createArtifactEdges(contentId("4"), [
directory,
...targets,
sourceMap,
]);
const edge = result.edges.find(
({ occurrence_id }) => occurrence_id === sourceMap.occurrence_id,
);
expect(edge).toMatchObject({
relation,
parent_artifact_id:
relation === "maps-source" ? contentId("2") : contentId("1"),
occurrence_id: sourceMap.occurrence_id,
});
expect(result.limitations.length > 0).toBe(
(targetIdentities.length === 1 && targetIdentities[0] === "unread") ||
targetIdentities.length > 1,
);
},
);
it("keeps a directory named like a source map contained by its parent", () => {
const archive = createOccurrence(entry("app", "directory"), "app", null);
archive.artifact_id = contentId("1");
const script = createOccurrence(
entry("app/main.js", "file"),
"app/main.js",
archive.occurrence_id,
);
script.artifact_id = contentId("2");
const directory = createOccurrence(
entry("app/main.js.map", "directory"),
"app/main.js.map",
archive.occurrence_id,
);
directory.artifact_id = contentId("3");
const { edges, limitations } = createArtifactEdges(contentId("4"), [
archive,
script,
directory,
]);
expect(directory).toMatchObject({
artifact_kind: "container",
artifact_format: "directory",
});
expect(
edges.find(
({ occurrence_id }) => occurrence_id === directory.occurrence_id,
),
).toMatchObject({
relation: "contains",
parent_artifact_id: contentId("1"),
});
expect(limitations).toEqual([]);
});
});
const fat = (wide = false): Buffer =>
Buffer.from(fatImage([{ cpu: CPU.arm64, bytes: machoImage({}) }], wide));
const expectStreamedFatClassification = (testCase: {
readonly slices: readonly {
readonly cpu: { readonly type: number; readonly subtype: number };
readonly bytes: Uint8Array;
}[];
readonly expected: string;
}): void => {
const bytes = Buffer.alloc(24_128);
const offsets = testCase.slices.map((_, index) => 20_000 + index * 4_000);
bytes.writeUInt32BE(0xcafebabe, 0);
bytes.writeUInt32BE(testCase.slices.length, 4);
testCase.slices.forEach((slice, index) => {
const entry = 8 + index * 20;
const sliceOffset = offsets[index]!;
bytes.writeUInt32BE(slice.cpu.type, entry);
bytes.writeUInt32BE(slice.cpu.subtype, entry + 4);
bytes.writeUInt32BE(sliceOffset, entry + 8);
bytes.writeUInt32BE(slice.bytes.length, entry + 12);
bytes.writeUInt32BE(0, entry + 16);
Buffer.from(slice.bytes).copy(bytes, sliceOffset);
});
const probe = createArtifactClassificationProbe();
const boundaries = [
8_192,
...offsets.flatMap((offset) => [offset + 3, offset + 4]),
bytes.length,
].sort((left, right) => left - right);
let previous = 0;
for (const boundary of boundaries) {
if (boundary <= previous) continue;
probe.write(bytes.subarray(previous, boundary));
previous = boundary;
}
const evidence = probe.finish(bytes.length);
expect(evidence.prefix.length).toBeLessThan(bytes.length);
expect(classifyArtifactContent("native", evidence, bytes.length).format).toBe(
testCase.expected,
);
};
describe("bounded FAT inventory classification", () => {
it("requires the complete table and an observed slice header", () => {
const bytes = fat();
for (const length of [4, 7, 8, 27]) {
expect(
classifyArtifactBytesAtPath(
"native",
bytes.subarray(0, length),
bytes.length,
),
).toEqual({ kind: "unknown", format: "unknown" });
}
expect(
classifyArtifactBytesAtPath(
"native.class",
bytes.subarray(0, 28),
bytes.length,
),
).toEqual({ kind: "unknown", format: "unknown" });
expect(classifyArtifactBytesAtPath("native.class", bytes)).toEqual({
kind: "executable",
format: "mach-o-universal",
});
});
it("does not classify known-CPU FAT archive slices as Mach-O", () => {
const archive = arArchive();
const bytes = Buffer.from(
fatImage([
{ cpu: CPU.x86_64, bytes: archive },
{ cpu: CPU.arm64, bytes: archive },
]),
);
expect(classifyArtifactBytesAtPath("libfat.a", bytes)).toEqual({
kind: "unknown",
format: "unknown",
});
});
it.each([
["empty table", (bytes: Buffer) => bytes.writeUInt32BE(0, 4)],
["slice overlapping table", (bytes: Buffer) => bytes.writeUInt32BE(0, 16)],
["empty slice", (bytes: Buffer) => bytes.writeUInt32BE(0, 20)],
[
"slice beyond file",
(bytes: Buffer) => bytes.writeUInt32BE(bytes.length, 20),
],
["unaligned slice", (bytes: Buffer) => bytes.writeUInt32BE(4097, 16)],
["unsupported alignment", (bytes: Buffer) => bytes.writeUInt32BE(53, 24)],
] as const)("keeps %s unknown", (_label, mutate) => {
const bytes = fat();
mutate(bytes);
expect(classifyArtifactBytesAtPath("native", bytes)).toEqual({
kind: "unknown",
format: "unknown",
});
});
it("does not infer Mach-O from an out-of-bounds architecture count", () => {
const bytes = fat();
bytes.writeUInt32BE(0xffffffff, 4);
expect(classifyArtifactBytesAtPath("native", bytes)).toEqual({
kind: "resource",
format: "file",
});
});
it("does not lose unsafe FAT64 range values to number conversion", () => {
const bytes = fat(true);
bytes.writeBigUInt64BE(BigInt(Number.MAX_SAFE_INTEGER) + 1n, 16);
expect(classifyArtifactBytesAtPath("native", bytes)).toEqual({
kind: "unknown",
format: "unknown",
});
});
it("requires valid ranges for every declared slice", () => {
const bytes = Buffer.from(
fatImage([
{ cpu: CPU.arm64, bytes: machoImage({}) },
{ cpu: CPU.x86_64, bytes: machoImage({ cpu: CPU.x86_64 }) },
]),
);
bytes.writeUInt32BE(bytes.length, 40);
expect(classifyArtifactBytesAtPath("native", bytes)).toEqual({
kind: "unknown",
format: "unknown",
});
});
it("requires observed slice magic for an unknown CPU type", () => {
const cpu = { type: 0x12345678, subtype: 0 };
const bytes = Buffer.from(fatImage([{ cpu, bytes: machoImage({ cpu }) }]));
expect(
classifyArtifactBytesAtPath(
"native",
bytes.subarray(0, 28),
bytes.length,
),
).toEqual({ kind: "unknown", format: "unknown" });
expect(classifyArtifactBytesAtPath("native", bytes)).toEqual({
kind: "executable",
format: "mach-o-universal",
});
});
it("classifies distant FAT headers from bounded streaming observations", () => {
const cases = [
{
name: "Mach-O",
slices: [{ cpu: CPU.arm64, bytes: machoImage({}) }],
expected: "mach-o-universal",
},
{
name: "archive",
slices: [{ cpu: CPU.arm64, bytes: arArchive() }],
expected: "unknown",
},
{
name: "mixed Mach-O and archive",
slices: [
{ cpu: CPU.x86_64, bytes: machoImage({ cpu: CPU.x86_64 }) },
{ cpu: CPU.arm64, bytes: arArchive() },
],
expected: "unknown",
},
] as const;
for (const testCase of cases) expectStreamedFatClassification(testCase);
});
});
describe("FAT prefix observation coverage", () => {
it("does not invent an observation for a header beyond the retained prefix", () => {
const bytes = Buffer.alloc(8_224);
bytes.writeUInt32BE(0xcafebabe, 0);
bytes.writeUInt32BE(2, 4);
for (const [index, slice] of [
{ cpu: CPU.x86_64, offset: 4_096 },
{ cpu: CPU.arm64, offset: 8_192 },
].entries()) {
const entry = 8 + index * 20;
bytes.writeUInt32BE(slice.cpu.type, entry);
bytes.writeUInt32BE(slice.cpu.subtype, entry + 4);
bytes.writeUInt32BE(slice.offset, entry + 8);
bytes.writeUInt32BE(32, entry + 12);
bytes.writeUInt32BE(12, entry + 16);
bytes.writeUInt32LE(0xfeedfacf, slice.offset);
bytes.writeUInt32LE(slice.cpu.type, slice.offset + 4);
bytes.writeUInt32LE(slice.cpu.subtype, slice.offset + 8);
}
const probe = createArtifactClassificationProbe();
probe.write(bytes.subarray(0, 8_192));
const evidence = probe.finish(bytes.length);
expect(
evidence.fatSliceHeaders?.sliceHeadersByOffset.get(4_096)?.magic,
).toBe(0xcffaedfe);
expect(evidence.fatSliceHeaders?.sliceHeadersByOffset.has(8_192)).toBe(
false,
);
});
});
describe("bounded FAT inventory classification", () => {
it.each([NaN, Infinity, -1, 8.5, Number.MAX_SAFE_INTEGER + 1, 27])(
"keeps invalid or contradictory file size %s unknown",
(size) => {
const bytes = fat();
expect(classifyArtifactBytesAtPath("native", bytes, size)).toEqual({
kind: "unknown",
format: "unknown",
});
},
);
});
it("preserves path-selected inventory roles for XML content", () => {
const xml = Buffer.from(
'<?xml version="1.0"?><plist version="1.0"><dict/></plist>',
);
expect(classifyArtifactBytesAtPath("state.archive", xml)).toEqual({
kind: "plist",
format: "plist",
});
expect(classifyArtifactBytesAtPath("state.js", xml)).toEqual({
kind: "javascript",
format: "javascript-bundle",
});
expect(classifyArtifactBytesAtPath("state.map", xml)).toEqual({
kind: "source-map",
format: "source-map",
});
expect(classifyArtifactBytesAtPath("state.asar", xml)).toEqual({
kind: "resource",
format: "file",
});
});