feat(elf): inspect dynamic dependencies and required symbol versions

Add offline ELF dependency, search-path, symbol-version and import inspection with retained Evidence summaries and pages. Bound GNU-hash work and preserve cancellation, stable identity and caller-selected parameters across CLI/MCP.

Assisted-by: Suika (gensokyo-skills:suika-scatter-gather-planning)
Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
This commit is contained in:
Matt Van Hornandgensokyo-dev authored and GitHub committed 2026-11-17 08:19:52 +00:00
1 parent af062e7a2d
commit e9c72dbd1f
100 files changed
+7137 -89

No files matched your search

+46 -1
View File
@@ -192,7 +192,33 @@ it("routes bundle resource MCP calls with null executable identity and retained
});
});
it("exposes the production resource session through the MCP SDK for a keyless bundle", async () => {
const expectExplicitSelection = async (
client: Client,
request: {
readonly name: "decode_interface_builder" | "inspect_keyed_archive";
readonly parameters: Record<string, JsonValue>;
readonly previous: {
readonly normalized_result: unknown;
readonly evidence_id: string;
};
},
) => {
const response = await client.callTool({
name: request.name,
arguments: request.parameters,
});
expect(response.isError).not.toBe(true);
const evidence = toolContract(request.name).outputSchema.parse(
response.structuredContent,
);
expect(evidence.parameters).toEqual(request.parameters);
expect(evidence.normalized_result).toEqual(
request.previous.normalized_result,
);
expect(evidence.evidence_id).not.toBe(request.previous.evidence_id);
};
const createResourceMcpFixture = async () => {
const parent = await createTestTempDirectory(
"rea-bundle-resource-production-mcp-",
);
@@ -220,6 +246,13 @@ it("exposes the production resource session through the MCP SDK for a keyless bu
clientIdentity: { name: "production-bundle-resource-test", version: "1" },
});
return { client, session, alias, canonical };
};
it("exposes the production resource session through the MCP SDK for a keyless bundle", async () => {
const { client, session, alias, canonical } =
await createResourceMcpFixture();
const opened = await client.callTool({
name: "open_bundle_resources",
arguments: { path: alias },
@@ -256,6 +289,12 @@ it("exposes the production resource session through the MCP SDK for a keyless bu
},
},
});
expect(decodedEvidence.parameters).toEqual({});
await expectExplicitSelection(client, {
name: "decode_interface_builder",
parameters: { max_documents: 64 },
previous: decodedEvidence,
});
const decodedEvidenceId = z
.object({ evidence_id: z.string() })
.parse(decodedEvidence).evidence_id;
@@ -315,6 +354,12 @@ it("exposes the production resource session through the MCP SDK for a keyless bu
]),
},
});
expect(evidence.parameters).toEqual({ path: "Resources/Archive.plist" });
await expectExplicitSelection(client, {
name: "inspect_keyed_archive",
parameters: { path: "Resources/Archive.plist", offset: 0 },
previous: evidence,
});
const evidenceId = z
.object({ evidence_id: z.string() })
.parse(evidence).evidence_id;
+3 -1
View File
@@ -75,7 +75,7 @@ import {
const currentRequestSignal = new AsyncLocalStorage<AbortSignal>();
/** Capture structured issues from the canonical validation the SDK already performs. */
/** Capture caller selections and issues at the canonical SDK validation boundary. */
const captureInputValidation = <Schema extends StandardSchemaWithJSON>(
tool: string,
schema: Schema,
@@ -96,6 +96,8 @@ const captureInputValidation = <Schema extends StandardSchemaWithJSON>(
issues: result.issues as readonly z.core.$ZodIssue[],
input: value,
};
if (result.issues === undefined)
context?.captureCallerParameters(tool, value, result.value);
return result;
};
const result = standard.validate(value);
+35
View File
@@ -12,11 +12,21 @@ import {
} from "../domain/analysisErrorCore.js";
import { err, ok, type Result } from "../domain/result.js";
import { callerAnalysisParameters } from "../application/AnalysisInput.js";
import type { JsonValue } from "../domain/jsonValue.js";
const currentRequest = new AsyncLocalStorage<McpToolRequest>();
/** One SDK request owns validation, cancellation and its publication boundary. */
export class McpToolRequest {
readonly cancellation = new AbortController();
readonly #parameterSelections = new WeakMap<
object,
{
readonly tool: string;
readonly select: ReturnType<typeof callerAnalysisParameters>;
}
>();
validation?: {
readonly issues: readonly z.core.$ZodIssue[];
readonly input: unknown;
@@ -41,6 +51,31 @@ export class McpToolRequest {
readonly tool: string,
) {}
/** Capture only selected names at canonical validation, not the raw input tree. */
captureCallerParameters(tool: string, input: unknown, parsed: unknown): void {
if (parsed !== null && typeof parsed === "object")
this.#parameterSelections.set(parsed, {
tool,
select: callerAnalysisParameters(input),
});
}
/** The exact parsed object identifies its validation, including nested tool calls. */
callerParameters(
tool: string,
parsed: unknown,
parameters: Readonly<Record<string, JsonValue>>,
): Readonly<Record<string, JsonValue>> {
const selection =
parsed !== null && typeof parsed === "object"
? this.#parameterSelections.get(parsed)
: undefined;
// Dropping properties from a validated JSON object preserves its value type.
return (
selection?.tool === tool ? selection.select(parameters) : parameters
) as Readonly<Record<string, JsonValue>>;
}
beginHandler(): void {
this.#handlerStarted = true;
}
+4 -5
View File
@@ -44,6 +44,7 @@ import {
type DerivedSources,
createEvidenceToolHandler,
createRetainedSummaryToolHandler,
type RetainedSummaryOperation,
createValueToolHandler,
type ContractToolService,
type ValueOutcome,
@@ -287,9 +288,7 @@ type DerivedBinding = {
* Admit `detail`/`view` in the adapter, run the workflow on the remaining
* input, and retain the complete Evidence behind a summary.
*/
interface RetainedSummaryBinding<Input> {
readonly admission: ContractInputAdmission;
readonly summary: EvidenceOperation<Omit<Input, "detail" | "view">>;
type RetainedSummaryBinding<Input> = RetainedSummaryOperation<Input> & {
readonly run?: never;
readonly value?: never;
readonly derive?: never;
@@ -300,7 +299,7 @@ interface RetainedSummaryBinding<Input> {
readonly mutation?: never;
readonly query?: never;
readonly provider?: never;
}
};
/**
* Run an application workflow that completes Evidence from session-held
@@ -647,7 +646,7 @@ export const registerContractTools = (
: createRetainedSummaryToolHandler(
server,
contract as SummaryContract,
binding.summary,
binding,
logger,
retention,
withAdmittedAnalysis,
+31 -5
View File
@@ -27,6 +27,7 @@ import type { ToolContract } from "../contracts/toolContractTypes.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import type { Evidence } from "../domain/evidence.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { isRecord } from "../kernel/isRecord.js";
import { err, ok, type Result } from "../domain/result.js";
import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";
@@ -98,6 +99,23 @@ export const createContractToolHandler =
withAdmittedAnalysis,
)(contract);
/** Input admission owns whether inspection receives defaults or caller selections. */
export type RetainedSummaryOperation<Input> =
| {
readonly admission: "sdk";
readonly summary: (
input: Omit<Input, "detail" | "view">,
options: ExecutionOptions,
) => Promise<Result<Evidence, AnalysisError>>;
}
| {
readonly admission: "application";
readonly summary: (
input: unknown,
options: ExecutionOptions,
) => Promise<Result<Evidence, AnalysisError>>;
};
/** Validate delivery selection before inspection and retain its complete source for summaries. */
export const createRetainedSummaryToolHandler = <
Name extends string,
@@ -110,10 +128,7 @@ export const createRetainedSummaryToolHandler = <
>(
server: EvidenceMcpServer,
contract: ToolContract<Name, InputSchema>,
inspect: (
input: Omit<z.output<InputSchema>, "detail" | "view">,
options: ExecutionOptions,
) => Promise<Result<Evidence, AnalysisError>>,
operation: RetainedSummaryOperation<z.output<InputSchema>>,
logger: Logger,
retention: AnalysisViewRetention,
withAdmittedAnalysis?: WithAdmittedAnalysis,
@@ -136,7 +151,18 @@ export const createRetainedSummaryToolHandler = <
const ready = requireAnalysisViewRetention(contract.name, retention);
if (!ready.ok) return ready;
}
const inspected = await inspect(input, options);
const inspected = await (operation.admission === "sdk"
? operation.summary(input, options)
: operation.summary(
isRecord(rawInput)
? Object.fromEntries(
Object.entries(rawInput).filter(
([field]) => field !== "detail" && field !== "view",
),
)
: rawInput,
options,
));
return detail === "summary" && inspected.ok
? projectRetainedAnalysis(
inspected.value,
+2
View File
@@ -201,6 +201,7 @@ export const createServer = (
electronFuses,
releaseExposure,
pythonPyc,
elfDependencies,
webNetworkCapture,
javascriptRecovery,
artifactResources,
@@ -405,6 +406,7 @@ export const createServer = (
peImports,
windowsShortcut,
recordedCrash,
elfDependencies,
},
contractTools,
);
+11 -3
View File
@@ -27,6 +27,8 @@ import type { WithAdmittedAnalysis } from "./analysisAdmission.js";
import { recordEvidenceSources } from "../application/investigation/recordEvidenceSources.js";
import { createOperationProgress } from "./operationProgress.js";
import { currentMcpToolRequest } from "./McpToolRequest.js";
/** A provider operation a tool contract names. */
export type ProviderOperation = Exclude<AnalysisOperation, "health">;
@@ -82,8 +84,14 @@ export const createProviderOperationToolHandler =
input: unknown,
context: ServerContext,
): Promise<CallToolResult> => {
const parameters = jsonObjectSchema.parse(input);
const ready = delivery?.preflight(parameters) ?? ok(null);
const resolved = jsonObjectSchema.parse(input);
const parameters =
currentMcpToolRequest()?.callerParameters(
contract.name,
input,
resolved,
) ?? resolved;
const ready = delivery?.preflight(resolved) ?? ok(null);
if (!ready.ok) return server.delivery.toCallToolResult(ready, contract);
const admitted = await dependencies.withAdmittedAnalysis(
contract.name,
@@ -147,7 +155,7 @@ export const createProviderOperationToolHandler =
server.delivery.toCallToolResult(evidence, contract),
);
const projected =
delivery?.projectEvidence(parameters, evidence.value) ??
delivery?.projectEvidence(resolved, evidence.value) ??
ok(evidence.value);
if (!projected.ok)
return progress.complete(
+7
View File
@@ -1,3 +1,4 @@
import type { ElfDependenciesService } from "../application/binaryDiagnostics/ElfDependenciesService.js";
import type { AdbDeviceAnalysisService } from "../application/adb/AdbDeviceAnalysisService.js";
import type { AnalysisSettings } from "../application/AnalysisSettings.js";
import type { AnalysisSettingsReader } from "../domain/analysisSettings.js";
@@ -846,6 +847,12 @@ const SERVICE_TOOL_BINDINGS = {
run: (input, options) => service.recover(input, options),
},
})) satisfies Bind<JavaScriptRecoveryService>,
elfDependencies: ((service) => ({
inspect_elf_dependencies: {
admission: "application",
summary: (input, options) => service.inspect(input, options),
},
})) satisfies Bind<ElfDependenciesService>,
guidance: ((resources) => ({
search_guidance: {
admission: "application",