Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(pcap): name the host tool to configure in capability refusals (#2507)
Kaoru0822bb96afdbe32f
diff --git a/src/pcap/PcapCommand.ts b/src/pcap/PcapCommand.tsindex a0833f599..0d28a3d75 100644--- a/src/pcap/PcapCommand.ts+++ b/src/pcap/PcapCommand.ts@@ -2,7 +2,6 @@ import { randomUUID } from "node:crypto";import { AnalysisError } from "../domain/analysisErrorBase.js";import {AnalysisCancelledError,- AnalysisCapabilityUnavailableError,AnalysisProtocolError,AnalysisResourceConstraintError,AnalysisTimeoutError,@@ -19,6 +18,7 @@ import {windowsBatchCommand,WindowsBatchCommandError,} from "../process/WindowsBatchCommand.js";+import { pcapToolUnavailable } from "./PcapConfiguration.js";export interface PcapCommandLimits {readonly timeoutMs: number;@@ -168,8 +168,7 @@ export const runPcapCommand = async (options: {"code" in cause &&(cause.code === "ENOENT" || cause.code === "EACCES")))- throw new AnalysisCapabilityUnavailableError(- "pcap",+ throw pcapToolUnavailable(operation,`Cannot run selected tool ${command}: ${cause.message}`,details,@@ -181,8 +180,7 @@ export const runPcapCommand = async (options: {? cause.message: String(cause);if (options.inputPath === undefined)- throw new AnalysisCapabilityUnavailableError(- "pcap",+ throw pcapToolUnavailable(operation,`The selected tool ${command} cannot report its version: ${diagnostic}`,details,diff --git a/src/pcap/PcapConfiguration.ts b/src/pcap/PcapConfiguration.tsindex 8f75b4602..b2a6212d1 100644--- a/src/pcap/PcapConfiguration.ts+++ b/src/pcap/PcapConfiguration.ts@@ -2,12 +2,31 @@ import { isAbsolute } from "node:path";import type { ProviderAvailability } from "../application/AnalysisProvider.js";import type { ProviderRejectionCode } from "../contracts/providerSelection.js";+import type { AnalysisErrorOptions } from "../domain/analysisErrorBase.js";+import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";import type { JsonValue } from "../domain/jsonValue.js";/** Environment keys selecting the caller's tshark and capinfos binaries. */export const TSHARK_COMMAND_ENV = "REA_TSHARK_COMMAND";export const CAPINFOS_COMMAND_ENV = "REA_CAPINFOS_COMMAND";+const TOOL_REMEDIATION = `Supply Wireshark 4.x tshark and capinfos on PATH or through absolute ${TSHARK_COMMAND_ENV} and ${CAPINFOS_COMMAND_ENV}; REA does not install them.`;++/**+ * Host-tool refusals concern the caller's Wireshark installation, not the+ * target, so they carry their own guidance instead of the generic advice to+ * choose another target.+ */+export const pcapToolUnavailable = (+ operation: string,+ reason: string,+ options?: AnalysisErrorOptions,+): AnalysisCapabilityUnavailableError =>+ new AnalysisCapabilityUnavailableError("pcap", operation, reason, {+ ...options,+ userMessage: `${/[.!?]$/u.test(reason) ? reason : `${reason}.`} ${TOOL_REMEDIATION}`,+ });+/** How each tool was selected for this provider instance. */export interface PcapToolSelection {readonly tshark: { command: string; source: "environment" | "path" };diff --git a/src/pcap/PcapNativeBound.ts b/src/pcap/PcapNativeBound.tsindex 172eaba91..dc98bfca0 100644--- a/src/pcap/PcapNativeBound.ts+++ b/src/pcap/PcapNativeBound.ts@@ -6,6 +6,8 @@ import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.import type { ArtifactAnalysisResources } from "../process/ArtifactAnalysisResources.js";import type { runPcapCommand } from "./PcapCommand.js";+const PRLIMIT_COMMAND_ENV = "REA_TSHARK_PRLIMIT_COMMAND";+/** Own native capture admission and the exact enforced resource profile. */export const preparePcapNativeBound = async (environment: Readonly<Record<string, string | undefined>>,@@ -22,17 +24,20 @@ export const preparePcapNativeBound = async (],};}- if (process.platform !== "linux")+ if (process.platform !== "linux") {+ const reason =+ "Packet summaries require an enforceable native memory bound: Linux with util-linux prlimit, or Windows with owned Job Objects. This host's capture boundary remains unsupported.";throw new AnalysisCapabilityUnavailableError("pcap","inspect_pcap_capture",- "Packet summaries require an enforceable native memory bound: Linux with util-linux prlimit, or Windows with owned Job Objects. This host's capture boundary remains unsupported.",+ reason,+ { userMessage: reason },);- const configured =- environment.REA_TSHARK_PRLIMIT_COMMAND ?? "/usr/bin/prlimit";+ }+ const configured = environment[PRLIMIT_COMMAND_ENV] ?? "/usr/bin/prlimit";try {if (!isAbsolute(configured))- throw new Error("REA_TSHARK_PRLIMIT_COMMAND must be absolute.");+ throw new Error(`${PRLIMIT_COMMAND_ENV} must be absolute.`);const limiter = await realpath(configured);await access(limiter, constants.X_OK);const limits = await resources.readLimits({@@ -58,11 +63,16 @@ export const preparePcapNativeBound = async (return { nativeBound, limitations };} catch (cause) {if (cause instanceof AnalysisError) throw cause;+ const reason =+ "Cannot establish the selected Linux resource limiter before processing capture bytes.";throw new AnalysisCapabilityUnavailableError("pcap","inspect_pcap_capture",- "Cannot establish the selected Linux resource limiter before processing capture bytes.",- { cause },+ reason,+ {+ cause,+ userMessage: `${reason} (${cause instanceof Error ? cause.message : String(cause)}) Check that ${PRLIMIT_COMMAND_ENV} (default /usr/bin/prlimit) names an absolute, executable util-linux prlimit.`,+ },);}};diff --git a/src/pcap/PcapProvider.ts b/src/pcap/PcapProvider.tsindex 7228d694f..be2c12ed2 100644--- a/src/pcap/PcapProvider.ts+++ b/src/pcap/PcapProvider.ts@@ -25,6 +25,7 @@ import {inspectPcapClient,resolvePcapTools,pcapConfigurationAvailability,+ pcapToolUnavailable,type PcapToolSelection,} from "./PcapConfiguration.js";import {@@ -346,12 +347,9 @@ export class PcapProvider {: signal?.aborted? new AnalysisCancelledError(request.operation, { cause }): cause instanceof PcapConfigurationFailure- ? new AnalysisCapabilityUnavailableError(- "pcap",- request.operation,- cause.message,- { cause },- )+ ? pcapToolUnavailable(request.operation, cause.message, {+ cause,+ }): new AnalysisProtocolError(`Packet-capture analysis failed: ${cause instanceof Error ? cause.message : String(cause)}`,{ cause },diff --git a/src/pcap/PcapSnapshot.ts b/src/pcap/PcapSnapshot.tsindex 08f1ea552..2e9082ccd 100644--- a/src/pcap/PcapSnapshot.ts+++ b/src/pcap/PcapSnapshot.ts@@ -43,7 +43,7 @@ export class PcapSnapshot {"pcap",OPERATION,cause.message,- { cause },+ { cause, retryable: cause.retryable },);throw new AnalysisResourceConstraintError(OPERATION,diff --git a/tests/boundary/cli/pcapCli.test.ts b/tests/boundary/cli/pcapCli.test.tsindex 26e253455..1eb61cdcf 100644--- a/tests/boundary/cli/pcapCli.test.ts+++ b/tests/boundary/cli/pcapCli.test.ts@@ -1,6 +1,6 @@import { expect, it } from "vitest";-import { serveCli } from "./cliServeHarness.js";+import { expectConfigurationRefusal, serveCli } from "./cliServeHarness.js";it.each(["inspect-pcap-client", "inspect-pcap-capture"])("%s advertises a schema through the public CLI",@@ -11,13 +11,27 @@ it.each(["inspect-pcap-client", "inspect-pcap-capture"])(},);-it("reports missing tools with a capability refusal", async () => {- const result = await serveCli(- ["inspect-pcap-capture", "/nonexistent/capture.pcap", "--json"],- {- REA_TSHARK_COMMAND: "/nonexistent/tshark",- REA_CAPINFOS_COMMAND: "/nonexistent/capinfos",- },+it.each([+ ["inspect-pcap-client"],+ ["inspect-pcap-capture", "/nonexistent/capture.pcap"],+])("%s names the missing Wireshark tool to configure", async (...argv) => {+ const result = await serveCli([...argv, "--json"], {+ REA_TSHARK_COMMAND: "/nonexistent/tshark",+ REA_CAPINFOS_COMMAND: "/nonexistent/capinfos",+ });+ expectConfigurationRefusal(+ result,+ "Cannot run selected tool /nonexistent/tshark",+ );+ expectConfigurationRefusal(result, "through absolute REA_TSHARK_COMMAND");+});++it("names a relative tool selection as configuration to fix", async () => {+ const result = await serveCli(["inspect-pcap-client", "--json"], {+ REA_TSHARK_COMMAND: "tshark",+ });+ expectConfigurationRefusal(+ result,+ "REA_TSHARK_COMMAND must be an absolute path to the tshark binary",);- expect(result.stdout).toContain("capability_unavailable");});diff --git a/tests/boundary/pcap/pcapProvider.test.ts b/tests/boundary/pcap/pcapProvider.test.tsindex 50204a479..fcb299ade 100644--- a/tests/boundary/pcap/pcapProvider.test.ts+++ b/tests/boundary/pcap/pcapProvider.test.ts@@ -246,12 +246,37 @@ it("reports relative configuration and missing capinfos as capability gaps", asyinput: {},});if (result.ok) throw new Error("expected unavailable tools");- expect(projectAnalysisError(result.error).code).toBe(- "capability_unavailable",+ const projected = projectAnalysisError(result.error);+ expect(projected.code).toBe("capability_unavailable");+ expect(projected.message).toContain(+ "Supply Wireshark 4.x tshark and capinfos",);}});+it("names the prlimit selection when the Linux limiter is unusable", async () => {+ const root = await createTestTempDirectory("rea-pcap-prlimit-");+ const tools = await writeStubTools(root);+ const provider = new PcapProvider({+ environment: {+ REA_TSHARK_COMMAND: tools.tshark,+ REA_CAPINFOS_COMMAND: tools.capinfos,+ REA_TSHARK_PRLIMIT_COMMAND: "relative/prlimit",+ },+ });+ onTestFinished(() => provider.close());+ const result = await provider.execute({+ operation: "inspect_pcap_capture",+ input: { path: "/not-opened/capture.pcap" },+ });+ if (result.ok) throw new Error("expected an unusable limiter");+ const projected = projectAnalysisError(result.error);+ expect(projected.code).toBe("capability_unavailable");+ expect(projected.message).toContain(+ "(REA_TSHARK_PRLIMIT_COMMAND must be absolute.) Check that REA_TSHARK_PRLIMIT_COMMAND",+ );+});+const nodeTool = async (root: string,name: string,diff --git a/tests/boundary/pcap/pcapProviderCrossPlatform.test.ts b/tests/boundary/pcap/pcapProviderCrossPlatform.test.tsindex 59ff76c57..c19e682fe 100644--- a/tests/boundary/pcap/pcapProviderCrossPlatform.test.ts+++ b/tests/boundary/pcap/pcapProviderCrossPlatform.test.ts@@ -141,9 +141,13 @@ it.runIf(!hasNativeBound)(input: { path: "/not-opened/capture.pcap" },});expect(result.ok).toBe(false);- if (!result.ok)- expect(projectAnalysisError(result.error)).toMatchObject({- code: "capability_unavailable",- });+ if (result.ok) return;+ const projected = projectAnalysisError(result.error);+ expect(projected.code).toBe("capability_unavailable");+ // The refusal concerns this host, so it must not suggest another target.+ expect(projected.message).toContain(+ "Linux with util-linux prlimit, or Windows with owned Job Objects",+ );+ expect(projected.remediation.action).toBe(projected.message);},);