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 { EventEmitter } from "node:events";
import { chmod, mkdir, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { PassThrough } from "node:stream";
import { expect, it as test, vi } from "vitest";
import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js";
import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { FirmwareFileAccess } from "./FirmwareFiles.js";
import {
resolveFirmwareCommand,
runFirmwareCommand,
} from "./FirmwareCommand.js";
import {
spawnOwnedProviderProcess,
type ProviderProcessHandle,
} from "../process/ProviderProcess.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import { ExecFileOutputCancelledError } from "../process/ExecFileOutput.js";
const it = test.skipIf(process.platform !== "linux");
it.each([
{ source: "analysis", wrapped: false },
{ source: "caller", wrapped: false },
{ source: "analysis", wrapped: true },
{ source: "caller", wrapped: true },
] as const)(
"classifies $source cancellation during launcher admission (wrapped: $wrapped)",
async ({ source, wrapped }) => {
const analysis = new AbortController();
const caller = new AbortController();
const reason =
source === "analysis"
? new DOMException("selected deadline", "TimeoutError")
: { caller: "opaque admission cancellation" };
const retainCleanup = vi.fn();
const failure: unknown = await runFirmwareCommand({
engine: "binwalk",
operation: "inspect_firmware_regions",
command: "/usr/bin/true",
limiter: "/usr/bin/true",
args: ["--version"],
cwd: await createTestTempDirectory("rea-firmware-admission-"),
environment: process.env,
signal: AbortSignal.any([analysis.signal, caller.signal]),
deadline: {
phase: "analysis",
signal: analysis.signal,
timeoutMs: 1234,
expiresAtMs: performance.now() + 1234,
},
launcher: async (options) => {
// Real launcher is paused at its first ownership-preparation await;
// it must reject before acquiring a child after this cancellation.
const admission = wrapped
? undefined
: spawnOwnedProviderProcess(options);
(source === "analysis" ? analysis : caller).abort(reason);
if (admission !== undefined) return admission;
throw new ExecFileOutputCancelledError(reason);
},
retainCleanup,
}).catch((cause: unknown) => cause);
expect(failure).toBeInstanceOf(AnalysisError);
if (!(failure instanceof AnalysisError))
throw new Error("Expected typed admission interruption");
expect(failure.cause).toBe(reason);
expect(projectAnalysisError(failure)).toMatchObject(
source === "analysis"
? {
code: "provider_timeout",
details: { timeout_ms: 1234, diagnostics: { phase: "analysis" } },
remediation: {
action: expect.stringContaining("analysis_timeout_ms"),
},
}
: { code: "cancelled" },
);
expect(retainCleanup).not.toHaveBeenCalled();
},
);
it("does not relabel an unrelated launch failure when a deadline also fires", async () => {
const analysis = new AbortController();
const failure = new Error("distinct launch refusal");
await expect(
runFirmwareCommand({
engine: "binwalk",
operation: "inspect_firmware_regions",
command: "/usr/bin/true",
limiter: "/usr/bin/true",
args: [],
cwd: await createTestTempDirectory("rea-firmware-admission-error-"),
environment: process.env,
signal: analysis.signal,
deadline: {
phase: "analysis",
signal: analysis.signal,
timeoutMs: 1234,
expiresAtMs: performance.now() + 1234,
},
launcher: async () => {
analysis.abort();
throw failure;
},
retainCleanup: vi.fn(),
}),
).rejects.toBe(failure);
});
test("names the host and tool requirement of an unconfigured engine", async () => {
const refusal: unknown = await resolveFirmwareCommand(
{},
"binwalk",
"inspect_firmware_regions",
new FirmwareFileAccess(),
).catch((cause: unknown) => cause);
expect(refusal).toMatchObject({
_tag: "AnalysisCapabilityUnavailableError",
});
if (!(refusal instanceof AnalysisCapabilityUnavailableError))
throw new Error("Expected a capability refusal");
expect(projectAnalysisError(refusal)).toMatchObject({
code: "capability_unavailable",
message: refusal.reason,
remediation: { action: refusal.reason },
});
expect(refusal.reason).toContain("REA_BINWALK_COMMAND");
});
it("rejects a directory configured as the firmware engine executable", async () => {
const root = await createTestTempDirectory("rea-firmware-command-");
const command = join(root, "binwalk");
const limiter = await executableFixture(root, "prlimit");
await mkdir(command);
await expect(
resolveFirmwareCommand(
{
REA_BINWALK_COMMAND: command,
REA_FIRMWARE_PRLIMIT_COMMAND: limiter,
},
"binwalk",
"inspect_firmware_regions",
new FirmwareFileAccess(),
),
).rejects.toMatchObject({
_tag: "AnalysisCapabilityUnavailableError",
reason: expect.stringContaining(command),
});
});
it("classifies an unusable firmware engine as an unavailable capability", async () => {
const root = await createTestTempDirectory("rea-firmware-command-");
const command = join(root, "binwalk");
const limiter = await executableFixture(root, "prlimit");
await writeFile(command, "not executable", { mode: 0o600 });
await expect(
resolveFirmwareCommand(
{
REA_BINWALK_COMMAND: command,
REA_FIRMWARE_PRLIMIT_COMMAND: limiter,
},
"binwalk",
"inspect_firmware_regions",
new FirmwareFileAccess(),
),
).rejects.toMatchObject({
_tag: "AnalysisCapabilityUnavailableError",
reason: expect.stringContaining(command),
});
});
it("rejects a directory configured as the resource limiter executable", async () => {
const root = await createTestTempDirectory("rea-firmware-limiter-");
const command = await executableFixture(root, "binwalk");
const limiter = join(root, "prlimit");
await mkdir(limiter);
await expect(
resolveFirmwareCommand(
{
REA_BINWALK_COMMAND: command,
REA_FIRMWARE_PRLIMIT_COMMAND: limiter,
},
"binwalk",
"inspect_firmware_regions",
new FirmwareFileAccess(),
),
).rejects.toMatchObject({
_tag: "AnalysisCapabilityUnavailableError",
reason: expect.stringContaining(limiter),
});
});
it("keeps captured tool output when firmware stops on SIGXCPU", async () => {
const stdout = new PassThrough();
const stderr = new PassThrough();
const emitter = new EventEmitter();
const child: ProviderProcessHandle = {
on: emitter.on.bind(emitter),
once: emitter.once.bind(emitter),
off: emitter.off.bind(emitter),
pid: 4242,
stdout,
stderr,
exitCode: null,
signalCode: "SIGXCPU",
kill: () => false,
};
let ended = 0;
const close = () => {
ended += 1;
if (ended === 2) emitter.emit("close", null, "SIGXCPU");
};
stdout.once("end", close);
stderr.once("end", close);
setTimeout(() => {
stdout.end("partial scan\n");
stderr.end("cpu limit\n");
}, 15);
const analysis = new AbortController();
const failure: unknown = await runFirmwareCommand({
engine: "binwalk",
operation: "inspect_firmware_regions",
command: "/opt/binwalk",
limiter: "/usr/bin/prlimit",
args: ["--quiet"],
cwd: await createTestTempDirectory("rea-firmware-signal-"),
environment: process.env,
signal: analysis.signal,
deadline: {
phase: "analysis",
signal: analysis.signal,
timeoutMs: 30_000,
expiresAtMs: performance.now() + 30_000,
},
launcher: () =>
Promise.resolve({
process: child,
ownership: {
runId: "rea-firmware-signal",
leaderPid: 4242,
processGroupId: 4242,
},
cleanup: () => Promise.resolve({ cleaned: true, signaled: false }),
}),
retainCleanup: vi.fn(),
}).catch((cause: unknown) => cause);
expect(failure).toMatchObject({
_tag: "AnalysisResourceConstraintError",
resource: "cpu",
capturedOutput: {
stdout: "partial scan\n",
stderr: "cpu limit\n",
signal: "SIGXCPU",
exit_code: null,
truncated: false,
},
});
if (!(failure instanceof AnalysisError))
throw new Error("Expected a firmware resource constraint");
expect(projectAnalysisError(failure).details?.captured_output).toMatchObject({
stdout: "partial scan\n",
stderr: "cpu limit\n",
signal: "SIGXCPU",
});
});
const executableFixture = async (root: string, name: string) => {
const path = join(root, name);
await writeFile(path, "#!/bin/sh\n");
await chmod(path, 0o700);
return path;
};