From df2c08b546d4f40103e11b8b31dbfc3d41ee687b Mon Sep 17 00:00:00 2001 From: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com> Date: Mon, 12 Oct 2026 06:49:15 -0700 Subject: [PATCH 1/8] fix(jeb): confine an invalid REA_JEB_MCP_URL to the JEB tools (#2145) JebProvider throws when REA_JEB_MCP_URL fails endpoint validation, and the composition built it eagerly for the CLI and every MCP connection. A malformed value, or http://localhost:8425/mcp, therefore crashed every CLI command with a stack trace and failed every MCP connection with an internal server error. The composition now parses the endpoint first and, when it is unusable, returns a JEB port that reports not_configured availability and a ConfigurationError naming REA_JEB_MCP_URL. Fixes #2143 Co-authored-by: Claude Opus 5.5 --- src/composition/jeb.ts | 41 +++++++++++++++++++++++++++--- tests/boundary/cli/jebCli.test.ts | 11 ++++++++ tests/boundary/mcp/jebMcp.test.ts | 42 +++++++++++++++++++++++++++++++ 3 files changed, 91 insertions(+), 3 deletions(-) diff --git a/src/composition/jeb.ts b/src/composition/jeb.ts index 4abc33b9d..38f5dae5d 100644 --- a/src/composition/jeb.ts +++ b/src/composition/jeb.ts @@ -1,13 +1,48 @@ import type { JebAnalysisPort } from "../application/jeb/JebAnalysisPort.js"; +import { ConfigurationError } from "../domain/configurationErrors.js"; +import { err } from "../domain/result.js"; import type { JebMcpConnectionFactory } from "../jeb/JebMcpConnection.js"; +import { parseJebMcpEndpoint } from "../jeb/JebMcpEndpoint.js"; import { JebProvider } from "../jeb/JebProvider.js"; -/** Construct one JEB provider bound to the caller-selected MCP endpoint. */ +/** + * Construct one JEB provider bound to the caller-selected MCP endpoint. An + * unusable endpoint makes only JEB unavailable; every other CLI command and + * MCP tool is composed alongside it. + */ export const createJebAnalysisProvider = ( environment: Readonly> = process.env, connectionFactory?: JebMcpConnectionFactory, -): JebAnalysisPort => - new JebProvider({ +): JebAnalysisPort => { + const endpoint = parseJebMcpEndpoint(environment.REA_JEB_MCP_URL); + if (!endpoint.ok) { + const constraint = + typeof endpoint.error.cause === "string" + ? endpoint.error.cause + : endpoint.error.message; + return unconfiguredJebProvider( + new ConfigurationError("Invalid REA environment configuration", { + cause: endpoint.error, + settings: [{ setting: "REA_JEB_MCP_URL", constraint }], + }), + ); + } + return new JebProvider({ environment, ...(connectionFactory === undefined ? {} : { connectionFactory }), }); +}; + +const unconfiguredJebProvider = ( + error: ConfigurationError, +): JebAnalysisPort => ({ + inspectAvailability: () => + Promise.resolve({ + status: "unavailable", + code: "not_configured", + reason: `REA_JEB_MCP_URL is invalid: ${error.settings[0]?.constraint ?? error.message}`, + diagnostics: { setting: "REA_JEB_MCP_URL" }, + }), + close: () => Promise.resolve(), + execute: () => Promise.resolve(err(error)), +}); diff --git a/tests/boundary/cli/jebCli.test.ts b/tests/boundary/cli/jebCli.test.ts index c188b0e31..6e2325c7f 100644 --- a/tests/boundary/cli/jebCli.test.ts +++ b/tests/boundary/cli/jebCli.test.ts @@ -30,3 +30,14 @@ it("validates decompile item input before contacting the engine", async () => { ], }); }); + +it("reports an invalid endpoint without breaking other commands", async () => { + const environment = { REA_JEB_MCP_URL: "http://localhost:8425/mcp" }; + const jeb = await serveCli(["inspect-jeb-client", "--json"], environment); + expect(JSON.parse(jeb.stdout)).toMatchObject({ + code: "configuration_invalid", + details: { settings: [{ setting: "REA_JEB_MCP_URL" }] }, + }); + const capabilities = await serveCli(["capabilities", "--json"], environment); + expect(capabilities.exitCode).toBe(0); +}); diff --git a/tests/boundary/mcp/jebMcp.test.ts b/tests/boundary/mcp/jebMcp.test.ts index 7ccc0b579..44b482714 100644 --- a/tests/boundary/mcp/jebMcp.test.ts +++ b/tests/boundary/mcp/jebMcp.test.ts @@ -141,3 +141,45 @@ it("preserves JEB provider failure reasons through the MCP boundary", async () = expect(text).toContain("ECONNREFUSED"); expect(text).toContain("REA_JEB_MCP_URL"); }); + +it("keeps the MCP server usable when REA_JEB_MCP_URL is invalid", async () => { + const session = createTestBinarySession(() => { + throw new Error("deep provider must not start"); + }); + const server = createServer( + { kind: "session", session }, + { environment: { REA_JEB_MCP_URL: "http://localhost:8425/mcp" } }, + ); + const client = new Client({ name: "jeb-invalid-endpoint", version: "1" }); + onTestFinished(async () => { + await client.close(); + await server.close(); + await session.close(); + }); + const [clientTransport, serverTransport] = + InMemoryTransport.createLinkedPair(); + await server.connect(serverTransport); + await client.connect(clientTransport); + expect((await client.listTools()).tools.length).toBeGreaterThan(0); + const failed = await client.callTool({ + name: "inspect_jeb_client", + arguments: {}, + }); + expect(failed.isError).toBe(true); + const text = (failed.content ?? []) + .map((block) => (block.type === "text" ? block.text : "")) + .join(""); + expect(JSON.parse(text)).toMatchObject({ + error: { + code: "configuration_invalid", + details: { + settings: [ + { + setting: "REA_JEB_MCP_URL", + constraint: expect.stringContaining("loopback"), + }, + ], + }, + }, + }); +}); From 90e37f4152990be721784006a820a3794920213c Mon Sep 17 00:00:00 2001 From: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com> Date: Mon, 12 Oct 2026 06:53:26 -0700 Subject: [PATCH 2/8] fix(managed): report malformed PE layouts as invalid input (#2194) * fix(managed): report malformed PE layouts as invalid input readManagedPeLayout raises ManagedReaderFailure for DOS, COFF and section header failures such as section data past EOF. Those escaped the managed inspectors, so ManagedStaticProvider wrapped them as ProviderAdapterError and the CLI and MCP reported execution_failure with advice to run rea doctor. Map format failures to an invalid_format input issue carrying the reader's detail, as inspect-pe-resources and inspect-go-binary do. Fixes #2191 Co-Authored-By: Claude Opus 5.5 * fix(managed): route unmappable PE layouts through one input error inspect-managed-native-boundaries caught a layout-level ManagedReaderFailure itself and returned an empty malformed inspection with exit 0, while the other managed operations now report the same bytes as invalid input. Let the layout failure reach the provider's invalid_format mapping; metadata failures after a readable layout still return malformed coverage. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- src/dotnet/ManagedNativeBoundaryInspector.ts | 11 ++----- src/dotnet/ManagedStaticProvider.ts | 16 ++++++++++ tests/acceptance/managedCliOutput.test.ts | 33 ++++++++++++++++++++ 3 files changed, 51 insertions(+), 9 deletions(-) diff --git a/src/dotnet/ManagedNativeBoundaryInspector.ts b/src/dotnet/ManagedNativeBoundaryInspector.ts index 773a95c07..d2b84be04 100644 --- a/src/dotnet/ManagedNativeBoundaryInspector.ts +++ b/src/dotnet/ManagedNativeBoundaryInspector.ts @@ -121,15 +121,8 @@ export const inspectManagedNativeBoundariesBytes = ( bytes: Buffer, target: BinaryTarget, ): ManagedNativeBoundaryInspection => { - let pe: ManagedPeLayout; - try { - pe = readManagedPeLayout(bytes); - } catch (cause: unknown) { - if (!(cause instanceof ManagedReaderFailure)) throw cause; - return emptyInspection(target, bytes, "malformed", { - issues: [cause.issue], - }); - } + // An unmappable PE layout is invalid input for every managed operation. + const pe = readManagedPeLayout(bytes); if (pe.cli === null) return emptyInspection( target, diff --git a/src/dotnet/ManagedStaticProvider.ts b/src/dotnet/ManagedStaticProvider.ts index ba09a1939..d456455a2 100644 --- a/src/dotnet/ManagedStaticProvider.ts +++ b/src/dotnet/ManagedStaticProvider.ts @@ -22,6 +22,7 @@ import type { BinaryTarget } from "../domain/binaryTargetTypes.js"; import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, + AnalysisInputError, } from "../domain/analysisErrorCore.js"; import { EvidenceIntegrityError } from "../domain/evidenceErrors.js"; import { ProviderAdapterError } from "../domain/providerAdapterError.js"; @@ -38,6 +39,7 @@ import { inspectManagedArtifactBytes } from "./ManagedArtifactInspector.js"; import { inspectManagedMembersBytes } from "./ManagedMemberInspector.js"; import { inspectManagedNativeBoundariesBytes } from "./ManagedNativeBoundaryInspector.js"; import { RegularFileCleanupFailure } from "../application/RegularFileRead.js"; +import { ManagedReaderFailure } from "./ManagedReaderFailure.js"; import { hashManagedSource, managedCleanupError, @@ -135,6 +137,20 @@ class ManagedStaticClient implements AnalysisClient { if (cause instanceof AnalysisError) return err(cause); if (options?.signal?.aborted === true) return err(new AnalysisCancelledError(operation)); + // A PE header or section table the reader cannot map is malformed input. + if ( + cause instanceof ManagedReaderFailure && + cause.issue.code !== "resource-limit" + ) + return err( + new AnalysisInputError(operation, { cause }, [ + { + path: ["path"], + reason: "invalid_format", + message: `Selected artifact ${this.target.path}: ${cause.issue.detail}`, + }, + ]), + ); return err( new ProviderAdapterError(MANAGED_STATIC_PROVIDER.id, operation, { cause, diff --git a/tests/acceptance/managedCliOutput.test.ts b/tests/acceptance/managedCliOutput.test.ts index a24020d60..26ef7b85d 100644 --- a/tests/acceptance/managedCliOutput.test.ts +++ b/tests/acceptance/managedCliOutput.test.ts @@ -307,3 +307,36 @@ cliTest( } }, ); + +cliTest( + "managed CLI reports a section table past EOF as invalid input", + async ({ cli }) => { + const root = await createTestTempDirectory("rea-managed-cli-sections-"); + const path = join(root, "fixture.dll"); + const bytes = buildManagedPeFixture(); + const pe = bytes.readUInt32LE(0x3c); + const sections = pe + 24 + bytes.readUInt16LE(pe + 20); + bytes.writeUInt32LE(bytes.length + 0x1000, sections + 20); + await writeFile(path, bytes); + for (const command of [ + "inspect-managed-artifact", + "inspect-managed-members", + "inspect-managed-native-boundaries", + ]) { + const result = await cli.run({ arguments: [command, path, "--json"] }); + expect(result.exitCode).toBe(1); + expect(result.json).toMatchObject({ + code: "invalid_request", + details: { + issues: [ + { + path: ["path"], + reason: "invalid_format", + message: expect.stringContaining("pe.section-data"), + }, + ], + }, + }); + } + }, +); From 51367cae6f4e6ef9b9dcb28dc21fe6c92d1dd6f8 Mon Sep 17 00:00:00 2001 From: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com> Date: Mon, 12 Oct 2026 06:53:55 -0700 Subject: [PATCH 3/8] fix(setup): name structural problems in client configurations (#2154) A client configuration that parses but whose root or MCP server table is not an object (for example {"mcpServers": null} or []) made setup print a raw Zod issue dump and made uninstall claim the file was not valid JSON. parseClientConfiguration now raises a ClientConfigurationShapeError naming the root or the servers key, which setup reports as the malformed detail and uninstall reports instead of a syntax error. Fixes #2152 Co-authored-by: Claude Opus 5.5 --- .../ClientConfigurationDocument.ts | 31 +++++++++++++++++-- src/application/Uninstall.ts | 6 ++-- .../filesystem/clientLifecycle.test.ts | 29 +++++++++++++++++ 3 files changed, 61 insertions(+), 5 deletions(-) diff --git a/src/application/ClientConfigurationDocument.ts b/src/application/ClientConfigurationDocument.ts index 65b4ba8de..27b5393d2 100644 --- a/src/application/ClientConfigurationDocument.ts +++ b/src/application/ClientConfigurationDocument.ts @@ -128,6 +128,20 @@ const parseDocument = ( return objectSchema.parse(document); }; +/** A parsed configuration whose structure, not its syntax, cannot hold MCP servers. */ +export class ClientConfigurationShapeError extends TypeError {} + +const requireObject = ( + value: unknown, + description: string, +): Record => { + const parsed = objectSchema.safeParse(value); + if (parsed.success) return parsed.data; + throw new ClientConfigurationShapeError(`${description} must be an object`, { + cause: parsed.error, + }); +}; + /** Members of OpenCode V2's `mcp` object that are not server names. */ const OPENCODE_V2_MCP_SETTINGS = new Set(["servers", "timeout"]); @@ -140,10 +154,21 @@ export const parseClientConfiguration = ( throw new TypeError("client does not have a supported MCP config format"); // DeepSeek Harness stores a Cordis patch list, not a server table. if (format === "dsh") return parseDshCordisDocument(text); - const document = parseDocument(text, format); + let document: Record; + try { + document = parseDocument(text, format); + } catch (cause: unknown) { + if (cause instanceof z.ZodError) + throw new ClientConfigurationShapeError( + "The configuration root must be an object", + { cause }, + ); + throw cause; + } const serversKey = clientConfigurationServersKey(format); const value = document[serversKey]; - const servers = value === undefined ? {} : objectSchema.parse(value); + const servers = + value === undefined ? {} : requireObject(value, `"${serversKey}"`); const native = servers.servers; // A V1 server named `servers` has a string `type` discriminator; the V2 // table may instead hold a server object named `type`. @@ -164,7 +189,7 @@ export const parseClientConfiguration = ( }; return { document, - servers: objectSchema.parse(native), + servers: requireObject(native, `"${serversKey}.servers"`), serversPath: [serversKey, "servers"], dialect: "opencode_v2", legacyServers: Object.fromEntries( diff --git a/src/application/Uninstall.ts b/src/application/Uninstall.ts index 6822460bb..24ff88ea6 100644 --- a/src/application/Uninstall.ts +++ b/src/application/Uninstall.ts @@ -1,4 +1,5 @@ import { + ClientConfigurationShapeError, parseClientConfiguration, serializeClientConfiguration, clientServerPath, @@ -279,12 +280,13 @@ const readClientConfiguration = async ( const parsed = parseClientConfiguration(original, client.format); return { kind: "configuration", transactionPath, original, parsed }; } catch (cause: unknown) { - void cause; return itemRead( item( client.name, "failed", - `Configuration is not valid ${client.format === "toml" || client.format === "grok" ? "TOML" : client.format === "opencode" ? "JSONC" : "JSON"} and was not changed. Repair it, then rerun uninstall.`, + cause instanceof ClientConfigurationShapeError + ? `Configuration was not changed: ${cause.message}. Repair it, then rerun uninstall.` + : `Configuration is not valid ${client.format === "toml" || client.format === "grok" ? "TOML" : client.format === "opencode" ? "JSONC" : "JSON"} and was not changed. Repair it, then rerun uninstall.`, ), ); } diff --git a/tests/boundary/filesystem/clientLifecycle.test.ts b/tests/boundary/filesystem/clientLifecycle.test.ts index db0b517e7..6ee7543e9 100644 --- a/tests/boundary/filesystem/clientLifecycle.test.ts +++ b/tests/boundary/filesystem/clientLifecycle.test.ts @@ -21,6 +21,7 @@ import { PRODUCT_IDENTITY } from "../../../src/identity.js"; import { readClientRegistrationStatuses } from "../../../src/application/ClientRegistrationStatus.js"; import { configureClientConfiguration } from "../../../src/application/SetupClientConfiguration.js"; +import { readConfigurationFile } from "../../../src/application/ClientConfigurationFiles.js"; import { detectClients, systemSetupHost, @@ -1593,6 +1594,34 @@ describe("uninstall configuration preflight", () => { expect(await readFile(config, "utf8")).toBe("not-json"); }); + it.each([ + ['{"mcpServers": null}', '"mcpServers" must be an object'], + ["[]", "The configuration root must be an object"], + ])( + "names the structural problem in valid JSON %s", + async (content, problem) => { + const home = await createTestTempDirectory("rea-uninstall-shape-"); + roots.push(home); + const config = join(home, ".cursor/mcp.json"); + await mkdir(dirname(config), { recursive: true }); + await writeFile(config, content); + expect(await readConfigurationFile(config, "json")).toMatchObject({ + ok: false, + error: { + kind: "malformed", + detail: `Configuration ${config} is malformed: ${problem}`, + }, + }); + const result = await runUninstall(false, systemUninstallHost(home)); + expect(result.items).toContainEqual({ + name: "cursor", + status: "failed", + detail: `Configuration was not changed: ${problem}. Repair it, then rerun uninstall.`, + }); + expect(await readFile(config, "utf8")).toBe(content); + }, + ); + it("stops before any removal when one client configuration is malformed", async () => { const home = await createTestTempDirectory("rea-uninstall-stop-"); roots.push(home); From d35035780a643e38301b8eaea03f01bb506e9df9 Mon Sep 17 00:00:00 2001 From: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com> Date: Mon, 12 Oct 2026 06:54:38 -0700 Subject: [PATCH 4/8] fix(setup): remove emptied skill directories on uninstall (#2182) * fix(setup): remove emptied skill directories on uninstall Uninstall removes only the managed skill files so user files survive, but it left every emptied reverse-engineer-anything directory and its references/ subdirectory behind. After the ownership manifest is removed, remove the managed directories deepest first with a non-recursive rmdir, which keeps any directory that still holds user files. Fixes #2159 Co-Authored-By: Claude Opus 5.5 * fix(setup): report emptied skill directories that cannot be removed Only a directory that still holds user files, is already absent, or is no longer a directory is kept silently. Any other rmdir failure, such as a parent that denies deletion, now fails the skill item with the directory path instead of reporting the skill as removed. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- src/application/Uninstall.ts | 61 ++++++++++++++++-- .../filesystem/clientLifecycle.test.ts | 63 +++++++++++++++++++ 2 files changed, 120 insertions(+), 4 deletions(-) diff --git a/src/application/Uninstall.ts b/src/application/Uninstall.ts index 24ff88ea6..570b5589e 100644 --- a/src/application/Uninstall.ts +++ b/src/application/Uninstall.ts @@ -7,7 +7,7 @@ import { withClientServers, type ClientConfigurationDocument, } from "./ClientConfigurationDocument.js"; -import { copyFile, lstat, realpath, rm } from "node:fs/promises"; +import { copyFile, lstat, realpath, rm, rmdir } from "node:fs/promises"; import { constants as fsConstants } from "node:fs"; import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js"; import { join } from "node:path"; @@ -51,6 +51,8 @@ export interface UninstallFileSystem { stat(path: string): Promise; realpath?(path: string): Promise; remove(path: string, recursive?: boolean): Promise; + /** Remove a directory only if it is empty; a non-empty one is kept. */ + removeEmptyDirectory?(path: string): Promise; } const systemFileSystem = ( @@ -65,6 +67,7 @@ const systemFileSystem = ( stat: (path) => lstat(path), realpath: (path) => realpath(path), remove: (path, recursive = true) => rm(path, { recursive }), + removeEmptyDirectory: (path) => rmdir(path), }); /** One explicitly classified uninstall action. */ @@ -602,10 +605,20 @@ const removeManagedSkill = async ( "REA ownership manifest was retained because a managed file could not be safely removed.", ), ); - else - results.push( - await removeManagedSkillFile(path, manifestName, name, fileSystem), + else { + const manifest = await removeManagedSkillFile( + path, + manifestName, + name, + fileSystem, ); + results.push(manifest); + const directories = + manifest.status === "removed" + ? await removeEmptyManagedDirectories(path, name, fileSystem) + : undefined; + if (directories !== undefined) results.push(directories); + } const failed = results.find(({ status }) => status === "failed"); if (failed !== undefined) return item(name, "failed", results.map(({ detail }) => detail).join(" ")); @@ -617,6 +630,46 @@ const removeManagedSkill = async ( ); }; +/** Directories setup creates for managed files, deepest first, then the root. */ +const MANAGED_SKILL_DIRECTORIES = [ + ...new Set( + MANAGED_SKILL_FILES.map((relativePath) => + relativePath.split("/").slice(0, -1).join("/"), + ).filter((directory) => directory.length > 0), + ), +].sort((left, right) => right.split("/").length - left.split("/").length); + +/** Remove managed directories left empty; any remaining user file keeps them. */ +const removeEmptyManagedDirectories = async ( + root: string, + name: string, + fileSystem: UninstallFileSystem, +): Promise => { + if (fileSystem.removeEmptyDirectory === undefined) return undefined; + for (const directory of [ + ...MANAGED_SKILL_DIRECTORIES.map((relative) => join(root, relative)), + root, + ]) { + try { + await fileSystem.removeEmptyDirectory(directory); + } catch (cause: unknown) { + // User files, an absent directory, or a non-directory keep it as is. + if (!isKeptDirectory(cause)) + return item( + name, + "failed", + `Managed skill directory could not be removed: ${directory}.`, + ); + } + } + return undefined; +}; + +const isKeptDirectory = (cause: unknown): boolean => + cause instanceof Error && + "code" in cause && + ["ENOTEMPTY", "EEXIST", "ENOENT", "ENOTDIR"].includes(String(cause.code)); + const removeManagedSkillFile = async ( root: string, relativePath: string, diff --git a/tests/boundary/filesystem/clientLifecycle.test.ts b/tests/boundary/filesystem/clientLifecycle.test.ts index 6ee7543e9..89c4dc95a 100644 --- a/tests/boundary/filesystem/clientLifecycle.test.ts +++ b/tests/boundary/filesystem/clientLifecycle.test.ts @@ -1,5 +1,6 @@ import { constants as fsConstants } from "node:fs"; import { + chmod, copyFile, lstat, mkdir, @@ -1527,6 +1528,68 @@ describe("client configuration filesystem removal", () => { ); }); + it("removes emptied skill directories and keeps ones with user files", async () => { + const home = await createTestTempDirectory("rea-uninstall-skill-dirs-"); + roots.push(home); + const shared = join(home, ".agents/skills/reverse-engineer-anything"); + const claude = join(home, ".claude/skills/reverse-engineer-anything"); + for (const root of [shared, claude]) { + await mkdir(join(root, "references"), { recursive: true }); + await writeFile(join(root, "SKILL.md"), ownedSkillManifest); + await writeFile( + join(root, "references/evidence-workflows.md"), + "managed", + ); + } + await writeFile(join(claude, "notes.md"), "user"); + + const result = await runUninstall( + false, + systemUninstallHost(home, undefined, { + HOME: home, + CLAUDE_CONFIG_DIR: join(home, ".claude"), + }), + ); + + expect(result.status).toBe("complete"); + await expect(lstat(shared)).rejects.toMatchObject({ code: "ENOENT" }); + await expect(lstat(join(claude, "references"))).rejects.toMatchObject({ + code: "ENOENT", + }); + expect(await readFile(join(claude, "notes.md"), "utf8")).toBe("user"); + }); + + it.skipIf(process.platform === "win32" || process.getuid?.() === 0)( + "reports an emptied skill directory that cannot be removed", + async () => { + const home = await createTestTempDirectory("rea-uninstall-skill-perm-"); + roots.push(home); + const parent = join(home, ".agents/skills"); + const root = join(parent, "reverse-engineer-anything"); + await mkdir(join(root, "references"), { recursive: true }); + await writeFile(join(root, "SKILL.md"), ownedSkillManifest); + await chmod(parent, 0o555); + try { + const result = await runUninstall( + false, + systemUninstallHost(home, undefined, { HOME: home }), + ); + expect(result.status).toBe("failed"); + expect(result.items).toContainEqual( + expect.objectContaining({ + name: "skill", + status: "failed", + detail: expect.stringContaining( + `Managed skill directory could not be removed: ${root}.`, + ), + }), + ); + } finally { + await chmod(parent, 0o755); + } + }, + ); + it("removes an owned entry through a symlink without replacing it", async () => { const home = await createTestTempDirectory("rea-uninstall-symlink-"); roots.push(home); From 7c9c1ebdb77662f6276ef2f7250e7df414bd03ca Mon Sep 17 00:00:00 2001 From: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com> Date: Mon, 12 Oct 2026 06:56:45 -0700 Subject: [PATCH 5/8] fix(mcp): keep shared optional providers open across discarded probes (#2205) startMcpTransport loads optional observation providers once per process and passes them to every server instance the SDK constructs. Each instance's closeProviders also closed the shared browser scenario provider, so when the SDK discarded a server/discover probe instance for a legacy initialize, every later capture_browser_scenario call failed with "Browser scenario provider is closing." Server instances no longer close the caller-supplied provider; the transport returns closeOptionalProviders and process shutdown closes it once. Fixes #2195 Co-authored-by: Claude Opus 5.5 --- src/main.ts | 1 + src/main/shutdown.ts | 4 ++ src/main/transport.ts | 8 ++- src/server/createServer.ts | 1 - .../browserScenarioProbeLifecycle.test.ts | 61 +++++++++++++++++++ 5 files changed, 73 insertions(+), 2 deletions(-) create mode 100644 tests/boundary/process/browserScenarioProbeLifecycle.test.ts diff --git a/src/main.ts b/src/main.ts index 40c241b47..3d32798b7 100644 --- a/src/main.ts +++ b/src/main.ts @@ -82,6 +82,7 @@ export const run = async ( createShutdown({ handle: transport.handle, closeAndroid: transport.closeAndroid, + closeOptionalProviders: transport.closeOptionalProviders, session, dependencies, serverLogger, diff --git a/src/main/shutdown.ts b/src/main/shutdown.ts index f6722eb97..90d30c575 100644 --- a/src/main/shutdown.ts +++ b/src/main/shutdown.ts @@ -16,6 +16,7 @@ interface ShutdownCleanupOwner { export const createShutdown = (input: { readonly handle: StdioServerHandle; readonly closeAndroid?: () => Promise; + readonly closeOptionalProviders?: () => Promise; readonly session: BinarySession; readonly dependencies: RuntimeDependencies; readonly serverLogger: Logger; @@ -30,6 +31,9 @@ export const createShutdown = (input: { ...(input.closeAndroid === undefined ? [] : [{ close: input.closeAndroid, closed: false }]), + ...(input.closeOptionalProviders === undefined + ? [] + : [{ close: input.closeOptionalProviders, closed: false }]), { close: async () => { const closed = await session.close({ retainProviderDocuments: true }); diff --git a/src/main/transport.ts b/src/main/transport.ts index f8d6014f3..f9a5cd0ea 100644 --- a/src/main/transport.ts +++ b/src/main/transport.ts @@ -31,6 +31,7 @@ export const startMcpTransport = async ( readonly ok: true; readonly handle: StdioServerHandle; readonly closeAndroid: () => Promise; + readonly closeOptionalProviders: () => Promise; } | { readonly ok: false } > => { @@ -62,6 +63,11 @@ export const startMcpTransport = async ( for (const result of results) if (result.status === "rejected") throw result.reason; }; + // Optional providers are shared by every server instance the SDK creates, + // including a discarded discovery probe, so only process shutdown closes them. + const closeOptionalProviders = async (): Promise => { + await optionalProviders.browserScenarioCapture?.close?.(); + }; let handle: StdioServerHandle; try { handle = dependencies.serve( @@ -124,5 +130,5 @@ export const startMcpTransport = async ( } return { ok: false }; } - return { ok: true, handle, closeAndroid }; + return { ok: true, handle, closeAndroid, closeOptionalProviders }; }; diff --git a/src/server/createServer.ts b/src/server/createServer.ts index 0e5c69cba..3220fe8e7 100644 --- a/src/server/createServer.ts +++ b/src/server/createServer.ts @@ -270,7 +270,6 @@ export const createServer = ( javascriptRecovery.close?.() ?? Promise.resolve(), artifactResources.close(), firmwareAnalysis.close(), - options.browserScenarioCapture?.close?.() ?? Promise.resolve(), ]) .then((results) => { const failures = results.flatMap((result) => diff --git a/tests/boundary/process/browserScenarioProbeLifecycle.test.ts b/tests/boundary/process/browserScenarioProbeLifecycle.test.ts new file mode 100644 index 000000000..42871d13a --- /dev/null +++ b/tests/boundary/process/browserScenarioProbeLifecycle.test.ts @@ -0,0 +1,61 @@ +import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server"; +import { expect, it, vi } from "vitest"; + +import type { BrowserScenarioCapturePort } from "../../../src/application/BrowserScenarioCapturePort.js"; +import { silentLogger } from "../../../src/logger.js"; +import { startMcpTransport } from "../../../src/main/transport.js"; +import type { RuntimeDependencies } from "../../../src/main/types.js"; +import { ToolResultDelivery } from "../../../src/server/toolResult.js"; +import { createTestBinarySession } from "../../fixtures/binarySession.js"; + +it("keeps the shared browser scenario provider open when the SDK discards its discovery probe", async () => { + const session = createTestBinarySession(() => { + throw new Error("Unexpected deep provider"); + }); + const close = vi.fn(async () => undefined); + const browserScenarioCapture: BrowserScenarioCapturePort = { + identity: () => ({ + id: "fake-browser", + name: "Fake browser", + version: "1", + }), + captureScenario: async () => { + throw new Error("Unexpected scenario capture"); + }, + close, + }; + const factories: Parameters[0][] = []; + const runtime: RuntimeDependencies = { + env: {}, + serve: (factory) => { + factories.push(factory); + return { close: async () => undefined }; + }, + writeStderr: () => undefined, + setExitCode: () => undefined, + registerShutdown: () => () => undefined, + }; + const transport = await startMcpTransport(runtime, session, { + logger: silentLogger, + serverLogger: silentLogger, + environment: runtime.env, + delivery: new ToolResultDelivery(STDIO_DEFAULT_MAX_BUFFER_SIZE), + loadOptionalProviders: async () => ({ browserScenarioCapture }), + }); + if (!transport.ok) throw new Error("Transport failed"); + const factory = factories[0]; + if (factory === undefined) throw new Error("Missing SDK server factory"); + try { + const probe = await factory({ era: "modern" }); + await probe.close(); + const replacement = await factory({ era: "legacy" }); + await replacement.close(); + expect(close).not.toHaveBeenCalled(); + + await transport.closeOptionalProviders(); + expect(close).toHaveBeenCalledTimes(1); + } finally { + await transport.closeAndroid(); + await session.close(); + } +}); From 0b7145361ec02d27260eb1f5bc0be955c9374a96 Mon Sep 17 00:00:00 2001 From: Ysopwnable <161784452+N0zoM1z0@users.noreply.github.com> Date: Mon, 12 Oct 2026 22:01:47 +0800 Subject: [PATCH 6/8] feat(wasm): add opt-in first-call summary delivery (#2193) Add explicit first-call WASM summary delivery while preserving omitted/complete MCP requests, CLI output, original Evidence identity and provider inputs. Reuse exact retained export views and schema-based capability discovery. Nine paired public SDK comparisons and ten actual Codex CLI answers preserve selected facts and source references. Record token reductions alongside mixed latency and unverified final resource-counter conditions. Current-main integration passes seven relevant WASM MCP workflows, a fresh real-WABT SQLite workflow and required static gates. Refs #2016. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- .../references/native-and-artifacts.md | 4 + docs/mcp-contracts.md | 8 +- experiments/analysis-efficiency/README.md | 9 +- experiments/analysis-efficiency/corpus.json | 34 ++++ experiments/analysis-efficiency/measure.mjs | 183 ++++++++++-------- .../questions/wasm-interface.txt | 1 + .../analysis-efficiency/wasm-first-call.md | 149 ++++++++++++++ src/contracts/wasm/wasmToolContracts.ts | 21 +- src/domain/analysisView/analysisView.ts | 7 + src/server/createServer.ts | 1 + src/server/registerWasmTools.ts | 26 ++- tests/boundary/mcp/wasmArtifactMcp.test.ts | 144 +++++++++++++- 12 files changed, 499 insertions(+), 88 deletions(-) create mode 100644 experiments/analysis-efficiency/questions/wasm-interface.txt create mode 100644 experiments/analysis-efficiency/wasm-first-call.md diff --git a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md index 1b02a7ed2..dfb701760 100644 --- a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md +++ b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md @@ -39,6 +39,10 @@ read a single object. ## Offline WASM Use `inspect_wasm_artifact` with caller-supplied WABT for selected local bytes. +For counts, validation and WAT identity, select `detail: "summary"` on the first +MCP call. The complete original Evidence stays retained; use +`normalized_result.parent_evidence_id` for exact exports or text pages. Omitted +or complete detail keeps the existing complete result. For a completed result, use `inspect_analysis_view` with its reported retained reference for a summary or `view: {kind: "wasm", facet: "exports", offset: 0, limit: 32}`. Facets also include sections, imports, candidates, glue, WAT, headers, details diff --git a/docs/mcp-contracts.md b/docs/mcp-contracts.md index 8e5755caf..1fb3b5e5d 100644 --- a/docs/mcp-contracts.md +++ b/docs/mcp-contracts.md @@ -412,7 +412,8 @@ Ordinary responses keep their existing complete result contract. ## Retained application Evidence inputs -`analyze_javascript_application`, `inspect_binary_layout`, and `inspect_artifact` accept `detail`: +`analyze_javascript_application`, `inspect_binary_layout`, `inspect_artifact`, and +`inspect_wasm_artifact` accept `detail`: `complete` (default) returns the complete analysis Evidence; `summary` records that complete Evidence in the session and returns the derived `inspect_analysis_view` summary Evidence instead. Its @@ -476,6 +477,11 @@ The original producer still returns complete Evidence by default. When its complete MCP reply exceeds the frame, use the exact reported retained reference with these views, or export the complete source. Views do not run WABT again and do not turn decoded WAT into original source. +For counts, validation and WAT identity, select `detail: "summary"` on the first +`inspect_wasm_artifact` call. It retains the original complete source without +attempting oversized delivery, and returns the same summary with an exact +`parent_evidence_id` for later export or facet reads. Delivery detail does not +reach WABT or change the original source Evidence ID. `trace_application_feature`, `trace_javascript_semantics`, `compare_application_versions`, `compare_source_to_bundle`, and diff --git a/experiments/analysis-efficiency/README.md b/experiments/analysis-efficiency/README.md index 8c1708009..9a09e9d36 100644 --- a/experiments/analysis-efficiency/README.md +++ b/experiments/analysis-efficiency/README.md @@ -137,8 +137,11 @@ inventory. It must be supported by the selected server's advertised schema. The default `complete` runs the existing calls unchanged. Compare the same analyst facts and complete source Evidence before crediting a smaller response. Projection can reduce delivery bytes without reducing upstream analysis time. -For SQLite WASM, summary delivery reads the completed retained result through -the summary and exports views after preserving the original transport error. +For WASM, the runner validates a summary request against the actual advertised +2020-12 input schema, including SDK-generated references. Supporting servers +return the first-call summary; older servers retain their complete path and use +summary/export views after an observed transport constraint. Original errors +remain in the receipts, and the complete source Evidence ID is a compared fact. `--javascript-question selected` analyzes only the exact Obsidian sources `package.json` and `main.js`, keeps inventory identity, and reads each observed `main.js` module by its exact node ID. Package metadata is not a module selector. @@ -538,3 +541,5 @@ observations, not verified final counters. Their bytes, facts and token reports remain original observations; resource-qualified performance conclusions need this additional closeout evidence. No analyzer/build/schema/package behavior is changed, so unrelated verification is not repeated for this research-driver fix. + +The next bounded WASM delivery cohort is documented in [first-call summary measurements](wasm-first-call.md). diff --git a/experiments/analysis-efficiency/corpus.json b/experiments/analysis-efficiency/corpus.json index c85180568..911fa88f5 100644 --- a/experiments/analysis-efficiency/corpus.json +++ b/experiments/analysis-efficiency/corpus.json @@ -115,6 +115,40 @@ "transport_bytes": 168796487, "derivation": "selected regular ZIP member ShareX.HelpersLib.dll; no target execution" } + }, + { + "id": "vscode.tree-sitter.wasm", + "file": "tree-sitter.wasm", + "bytes": 206218, + "sha256": "3a31af706ffdf4a7116b064cdd4988df6791823298615009fc5b6bccbd42909b", + "provenance": { + "project": "VS Code Tree-sitter published WASM package", + "version": "0.3.1", + "project_url": "https://github.com/microsoft/vscode-tree-sitter-wasm", + "upstreamFile": "tree-sitter-wasm-0.3.1.tgz", + "url": "https://registry.npmjs.org/@vscode/tree-sitter-wasm/-/tree-sitter-wasm-0.3.1.tgz", + "transport_sha256": "985684b2cfbe5e8f90499a9f36e37519887c7d4e2697d0457d0f1e923ce5184c", + "transport_bytes": 2053205, + "transport_integrity": "sha512-RJFoomET6FajjG511fmQxeBQfU6M24a0aFZPqpid+ttIxanWf1VGytBG0UmsGjt07qmIPJS8U31D+aecuCucsQ==", + "derivation": "selected regular tar member package/wasm/tree-sitter.wasm; no target execution" + } + }, + { + "id": "vscode.tree-sitter-css.wasm", + "file": "tree-sitter-css.wasm", + "bytes": 128668, + "sha256": "8a23977fe271357cce6f254ef88c9bebf3854602d8046605aef6a45c02135c59", + "provenance": { + "project": "VS Code Tree-sitter published WASM package", + "version": "0.3.1", + "project_url": "https://github.com/microsoft/vscode-tree-sitter-wasm", + "upstreamFile": "tree-sitter-wasm-0.3.1.tgz", + "url": "https://registry.npmjs.org/@vscode/tree-sitter-wasm/-/tree-sitter-wasm-0.3.1.tgz", + "transport_sha256": "985684b2cfbe5e8f90499a9f36e37519887c7d4e2697d0457d0f1e923ce5184c", + "transport_bytes": 2053205, + "transport_integrity": "sha512-RJFoomET6FajjG511fmQxeBQfU6M24a0aFZPqpid+ttIxanWf1VGytBG0UmsGjt07qmIPJS8U31D+aecuCucsQ==", + "derivation": "selected regular tar member package/wasm/tree-sitter-css.wasm; no target execution" + } } ] } diff --git a/experiments/analysis-efficiency/measure.mjs b/experiments/analysis-efficiency/measure.mjs index a10eb23d8..348bf02c2 100644 --- a/experiments/analysis-efficiency/measure.mjs +++ b/experiments/analysis-efficiency/measure.mjs @@ -13,6 +13,7 @@ import { fileURLToPath, pathToFileURL } from "node:url"; import { parseArgs } from "node:util"; import { Client } from "@modelcontextprotocol/client"; import { StdioClientTransport } from "@modelcontextprotocol/client/stdio"; +import { Ajv2020 } from "ajv/dist/2020.js"; const root = resolve(dirname(fileURLToPath(import.meta.url)), "../.."); const { values } = parseArgs({ @@ -243,6 +244,106 @@ const inspectManagedTarget = async () => { }; }; +/** The same counts/export question for each pinned shipped WASM module. */ +const inspectWasmTarget = async () => { + let info; + let recovery = null; + const arguments_ = { + path: values.path, + glue_paths: [], + candidate_paths: [], + }; + const definition = catalogDefinitions.get("inspect_wasm_artifact"); + if (!definition) throw new Error("Missing advertised WASM definition"); + // Validate the real advertised dialect, including SDK-generated local refs. + const supportsSummary = new Ajv2020({ + strict: false, + validateFormats: false, + }).compile(definition.inputSchema)({ ...arguments_, detail: "summary" }); + try { + info = await call("inspect_wasm_artifact", { + ...arguments_, + ...(values.delivery === "summary" && supportsSummary + ? { detail: "summary" } + : {}), + }); + } catch (error) { + const reference = + error instanceof ToolFailure && + error.value?.error?.code === "resource_constraint" + ? error.value.error.details?.reported_limits?.evidence_reference + : undefined; + if (reference?.kind !== "retained-evidence") throw error; + if (values.delivery === "summary") { + info = await call("inspect_analysis_view", { + source: reference, + view: { kind: "summary" }, + }); + recovery = + "existing completed producer reference read through typed WASM views"; + } else { + const path = resolve(values.output, "retained-evidence.json"); + await call("export_evidence_bundle", { path }); + const bundle = JSON.parse(await readFile(path, "utf8")); + const record = bundle.records.find( + (row) => row.evidence_id === reference.evidence_id, + ); + const { parseEvidence } = await import( + pathToFileURL( + resolve(values["runtime-root"], "dist/domain/evidence.js"), + ).href + ); + info = parseEvidence(record); + recovery = + "complete producer Evidence exported after an observed transport constraint"; + } + } + const n = normalized(info); + if (n.kind === "summary") { + const summary = n.summary; + const exportsEvidence = await call("inspect_analysis_view", { + source: { kind: "retained-evidence", evidence_id: n.parent_evidence_id }, + view: { kind: "wasm", facet: "exports", offset: 0, limit: 4 }, + }); + return { + artifact_sha256: targetSha(info), + validation: summary.validation, + section_count: summary.available_counts.sections, + import_count: summary.available_counts.imports, + export_count: summary.available_counts.exports, + exports_first4: normalized(exportsEvidence).item, + wat_sha256: summary.wat.sha256, + wat_code_units: summary.wat.code_units, + tool_profile: summary.tool_profile, + runtime_execution: summary.runtime_execution, + network_fetch: summary.network_fetch, + evidence_ids: [ + n.parent_evidence_id, + info.evidence_id, + exportsEvidence.evidence_id, + ], + source_evidence_id: n.parent_evidence_id, + recovery, + }; + } + return { + artifact_sha256: targetSha(info), + validation: n.validation, + section_count: n.sections.length, + import_count: n.imports.length, + export_count: n.exports.length, + exports_first4: n.exports.slice(0, 4), + wat_sha256: n.wat.sha256, + wat_code_units: n.wat.text.length, + tool_profile: n.tool_profile, + runtime_execution: n.runtime_execution, + network_fetch: n.network_fetch, + evidence_ids: [info.evidence_id], + source_evidence_id: info.evidence_id, + recovery, + }; +}; + const workflows = { "obsidian.asar": async () => { if (values["javascript-question"] === "selected") { @@ -424,85 +525,9 @@ const workflows = { evidence_ids: [info.evidence_id], }; }, - "sqlite.wasm": async () => { - let info; - let recovery = null; - try { - info = await call("inspect_wasm_artifact", { - path: values.path, - glue_paths: [], - candidate_paths: [], - }); - } catch (error) { - const reference = - error instanceof ToolFailure && - error.value?.error?.code === "resource_constraint" - ? error.value.error.details?.reported_limits?.evidence_reference - : undefined; - if (reference?.kind !== "retained-evidence") throw error; - if (values.delivery === "summary") { - const summaryEvidence = await call("inspect_analysis_view", { - source: reference, - view: { kind: "summary" }, - }); - const summary = normalized(summaryEvidence).summary; - const exportsEvidence = await call("inspect_analysis_view", { - source: reference, - view: { kind: "wasm", facet: "exports", offset: 0, limit: 4 }, - }); - return { - artifact_sha256: targetSha(summaryEvidence), - validation: summary.validation, - section_count: summary.available_counts.sections, - import_count: summary.available_counts.imports, - export_count: summary.available_counts.exports, - exports_first4: normalized(exportsEvidence).item, - wat_sha256: summary.wat.sha256, - wat_code_units: summary.wat.code_units, - tool_profile: summary.tool_profile, - runtime_execution: summary.runtime_execution, - network_fetch: summary.network_fetch, - evidence_ids: [ - reference.evidence_id, - summaryEvidence.evidence_id, - exportsEvidence.evidence_id, - ], - recovery: - "existing completed producer reference read through typed WASM views", - }; - } - const path = resolve(values.output, "retained-evidence.json"); - await call("export_evidence_bundle", { path }); - const bundle = JSON.parse(await readFile(path, "utf8")); - const record = bundle.records.find( - (row) => row.evidence_id === reference.evidence_id, - ); - const { parseEvidence } = await import( - pathToFileURL( - resolve(values["runtime-root"], "dist/domain/evidence.js"), - ).href - ); - info = parseEvidence(record); - recovery = - "complete producer Evidence exported after an observed transport constraint"; - } - const n = normalized(info); - return { - artifact_sha256: targetSha(info), - validation: n.validation, - section_count: n.sections.length, - import_count: n.imports.length, - export_count: n.exports.length, - exports_first4: n.exports.slice(0, 4), - wat_sha256: n.wat.sha256, - wat_code_units: n.wat.text.length, - tool_profile: n.tool_profile, - runtime_execution: n.runtime_execution, - network_fetch: n.network_fetch, - evidence_ids: [info.evidence_id], - recovery, - }; - }, + "sqlite.wasm": inspectWasmTarget, + "vscode.tree-sitter.wasm": inspectWasmTarget, + "vscode.tree-sitter-css.wasm": inspectWasmTarget, "weth.hex": async () => { const info = await call("inspect_evm_interface", { path: values.path, diff --git a/experiments/analysis-efficiency/questions/wasm-interface.txt b/experiments/analysis-efficiency/questions/wasm-interface.txt new file mode 100644 index 000000000..fd09040cd --- /dev/null +++ b/experiments/analysis-efficiency/questions/wasm-interface.txt @@ -0,0 +1 @@ +Statically inspect the real shipped WASM module at {{artifact_path}} using only REA tools. Report exact selected artifact SHA-256, valid/invalid status, section count, import count, export count, first four complete export WAT forms in producer order, decoded WAT SHA-256 and code-unit length, WABT release/source commit, and exact runtime_execution/network_fetch states. If complete delivery exceeds the MCP frame, use the exact retained reference for summary and wasm exports views. Preserve original strings, uncertainties and real Evidence IDs. Do not execute WASM, fetch URLs or use shell/file tools. Final JSON fields: artifact_sha256, validation, section_count, import_count, export_count, exports_first4, wat_sha256, wat_code_units, wabt_release, wabt_source_commit, runtime_execution, network_fetch, evidence_ids, limitations. diff --git a/experiments/analysis-efficiency/wasm-first-call.md b/experiments/analysis-efficiency/wasm-first-call.md new file mode 100644 index 000000000..fb554507a --- /dev/null +++ b/experiments/analysis-efficiency/wasm-first-call.md @@ -0,0 +1,149 @@ +# WASM first-call summary delivery + +Refs [#2016](https://github.com/morluto/rea/issues/2016). This bounded follow-up +adds optional MCP `inspect_wasm_artifact detail: summary`. Omitted/complete MCP +requests and CLI output remain complete. Full original Evidence is retained; +delivery selection is stripped before provider inputs, and exact export views +read the original parent without another WABT invocation. + +## Pinned repeated public SDK cohort + +- Control: `18e5d6275965c5f1d3ef9fe373d1792822098003`. +- Candidate: `45831c622a13368494d2a8f3a9718effa91c937c`. +- Runtime file-table SHA-256: control `ef65527c2d41b621f71059b7553050660d801ad905a61a71b81aba266f70e1ec`; + candidate `353f5513ea09b0a627fa99814cebe0a1231c6c8f7e0e12a28205521133478b1a`. +- Actual WABT 1.0.42, identical explicitly selected provider configuration and + effective search-path fingerprint, pinned Node 24.18.0 and locked SDK. +- Three paired fresh-process trials per digest-pinned shipped module, serial + on one CPU: control/candidate, candidate/control, control/candidate. +- Same validation/counts/first-four complete export forms/WAT identity/provider + identity/execution and fetch states; complete original source Evidence ID is + also compared. All nine pairs preserve these selected facts and source IDs. + +| Shipped module | Result JSON bytes, control → summary | Calls / errors | Median seconds, control → summary (ranges) | +| ----------------------------- | -----------------------------------: | -------------- | ----------------------------------------------- | +| `sqlite.wasm` | 20,118 → 18,533 | 3/1 → 2/0 | 15.962 (15.719–21.138) → 18.171 (10.242–18.649) | +| `vscode.tree-sitter-css.wasm` | 20,366 → 18,781 | 3/1 → 2/0 | 4.920 (4.885–4.936) → 5.191 (4.971–5.232) | +| `vscode.tree-sitter.wasm` | 6,433,872 → 18,891 | 1/0 → 2/0 | 5.225 (5.172–5.519) → 4.763 (4.729–4.830) | + +Byte counts include all investigation call results, including failed delivery +and extra views. They exclude catalog responses, raw wire framing and file +exports; they are not actual model tokens. The complete catalog is 2,359,082 +versus 2,362,451 JSON bytes (+3,369 bytes, about 0.14%). An extra export-view +call is included when summary replaces an otherwise fitting complete reply. + +| Shipped module | Median owned CPU seconds, control → summary | Median sampled family MiB, control → summary (maxima) | +| ----------------------------- | ------------------------------------------- | ----------------------------------------------------- | +| `sqlite.wasm` | 15.376 → 15.954 | 660.84 (671.27) → 633.07 (671.51) | +| `vscode.tree-sitter-css.wasm` | 5.760 → 6.027 | 692.91 (694.93) → 678.98 (693.88) | +| `vscode.tree-sitter.wasm` | 6.134 → 5.663 | 674.04 (695.66) → 550.66 (553.47) | + +All 18 scopes have no sampled abort and their last observations contain no +memory-high/hard/OOM/OOM-kill or task-limit event. Final counters are unverified +under the subsequent closeout audit below. Sampling can miss brief peaks. Application caches are cold per process; +host page caches are not flushed. SDK elapsed time includes startup, discovery, +schema work and persistence, not just provider analysis. Three observations +give descriptive medians/ranges, not a statistical or cross-domain speed claim. + +SQLite and the CSS grammar already recovered an oversized complete result +through retained views in the control. The new path removes the initial error +and one call; result-byte savings are correspondingly modest. The Tree-sitter +runtime fits the MCP frame but delivers megabytes of unneeded WAT; its summary +plus exact exports greatly reduces delivery. Full provider analysis and complete +Evidence retention still occur, so this does not establish an engine shortcut. + +An earlier 18-run cohort did not activate the treatment: the driver looked +for an inline enum and missed SDK-generated `$ref` definitions. Those original +runs and their source are archived separately and excluded from benefit claims. +The corrected driver validates the actual advertised 2020-12 request schema. + +## Real model verification + +Ten actual Codex CLI 0.161.0 trials request `gpt-5.6-terra` high: three paired +SQLite repetitions and one pair for each published VS Code component. The +resolved server-side model identity is not inferred from the requested alias. +Same question, fixed developer instructions, four allowlisted REA tools and +explicit WABT settings; private profiles, shell/web/other-agent restrictions +and target-byte preservation remain verified. + +All ten answers match the 12 requested producer facts, including exact export +forms and explicit execution/fetch states. Reported Evidence IDs occur in real +responses; all copied profiles are removed. Manual review retains static-analysis +limitations and makes no original-source/runtime claim. Every candidate chooses +`detail: summary` on its first inspection and then reads exports without WABT +rerun. Original control errors and client-context clipping remain in transcripts. + +| Module / observations per side | Total input, control → summary | Cached input | Uncached input | Output | +| --------------------------------- | -----------------------------: | ----------------: | --------------: | ------------: | +| `sqlite.wasm` / 3 | 96,832 → 79,264 | 70,656 → 51,456 | 26,215 → 28,004 | 1,470 → 1,512 | +| `vscode.tree-sitter-css.wasm` / 1 | 247,889 → 79,389 | 207,872 → 61,440 | 40,017 → 17,949 | 1,931 → 1,327 | +| `vscode.tree-sitter.wasm` / 1 | 556,424 → 282,165 | 478,208 → 239,360 | 78,216 → 42,805 | 2,560 → 2,110 | + +SQLite rows show medians of three observations; VS Code rows are single pairs. +Usage is the CLI-reported total for the turn, with cached/uncached input listed +separately. Lower total input does not imply a proportional monetary saving, +uncached-input reduction or faster answer. + +| Module | Calls / observed errors, control → summary | Seconds, control → summary | +| ----------------------------- | ------------------------------------------ | ----------------------------------------------- | +| `sqlite.wasm` | 3/1 → 2/0 | 61.521 (54.301–80.579) → 55.656 (42.960–62.145) | +| `vscode.tree-sitter-css.wasm` | 3/1 → 2/0 | 87.126 → 106.580 | +| `vscode.tree-sitter.wasm` | 4/0 → 2/0 | 56.952 → 104.999 | + +SQLite total input falls about 18% and median answer time about 10%, while +its median uncached input rises about 7%. The two VS Code pairs reduce total +input by about 49% and 68%, but observed answer time rises about 84% and 22%. +These data support optional smaller delivery; they do not establish uniform +model speedup. The runtime control also makes one protocol resource-discovery +call, included in the four-call count. Cache state, model reasoning and service +latency are not separated by this small sample. + +The model and SDK cohorts ran with the original resource wrapper. Their final +receipts retain last-sampled cgroup counters, not verified final counters. +The subsequent closeout correction regrades all ten existing answers: selected +facts, real IDs, unchanged target bytes and profile cleanup still pass, while +the final resource conditions are **unverified**. No model/build/provider run +was repeated for that review-only correction. Last-sampled peaks are 656–944 +MiB for model scopes with no observed limit events; one CPU, 4 GiB hard ceiling, +3 GiB early-stop and no-swap controls were active. This is not a proof of absent +late resource events or a fully resource-qualified performance conclusion. +The original transcripts/usage and regrades remain archived separately. + +## Reproduction and verification + +Use [the common measurement/model instructions](README.md) with the public +digest-pinned inputs in [corpus.json](corpus.json), `--schemas selected` and +`--delivery summary`. For each artifact run the above three paired orders +against separately frozen runtimes, then `compare.mjs`. Use the same +[WASM interface question](questions/wasm-interface.txt), four exact enabled +tools (`inspect_wasm_artifact`, `inspect_analysis_view`, `get_evidence_bundle`, +`export_evidence_bundle`), explicit WABT settings and resource scope for models. + +The VS Code artifacts are two published components from +[@vscode/tree-sitter-wasm 0.3.1](https://github.com/microsoft/vscode-tree-sitter-wasm). +The selected regular archive members have verified digests and package SHA-512 +integrity. This is component analysis, not proof of the whole VS Code runtime. + +The prototype passes 54 focused assertions and full static/docs gates. After +rebasing, 29 focused assertions and 42 actual installed-package WABT CLI/MCP +cases pass; the final rebased snapshot passes build/fast static and seven WASM +MCP workflows again. Omitted/explicit-complete behavior, retained identity, +fixed-server absence of retention, oversized continuation and invalid WAT +digest remain checked. No version publication or target execution occurs. +The final static/build scope has 51 soft memory-high events and no hard/OOM +events; this is not credited as a performance trial. + +Detailed JSON, transcripts, target bytes, profiles and acquisition receipts +stay outside Git. Source inputs, scripts and this concise measured scope are +reviewable in the repository. + +## Main integration checkpoint + +Prerequisite #2122 is merged at `58fb372071e56da9c5df0e37593ee3f0da6b64bc`. +The follow-up is rebased directly onto latest fetched main. Intervening changes +outside the prerequisite concern CLI/logging/CI planning rather than WASM +production/delivery. Seven focused WASM MCP workflows and one fresh real-WABT +SQLite public-SDK request pass against the new build: selected facts and original +source ID match the pinned candidate, summary uses two calls with no tool error. +Only the relevant integration checks and required pre-push gate are repeated; +earlier measurements retain their original runtimes, not the new main label. diff --git a/src/contracts/wasm/wasmToolContracts.ts b/src/contracts/wasm/wasmToolContracts.ts index 901dd7ded..34f26f11d 100644 --- a/src/contracts/wasm/wasmToolContracts.ts +++ b/src/contracts/wasm/wasmToolContracts.ts @@ -4,16 +4,29 @@ import { } from "../../domain/wasm/wasmArtifact.js"; import type { ToolContract } from "../toolContractTypes.js"; import { toolContractMetadata } from "../toolEffects.js"; -import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js"; +import { + analysisDetailSchema, + analysisDetailOutputSchemaOf, +} from "../analysisDetail.js"; +import { wasmArtifactSummaryViewResultSchema } from "../../domain/analysisView/analysisView.js"; + +/** Delivery selection does not change the provider input or original Evidence. */ +export const wasmArtifactInspectionInputSchema = + inspectWasmArtifactInputSchema.extend({ + detail: analysisDetailSchema.unwrap().optional(), + }); /** Optional caller-supplied WABT capability with target-free CLI/MCP parity. */ export const INSPECT_WASM_ARTIFACT_CONTRACT = { name: "inspect_wasm_artifact", ...toolContractMetadata("inspect_wasm_artifact"), kind: "artifact-provider", description: - "Validate an explicit local WASM artifact with caller-supplied WABT 1.0.42, retain exact byte SHA-256, sections, upstream import/export WAT forms and decoded WAT inline as Evidence. Optionally associate selected JavaScript glue literals with explicit local candidates while preserving ambiguous URL/basename matches. Configure absolute REA_WABT_BIN_DIRECTORY. No installation, implicit fetch, WASM execution or original-source claim.", - inputSchema: inspectWasmArtifactInputSchema, - outputSchema: evidenceResultOf(wasmArtifactSchema), + 'Validate an explicit local WASM artifact with caller-supplied WABT 1.0.42. Omitted or complete detail returns exact byte SHA-256, sections, upstream import/export WAT forms and decoded WAT inline as Evidence. For counts, validation and WAT identity without WAT text, pass detail: "summary" on this first call; it retains the complete original Evidence and returns the same typed summary as inspect_analysis_view, avoiding oversized complete delivery. Read exact imports/exports or WAT pages with inspect_analysis_view using normalized_result.parent_evidence_id. Delivery selection does not change analysis, provider inputs or source identity. Optionally associate selected JavaScript glue literals with explicit local candidates while preserving ambiguous URL/basename matches. Configure absolute REA_WABT_BIN_DIRECTORY. No installation, implicit fetch, WASM execution or original-source claim.', + inputSchema: wasmArtifactInspectionInputSchema, + outputSchema: analysisDetailOutputSchemaOf( + wasmArtifactSchema, + wasmArtifactSummaryViewResultSchema, + ), examples: [ { title: "Inspect a selected local WASM module", diff --git a/src/domain/analysisView/analysisView.ts b/src/domain/analysisView/analysisView.ts index ce0b55946..539557877 100644 --- a/src/domain/analysisView/analysisView.ts +++ b/src/domain/analysisView/analysisView.ts @@ -302,6 +302,13 @@ export const artifactInventorySummaryViewResultSchema = z.strictObject({ summary: inventorySummarySchema, }); +/** Exact summary carrier for WASM inspection's optional delivery contract. */ +export const wasmArtifactSummaryViewResultSchema = z.strictObject({ + ...summaryViewResultBase, + parent_operation: z.literal("inspect_wasm_artifact"), + summary: wasmSummarySchema, +}); + /** Projected facts for one selected view of retained analysis Evidence. */ export const analysisViewResultSchema = z.discriminatedUnion("kind", [ z.strictObject({ diff --git a/src/server/createServer.ts b/src/server/createServer.ts index 3220fe8e7..742511ffc 100644 --- a/src/server/createServer.ts +++ b/src/server/createServer.ts @@ -453,6 +453,7 @@ const registerConfiguredAnalysisTools = ( toolLogger, recordEvidence, withAdmittedAnalysis, + evidenceById, ); registerEvmTools( server, diff --git a/src/server/registerWasmTools.ts b/src/server/registerWasmTools.ts index 9c0bd7699..494972b2f 100644 --- a/src/server/registerWasmTools.ts +++ b/src/server/registerWasmTools.ts @@ -2,6 +2,10 @@ import type { EvidenceMcpServer } from "./EvidenceMcpServer.js"; import type { WasmArtifactService } from "../application/wasm/WasmArtifactService.js"; import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js"; +import type { EvidenceLookup } from "../application/EvidenceInputResolver.js"; +import { summarizeRetainedAnalysis } from "../application/analysisView/AnalysisViewService.js"; +import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js"; +import { err } from "../domain/result.js"; import { wasmArtifactModule } from "../composition/wasm.js"; import type { Logger } from "pino"; import { createEvidenceToolHandler } from "./contractToolHandler.js"; @@ -15,11 +19,31 @@ export const registerWasmTools = ( logger: Logger, recordEvidence?: EvidenceWriter["recordEvidence"], withAdmittedAnalysis?: WithAdmittedAnalysis, + evidenceById?: EvidenceLookup, ): void => { const contract = wasmArtifactModule.contract; const handler = createEvidenceToolHandler( server, - (input, options) => service.inspect(input, options), + async (rawInput, options) => { + const parsed = contract.inputSchema.safeParse(rawInput); + if (!parsed.success) + return err( + analysisInputErrorFromIssues( + contract.name, + parsed.error.issues, + rawInput, + { cause: parsed.error }, + ), + ); + const { detail, ...input } = parsed.data; + const inspected = await service.inspect(input, options); + return detail === "summary" && inspected.ok + ? summarizeRetainedAnalysis(inspected.value, { + recordEvidence, + evidenceById, + }) + : inspected; + }, logger, recordEvidence, withAdmittedAnalysis, diff --git a/tests/boundary/mcp/wasmArtifactMcp.test.ts b/tests/boundary/mcp/wasmArtifactMcp.test.ts index ce42e9b9c..49c7ad762 100644 --- a/tests/boundary/mcp/wasmArtifactMcp.test.ts +++ b/tests/boundary/mcp/wasmArtifactMcp.test.ts @@ -6,6 +6,7 @@ import { join } from "node:path"; import { WasmArtifactService } from "../../../src/application/wasm/WasmArtifactService.js"; import { toolContract } from "../../../src/contracts/toolContracts.js"; import { createEvidence, parseEvidence } from "../../../src/domain/evidence.js"; +import { wasmArtifactSummaryViewResultSchema } from "../../../src/domain/analysisView/analysisView.js"; import { createHash } from "node:crypto"; import { z } from "zod"; import { createServer } from "../../../src/server/createServer.js"; @@ -33,6 +34,63 @@ const wasmToolSchemas = async (client: Client) => { return { name: advertised.name, ajv, inputSchema, outputSchema }; }; +const assertFirstSummaryDelivery = async ( + harness: Awaited>, + value: ReturnType, + inspect: WasmArtifactService["provider"]["inspect"], +) => { + const { + ajv: wasmAjv, + inputSchema, + outputSchema, + } = await wasmToolSchemas(harness.client); + const summaryInput = { path: value.artifact.path, detail: "summary" }; + expect(wasmAjv.validate(inputSchema, summaryInput)).toBe(true); + expect( + wasmAjv.validate(inputSchema, { ...summaryInput, detail: "brief" }), + ).toBe(false); + const directSummary = await harness.client.callTool({ + name: "inspect_wasm_artifact", + arguments: summaryInput, + }); + expect(directSummary.isError).not.toBe(true); + expect( + wasmAjv.validate(outputSchema, directSummary.structuredContent), + JSON.stringify(wasmAjv.errors), + ).toBe(true); + const summaryEvidence = parseEvidence(directSummary.structuredContent); + const summary = wasmArtifactSummaryViewResultSchema.parse( + summaryEvidence.normalized_result, + ); + expect(summaryEvidence.confidence).toBe("derived"); + expect(summaryEvidence.evidence_links).toEqual([summary.parent_evidence_id]); + expect(summary.summary.wat).toMatchObject({ + sha256: value.wat.sha256, + code_units: value.wat.text.length, + }); + expect(summary.summary.wat).not.toHaveProperty("text"); + const retained = harness.session.evidenceById(summary.parent_evidence_id); + if (retained === undefined) throw new Error("Summary lost original Evidence"); + expect(retained.normalized_result).toEqual(value); + expect(retained.parameters).toEqual({ + path: value.artifact.path, + glue_paths: [], + candidate_paths: [], + }); + expect(inspect).toHaveBeenCalledTimes(1); + expect(inspect).toHaveBeenLastCalledWith( + retained.parameters, + expect.objectContaining({ signal: expect.any(AbortSignal) }), + ); + expect( + wasmAjv.validate(outputSchema, { + ...summaryEvidence, + normalized_result: { ...summary, parent_operation: "inventory_artifact" }, + }), + ).toBe(false); + return { summary, retained }; +}; + it("directs rejected native WASM opening to the advertised static tool while preserving missing-WABT diagnostics", async () => { const directory = await createTestTempDirectory("rea-wasm-recovery-"); const path = join( @@ -84,6 +142,16 @@ it("directs rejected native WASM opening to the advertised static tool while pre }, }, }); + const summary = await client.callTool({ + name, + arguments: { ...input, detail: "summary" }, + }); + expect(parseMcpToolError(summary)).toMatchObject({ + error: { + code: "capability_unavailable", + details: { reason: expect.stringContaining("REA_WABT_BIN_DIRECTORY") }, + }, + }); await client.ping(); expect(createClient).not.toHaveBeenCalled(); expect(await readFile(path)).toEqual( @@ -157,14 +225,22 @@ it("reads an oversized completed WASM result through its reported retained refer representation: "decoded-wat" as const, }, }; + const inspect = vi.fn(() => + Promise.resolve(ok(wasmArtifactExecution(value))), + ); const service = new WasmArtifactService({ close: () => Promise.resolve(), - inspect: () => Promise.resolve(ok(wasmArtifactExecution(value))), + inspect, }); const harness = await createApplicationMcpHarness({ serverOptions: { wasmArtifact: service }, }); onTestFinished(harness.close); + const { summary, retained } = await assertFirstSummaryDelivery( + harness, + value, + inspect, + ); const reply = await harness.client.callTool({ name: "inspect_wasm_artifact", arguments: { path: value.artifact.path }, @@ -182,6 +258,17 @@ it("reads an oversized completed WASM result through its reported retained refer }) .parse(parseMcpToolError(reply).error).details .reported_limits.evidence_reference; + expect(reference.evidence_id).toBe(summary.parent_evidence_id); + const explicitComplete = await harness.client.callTool({ + name: "inspect_wasm_artifact", + arguments: { path: value.artifact.path, detail: "complete" }, + }); + expect(parseMcpToolError(explicitComplete)).toMatchObject({ + error: { + code: "resource_constraint", + details: { reported_limits: { evidence_reference: reference } }, + }, + }); const catalog = await harness.client.listTools(); const advertised = catalog.tools.find( (tool) => tool.name === "inspect_analysis_view", @@ -244,6 +331,17 @@ it("reads an oversized completed WASM result through its reported retained refer } const original = harness.session.evidenceById(reference.evidence_id); expect(original?.normalized_result).toEqual(value); + expect(original).toEqual(retained); + expect(inspect).toHaveBeenCalledTimes(3); + await harness.client.ping(); +}); + +it("rejects inconsistent decoded-WAT digests in portable Evidence without a provider run", async () => { + const value = wasmArtifactFixture(); + const harness = await createApplicationMcpHarness({ + serverOptions: { environment: {} }, + }); + onTestFinished(harness.close); const inconsistent = createEvidence( { path: value.artifact.path, @@ -325,6 +423,50 @@ it("rejects absent or inconsistent WASM source identity before deriving portable await harness.client.ping(); }); +it("requires retention for WASM summary delivery while keeping fixed-server complete delivery", async () => { + const value = wasmArtifactFixture(); + const service = new WasmArtifactService({ + close: () => Promise.resolve(), + inspect: () => Promise.resolve(ok(wasmArtifactExecution(value))), + }); + const session = createTestBinarySession(() => { + throw new Error("No deep provider"); + }); + const server = createServer( + { kind: "fixed", analysis: session }, + { wasmArtifact: service }, + ); + const client = new Client({ name: "wasm-fixed-delivery", version: "1" }); + const [a, b] = InMemoryTransport.createLinkedPair(); + try { + await server.connect(b); + await client.connect(a); + const summary = await client.callTool({ + name: "inspect_wasm_artifact", + arguments: { path: value.artifact.path, detail: "summary" }, + }); + expect(parseMcpToolError(summary)).toMatchObject({ + error: { + code: "capability_unavailable", + message: expect.stringContaining("does not retain Evidence"), + }, + }); + const complete = await client.callTool({ + name: "inspect_wasm_artifact", + arguments: { path: value.artifact.path }, + }); + expect(complete.isError).not.toBe(true); + expect(parseEvidence(complete.structuredContent).normalized_result).toEqual( + value, + ); + await client.ping(); + } finally { + await client.close(); + await server.close(); + await session.close(); + } +}); + it("retries cleanup of the injected WASM module after server shutdown fails", async () => { const close = vi .fn() From 4a4ae9b2b9712f7ac16f2d23c71b5c29b0c23d2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Gon=C3=A7alves=20Araujo?= <47118053+dandgabr@users.noreply.github.com> Date: Mon, 12 Oct 2026 11:01:58 -0300 Subject: [PATCH 7/8] feat: add Frida instrumentation support (#1359) * feat: add Frida instrumentation support * fix: resolve Frida CI checks * test: cover Frida contract validation branches * docs: link Frida instrumentation guide * fix(frida): handle cancellation cleanup safely * fix(frida): address PR review findings * fix(frida): preserve resume and message observations * fix(ci): use canonical registry for rolldown * fix(frida): declare foreign code effects * fix(frida): retain failed startup resources for cleanup retries Keep failed startup session and spawn handles owned until detach, resume, and remote lease cleanup complete. Serialize retries and release each remote reference once. Await CLI provider cleanup while preserving the primary failure and any completed observations. Add regressions for retained startup resources, concurrent cleanup, shared remote leases, and CLI cleanup outcomes. Validation: 41 focused tests pass on the PR head and its latest-main integration; serial static and docs checks pass. Real Linux Frida 17.23.2 workflows and the native spawn/controlled-failure cleanup probe pass. Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing) --------- Co-authored-by: N0zoM1z0 <1705004398@qq.com> --- docs/frida-instrumentation.md | 13 + docs/index.md | 2 + docs/testing.md | 12 + knip.json | 1 + package-lock.json | 450 ++++-- package.json | 8 + scripts/lib/catalog-builders.mjs | 9 + scripts/lib/catalog-core.mjs | 2 + scripts/verify-frida.mjs | 198 +++ scripts/verify/fridaBindingsCompatibility.ts | 28 + src/application/CapabilityInventory.ts | 6 + .../OptionalObservationProviders.ts | 5 +- .../frida/FridaInstrumentationManager.test.ts | 988 +++++++++++++ .../frida/FridaInstrumentationPort.ts | 117 ++ .../frida/FridaInstrumentationService.test.ts | 508 +++++++ .../frida/FridaInstrumentationService.ts | 400 ++++++ src/cli.ts | 4 + src/cli/fridaCommands.ts | 275 ++++ src/cliCommandNames.ts | 12 + src/contracts/fridaRemoteAddress.ts | 21 + src/contracts/fridaToolContracts.test.ts | 170 +++ src/contracts/fridaToolContracts.ts | 327 +++++ src/contracts/toolContractExamples.ts | 23 + src/contracts/toolContracts.ts | 2 + src/contracts/toolEffects.test.ts | 5 + src/contracts/toolEffects.ts | 51 + src/frida/FridaInstrumentationManager.ts | 1230 +++++++++++++++++ src/frida/frida-bindings.d.ts | 78 ++ src/server/createServer.ts | 35 +- src/server/registerFridaTools.ts | 342 +++++ tests/boundary/cli/fridaCli.test.ts | 236 ++++ .../filesystem/productCatalog.test.ts | 9 + tests/boundary/mcp/fridaMcp.test.ts | 415 ++++++ tsconfig.frida-verification.json | 11 + 34 files changed, 5845 insertions(+), 148 deletions(-) create mode 100644 docs/frida-instrumentation.md create mode 100644 scripts/verify-frida.mjs create mode 100644 scripts/verify/fridaBindingsCompatibility.ts create mode 100644 src/application/frida/FridaInstrumentationManager.test.ts create mode 100644 src/application/frida/FridaInstrumentationPort.ts create mode 100644 src/application/frida/FridaInstrumentationService.test.ts create mode 100644 src/application/frida/FridaInstrumentationService.ts create mode 100644 src/cli/fridaCommands.ts create mode 100644 src/contracts/fridaRemoteAddress.ts create mode 100644 src/contracts/fridaToolContracts.test.ts create mode 100644 src/contracts/fridaToolContracts.ts create mode 100644 src/frida/FridaInstrumentationManager.ts create mode 100644 src/frida/frida-bindings.d.ts create mode 100644 src/server/registerFridaTools.ts create mode 100644 tests/boundary/cli/fridaCli.test.ts create mode 100644 tests/boundary/mcp/fridaMcp.test.ts create mode 100644 tsconfig.frida-verification.json diff --git a/docs/frida-instrumentation.md b/docs/frida-instrumentation.md new file mode 100644 index 000000000..c93c76465 --- /dev/null +++ b/docs/frida-instrumentation.md @@ -0,0 +1,13 @@ +# Frida instrumentation + +REA exposes Frida device and process discovery, attach or spawn sessions, and caller-authored JavaScript instrumentation through the CLI and MCP. The Node bindings are an optional package dependency and load only when a Frida operation runs. REA does not install Frida server on a target. + +For remote devices, pass a host with an optional port (`host[:port]`; bracket IPv6 addresses) and any token, certificate, origin, or keepalive options on that operation. The keepalive interval is measured in seconds, matching Frida Core 17.23.2. Authentication values are held only for the active call or session and are excluded from Evidence. Do not embed credentials in the endpoint address. + +MCP exposes `list_frida_devices`, `list_frida_processes`, `start_frida_session`, `load_frida_script`, `resume_frida_session`, `unload_frida_script`, `frida_session_status`, and `close_frida_session`. A spawned process starts paused so scripts can load first. Closing unloads session scripts and detaches. If a spawn remains paused, REA resumes it only after script cleanup or session detach confirms the instrumentation is released; if both cleanup paths fail, the target stays paused and the cleanup error is retained. REA never kills the target. MCP sessions end with the server process. The one-shot CLI command `instrument-with-frida` accepts one inline script or script file, observes messages for a bounded duration, and returns Evidence with the source hash and captured messages. + +Failed startup cleanup retains acquired Frida handles, including a paused spawn that has not attached, for later cleanup retries. Its remote connection stays leased until session detach and target resume complete. CLI commands await provider cleanup before returning; MCP retains these resources for cleanup when its server closes. A failed cleanup remains reported rather than treating an unregistered session as fully released. + +Frida scripts execute inside the selected target with that process's memory, filesystem, and network authority. Message capture is bounded to 16 MiB and reports truncation. Script source is not stored in Evidence; its selected path and SHA-256 digest are. Evidence retains non-authentication target selection such as device or endpoint, mode, program or PID, and spawn arguments. Authentication values remain excluded. Results report the observed session and messages, while unsupported platform metadata remains unknown. A request cancelled before a Frida operation starts has no provider effects. If cancellation arrives during a native Frida call, REA waits for that call to return, then closes any session it created and returns the observed session as a partial observation. Cancellation Evidence separately reports whether a target resume was observed, whether instrumentation cleanup completed, and that final target liveness remains unknown. REA does not kill the target. Remote discovery retains its observations and reports a separate cleanup error if the temporary connection cannot be removed. + +The [Frida Core API](https://frida.re/docs/frida-core-api/) documents device management, sessions, and script loading; the [JavaScript API](https://frida.re/docs/javascript-api/) documents target-side instrumentation. [Luma](https://luma.frida.re/) is Frida's standalone GUI; REA does not automate or control it. `npm run verify:frida` requires a Linux host with the optional Frida binding and uses a short-lived local Node.js fixture created by the verifier. Add `-- --address HOST:PORT --pid PID` to run the separate remote attach lane against a caller-selected target. Mock tests do not establish real device/server compatibility. diff --git a/docs/index.md b/docs/index.md index 42ae8f680..17fed2a95 100644 --- a/docs/index.md +++ b/docs/index.md @@ -43,4 +43,6 @@ npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app -- See [installation and setup](./installation.md) for requirements and configuration. +For runtime instrumentation, see the [Frida guide](./frida-instrumentation.md). + ![REA inspecting a native binary in Hopper](./assets/rea-hopper-analysis.png) diff --git a/docs/testing.md b/docs/testing.md index 9aaeb8464..5df9c4d9e 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1414,6 +1414,18 @@ npm run evidence:check The records preserve unsupported and unverified coverage as explicit unknowns. Run the matching real-tool prerequisites described in this guide. +## Frida instrumentation + +`npm run verify:frida` builds REA, spawns a short-lived local Node.js fixture, +loads a harmless marker script before resuming it, captures the message, and +detaches. This lane requires Linux on the REA host and the optional Frida +binding; it does not need a Frida server or a caller-selected process. To run +the separate remote attach lane, pass `-- --address HOST:PORT --pid PID` for an +explicitly selected process. Optional remote flags are `--token`, +`--certificate`, `--origin`, and `--keepalive-interval` (seconds); authentication values +are not written to files or included in the report. Mock tests do not establish +real device/server compatibility. + ### Offline WASM artifacts `npm run verify:wasm:artifact -- --require-tools` uses an absolute diff --git a/knip.json b/knip.json index 8d38b4ef1..72d093397 100644 --- a/knip.json +++ b/knip.json @@ -7,6 +7,7 @@ "src/contracts/errorSchemas.ts", "src/evaluation/AgentEvaluationFixtures.ts", "src/application/RealHopperAssertions.ts", + "scripts/verify/fridaBindingsCompatibility.ts", "scripts/verify/termux/browser.mjs", "scripts/verify-real-ghidra-noreturn.mjs", "tests/processOwnershipRunner.ts" diff --git a/package-lock.json b/package-lock.json index de9c141f5..749f4614f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -73,6 +73,9 @@ }, "engines": { "node": "^22.19.0 || ^24.11.0 || >=26.0.0" + }, + "optionalDependencies": { + "frida": "17.23.2" } }, "node_modules/@algolia/abtesting": { @@ -742,9 +745,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -903,9 +903,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -923,9 +920,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -943,9 +937,6 @@ "ppc64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -963,9 +954,6 @@ "riscv64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -983,9 +971,6 @@ "riscv64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1003,9 +988,6 @@ "s390x" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1023,9 +1005,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1043,9 +1022,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1239,9 +1215,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1256,9 +1229,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1273,9 +1243,6 @@ "ppc64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1290,9 +1257,6 @@ "riscv64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1307,9 +1271,6 @@ "riscv64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1324,9 +1285,6 @@ "s390x" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1341,9 +1299,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1358,9 +1313,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1878,9 +1830,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1898,9 +1847,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1918,9 +1864,6 @@ "ppc64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1938,9 +1881,6 @@ "riscv64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1958,9 +1898,6 @@ "riscv64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1978,9 +1915,6 @@ "s390x" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1998,9 +1932,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -2018,9 +1949,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -2214,9 +2142,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -2234,9 +2159,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -2254,9 +2176,6 @@ "ppc64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -2274,9 +2193,6 @@ "s390x" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -2294,9 +2210,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -2314,9 +2227,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -2476,9 +2386,6 @@ "arm" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -2493,9 +2400,6 @@ "arm" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -2510,9 +2414,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -2527,9 +2428,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -2544,9 +2442,6 @@ "loong64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -2561,9 +2456,6 @@ "loong64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -2578,9 +2470,6 @@ "ppc64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -2595,9 +2484,6 @@ "ppc64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -2612,9 +2498,6 @@ "riscv64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -2629,9 +2512,6 @@ "riscv64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -2646,9 +2526,6 @@ "s390x" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -2663,9 +2540,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -2680,9 +2554,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -4142,6 +4013,16 @@ ], "license": "MIT" }, + "node_modules/bindings": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/bindings/-/bindings-1.5.0.tgz", + "integrity": "sha512-p2q/t/mhvuOj/UeLlV6566GD/guowlr0hHxClI0W9m7MWYkL1F0hLo+0Aexs9HSPCtR1SXQ0TD3MMKrXZajbiQ==", + "license": "MIT", + "optional": true, + "dependencies": { + "file-uri-to-path": "1.0.0" + } + }, "node_modules/birpc": { "version": "2.9.0", "resolved": "https://registry.npmjs.org/birpc/-/birpc-2.9.0.tgz", @@ -4152,6 +4033,58 @@ "url": "https://github.com/sponsors/antfu" } }, + "node_modules/bl": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/bl/-/bl-4.1.0.tgz", + "integrity": "sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w==", + "license": "MIT", + "optional": true, + "dependencies": { + "buffer": "^5.5.0", + "inherits": "^2.0.4", + "readable-stream": "^3.4.0" + } + }, + "node_modules/bl/node_modules/buffer": { + "version": "5.7.1", + "resolved": "https://registry.npmjs.org/buffer/-/buffer-5.7.1.tgz", + "integrity": "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT", + "optional": true, + "dependencies": { + "base64-js": "^1.3.1", + "ieee754": "^1.1.13" + } + }, + "node_modules/bl/node_modules/readable-stream": { + "version": "3.6.2", + "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz", + "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==", + "license": "MIT", + "optional": true, + "dependencies": { + "inherits": "^2.0.3", + "string_decoder": "^1.1.1", + "util-deprecate": "^1.0.1" + }, + "engines": { + "node": ">= 6" + } + }, "node_modules/brace-expansion": { "version": "5.0.12", "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.12.tgz", @@ -4290,6 +4223,13 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/chownr": { + "version": "1.1.4", + "resolved": "https://registry.npmjs.org/chownr/-/chownr-1.1.4.tgz", + "integrity": "sha512-jJ0bqzaylmJtVnNgzTeSOs8DPavpbYgEr/b0YL8/2GO3xJEhInFmhKMUnEJQjZumK7KXGFhUy89PrsJWlakBVg==", + "license": "ISC", + "optional": true + }, "node_modules/clean-git-ref": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/clean-git-ref/-/clean-git-ref-2.0.1.tgz", @@ -4418,6 +4358,16 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/deep-extend": { + "version": "0.6.0", + "resolved": "https://registry.npmjs.org/deep-extend/-/deep-extend-0.6.0.tgz", + "integrity": "sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA==", + "license": "MIT", + "optional": true, + "engines": { + "node": ">=4.0.0" + } + }, "node_modules/define-data-property": { "version": "1.1.4", "resolved": "https://registry.npmjs.org/define-data-property/-/define-data-property-1.1.4.tgz", @@ -4449,9 +4399,8 @@ "version": "2.1.2", "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz", "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==", - "dev": true, + "devOptional": true, "license": "Apache-2.0", - "peer": true, "engines": { "node": ">=8" } @@ -4513,6 +4462,16 @@ "dev": true, "license": "MIT" }, + "node_modules/end-of-stream": { + "version": "1.4.5", + "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz", + "integrity": "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==", + "license": "MIT", + "optional": true, + "dependencies": { + "once": "^1.4.0" + } + }, "node_modules/entities": { "version": "7.0.1", "resolved": "https://registry.npmjs.org/entities/-/entities-7.0.1.tgz", @@ -4644,6 +4603,16 @@ "node": ">=22" } }, + "node_modules/expand-template": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/expand-template/-/expand-template-2.0.3.tgz", + "integrity": "sha512-XYfuKMvj4O35f/pOXLObndIRvyQ+/+6AhODh+OKWj9S9498pHHn/IMszH+gt0fBCRWMNfk1ZSp5x3AifmnI2vg==", + "license": "(MIT OR WTFPL)", + "optional": true, + "engines": { + "node": ">=6" + } + }, "node_modules/expect-type": { "version": "1.4.0", "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.4.0.tgz", @@ -4751,6 +4720,13 @@ } } }, + "node_modules/file-uri-to-path": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/file-uri-to-path/-/file-uri-to-path-1.0.0.tgz", + "integrity": "sha512-0Zt+s3L7Vf1biwWZ29aARiVYLx7iMGnEUl9x33fbB/j3jR81u/O2LbqK+Bm1CDSNDKVtJ/YjwY7TUd5SkeLQLw==", + "license": "MIT", + "optional": true + }, "node_modules/focus-trap": { "version": "7.8.0", "resolved": "https://registry.npmjs.org/focus-trap/-/focus-trap-7.8.0.tgz", @@ -4793,6 +4769,29 @@ "node": ">=18.3.0" } }, + "node_modules/frida": { + "version": "17.23.2", + "resolved": "https://registry.npmjs.org/frida/-/frida-17.23.2.tgz", + "integrity": "sha512-gRCmmTUFdEILyHRN1b66erRoXafwsfWTqXyoBBqkSCFX0Ue7Jhvs/KhA3JO0XrgITNlPd91QAGsFvWzh0mhVgg==", + "hasInstallScript": true, + "license": "LGPL-2.0 WITH WxWindows-exception-3.1", + "optional": true, + "dependencies": { + "bindings": "^1.5.0", + "minimatch": "^10.0.1", + "prebuild-install": "^7.1.3" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/fs-constants": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/fs-constants/-/fs-constants-1.0.0.tgz", + "integrity": "sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow==", + "license": "MIT", + "optional": true + }, "node_modules/fsevents": { "version": "2.3.3", "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz", @@ -4880,6 +4879,13 @@ "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1" } }, + "node_modules/github-from-package": { + "version": "0.0.0", + "resolved": "https://registry.npmjs.org/github-from-package/-/github-from-package-0.0.0.tgz", + "integrity": "sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw==", + "license": "MIT", + "optional": true + }, "node_modules/glob": { "version": "13.0.6", "resolved": "https://registry.npmjs.org/glob/-/glob-13.0.6.tgz", @@ -5119,6 +5125,13 @@ "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", "license": "ISC" }, + "node_modules/ini": { + "version": "1.3.8", + "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz", + "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==", + "license": "ISC", + "optional": true + }, "node_modules/is-callable": { "version": "1.2.7", "resolved": "https://registry.npmjs.org/is-callable/-/is-callable-1.2.7.tgz", @@ -5555,9 +5568,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MPL-2.0", "optional": true, "os": [ @@ -5580,9 +5590,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MPL-2.0", "optional": true, "os": [ @@ -5605,9 +5612,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MPL-2.0", "optional": true, "os": [ @@ -5630,9 +5634,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MPL-2.0", "optional": true, "os": [ @@ -6070,6 +6071,13 @@ "dev": true, "license": "MIT" }, + "node_modules/mkdirp-classic": { + "version": "0.5.3", + "resolved": "https://registry.npmjs.org/mkdirp-classic/-/mkdirp-classic-0.5.3.tgz", + "integrity": "sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A==", + "license": "MIT", + "optional": true + }, "node_modules/nanoid": { "version": "3.3.20", "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.20.tgz", @@ -6089,6 +6097,26 @@ "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1" } }, + "node_modules/napi-build-utils": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/napi-build-utils/-/napi-build-utils-2.0.0.tgz", + "integrity": "sha512-GEbrYkbfF7MoNaoh2iGG84Mnf/WZfB0GdGEsM8wz7Expx/LlWf5U8t9nvJKXSp3qr5IsEbK04cBGhol/KwOsWA==", + "license": "MIT", + "optional": true + }, + "node_modules/node-abi": { + "version": "3.98.0", + "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-3.98.0.tgz", + "integrity": "sha512-Llh8noNw7s15m+rmIrZnZQbe4gLyasL9loT74rC92PkmwWKeEedKvc7o6pjp8B3MhrYT/Cl846NOYZbz1wmddw==", + "license": "MIT", + "optional": true, + "dependencies": { + "semver": "^7.3.5" + }, + "engines": { + "node": ">=10" + } + }, "node_modules/obug": { "version": "2.2.1", "resolved": "https://registry.npmjs.org/obug/-/obug-2.2.1.tgz", @@ -6554,6 +6582,34 @@ } } }, + "node_modules/prebuild-install": { + "version": "7.1.3", + "resolved": "https://registry.npmjs.org/prebuild-install/-/prebuild-install-7.1.3.tgz", + "integrity": "sha512-8Mf2cbV7x1cXPUILADGI3wuhfqWvtiLA1iclTDbFRZkgRQS0NqsPZphna9V+HyTEadheuPmjaJMsbzKQFOzLug==", + "deprecated": "No longer maintained. Please contact the author of the relevant native addon; alternatives are available.", + "license": "MIT", + "optional": true, + "dependencies": { + "detect-libc": "^2.0.0", + "expand-template": "^2.0.3", + "github-from-package": "0.0.0", + "minimist": "^1.2.3", + "mkdirp-classic": "^0.5.3", + "napi-build-utils": "^2.0.0", + "node-abi": "^3.3.0", + "pump": "^3.0.0", + "rc": "^1.2.7", + "simple-get": "^4.0.0", + "tar-fs": "^2.0.0", + "tunnel-agent": "^0.6.0" + }, + "bin": { + "prebuild-install": "bin.js" + }, + "engines": { + "node": ">=10" + } + }, "node_modules/process": { "version": "0.11.10", "resolved": "https://registry.npmjs.org/process/-/process-0.11.10.tgz", @@ -6590,6 +6646,17 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/pump": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.4.tgz", + "integrity": "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA==", + "license": "MIT", + "optional": true, + "dependencies": { + "end-of-stream": "^1.1.0", + "once": "^1.3.1" + } + }, "node_modules/pure-rand": { "version": "8.4.2", "resolved": "https://registry.npmjs.org/pure-rand/-/pure-rand-8.4.2.tgz", @@ -6613,6 +6680,32 @@ "integrity": "sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg==", "license": "MIT" }, + "node_modules/rc": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/rc/-/rc-1.2.8.tgz", + "integrity": "sha512-y3bGgqKj3QBdxLbLkomlohkvsA8gdAiUQlSBJnBhfn+BPxg4bc62d8TcBW15wavDfgexCgccckhcZvywyQYPOw==", + "license": "(BSD-2-Clause OR MIT OR Apache-2.0)", + "optional": true, + "dependencies": { + "deep-extend": "^0.6.0", + "ini": "~1.3.0", + "minimist": "^1.2.0", + "strip-json-comments": "~2.0.1" + }, + "bin": { + "rc": "cli.js" + } + }, + "node_modules/rc/node_modules/strip-json-comments": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz", + "integrity": "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==", + "license": "MIT", + "optional": true, + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/readable-stream": { "version": "4.7.0", "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-4.7.0.tgz", @@ -7178,6 +7271,51 @@ "dev": true, "license": "MIT" }, + "node_modules/tar-fs": { + "version": "2.1.5", + "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-2.1.5.tgz", + "integrity": "sha512-OboTd8mmMhZDNPV+UjQcK9yKAatXu2aJ+r1w4im1Otd4M4fl2hwvdoXUxIYHFTHWK/3y3FarBP70v3vwmGlOxw==", + "license": "MIT", + "optional": true, + "dependencies": { + "chownr": "^1.1.1", + "mkdirp-classic": "^0.5.2", + "pump": "^3.0.0", + "tar-stream": "^2.1.4" + } + }, + "node_modules/tar-stream": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-2.2.0.tgz", + "integrity": "sha512-ujeqbceABgwMZxEJnk2HDY2DlnUZ+9oEcb1KzTVfYHio0UE6dG71n60d8D2I4qNvleWrrXpmjpt7vZeF1LnMZQ==", + "license": "MIT", + "optional": true, + "dependencies": { + "bl": "^4.0.3", + "end-of-stream": "^1.4.1", + "fs-constants": "^1.0.0", + "inherits": "^2.0.3", + "readable-stream": "^3.1.1" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/tar-stream/node_modules/readable-stream": { + "version": "3.6.2", + "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz", + "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==", + "license": "MIT", + "optional": true, + "dependencies": { + "inherits": "^2.0.3", + "string_decoder": "^1.1.1", + "util-deprecate": "^1.0.1" + }, + "engines": { + "node": ">= 6" + } + }, "node_modules/thread-stream": { "version": "4.2.0", "resolved": "https://registry.npmjs.org/thread-stream/-/thread-stream-4.2.0.tgz", @@ -7286,6 +7424,19 @@ "license": "0BSD", "optional": true }, + "node_modules/tunnel-agent": { + "version": "0.6.0", + "resolved": "https://registry.npmjs.org/tunnel-agent/-/tunnel-agent-0.6.0.tgz", + "integrity": "sha512-McnNiV1l8RYeY8tBgEpuodCC1mLUdbSN+CYBL7kJsJNInOP8UjDDEwdk6Mw60vdLLrr5NHKZhMAOSrR2NZuQ+w==", + "license": "Apache-2.0", + "optional": true, + "dependencies": { + "safe-buffer": "^5.0.1" + }, + "engines": { + "node": "*" + } + }, "node_modules/turbo": { "version": "2.11.7", "resolved": "https://registry.npmjs.org/turbo/-/turbo-2.11.7.tgz", @@ -7458,6 +7609,13 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/util-deprecate": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz", + "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==", + "license": "MIT", + "optional": true + }, "node_modules/vfile": { "version": "6.0.3", "resolved": "https://registry.npmjs.org/vfile/-/vfile-6.0.3.tgz", diff --git a/package.json b/package.json index da611da56..0393f84c3 100644 --- a/package.json +++ b/package.json @@ -181,6 +181,8 @@ "verify:ghidra:cross-format": "npm run build:cached && node scripts/verify-real-ghidra.mjs --cross-format", "verify:ghidra:windows": "npm run build:cached && npm run build:ghidra-windows-fixture && node scripts/verify-real-ghidra-windows.mjs", "verify:browser": "npm run build:cached && node scripts/verify-real-browser.mjs", + "verify:frida": "npm run build:cached && node scripts/verify-frida.mjs", + "verify:frida:bindings": "tsc --noEmit -p tsconfig.frida-verification.json", "verify:browser:dom": "node scripts/verify-browser-dom-destinations.mjs", "verify:browser:network": "npm run build:cached && node scripts/verify-browser-network.mjs", "verify:electron": "npm run build:cached && node scripts/verify-real-electron.mjs", @@ -341,5 +343,11 @@ "typescript-termux": "npm:typescript@5.9.3", "vitepress": "1.6.4", "vitest": "5.0.3" + }, + "optionalDependencies": { + "frida": "17.23.2" + }, + "allowScripts": { + "frida@17.23.2": true } } diff --git a/scripts/lib/catalog-builders.mjs b/scripts/lib/catalog-builders.mjs index f9e0c0cef..787d6255d 100644 --- a/scripts/lib/catalog-builders.mjs +++ b/scripts/lib/catalog-builders.mjs @@ -49,6 +49,11 @@ export const toolFamilyCatalog = (sources) => { surface: "android-provider", contracts: sources.androidContracts.ANDROID_TOOL_CONTRACTS, }, + { + id: "frida", + surface: "instrumentation-provider", + contracts: sources.fridaContracts.FRIDA_TOOL_CONTRACTS, + }, { id: "apktool", surface: "apktool-provider", @@ -145,6 +150,10 @@ export const providerCatalog = (sources) => { activeContracts, } = electronContractSlices(sources); return [ + { + identity: sources.fridaProvider.FRIDA_PROVIDER_IDENTITY, + contracts: sources.fridaContracts.FRIDA_TOOL_CONTRACTS, + }, { identity: sources.hopperProvider.HOPPER_PROVIDER_IDENTITY, contracts: declaredContracts( diff --git a/scripts/lib/catalog-core.mjs b/scripts/lib/catalog-core.mjs index 56ffd544c..546b7359c 100644 --- a/scripts/lib/catalog-core.mjs +++ b/scripts/lib/catalog-core.mjs @@ -43,6 +43,8 @@ const SOURCE_PATHS = { sessionContracts: "dist/contracts/sessionToolContracts.js", binaryDiagnosticsContracts: "dist/contracts/native/binaryDiagnosticsToolContracts.js", + fridaContracts: "dist/contracts/fridaToolContracts.js", + fridaProvider: "dist/frida/FridaInstrumentationManager.js", pwntoolsProvider: "dist/native/pwntools/PwntoolsRelease.js", nativeContracts: "dist/contracts/native/nativeToolContracts.js", wasmContracts: "dist/contracts/wasm/wasmToolContracts.js", diff --git a/scripts/verify-frida.mjs b/scripts/verify-frida.mjs new file mode 100644 index 000000000..ece121a14 --- /dev/null +++ b/scripts/verify-frida.mjs @@ -0,0 +1,198 @@ +import { basename } from "node:path"; + +import { FridaInstrumentationService } from "../dist/application/frida/FridaInstrumentationService.js"; +import { FridaInstrumentationManager } from "../dist/frida/FridaInstrumentationManager.js"; +import { isValidFridaRemoteAddress } from "../dist/contracts/fridaRemoteAddress.js"; + +const options = parseArguments(process.argv.slice(2)); +if (options.help) { + process.stdout.write( + "Usage: npm run verify:frida [-- --address HOST:PORT --pid PID [remote auth flags]]\n" + + "Without flags, verifies a local Node.js process created by this script.\n", + ); + process.exit(0); +} + +const manager = new FridaInstrumentationManager(); +const service = new FridaInstrumentationService(manager); +const remote = + options.address === undefined + ? undefined + : { + address: options.address, + ...(options.token === undefined ? {} : { token: options.token }), + ...(options.certificate === undefined + ? {} + : { certificate: options.certificate }), + ...(options.origin === undefined ? {} : { origin: options.origin }), + ...(options.keepaliveInterval === undefined + ? {} + : { keepaliveInterval: options.keepaliveInterval }), + }; + +try { + let targetProcess; + let input; + if (remote === undefined) { + input = { + mode: "spawn", + deviceId: "local", + program: process.execPath, + argv: ["-e", "setTimeout(() => {}, 1500)"], + source: { + sourceKind: "inline", + source: "send({ rea_frida_verification: 'ok', pid: Process.id });", + }, + durationMs: 500, + }; + targetProcess = { pid: undefined, name: basename(process.execPath) }; + } else { + const inventory = await service.listProcesses({ remote }); + if (!inventory.ok) throw new Error(inventory.error.message); + targetProcess = inventory.value.processes.find( + ({ pid }) => pid === options.pid, + ); + if (targetProcess === undefined) + throw new Error( + `Selected PID ${String(options.pid)} was not observed remotely`, + ); + input = { + mode: "attach", + remote, + pid: options.pid, + source: { + sourceKind: "inline", + source: "send({ rea_frida_verification: 'ok', pid: Process.id });", + }, + durationMs: 500, + }; + } + + const result = await service.instrument(input); + if (!result.ok) throw new Error(result.error.message); + const observed = result.value.evidence.normalized_result; + if ( + typeof observed !== "object" || + observed === null || + Array.isArray(observed) || + !Array.isArray(observed.messages) + ) + throw new Error("Frida returned no message observation"); + const messageObserved = observed.messages.some( + (message) => + typeof message === "object" && + message !== null && + !Array.isArray(message) && + message.type === "send" && + typeof message.payload === "object" && + message.payload !== null && + !Array.isArray(message.payload) && + message.payload.rea_frida_verification === "ok" && + message.payload.pid === observed.pid, + ); + if (!messageObserved) + throw new Error("Selected target did not return the Frida marker"); + const report = { + ok: result.value.cleanupError === null, + provider: "frida", + host_platform: process.platform, + target_mode: remote === undefined ? "local_spawn" : "remote_attach", + target_pid: observed.pid, + target_name: targetProcess.name, + ...(remote === undefined ? {} : { remote_target_observed: true }), + script_message_observed: true, + cleanup_error: result.value.cleanupError, + }; + process.stdout.write(`${JSON.stringify(report)}\n`); + if (!report.ok) process.exitCode = 1; +} catch (cause) { + process.stderr.write( + `Frida real-provider verification failed: ${cause instanceof Error ? cause.message : String(cause)}\n`, + ); + process.exitCode = 1; +} finally { + await manager.closeAll().catch(() => undefined); +} + +function parseArguments(args) { + if (args.length === 1 && args[0] === "--help") return { help: true }; + const values = parseOptionValues(args); + const address = values.get("--address"); + const pidValue = values.get("--pid"); + const pid = parseRemotePid(address, pidValue); + if (address === undefined) assertNoRemoteOptions(values); + const keepaliveInterval = parseKeepalive(values.get("--keepalive-interval")); + return { + help: false, + ...(address === undefined ? {} : { address }), + ...(pid === undefined ? {} : { pid }), + ...(values.has("--token") ? { token: values.get("--token") } : {}), + ...(values.has("--certificate") + ? { certificate: values.get("--certificate") } + : {}), + ...(values.has("--origin") ? { origin: values.get("--origin") } : {}), + ...(keepaliveInterval === undefined ? {} : { keepaliveInterval }), + }; +} + +function parseOptionValues(args) { + const values = new Map(); + const valueFlags = new Set([ + "--address", + "--pid", + "--token", + "--certificate", + "--origin", + "--keepalive-interval", + ]); + for (let index = 0; index < args.length; index += 1) { + const flag = args[index]; + const value = args[index + 1]; + if ( + typeof flag !== "string" || + !valueFlags.has(flag) || + value === undefined || + values.has(flag) + ) + throw new Error( + "Expected no arguments for local-fixture verification, or --address HOST:PORT --pid PID and optional remote auth flags", + ); + values.set(flag, value); + index += 1; + } + return values; +} + +function parseRemotePid(address, pidValue) { + if ((address === undefined) !== (pidValue === undefined)) + throw new Error("Remote verification requires both --address and --pid"); + if (address !== undefined && !isValidFridaRemoteAddress(address)) + throw new Error( + "--address must be a host[:port] without credentials, path, query, or fragment", + ); + const pid = pidValue === undefined ? undefined : Number(pidValue); + if (pid !== undefined && (!Number.isSafeInteger(pid) || pid <= 0)) + throw new Error("--pid must be a positive process identifier"); + return pid; +} + +function assertNoRemoteOptions(values) { + for (const flag of [ + "--token", + "--certificate", + "--origin", + "--keepalive-interval", + ]) + if (values.has(flag)) + throw new Error("Remote connection options require --address and --pid"); +} + +function parseKeepalive(value) { + const interval = value === undefined ? undefined : Number(value); + if ( + interval !== undefined && + (!Number.isSafeInteger(interval) || interval <= 0) + ) + throw new Error("--keepalive-interval must be a positive integer"); + return interval; +} diff --git a/scripts/verify/fridaBindingsCompatibility.ts b/scripts/verify/fridaBindingsCompatibility.ts new file mode 100644 index 000000000..cb156efb6 --- /dev/null +++ b/scripts/verify/fridaBindingsCompatibility.ts @@ -0,0 +1,28 @@ +import type { + Device as VendorDevice, + DeviceManager as VendorDeviceManager, + Script as VendorScript, + Session as VendorSession, +} from "../../node_modules/frida/build/src/frida_binding.js"; +import type { Device, DeviceManager, Script, Session } from "frida"; + +type Assert = Condition; + +type VendorDeviceManagerFitsShim = Assert< + VendorDeviceManager extends DeviceManager ? true : false +>; +type VendorDeviceFitsShim = Assert; +type VendorSessionFitsShim = Assert< + VendorSession extends Session ? true : false +>; +type VendorScriptFitsShim = Assert; + +// These aliases intentionally fail when the pinned Frida API narrows incompatibly. +const compatibility: readonly [ + VendorDeviceManagerFitsShim, + VendorDeviceFitsShim, + VendorSessionFitsShim, + VendorScriptFitsShim, +] = [true, true, true, true]; + +void compatibility; diff --git a/src/application/CapabilityInventory.ts b/src/application/CapabilityInventory.ts index 7c9d3910c..76c5cafbb 100644 --- a/src/application/CapabilityInventory.ts +++ b/src/application/CapabilityInventory.ts @@ -22,6 +22,7 @@ import type { JsonValue } from "../domain/jsonValue.js"; import { isMachOFormat } from "../domain/binaryTargetTypes.js"; import type { ProviderAvailability } from "./AnalysisProvider.js"; import { TOOL_CONTRACTS } from "../contracts/toolContracts.js"; +import { FRIDA_TOOL_CONTRACTS } from "../contracts/fridaToolContracts.js"; import { clientRequirementsFor, NO_CLIENT_FEATURES, @@ -131,6 +132,9 @@ const ACTIVE_TARGET_KINDS: ReadonlySet = new Set([ "native-provider", "artifact-provider", ]); +const FRIDA_OPERATION_NAMES: ReadonlySet = new Set( + FRIDA_TOOL_CONTRACTS.map(({ name }) => name), +); /** Native contracts defined only for an active Mach-O executable. */ const MACHO_TARGET_OPERATIONS: ReadonlySet = new Set([ @@ -316,6 +320,7 @@ const optionalProviderFailureFor = ({ if (kind === "electron-provider") return failures?.electronObservation; if (kind === "runtime-provider") return failures?.javascriptRuntimeObservation; + if (FRIDA_OPERATION_NAMES.has(name)) return failures?.fridaInstrumentation; return undefined; }; @@ -533,6 +538,7 @@ const targetAvailability = ({ targetFormat, targetOpen, }: AvailabilityContext): Availability | null => { + if (FRIDA_OPERATION_NAMES.has(name)) return null; if (!targetOpen && ACTIVE_TARGET_KINDS.has(kind)) return { reason: "target_required", diff --git a/src/application/OptionalObservationProviders.ts b/src/application/OptionalObservationProviders.ts index d66554966..499925a7c 100644 --- a/src/application/OptionalObservationProviders.ts +++ b/src/application/OptionalObservationProviders.ts @@ -22,7 +22,10 @@ export interface OptionalProviderLoadFailure { export type OptionalProviderLoadFailures = Readonly< Partial< - Record + Record< + keyof OptionalObservationProviders | "fridaInstrumentation", + OptionalProviderLoadFailure + > > >; diff --git a/src/application/frida/FridaInstrumentationManager.test.ts b/src/application/frida/FridaInstrumentationManager.test.ts new file mode 100644 index 000000000..8c315c0d5 --- /dev/null +++ b/src/application/frida/FridaInstrumentationManager.test.ts @@ -0,0 +1,988 @@ +import { describe, expect, it } from "vitest"; + +import type { + Device, + DeviceManager, + FridaMessage, + Process, + Script, + Session, + Signal, +} from "frida"; +import { FridaInstrumentationManager } from "../../frida/FridaInstrumentationManager.js"; + +const signal = void>() => { + let connected: Handler | undefined; + const value: Signal & { + emit: (...args: Parameters) => void; + } = { + connect: (handler) => { + connected = handler; + }, + disconnect: (handler) => { + if (connected === handler) connected = undefined; + }, + emit: (...args) => connected?.(...args), + }; + return value; +}; + +class FakeScript implements Script { + readonly message = + signal<(message: FridaMessage, data: Buffer | null) => void>(); + isDestroyed = false; + loadFailure: Error | undefined; + unloadFailureCount = 0; + unloadCalls = 0; + + constructor( + readonly payload: unknown = { event: "loaded" }, + readonly beforeLoad: () => Promise = async () => {}, + readonly description = "script loaded", + readonly stack = "", + ) {} + + async load(): Promise { + await this.beforeLoad(); + if (this.loadFailure !== undefined) throw this.loadFailure; + this.message.emit( + { + type: "send", + payload: this.payload, + description: this.description, + stack: this.stack, + }, + null, + ); + } + + async unload(): Promise { + this.unloadCalls += 1; + if (this.unloadFailureCount > 0) { + this.unloadFailureCount -= 1; + throw new Error("script unload failed"); + } + if (this.isDestroyed) throw new Error("Script is destroyed"); + this.isDestroyed = true; + } +} + +class FakeSession implements Session { + readonly detached = signal<() => void>(); + readonly scripts: FakeScript[] = []; + nextPayload: unknown = { event: "loaded" }; + nextDescription = "script loaded"; + nextStack = ""; + nextLoadFailure: Error | undefined; + nextUnloadFailureCount = 0; + detachFailureCount = 0; + scriptLoadGate: Promise | undefined; + onScriptLoadStarted: (() => void) | undefined; + private detachedState = false; + readonly pid = 512; + + isDetached(): boolean { + return this.detachedState; + } + + async createScript(): Promise