Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(native): inspect PE and ELF export tables without an engine (#6278)
Kaoru0822933af60eba43
diff --git a/.agents/skills/reverse-engineer-anything/SKILL.md b/.agents/skills/reverse-engineer-anything/SKILL.mdindex c9203a252..8391d3704 100644--- a/.agents/skills/reverse-engineer-anything/SKILL.md+++ b/.agents/skills/reverse-engineer-anything/SKILL.md@@ -247,6 +247,8 @@ explicit path or endpoint and do not need it.- PE resource type/name/language trees and static icon group references:`inspect_pe_resources` with an explicit path. This portable operation requiresno active target or engine; opaque payloads retain file ranges and SHA-256.+- PE export directories and ELF dynamic-symbol exports: `inspect_native_exports`+ with an explicit path; portable, no active target or engine.- Native executable, library, or analysis database: `open_binary`, thenuse focused analysis tools directly; call `binary_overview` when metadata orinventory context is useful and available from the selected provider.diff --git a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.mdindex b31021e6b..5bb2956e8 100644--- a/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md+++ b/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md@@ -409,6 +409,16 @@ Other payloads are opaque, and this operation does not decode images or simulateWindows resource loading. Consult the budgets and supported tree profile in[offline binary diagnostics](https://github.com/morluto/rea/blob/main/docs/binary-diagnostics.md).+## Offline PE and ELF export tables++Use `inspect_native_exports` with an absolute `path`, or+`rea inspect-native-exports ./libexample.so --json`, to read a PE export+directory or ELF dynamic symbol table on any host without opening a native+target. Ordinal-only, forwarded and hidden-version exports stay distinct;+partial or unsupported coverage means the inventory is incomplete, not that+exports are absent. Use `inspect_macho` for Mach-O. See+[offline binary diagnostics](https://github.com/morluto/rea/blob/main/docs/binary-diagnostics.md).+For exact core-module import/export differences, use `compare_wasm_interfaces`with two complete inspection Evidence records (or current-session retainedreferences) and explicit scope. Preserve unknown types/duplicate names; staticdiff --git a/docs/binary-diagnostics.md b/docs/binary-diagnostics.mdindex a17368b74..1e6ce267a 100644--- a/docs/binary-diagnostics.md+++ b/docs/binary-diagnostics.md@@ -299,3 +299,52 @@ arm64 host and Node version. Cold disk I/O, token counts and an agentinvestigation were not measured; there was no previous equivalent tool tobenchmark. These figures do not establish a portable peak-memory bound,constant memory for retained Evidence or faster agent task completion.++## Portable native exports++`inspect_native_exports` / `inspect-native-exports` reads the export table of an+explicit PE or ELF image on any supported host, without an active target,+native engine, `objdump` or Windows SDK:++```sh+rea inspect-native-exports ./runtimes/linux-x64/native/libexample.so --json+```++```json+{+ "name": "inspect_native_exports",+ "arguments": { "path": "/artifacts/native/example.dll" }+}+```++The complete Evidence identifies the stable artifact snapshot by path, byte+count and SHA-256.++- PE rows reproduce the export directory: each used export-address-table slot+ with its `ordinal`, one row per name (aliases share an ordinal), `address`+ as the preferred-base virtual address, or `forwarder` text when the slot+ forwards to another DLL. Ordinal-only exports have a null `name`. The+ directory's DLL name, ordinal base and timestamp are reported, and an image+ without an export directory is a complete empty inventory.+- ELF rows list defined `.dynsym` symbols with global, weak or GNU-unique+ binding and default or protected visibility. Each row keeps `value`+ (`st_value` as stored; bit 0 marks Thumb code on 32-bit ARM), `size`, `type`+ and `binding`. `version` is null for an unversioned symbol, the+ `.gnu.version_d` index, name and `hidden` flag for a versioned one, or+ `"unknown"` when the version table cannot be read. A hidden version is not+ the default version that a by-name `dlsym` lookup selects.++Unreadable names, out-of-range name ordinals and unreadable forwarders are+listed in `issues`, their entries are not reported, and coverage is `partial`.+Unresolved symbol versions keep their rows: the version name is null for an+index no definition names, and `version` is `"unknown"` when the version table+cannot be read; coverage is likewise `partial`. A dynamic symbol table without+its null entry is malformed. An ELF without section headers is `unsupported`:+enumerating dynamic symbols from the dynamic segment is not+implemented. Mach-O exports are reported by `inspect_macho`.++`max_file_bytes` defaults to 256 MiB (maximum 512 MiB; CLI `--max-file-bytes`).+Export directories in PE headers are read like those in sections. An export or+dynamic symbol table above 262144 entries, more than 262144 rows, or more than+16 MiB of retained names fails without partial success. Export rows do not establish that a symbol is reachable, safe to call+or loaded at runtime.diff --git a/scripts/lib/catalog-builders.mjs b/scripts/lib/catalog-builders.mjsindex 31557cea7..69bc92b73 100644--- a/scripts/lib/catalog-builders.mjs+++ b/scripts/lib/catalog-builders.mjs@@ -264,6 +264,13 @@ export const providerCatalog = (sources) => {({ name }) => name === "inspect_byte_entropy",),},+ {+ identity: sources.artifactProviders.NATIVE_EXPORTS_PROVIDER,+ contracts:+ sources.binaryDiagnosticsContracts.BINARY_DIAGNOSTICS_TOOL_CONTRACTS.filter(+ ({ name }) => name === "inspect_native_exports",+ ),+ },{identity: sources.captureProvider.TSHARK_PROVIDER_IDENTITY,contracts: sources.captureContracts.CAPTURE_TOOL_CONTRACTS,diff --git a/src/application/CapabilityInventory.ts b/src/application/CapabilityInventory.tsindex bbcd1a953..f110b005a 100644--- a/src/application/CapabilityInventory.ts+++ b/src/application/CapabilityInventory.ts@@ -498,7 +498,7 @@ const workflowAvailabilityFor = ({remediation:"Supply WABT 1.0.42 via absolute REA_WABT_BIN_DIRECTORY. No active binary target is required; tools are checked at execution.",};- if (name === "inspect_pe_resources")+ if (name === "inspect_pe_resources" || name === "inspect_native_exports")return { reason: "available", remediation: null };if (name === "inspect_elf_notes")return { reason: "available", remediation: null };diff --git a/src/application/InvestigationProviders.ts b/src/application/InvestigationProviders.tsindex 3ad47a962..88b3bb052 100644--- a/src/application/InvestigationProviders.ts+++ b/src/application/InvestigationProviders.ts@@ -62,6 +62,13 @@ export const BYTE_ENTROPY_PROVIDER = Object.freeze({version: "1",} as const);+/** Provider identity for portable, execution-free PE and ELF export tables. */+export const NATIVE_EXPORTS_PROVIDER = Object.freeze({+ id: "rea-native-exports",+ name: "REA PE/ELF export table reader",+ version: "1",+} as const);+/** Provider identity for deterministic managed-code comparison workflows. */export const MANAGED_WORKFLOW_PROVIDER = {id: "rea-dotnet-workflows",diff --git a/src/application/binaryDiagnostics/NativeExportsPort.ts b/src/application/binaryDiagnostics/NativeExportsPort.tsnew file mode 100644index 000000000..640d8e186--- /dev/null+++ b/src/application/binaryDiagnostics/NativeExportsPort.ts@@ -0,0 +1,20 @@+import type {+ ExecutionOptions,+ ProviderIdentity,+} from "../AnalysisProvider.js";+import type { AnalysisError } from "../../domain/analysisErrorBase.js";+import type {+ InspectNativeExportsInput,+ NativeExports,+} from "../../domain/native/nativeExports.js";+import type { Result } from "../../domain/result.js";++/** Stable read and export-table decoding, independent of an active engine session. */+export interface NativeExportsPort {+ readonly identity: ProviderIdentity;+ close?(): Promise<void>;+ inspect(+ input: InspectNativeExportsInput,+ options?: ExecutionOptions,+ ): Promise<Result<NativeExports, AnalysisError>>;+}diff --git a/src/application/binaryDiagnostics/NativeExportsService.ts b/src/application/binaryDiagnostics/NativeExportsService.tsnew file mode 100644index 000000000..d8d5bceb3--- /dev/null+++ b/src/application/binaryDiagnostics/NativeExportsService.ts@@ -0,0 +1,79 @@+import type { ExecutionOptions } from "../AnalysisProvider.js";+import type { NativeExportsPort } from "./NativeExportsPort.js";+import type { AnalysisError } from "../../domain/analysisErrorBase.js";+import {+ AnalysisCancelledError,+ AnalysisOutputError,+} from "../../domain/analysisErrorCore.js";+import { createEvidence, type Evidence } from "../../domain/evidence.js";+import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";+import {+ inspectNativeExportsInputSchema,+ nativeExportsSchema,+} from "../../domain/native/nativeExports.js";+import { err, type Result } from "../../domain/result.js";+import { completeProviderEvidence } from "../ProviderOperationExecution.js";++const OPERATION = "inspect_native_exports";++/** Shared caller validation, output parsing and Evidence provenance for CLI/MCP. */+export class NativeExportsService {+ constructor(readonly provider: NativeExportsPort) {}++ close(): Promise<void> {+ return this.provider.close?.() ?? Promise.resolve();+ }++ /** Read one explicitly selected PE or ELF image's export table. */+ async inspect(+ rawInput: unknown,+ options?: ExecutionOptions,+ ): Promise<Result<Evidence, AnalysisError>> {+ if (options?.signal?.aborted)+ return err(+ new AnalysisCancelledError(OPERATION, { cause: options.signal.reason }),+ );+ const input = inspectNativeExportsInputSchema.safeParse(rawInput);+ if (!input.success)+ return err(+ analysisInputErrorFromIssues(OPERATION, input.error.issues, rawInput, {+ cause: input.error,+ }),+ );+ const result = await this.provider.inspect(input.data, options);+ if (!result.ok) return result;+ const report = nativeExportsSchema.safeParse(result.value);+ if (+ !report.success ||+ report.data.artifact.path !== input.data.path ||+ report.data.artifact.bytes > input.data.max_file_bytes ||+ report.data.coverage.exports !== report.data.exports.length+ )+ return err(+ new AnalysisOutputError(+ OPERATION,+ "Native export reader returned malformed output or changed artifact identity.",+ ),+ );+ const value = report.data;+ return completeProviderEvidence(+ createEvidence(+ {+ path: value.artifact.path,+ format: value.format,+ sha256: value.artifact.sha256,+ },+ this.provider.identity,+ {+ operation: OPERATION,+ parameters: input.data,+ result: value,+ confidence: "observed",+ limitations: value.limitations,+ locations: [{ kind: "artifact-path", path: value.artifact.path }],+ },+ ),+ options?.signal,+ );+ }+}diff --git a/src/cli/binaryDiagnosticsCommands.ts b/src/cli/binaryDiagnosticsCommands.tsindex 9e125c22d..45cf8921d 100644--- a/src/cli/binaryDiagnosticsCommands.ts+++ b/src/cli/binaryDiagnosticsCommands.ts@@ -6,6 +6,7 @@ import {createBinaryLayoutService,createElfNotesService,createPeResourcesService,+ createNativeExportsService,} from "../composition/binaryDiagnostics.js";import { CLI_COMMANDS } from "../cliCommandNames.js";import { logCliCommand } from "../cliLogging.js";@@ -15,6 +16,7 @@ import { withCommandCancellation } from "./commandCancellation.js";import { inspectBinaryLayoutInputSchema } from "../domain/native/binaryLayout.js";import { inspectRecordedCrashInputSchema } from "../domain/native/recordedCrash.js";import { inspectPeResourcesInputSchema } from "../domain/native/peResources.js";+import { inspectNativeExportsInputSchema } from "../domain/native/nativeExports.js";import { inspectElfNotesInputSchema } from "../domain/native/elfNotes.js";import { projectAnalysisError } from "../domain/analysisErrorProjection.js";import { finishAnalysisCommand } from "./finishAnalysisCommand.js";@@ -130,6 +132,37 @@ export const registerBinaryDiagnosticsCommands = ();}),});+ cli.command(CLI_COMMANDS.inspectNativeExports, {+ description:+ "Inspect a PE or ELF image's export table without executing it",+ args: z.object({ path: z.string().describe("Local PE or ELF image") }),+ options: z.object({+ maxFileBytes: inspectNativeExportsInputSchema.shape.max_file_bytes,+ }),+ run: ({ args, options }) =>+ withCommandCancellation(async (signal) => {+ const exports = createNativeExportsService();+ return await logCliCommand(+ logger,+ CLI_COMMANDS.inspectNativeExports,+ async () =>+ finishAnalysisCommand(+ () =>+ exports.inspect(+ {+ path: absoluteCallerPath(args.path),+ max_file_bytes: options.maxFileBytes,+ },+ { signal },+ ),+ exports,+ "rea-native-exports",+ "inspect_native_exports",+ signal,+ ),+ );+ }),+ });const service = createBinaryLayoutService(environment);cli.command(CLI_COMMANDS.inspectBinaryLayout, {description:diff --git a/src/cliCommandNames.ts b/src/cliCommandNames.tsindex 45b847f37..f9b549ea1 100644--- a/src/cliCommandNames.ts+++ b/src/cliCommandNames.ts@@ -66,6 +66,7 @@ export const CLI_COMMANDS = Object.freeze({inspectGpuCodeObjects: "inspect-gpu-code-objects",inspectRustBinary: "inspect-rust-binary",inspectPeResources: "inspect-pe-resources",+ inspectNativeExports: "inspect-native-exports",inspectElfNotes: "inspect-elf-notes",inspectAnalysisView: "inspect-analysis-view",listFridaDevices: "list-frida-devices",diff --git a/src/composition/binaryDiagnostics.ts b/src/composition/binaryDiagnostics.tsindex e17ed4e22..ff7f51931 100644--- a/src/composition/binaryDiagnostics.ts+++ b/src/composition/binaryDiagnostics.ts@@ -8,11 +8,16 @@ import { PeResourcesProvider } from "../native/pe/PeResourcesProvider.js";import { ElfNotesService } from "../application/binaryDiagnostics/ElfNotesService.js";import { ElfNotesProvider } from "../native/elf/ElfNotesProvider.js";import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import { NativeExportsService } from "../application/binaryDiagnostics/NativeExportsService.js";+import { NativeExportsProvider } from "../native/exports/NativeExportsProvider.js";/** Portable PE inspection with no engine, installation or target acquisition. */export const createPeResourcesService = (): PeResourcesService =>new PeResourcesService(new PeResourcesProvider());+/** Portable PE/ELF export tables with no engine, toolchain or target acquisition. */+export const createNativeExportsService = (): NativeExportsService =>+ new NativeExportsService(new NativeExportsProvider());/** Portable ELF note-table inspection with no engine or package catalog. */export const createElfNotesService = (): ElfNotesService =>new ElfNotesService(new ElfNotesProvider());diff --git a/src/contracts/native/binaryDiagnosticsToolContracts.ts b/src/contracts/native/binaryDiagnosticsToolContracts.tsindex 9c63f3aa5..1c7728f2a 100644--- a/src/contracts/native/binaryDiagnosticsToolContracts.ts+++ b/src/contracts/native/binaryDiagnosticsToolContracts.ts@@ -14,6 +14,10 @@ import {analysisDetailOutputSchemaOf,analysisDetailSchema,} from "../analysisDetail.js";+import {+ inspectNativeExportsInputSchema,+ nativeExportsSchema,+} from "../../domain/native/nativeExports.js";import type { ToolContract } from "../toolContractTypes.js";import { toolContractMetadata } from "../toolEffects.js";import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";@@ -95,6 +99,21 @@ export const BINARY_DIAGNOSTICS_TOOL_CONTRACTS = [},],},+ {+ name: "inspect_native_exports",+ ...toolContractMetadata("inspect_native_exports"),+ kind: "native-provider",+ description:+ "Inspect one explicit local PE or ELF image's export table without executing it or opening an engine: PE export-directory names, ordinals, addresses and forwarders, or ELF defined default/protected global, weak and unique .dynsym symbols with type, binding and symbol version. Ordinal-only, forwarded and hidden-version exports stay distinct. Portable on any supported host. Coverage is partial when table entries are unreadable and unsupported for an ELF without section headers; an empty complete inventory means the image declares no exports. Mach-O exports use inspect_macho.",+ inputSchema: inspectNativeExportsInputSchema,+ outputSchema: evidenceResultOf(nativeExportsSchema),+ examples: [+ {+ title: "List a native library's exports",+ input: { path: "/artifacts/native/libexample.so" },+ },+ ],+ },{name: "inspect_binary_layout",...toolContractMetadata("inspect_binary_layout"),diff --git a/src/contracts/toolEffects.test.ts b/src/contracts/toolEffects.test.tsindex 8c448d908..8cd30a7be 100644--- a/src/contracts/toolEffects.test.ts+++ b/src/contracts/toolEffects.test.ts@@ -27,6 +27,7 @@ const EXECUTION_WORDING_EXCEPTIONS: Readonly<Record<string, string>> = {resolve_native_call_targets: "states that it does not execute code",inspect_byte_entropy: "states that it profiles the file without execution",inspect_pe_resources: "states that it does not execute the image",+ inspect_native_exports: "reads the export table without executing it",inspect_elf_notes: "states that it does not execute the image",inspect_desktop_application:"states that directory triage performs no target execution",diff --git a/src/contracts/toolEffects.ts b/src/contracts/toolEffects.tsindex 8a855a285..6c3b21d5c 100644--- a/src/contracts/toolEffects.ts+++ b/src/contracts/toolEffects.ts@@ -253,6 +253,7 @@ export const TOOL_EFFECTS: Readonly<Record<string, ToolEffects>> = {}),inspect_byte_entropy: evidence,inspect_pe_resources: evidence,+ inspect_native_exports: evidence,inspect_elf_notes: evidence,inspect_analysis_view: evidence,inspect_firmware_regions: effects({diff --git a/src/domain/native/nativeExports.ts b/src/domain/native/nativeExports.tsnew file mode 100644index 000000000..e258c919f--- /dev/null+++ b/src/domain/native/nativeExports.ts@@ -0,0 +1,128 @@+import { z } from "zod";++import { absoluteLocalPathStringSchema } from "../localPath.js";++const uint = z.number().int().min(0).max(0xffffffff);+const address = z.string().regex(/^0x[0-9a-f]+$/u);++/** Hard ceiling on the caller-selected input read budget. */+export const MAX_INSPECT_NATIVE_EXPORTS_FILE_BYTES = 536870912;+/** Fixed bound on reported export rows, so one library cannot flood a reply. */+export const MAX_NATIVE_EXPORT_ROWS = 262144;++/** One explicitly selected PE or ELF library or executable. */+export const inspectNativeExportsInputSchema = z.strictObject({+ path: absoluteLocalPathStringSchema.describe(+ "Absolute filesystem path to a PE or ELF image",+ ),+ max_file_bytes: z+ .number()+ .int()+ .min(64)+ .max(MAX_INSPECT_NATIVE_EXPORTS_FILE_BYTES)+ .default(268435456)+ .describe("Maximum stable artifact bytes to read (default 256 MiB)"),+});+export type InspectNativeExportsInput = z.infer<+ typeof inspectNativeExportsInputSchema+>;++/**+ * One PE export-address-table slot as the export directory states it. A+ * forwarder has no address in this image; an ordinal-only export has no name.+ */+const peExportSchema = z.strictObject({+ name: z.string().min(1).nullable(),+ ordinal: z.number().int().min(0).max(0xffff),+ address: address.nullable(),+ forwarder: z.string().min(1).nullable(),+});++/**+ * One defined, default- or protected-visibility global, weak or unique+ * dynamic symbol. `version` is null when the symbol carries no version and+ * "unknown" when the version table could not be read; a hidden version is not+ * the default one a by-name lookup selects.+ */+const elfExportSchema = z.strictObject({+ name: z.string().min(1),+ /** `st_value` as stored; on 32-bit ARM, bit 0 of a function marks Thumb code. */+ value: address,+ size: z.string().regex(/^[0-9]+$/u),+ type: z.enum(["function", "ifunc", "object", "tls", "other"]),+ binding: z.enum(["global", "weak", "unique"]),+ version: z.union([+ z.null(),+ z.literal("unknown"),+ z.strictObject({+ index: z.number().int().min(2).max(0x7fff),+ name: z.string().min(1).nullable(),+ hidden: z.boolean(),+ }),+ ]),+});++/** Parsed table issue; rows it affects are counted, not silently dropped. */+const nativeExportIssueSchema = z.strictObject({+ code: z.enum([+ "malformed_entry",+ "name_unreadable",+ "version_unresolved",+ "table_unavailable",+ ]),+ location: z.string().min(1).nullable(),+ message: z.string().min(1),+});++const artifactSchema = z.strictObject({+ path: z.string().min(1),+ sha256: z.string().regex(/^[a-f0-9]{64}$/u),+ bytes: uint,+});++const coverageSchema = z.strictObject({+ /** complete: every table entry was read; partial: issues name the gaps. */+ status: z.enum(["complete", "partial", "unsupported"]),+ reason: z.string().min(1).nullable(),+ examined_entries: uint,+ exports: uint,+});++/** Static export inventory of one PE or ELF image, read without execution. */+export const nativeExportsSchema = z.discriminatedUnion("format", [+ z.strictObject({+ artifact: artifactSchema,+ format: z.literal("pe"),+ architecture: z.string().min(1),+ bits: z.union([z.literal(32), z.literal(64)]),+ /** Null when the image declares no export directory. */+ export_directory: z+ .strictObject({+ rva: uint,+ size: uint,+ dll_name: z.string().nullable(),+ ordinal_base: uint,+ timestamp: uint,+ })+ .nullable(),+ exports: z.array(peExportSchema).max(MAX_NATIVE_EXPORT_ROWS),+ coverage: coverageSchema,+ issues: z.array(nativeExportIssueSchema),+ limitations: z.array(z.string().min(1)),+ }),+ z.strictObject({+ artifact: artifactSchema,+ format: z.literal("elf"),+ architecture: z.string().min(1),+ bits: z.union([z.literal(32), z.literal(64)]),+ byte_order: z.enum(["little", "big"]),+ exports: z.array(elfExportSchema).max(MAX_NATIVE_EXPORT_ROWS),+ coverage: coverageSchema,+ issues: z.array(nativeExportIssueSchema),+ limitations: z.array(z.string().min(1)),+ }),+]);+export type NativeExports = z.infer<typeof nativeExportsSchema>;+export type PeExport = z.infer<typeof peExportSchema>;+export type ElfExport = z.infer<typeof elfExportSchema>;+export type NativeExportIssue = z.infer<typeof nativeExportIssueSchema>;diff --git a/src/native/exports/NativeExportParser.test.ts b/src/native/exports/NativeExportParser.test.tsnew file mode 100644index 000000000..32b934a92--- /dev/null+++ b/src/native/exports/NativeExportParser.test.ts@@ -0,0 +1,367 @@+import { describe, expect, it } from "vitest";++import {+ elfExportImage,+ peExportImage,+} from "../../../tests/fixtures/binaryDiagnostics/nativeExports.js";+import { nativeExportsSchema } from "../../domain/native/nativeExports.js";+import {+ BinaryFormatFailure,+ BinaryResourceFailure,+} from "../metadata/BinaryContainer.js";+import { parseNativeExports } from "./NativeExportParser.js";++const artifact = { path: "/fixture/lib", sha256: "a".repeat(64), bytes: 1 };+const parse = (bytes: Buffer) =>+ nativeExportsSchema.parse(parseNativeExports(bytes, artifact));++describe("PE export directories", () => {+ it.each([32, 64] as const)(+ "reports named, aliased, ordinal-only and forwarded PE%d exports",+ (bits) => {+ const result = parse(+ peExportImage({+ bits,+ ordinalBase: 5,+ functions: [+ { rva: 0x2000 },+ { rva: 0x2010 },+ null,+ { forwarder: "OTHER.Target" },+ ],+ names: [+ { name: "Alias", index: 0 },+ { name: "Forwarded", index: 3 },+ { name: "Primary", index: 0 },+ ],+ }),+ );+ const base = bits === 64 ? 0x180000000 : 0x10000000;++ expect(result).toMatchObject({+ format: "pe",+ bits,+ export_directory: {+ rva: 0x1000,+ size: 0x200,+ dll_name: "fixture.dll",+ ordinal_base: 5,+ },+ coverage: {+ status: "complete",+ examined_entries: 4,+ exports: 4,+ },+ issues: [],+ });+ expect(result.exports).toEqual([+ {+ name: "Alias",+ ordinal: 5,+ address: `0x${(base + 0x2000).toString(16)}`,+ forwarder: null,+ },+ {+ name: "Primary",+ ordinal: 5,+ address: `0x${(base + 0x2000).toString(16)}`,+ forwarder: null,+ },+ {+ name: null,+ ordinal: 6,+ address: `0x${(base + 0x2010).toString(16)}`,+ forwarder: null,+ },+ {+ name: "Forwarded",+ ordinal: 8,+ address: null,+ forwarder: "OTHER.Target",+ },+ ]);+ },+ );++ it("counts unreadable and out-of-range names without inventing exports", () => {+ const result = parse(+ peExportImage({+ functions: [{ rva: 0x2000 }, { rva: 0x2010 }],+ names: [+ { name: "Unmapped", index: 0 },+ { name: "Stray", index: 9 },+ { name: "Kept", index: 1 },+ ],+ nameRvaOverride: { position: 0, rva: 0x9000 },+ }),+ );++ expect(result.exports.map(({ name }) => name)).toEqual(["Kept"]);+ expect(result.coverage).toMatchObject({ status: "partial", exports: 1 });+ expect(result.issues.map(({ code }) => code)).toEqual([+ "name_unreadable",+ "malformed_entry",+ ]);+ });++ it("reports an image without an export directory as exporting nothing", () => {+ const result = parse(peExportImage({ exportDirectory: false }));++ expect(result).toMatchObject({+ export_directory: null,+ exports: [],+ coverage: { status: "complete", examined_entries: 0 },+ });+ expect(result.limitations[0]).toContain("declares no export directory");+ });++ it("refuses ordinals beyond the 16-bit ordinal space", () => {+ expect(() =>+ parseNativeExports(+ peExportImage({+ functions: [{ rva: 0x2000 }],+ ordinalBase: 0xffff + 1,+ }),+ artifact,+ ),+ ).toThrow("16-bit ordinals");+ });++ it("refuses an export table above the inventory allowance", () => {+ expect(() =>+ parseNativeExports(+ peExportImage({ functions: [], declaredFunctions: 0x40001 }),+ artifact,+ ),+ ).toThrow(BinaryResourceFailure);+ });+});++describe("ELF dynamic symbol exports", () => {+ const symbols = [+ { name: "plain_fn" },+ { name: "versioned_fn", version: 2 },+ { name: "old_fn", version: 0x8003 },+ { name: "weak_obj", binding: 2, type: 1 },+ { name: "ifunc_sym", type: 10 },+ { name: "protected_fn", visibility: 3 },+ { name: "hidden_fn", visibility: 2 },+ { name: "undefined_fn", section: 0 },+ { name: "local_fn", binding: 0 },+ { name: "local_version_fn", version: 0 },+ ];++ it("lists defined default and protected globals with their versions", () => {+ const result = parse(+ elfExportImage({+ symbols,+ versionDefinitions: ["libfixture.so", "VER_1", "VER_0"],+ }),+ );++ expect(result).toMatchObject({+ format: "elf",+ bits: 64,+ byte_order: "little",+ architecture: "amd64",+ coverage: { status: "complete", examined_entries: 10, exports: 6 },+ issues: [],+ });+ expect(+ result.format === "elf" &&+ result.exports.map(({ name, type, binding, version }) => ({+ name,+ type,+ binding,+ version,+ })),+ ).toEqual([+ { name: "plain_fn", type: "function", binding: "global", version: null },+ {+ name: "versioned_fn",+ type: "function",+ binding: "global",+ version: { index: 2, name: "VER_1", hidden: false },+ },+ {+ name: "old_fn",+ type: "function",+ binding: "global",+ version: { index: 3, name: "VER_0", hidden: true },+ },+ { name: "weak_obj", type: "object", binding: "weak", version: null },+ { name: "ifunc_sym", type: "ifunc", binding: "global", version: null },+ {+ name: "protected_fn",+ type: "function",+ binding: "global",+ version: null,+ },+ ]);+ });++ it("reads a big-endian ELF32 table", () => {+ const result = parse(+ elfExportImage({+ bits: 32,+ little: false,+ machine: 20,+ symbols: [{ name: "be_fn", value: 0x10000n, size: 8n }],+ }),+ );++ expect(result).toMatchObject({+ bits: 32,+ byte_order: "big",+ architecture: "ppc",+ exports: [{ name: "be_fn", value: "0x10000", size: "8" }],+ });+ });++ it("marks versions unknown when the version table does not fit", () => {+ const result = parse(+ elfExportImage({+ symbols: [{ name: "a" }, { name: "b", version: 2 }],+ versionDefinitions: ["lib.so", "V1"],+ truncatedVersions: true,+ }),+ );++ expect(+ result.format === "elf" && result.exports.map(({ version }) => version),+ ).toEqual(["unknown", "unknown"]);+ expect(result.coverage.status).toBe("partial");+ expect(result.issues).toMatchObject([{ code: "version_unresolved" }]);+ });++ it("reports one issue per undefined version index", () => {+ const result = parse(+ elfExportImage({+ symbols: [+ { name: "a", version: 7 },+ { name: "b", version: 7 },+ ],+ versionDefinitions: ["lib.so"],+ }),+ );++ expect(+ result.format === "elf" && result.exports.map(({ version }) => version),+ ).toEqual([+ { index: 7, name: null, hidden: false },+ { index: 7, name: null, hidden: false },+ ]);+ expect(result.issues).toHaveLength(1);+ });++ it("counts a symbol whose name is outside the string table", () => {+ const result = parse(+ elfExportImage({+ symbols: [{ name: "kept" }, { name: "lost", nameOffset: 0x7000 }],+ }),+ );++ expect(result.exports.map(({ name }) => name)).toEqual(["kept"]);+ expect(result.issues).toMatchObject([{ code: "name_unreadable" }]);+ expect(result.coverage.status).toBe("partial");+ });++ it("separates no dynamic symbols from unread section headers", () => {+ expect(+ parse(elfExportImage({ symbols: [], dynamicSymbols: false })),+ ).toMatchObject({ exports: [], coverage: { status: "complete" } });+ expect(+ parse(elfExportImage({ symbols: [], sectionHeaders: false })),+ ).toMatchObject({+ exports: [],+ coverage: {+ status: "unsupported",+ reason: expect.stringContaining("no section headers"),+ },+ });+ });+});++describe("export inventory review regressions", () => {+ it("reads an export directory stored in the PE headers", () => {+ const result = parse(+ peExportImage({+ inHeaders: true,+ functions: [{ rva: 0x2000 }, { forwarder: "OTHER.Target" }],+ names: [+ { name: "HeaderExport", index: 0 },+ { name: "HeaderForward", index: 1 },+ ],+ }),+ );++ expect(result).toMatchObject({+ export_directory: { rva: 0x200, dll_name: "fixture.dll" },+ coverage: { status: "complete", exports: 2 },+ });+ expect(result.exports.map(({ name }) => name)).toEqual([+ "HeaderExport",+ "HeaderForward",+ ]);+ });++ it("bounds retained name text before storing rows", () => {+ // 300 rows naming one 60000-byte string retain about 18 MB of text.+ const long = "n".repeat(60000);+ const bytes = elfExportImage({+ symbols: Array.from({ length: 300 }, () => ({ name: long })),+ });++ expect(bytes.length).toBeLessThan(100_000);+ expect(() => parseNativeExports(bytes, artifact)).toThrow(+ BinaryResourceFailure,+ );+ });++ it("keeps exports when the version table lies outside the file", () => {+ const result = parse(+ elfExportImage({+ symbols: [{ name: "a" }, { name: "b", version: 2 }],+ versionDefinitions: ["lib.so", "V1"],+ versionsOutsideFile: true,+ }),+ );++ expect(+ result.format === "elf" && result.exports.map(({ version }) => version),+ ).toEqual(["unknown", "unknown"]);+ expect(result.coverage.status).toBe("partial");+ });++ it("reports an empty version name as unresolved", () => {+ const result = parse(+ elfExportImage({+ symbols: [{ name: "a", version: 2 }],+ versionDefinitions: ["lib.so", ""],+ }),+ );++ expect(+ result.format === "elf" && result.exports.map(({ version }) => version),+ ).toEqual([{ index: 2, name: null, hidden: false }]);+ expect(result.issues).toMatchObject([{ code: "version_unresolved" }]);+ expect(result.coverage.status).toBe("partial");+ });++ it("rejects a dynamic symbol table without its null entry", () => {+ expect(() =>+ parseNativeExports(+ elfExportImage({ symbols: [], emptyDynamicSymbols: true }),+ artifact,+ ),+ ).toThrow(BinaryFormatFailure);+ });+});++it("refuses formats other than PE and ELF", () => {+ const macho = Buffer.alloc(64);+ macho.writeUInt32LE(0xfeedfacf, 0);+ expect(() => parseNativeExports(macho, artifact)).toThrow(+ BinaryFormatFailure,+ );+});diff --git a/src/native/exports/NativeExportParser.ts b/src/native/exports/NativeExportParser.tsnew file mode 100644index 000000000..a6bbede25--- /dev/null+++ b/src/native/exports/NativeExportParser.ts@@ -0,0 +1,502 @@+import {+ BinaryFormatFailure,+ BinaryReader,+ BinaryResourceFailure,+ mappedFileOffset,+} from "../metadata/BinaryContainer.js";+import { architectureForElfMachine } from "../metadata/ElfImage.js";+import { readElfString, readElfSymbol } from "../metadata/ElfSymbol.js";+import {+ readNativeDirectoryFromBuffer,+ type NativeSection,+} from "../metadata/NativeSectionDirectory.js";+import { readPeImage } from "../metadata/PeImage.js";+import {+ MAX_NATIVE_EXPORT_ROWS,+ type ElfExport,+ type NativeExportIssue,+ type NativeExports,+ type PeExport,+} from "../../domain/native/nativeExports.js";++type Artifact = NativeExports["artifact"];++const SHT_STRTAB = 3;+const SHT_DYNSYM = 11;+const SHT_GNU_VERDEF = 0x6ffffffd;+const SHT_GNU_VERSYM = 0x6fffffff;+const PE_EXPORT_DIRECTORY = 0;+const PE_EXPORT_DIRECTORY_BYTES = 40;+const MAXIMUM_NAME_BYTES = 4096;+/** Text retained across all rows; names can repeat one long string table entry. */+const MAXIMUM_RETAINED_TEXT_BYTES = 16 * 1024 * 1024;++/** Charge every retained row and its text before it is stored. */+const createRetention = () => {+ let rows = 0;+ let text = 0;+ return (...strings: readonly (string | null)[]): void => {+ rows++;+ rowBudget(rows, "Export inventory");+ for (const value of strings) text += value?.length ?? 0;+ if (text > MAXIMUM_RETAINED_TEXT_BYTES)+ throw new BinaryResourceFailure(+ "structure",+ MAXIMUM_RETAINED_TEXT_BYTES,+ `Export names exceed the ${String(MAXIMUM_RETAINED_TEXT_BYTES)}-byte retained-text allowance`,+ );+ };+};++const hex = (value: bigint | number) => `0x${value.toString(16)}`;++const rowBudget = (count: number, label: string): void => {+ if (count > MAX_NATIVE_EXPORT_ROWS)+ throw new BinaryResourceFailure(+ "structure",+ MAX_NATIVE_EXPORT_ROWS,+ `${label} declares ${String(count)} entries, above the ${String(MAX_NATIVE_EXPORT_ROWS)}-entry export inventory allowance`,+ );+};++const coverage = (+ issues: readonly NativeExportIssue[],+ examined: number,+ exports: number,+): NativeExports["coverage"] =>+ issues.length === 0+ ? { status: "complete", reason: null, examined_entries: examined, exports }+ : {+ status: "partial",+ reason: `${String(issues.length)} export table issue(s) left entries unreported; see issues`,+ examined_entries: examined,+ exports,+ };++const failureMessage = (cause: unknown): string => {+ if (cause instanceof BinaryFormatFailure) return cause.message;+ throw cause;+};++const PE_LIMITATIONS = [+ "Rows reproduce the PE export directory; they do not establish that an export is reachable, safe to call or loaded at runtime.",+ "Forwarded exports resolve in another DLL, which is not opened; ordinal-only exports have no name in this image.",+];++/** Read the PE export directory: every used address-table slot and its names. */+const parsePeExports = (bytes: Buffer, artifact: Artifact): NativeExports => {+ const image = readPeImage(bytes);+ const base = image.image_base ?? 0n;+ const directory = image.pe_data_directories?.[PE_EXPORT_DIRECTORY];+ const result = {+ artifact,+ format: "pe" as const,+ architecture: image.architecture,+ bits: image.bits,+ };+ if (directory === undefined || directory.virtual_address === 0)+ return {+ ...result,+ export_directory: null,+ exports: [],+ coverage: coverage([], 0, 0),+ issues: [],+ limitations: [+ "The image declares no export directory, so it exports nothing by name or ordinal.",+ ...PE_LIMITATIONS,+ ],+ };+ const reader = new BinaryReader(bytes, true);+ const mappings =+ image.pe_header_mapping === undefined+ ? image.mappings+ : [image.pe_header_mapping, ...image.mappings];+ const map = (rva: number, size: number): number =>+ mappedFileOffset(mappings, base + BigInt(rva), size, image.zero_fills);+ const cString = (rva: number): string => {+ const start = map(rva, 1);+ const end = bytes+ .subarray(start, start + MAXIMUM_NAME_BYTES + 1)+ .indexOf(0);+ if (end <= 0)+ throw new BinaryFormatFailure(+ "malformed",+ `Export name at RVA ${hex(rva)} is empty, unterminated or longer than ${String(MAXIMUM_NAME_BYTES)} bytes`,+ );+ // The whole string must stay inside one file-backed mapping.+ map(rva, end + 1);+ return bytes.toString("latin1", start, start + end);+ };++ const header = map(directory.virtual_address, PE_EXPORT_DIRECTORY_BYTES);+ const ordinalBase = reader.u32(header + 16);+ const functionCount = reader.u32(header + 20);+ const nameCount = reader.u32(header + 24);+ rowBudget(functionCount, "PE export address table");+ if (ordinalBase + functionCount > 0x10000)+ throw new BinaryFormatFailure(+ "malformed",+ "PE export ordinal base and address-table size exceed 16-bit ordinals",+ );+ rowBudget(nameCount, "PE export name table");+ const functions =+ functionCount === 0 ? 0 : map(reader.u32(header + 28), functionCount * 4);+ const names =+ nameCount === 0 ? 0 : map(reader.u32(header + 32), nameCount * 4);+ const ordinals =+ nameCount === 0 ? 0 : map(reader.u32(header + 36), nameCount * 2);+ const issues: NativeExportIssue[] = [];+ let dllName: string | null = null;+ try {+ dllName = cString(reader.u32(header + 12));+ } catch (cause) {+ issues.push({+ code: "name_unreadable",+ location: hex(reader.u32(header + 12)),+ message: `Export directory DLL name: ${failureMessage(cause)}`,+ });+ }++ const namesByFunction = new Map<number, string[]>();+ const namedFunctions = new Set<number>();+ for (let index = 0; index < nameCount; index++) {+ const functionIndex = reader.u16(ordinals + index * 2);+ const nameRva = reader.u32(names + index * 4);+ if (functionIndex >= functionCount) {+ issues.push({+ code: "malformed_entry",+ location: hex(nameRva),+ message: `Export name ${String(index)} selects address-table slot ${String(functionIndex)}, outside its ${String(functionCount)} slots`,+ });+ continue;+ }+ namedFunctions.add(functionIndex);+ try {+ const list = namesByFunction.get(functionIndex) ?? [];+ list.push(cString(nameRva));+ namesByFunction.set(functionIndex, list);+ } catch (cause) {+ issues.push({+ code: "name_unreadable",+ location: hex(nameRva),+ message: failureMessage(cause),+ });+ }+ }++ const forwarderEnd = directory.virtual_address + directory.size;+ const retain = createRetention();+ const exports: PeExport[] = [];+ for (let index = 0; index < functionCount; index++) {+ const rva = reader.u32(functions + index * 4);+ // A zero slot is an unused ordinal, not an export.+ if (rva === 0) continue;+ const ordinal = ordinalBase + index;+ let target: Pick<PeExport, "address" | "forwarder">;+ if (rva >= directory.virtual_address && rva < forwarderEnd) {+ try {+ target = { address: null, forwarder: cString(rva) };+ } catch (cause) {+ issues.push({+ code: "malformed_entry",+ location: hex(rva),+ message: `Forwarder of ordinal ${String(ordinal)}: ${failureMessage(cause)}`,+ });+ continue;+ }+ } else target = { address: hex(base + BigInt(rva)), forwarder: null };+ const exportNames = namesByFunction.get(index);+ if (exportNames !== undefined)+ for (const name of exportNames) {+ retain(name, target.forwarder);+ exports.push({ name, ordinal, ...target });+ }+ // A slot whose only name was unreadable is reported through its issue.+ else if (!namedFunctions.has(index)) {+ retain(target.forwarder);+ exports.push({ name: null, ordinal, ...target });+ }+ }+ return {+ ...result,+ export_directory: {+ rva: directory.virtual_address,+ size: directory.size,+ dll_name: dllName,+ ordinal_base: ordinalBase,+ timestamp: reader.u32(header + 4),+ },+ exports,+ coverage: coverage(issues, functionCount, exports.length),+ issues,+ limitations: PE_LIMITATIONS,+ };+};++const ELF_LIMITATIONS = [+ "Rows list defined default- or protected-visibility global, weak and unique dynamic symbols; local, hidden, internal and undefined symbols are not exports.",+ "A hidden symbol version is not the default version that a by-name dlsym lookup selects.",+ "Rows reproduce the dynamic symbol table; they do not establish that a symbol is reachable, safe to call or loaded at runtime.",+];++const ELF_TYPES: Readonly<Record<number, ElfExport["type"]>> = {+ 1: "object",+ 2: "function",+ 6: "tls",+ 10: "ifunc",+};+const ELF_BINDINGS: Readonly<Record<number, ElfExport["binding"]>> = {+ 1: "global",+ 2: "weak",+ 10: "unique",+};++/** Version definitions by index, read from `.gnu.version_d`. */+const readVersionDefinitions = (+ reader: BinaryReader,+ sections: readonly NativeSection[],+ issues: NativeExportIssue[],+): Map<number, string> => {+ const definitions = new Map<number, string>();+ const verdef = sections.find(({ type }) => type === SHT_GNU_VERDEF);+ if (verdef === undefined) return definitions;+ try {+ const strings = sections[verdef.link];+ if (strings?.type !== SHT_STRTAB)+ throw new BinaryFormatFailure(+ "malformed",+ "Version definitions do not link to a string table",+ );+ const names = reader.fileRange(+ strings.offset,+ strings.size,+ "Version strings",+ );+ const nameBytes = reader.bytes.subarray(+ names.offset,+ names.offset + names.size,+ );+ const table = reader.fileRange(+ verdef.offset,+ verdef.size,+ "Version definitions",+ );+ let offset = 0;+ for (let index = 0; index < verdef.info; index++) {+ if (offset + 20 > table.size)+ throw new BinaryFormatFailure(+ "malformed",+ "Version definition chain leaves its section",+ );+ const at = table.offset + offset;+ const versionIndex = reader.u16(at + 4) & 0x7fff;+ const aux = reader.u32(at + 12);+ const next = reader.u32(at + 16);+ if (aux < 20 || offset + aux + 8 > table.size)+ throw new BinaryFormatFailure(+ "malformed",+ "Version definition name entry leaves its section",+ );+ definitions.set(+ versionIndex,+ readElfString(nameBytes, reader.u32(at + aux)),+ );+ if (next === 0) break;+ offset += next;+ }+ } catch (cause) {+ issues.push({+ code: "version_unresolved",+ location: hex(verdef.offset),+ message: `Version definitions: ${failureMessage(cause)}`,+ });+ }+ return definitions;+};++/** Read defined exported entries of `.dynsym` with their symbol versions. */+const parseElfExports = (bytes: Buffer, artifact: Artifact): NativeExports => {+ const directory = readNativeDirectoryFromBuffer(bytes, "elf");+ const reader = new BinaryReader(bytes, directory.little);+ const result = {+ artifact,+ format: "elf" as const,+ architecture: architectureForElfMachine(directory.machine),+ bits: directory.bits,+ byte_order: directory.little ? ("little" as const) : ("big" as const),+ };+ const { sections } = directory;+ if (sections.length === 0)+ return {+ ...result,+ exports: [],+ coverage: {+ status: "unsupported",+ reason:+ "The ELF has no section headers; enumerating dynamic symbols from the dynamic segment is not implemented",+ examined_entries: 0,+ exports: 0,+ },+ issues: [],+ limitations: ELF_LIMITATIONS,+ };+ const dynsym = sections.find(({ type }) => type === SHT_DYNSYM);+ if (dynsym === undefined)+ return {+ ...result,+ exports: [],+ coverage: coverage([], 0, 0),+ issues: [],+ limitations: [+ "The ELF has no dynamic symbol table, so it exports no dynamic symbols.",+ ...ELF_LIMITATIONS,+ ],+ };+ const width = directory.bits === 64 ? 24 : 16;+ const strings = sections[dynsym.link];+ if (+ dynsym.entry_size !== BigInt(width) ||+ dynsym.size % BigInt(width) !== 0n ||+ // The table must hold at least its mandatory null symbol.+ dynsym.size < BigInt(width) ||+ strings?.type !== SHT_STRTAB+ )+ throw new BinaryFormatFailure(+ "malformed",+ "ELF dynamic symbol table entry size, length, null entry or string-table link is invalid",+ );+ const count = Number(dynsym.size / BigInt(width));+ rowBudget(count, "ELF dynamic symbol table");+ const table = reader.table(+ dynsym.offset,+ count,+ width,+ "ELF dynamic symbols",+ );+ const nameRange = reader.fileRange(+ strings.offset,+ strings.size,+ "ELF dynamic strings",+ );+ const names = bytes.subarray(+ nameRange.offset,+ nameRange.offset + nameRange.size,+ );+ const issues: NativeExportIssue[] = [];+ const versym = sections.find(+ ({ type, link }) => type === SHT_GNU_VERSYM && link === dynsym.index,+ );+ let versions: number | null = null;+ if (versym !== undefined) {+ try {+ if (versym.size !== BigInt(count * 2))+ throw new BinaryFormatFailure(+ "malformed",+ `Symbol version table has ${String(versym.size)} bytes for ${String(count)} symbols`,+ );+ versions = reader.table(versym.offset, count, 2, "ELF symbol versions");+ } catch (cause) {+ // Keep every export; their versions become unknown.+ issues.push({+ code: "version_unresolved",+ location: hex(versym.offset),+ message: failureMessage(cause),+ });+ }+ }+ const definitions = readVersionDefinitions(reader, sections, issues);+ const unresolvedVersions = new Set<number>();+ const retain = createRetention();+ const exports: ElfExport[] = [];+ for (let index = 1; index < count; index++) {+ const at = table + index * width;+ const symbol = readElfSymbol(+ bytes.subarray(at, at + width),+ directory.bits,+ directory.little,+ );+ const binding = ELF_BINDINGS[symbol.binding];+ const visibility = symbol.other & 3;+ // Undefined, local and hidden/internal symbols are not exports.+ if (+ binding === undefined ||+ symbol.section_index === 0 ||+ (visibility !== 0 && visibility !== 3)+ )+ continue;+ let version: ElfExport["version"] = null;+ if (versym !== undefined && versions === null) version = "unknown";+ else if (versions !== null) {+ const raw = reader.u16(versions + index * 2);+ const versionIndex = raw & 0x7fff;+ if (versionIndex === 0) continue;+ if (versionIndex >= 2) {+ const defined = definitions.get(versionIndex);+ const name = defined === undefined || defined === "" ? null : defined;+ if (name === null && !unresolvedVersions.has(versionIndex)) {+ unresolvedVersions.add(versionIndex);+ issues.push({+ code: "version_unresolved",+ location: hex(symbol.value),+ message: `Version index ${String(versionIndex)}, first used by symbol ${String(index)}, has no named version definition`,+ });+ }+ version = {+ index: versionIndex,+ name,+ hidden: (raw & 0x8000) !== 0,+ };+ }+ }+ let name: string;+ try {+ name = readElfString(names, symbol.name_offset);+ } catch (cause) {+ issues.push({+ code: "name_unreadable",+ location: hex(symbol.value),+ message: `Dynamic symbol ${String(index)}: ${failureMessage(cause)}`,+ });+ continue;+ }+ if (name === "") {+ issues.push({+ code: "name_unreadable",+ location: hex(symbol.value),+ message: `Defined global dynamic symbol ${String(index)} has an empty name`,+ });+ continue;+ }+ retain(name, typeof version === "object" ? (version?.name ?? null) : null);+ exports.push({+ name,+ value: hex(symbol.value),+ size: symbol.size.toString(),+ type: ELF_TYPES[symbol.type] ?? "other",+ binding,+ version,+ });+ }+ return {+ ...result,+ exports,+ coverage: coverage(issues, count - 1, exports.length),+ issues,+ limitations: ELF_LIMITATIONS,+ };+};++/** Static export inventory of one PE or ELF image; other formats are unsupported. */+export const parseNativeExports = (+ bytes: Buffer,+ artifact: Artifact,+): NativeExports => {+ if (bytes.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46])))+ return parseElfExports(bytes, artifact);+ if (bytes.subarray(0, 2).equals(Buffer.from("MZ")))+ return parsePeExports(bytes, artifact);+ throw new BinaryFormatFailure(+ "unsupported",+ "Only PE and ELF images are supported; inspect Mach-O exports with inspect_macho",+ );+};diff --git a/src/native/exports/NativeExportsProvider.ts b/src/native/exports/NativeExportsProvider.tsnew file mode 100644index 000000000..49291eee8--- /dev/null+++ b/src/native/exports/NativeExportsProvider.ts@@ -0,0 +1,212 @@+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";+import {+ ArtifactFileCleanupFailure,+ assertArtifactReadActive,+ bindArtifactFileCleanup,+ artifactFileCancellationCause,+} from "../../artifacts/ArtifactFileOperation.js";+import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";+import { analysisErrorWithCleanupFailure } from "../../domain/analysisErrorCleanup.js";+import type { NativeExportsPort } from "../../application/binaryDiagnostics/NativeExportsPort.js";+import type { ExecutionOptions } from "../../application/AnalysisProvider.js";+import { AnalysisError } from "../../domain/analysisErrorBase.js";+import {+ AnalysisAccessDeniedError,+ AnalysisArtifactChangedError,+ AnalysisCancelledError,+ AnalysisInputError,+ AnalysisResourceConstraintError,+ AnalysisUnsupportedTargetError,+} from "../../domain/analysisErrorCore.js";+import { fixedAllowanceOptions } from "../../domain/fixedAllowanceRemediation.js";+import {+ MAX_INSPECT_NATIVE_EXPORTS_FILE_BYTES,+ type InspectNativeExportsInput,+} from "../../domain/native/nativeExports.js";+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";+import { err, ok } from "../../domain/result.js";+import { NATIVE_EXPORTS_PROVIDER } from "../../application/InvestigationProviders.js";+import {+ BinaryFormatFailure,+ BinaryResourceFailure,+} from "../metadata/BinaryContainer.js";+import { parseNativeExports } from "./NativeExportParser.js";++const OPERATION = "inspect_native_exports";++/** Portable export-table reader over one bounded, identity-checked regular file. */+export class NativeExportsProvider implements NativeExportsPort {+ readonly identity = NATIVE_EXPORTS_PROVIDER;+ readonly #resources = new ArtifactResourceScope();++ async close(): Promise<void> {+ try {+ await this.#resources.close();+ } catch (cause: unknown) {+ if (+ !(cause instanceof ArtifactReaderFailure) ||+ cause.cleanup === undefined+ )+ throw cause;+ const error = new ProviderCleanupError(+ NATIVE_EXPORTS_PROVIDER.id,+ cause.cleanup.resources,+ { reason: cause.cleanup.reason },+ { cause, operation: OPERATION },+ );+ bindArtifactFileCleanup(cause, error);+ throw error;+ }+ }++ async inspect(input: InspectNativeExportsInput, options?: ExecutionOptions) {+ try {+ return await this.#resources.run(async () => {+ const snapshot = await readStableArtifact(+ input.path,+ input.max_file_bytes,+ options?.signal,+ undefined,+ this.#resources,+ );+ assertArtifactReadActive(options?.signal);+ const report = parseNativeExports(snapshot.bytes, {+ path: input.path,+ sha256: snapshot.sha256,+ bytes: snapshot.bytes.length,+ });+ assertArtifactReadActive(options?.signal);+ return ok(report);+ });+ } catch (cause) {+ return err(nativeExportsFailure(cause, input, options?.signal));+ }+ }+}++const fileSizeRemediation = (input: InspectNativeExportsInput): string =>+ input.max_file_bytes >= MAX_INSPECT_NATIVE_EXPORTS_FILE_BYTES+ ? `The image exceeds the ${String(MAX_INSPECT_NATIVE_EXPORTS_FILE_BYTES)}-byte input ceiling this operation accepts. This release has no runtime override. Select a smaller artifact.`+ : `Raise max_file_bytes above ${String(input.max_file_bytes)} bytes or select a smaller artifact; the limit is the caller-selected input read budget.`;++const nativeExportsFailurePrimary = (+ cause: unknown,+ input: InspectNativeExportsInput,+): AnalysisError => {+ if (cause instanceof AnalysisError) return cause;+ if (cause instanceof ArtifactReaderFailure && cause.reason === "integrity")+ return new AnalysisArtifactChangedError(+ OPERATION,+ input.path,+ cause.message,+ { cause },+ );+ if (cause instanceof ArtifactReaderFailure && cause.reason === "cancelled")+ return new AnalysisCancelledError(OPERATION, {+ cause: artifactFileCancellationCause(cause),+ });+ if (cause instanceof BinaryResourceFailure)+ return new AnalysisResourceConstraintError(+ OPERATION,+ "capacity",+ `Selected artifact ${input.path}: ${cause.message}`,+ { boundary: cause.boundary, maximum: cause.maximum_bytes },+ {+ cause,+ ...fixedAllowanceOptions(+ "The native export inventory allowance",+ "count",+ ),+ },+ );+ if (cause instanceof BinaryFormatFailure)+ return cause.kind === "unsupported"+ ? new AnalysisUnsupportedTargetError(+ OPERATION,+ input.path,+ cause.message,+ {+ cause,+ },+ )+ : new AnalysisInputError(OPERATION, { cause }, [+ {+ path: ["path"],+ reason: "invalid_format",+ message: `Selected artifact ${input.path}: ${cause.message}`,+ },+ ]);+ if (cause instanceof ArtifactReaderFailure) {+ if (cause.reason === "limit")+ return new AnalysisResourceConstraintError(+ OPERATION,+ "file-size",+ cause.message,+ { max_file_bytes: input.max_file_bytes },+ {+ cause,+ retryable: false,+ remediationAction: fileSizeRemediation(input),+ },+ );+ if (cause.reason === "path" || cause.reason === "format")+ return new AnalysisInputError(OPERATION, { cause }, [+ { path: ["path"], reason: "invalid_format", message: cause.message },+ ]);+ }+ if (cause instanceof Error && "code" in cause) {+ if (cause.code === "EACCES" || cause.code === "EPERM")+ return new AnalysisAccessDeniedError(OPERATION, input.path, cause.code, {+ cause,+ });+ if (+ ["ENOENT", "ENOTDIR", "ELOOP", "ENAMETOOLONG"].includes(+ String(cause.code),+ )+ )+ return new AnalysisInputError(OPERATION, { cause }, [+ {+ path: ["path"],+ reason: "invalid_value",+ message: `Selected image could not be read (${String(cause.code)}): ${input.path}.`,+ },+ ]);+ }+ return new ProviderAdapterError(NATIVE_EXPORTS_PROVIDER.id, OPERATION, {+ cause,+ diagnostics: {+ path: input.path,+ reason: cause instanceof Error ? cause.message : String(cause),+ },+ });+};++const nativeExportsFailure = (+ cause: unknown,+ input: InspectNativeExportsInput,+ signal: AbortSignal | undefined,+): AnalysisError => {+ const primary =+ cause instanceof ArtifactFileCleanupFailure &&+ cause.fileCleanupFailure.outcome.kind === "failed"+ ? nativeExportsFailurePrimary(+ cause.fileCleanupFailure.outcome.cause,+ input,+ )+ : cause instanceof ArtifactFileCleanupFailure && signal?.aborted+ ? new AnalysisCancelledError(OPERATION, { cause: signal.reason })+ : nativeExportsFailurePrimary(cause, input);+ if (!(cause instanceof ArtifactReaderFailure) || cause.cleanup === undefined)+ return primary;+ const cleanup = new ProviderCleanupError(+ NATIVE_EXPORTS_PROVIDER.id,+ cause.cleanup.resources,+ { reason: cause.cleanup.reason },+ { operation: OPERATION, cause },+ );+ const error = analysisErrorWithCleanupFailure(primary, cleanup, OPERATION);+ bindArtifactFileCleanup(cause, error);+ return error;+};diff --git a/src/native/metadata/BinaryContainer.ts b/src/native/metadata/BinaryContainer.tsindex 6d0766be2..fc063529c 100644--- a/src/native/metadata/BinaryContainer.ts+++ b/src/native/metadata/BinaryContainer.ts@@ -95,6 +95,16 @@ export interface BinaryContainer {readonly byte_order: "little" | "big";/** Declared PE preferred base, when available. */readonly image_base?: bigint;+ /**+ * File-backed PE headers (`SizeOfHeaders`, clipped to the file), which the+ * loader maps at the image base. Kept apart from section `mappings`.+ */+ readonly pe_header_mapping?: FileMapping;+ /** PE optional-header data directories, indexed as declared. */+ readonly pe_data_directories?: readonly {+ readonly virtual_address: number;+ readonly size: number;+ }[];/** Mach-O load-command observation, when available. */readonly macho_chained_fixups?: boolean;readonly mappings: readonly FileMapping[];diff --git a/src/native/metadata/ElfImage.ts b/src/native/metadata/ElfImage.tsindex 86a5251c8..1fba9c827 100644--- a/src/native/metadata/ElfImage.ts+++ b/src/native/metadata/ElfImage.ts@@ -104,7 +104,7 @@ export const readElfImage = (bytes: Buffer): BinaryContainer => {};/** Map ELF machine identifiers to stable architecture names. */-const architectureForElfMachine = (machine: number): string => {+export const architectureForElfMachine = (machine: number): string => {const names = new Map([[3, "386"],[8, "mips"],diff --git a/src/native/metadata/PeImage.ts b/src/native/metadata/PeImage.tsindex b68b1f6eb..bf36e6954 100644--- a/src/native/metadata/PeImage.ts+++ b/src/native/metadata/PeImage.ts@@ -82,7 +82,16 @@ export const readPeImage = (bytes: Buffer): BinaryContainer => {"malformed","PE data directories extend beyond the optional header",);+ const dataDirectories = Array.from({ length: directories }, (_, index) => {+ const entry = optional + directoriesOffset + index * 8;+ return { virtual_address: reader.u32(entry), size: reader.u32(entry + 4) };+ });const imageBase = reader.word(optional + (bits === 64 ? 24 : 28), bits);+ const headerMapping: FileMapping = {+ address: imageBase,+ offset: 0,+ size: Math.min(reader.u32(optional + 60), bytes.length),+ };const count = reader.u16(pe + 6);const start = reader.table(BigInt(optional + optionalSize),@@ -152,6 +161,8 @@ export const readPeImage = (bytes: Buffer): BinaryContainer => {return {format: "pe",image_base: imageBase,+ pe_data_directories: dataDirectories,+ pe_header_mapping: headerMapping,architecture: names.get(machine) ?? `pe-machine-${machine}`,bits,byte_order: "little",diff --git a/src/server/createServer.ts b/src/server/createServer.tsindex 4d81d8234..5b7feb6d8 100644--- a/src/server/createServer.ts+++ b/src/server/createServer.ts@@ -14,12 +14,15 @@ import { snapshotEnvironment } from "../process/snapshotEnvironment.js";import { captureProviderEnvironment } from "./providerEnvironment.js";import {createElfNotesService,+ createNativeExportsService,createPeResourcesService,} from "../composition/binaryDiagnostics.js";import type { ElfNotesService } from "../application/binaryDiagnostics/ElfNotesService.js";import type { PeResourcesService } from "../application/binaryDiagnostics/PeResourcesService.js";+import type { NativeExportsService } from "../application/binaryDiagnostics/NativeExportsService.js";import { registerElfNotesTool } from "./registerElfNotesTool.js";import { registerPeResourcesTool } from "./registerPeResourcesTool.js";+import { registerNativeExportsTool } from "./registerNativeExportsTool.js";import type { EvmInterfaceService } from "../application/evm/EvmInterfaceService.js";import {evmInterfaceModule,@@ -355,6 +358,7 @@ export const createServer = (const il2cppMetadata =options.il2cppMetadata ?? createIl2cppMetadataService();const peResources = createPeResourcesService();+ const nativeExports = createNativeExportsService();const elfNotes = createElfNotesService();const electronFuses = options.electronFuses ?? createElectronFuseService();const webNetworkCapture =@@ -457,6 +461,7 @@ export const createServer = (modelArtifact.close(),gpuCodeObjects.close(),peResources.close(),+ nativeExports.close(),elfNotes.close(),electronFuses.close(),webNetworkCapture.close(),@@ -521,6 +526,7 @@ export const createServer = (rustBinary,il2cppMetadata,peResources,+ nativeExports,elfNotes,electronFuses,webNetworkCapture,@@ -753,6 +759,7 @@ const registerConfiguredAnalysisTools = (rustBinary,il2cppMetadata,peResources,+ nativeExports,elfNotes,webNetworkCapture,artifactResources,@@ -803,6 +810,13 @@ const registerConfiguredAnalysisTools = (recordEvidence,withAdmittedAnalysis,);+ registerNativeExportsTool(+ server,+ nativeExports,+ toolLogger,+ recordEvidence,+ withAdmittedAnalysis,+ );registerElfNotesTool(server,elfNotes,@@ -943,6 +957,7 @@ interface ServerToolContext extends ReturnType<typeof createSessionRecorders> {readonly rustBinary: RustBinaryService;readonly il2cppMetadata: Il2cppMetadataService;readonly peResources: PeResourcesService;+ readonly nativeExports: NativeExportsService;readonly elfNotes: ElfNotesService;readonly electronFuses: ElectronFuseService;readonly webNetworkCapture: WebNetworkCaptureService;diff --git a/src/server/registerNativeExportsTool.ts b/src/server/registerNativeExportsTool.tsnew file mode 100644index 000000000..91e02b4b2--- /dev/null+++ b/src/server/registerNativeExportsTool.ts@@ -0,0 +1,31 @@+import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";+import type { NativeExportsService } from "../application/binaryDiagnostics/NativeExportsService.js";+import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";+import { toolContract } from "../contracts/toolContracts.js";+import type { Logger } from "pino";+import { createEvidenceToolHandler } from "./contractToolHandler.js";+import type { WithAdmittedAnalysis } from "./analysisAdmission.js";+import { applicationToolRegistrationOptions } from "./toolRegistrationOptions.js";++/** Register the explicit-file export-table workflow and retain its complete Evidence. */+export const registerNativeExportsTool = (+ server: EvidenceMcpServer,+ service: NativeExportsService,+ logger: Logger,+ recordEvidence?: EvidenceWriter["recordEvidence"],+ withAdmittedAnalysis?: WithAdmittedAnalysis,+): void => {+ const contract = toolContract("inspect_native_exports");+ const handler = createEvidenceToolHandler(+ server,+ (input, options) => service.inspect(input, options),+ logger,+ recordEvidence,+ withAdmittedAnalysis,+ );+ server.registerTool(+ contract.name,+ applicationToolRegistrationOptions(contract),+ handler(contract),+ );+};diff --git a/tests/acceptance/tools/localToolContracts.test.ts b/tests/acceptance/tools/localToolContracts.test.tsindex f0bb73c6c..b8d6b5baf 100644--- a/tests/acceptance/tools/localToolContracts.test.ts+++ b/tests/acceptance/tools/localToolContracts.test.ts@@ -218,6 +218,7 @@ const pathRequests: readonly [string, Record<string, unknown>][] = [{ capture_path: nul, output_directory: "/tmp/exported-scripts" },],["inspect_pe_resources", { path: nul }],+ ["inspect_native_exports", { path: nul }],["inspect_elf_notes", { path: nul }],["inspect_binary_layout", { path: nul }],["inspect_recorded_crash", { path: nul }],diff --git a/tests/boundary/filesystem/nativeExports.test.ts b/tests/boundary/filesystem/nativeExports.test.tsnew file mode 100644index 000000000..e79f80ac4--- /dev/null+++ b/tests/boundary/filesystem/nativeExports.test.ts@@ -0,0 +1,104 @@+import { createHash } from "node:crypto";+import { symlink, writeFile } from "node:fs/promises";+import { join } from "node:path";+import { describe, expect, it } from "vitest";+import { createNativeExportsService } from "../../../src/composition/binaryDiagnostics.js";+import { parseEvidence } from "../../../src/domain/evidence.js";+import { nativeExportsSchema } from "../../../src/domain/native/nativeExports.js";+import {+ elfExportImage,+ peExportImage,+} from "../../fixtures/binaryDiagnostics/nativeExports.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";++describe("native export stable filesystem boundary", () => {+ it("binds PE and ELF export inventories to the selected file", async () => {+ const root = await createTestTempDirectory("rea-native-exports-");+ const service = createNativeExportsService();+ for (const [name, bytes, format] of [+ [+ "fixture.dll",+ peExportImage({+ functions: [{ rva: 0x2000 }],+ names: [{ name: "Exported", index: 0 }],+ }),+ "pe",+ ],+ [+ "libfixture.so",+ elfExportImage({ symbols: [{ name: "exported" }] }),+ "elf",+ ],+ ] as const) {+ const path = join(root, name);+ await writeFile(path, bytes);+ const result = await service.inspect({ path });+ if (!result.ok) throw new Error(JSON.stringify(result.error));+ const evidence = parseEvidence(result.value);+ const sha256 = createHash("sha256").update(bytes).digest("hex");++ expect(evidence).toMatchObject({+ operation: "inspect_native_exports",+ provider: { id: "rea-native-exports" },+ confidence: "observed",+ subject: { local_path: path, format, digest: { sha256 } },+ });+ expect(+ nativeExportsSchema.parse(evidence.normalized_result),+ ).toMatchObject({+ artifact: { path, sha256, bytes: bytes.length },+ format,+ coverage: { status: "complete", exports: 1 },+ });+ }+ await service.close();+ });++ it("returns typed input, unsupported, budget and cancellation failures", async () => {+ const root = await createTestTempDirectory("rea-native-export-failures-");+ const path = join(root, "fixture.dll");+ const alias = join(root, "alias.dll");+ const macho = join(root, "fixture.dylib");+ const malformed = join(root, "malformed.dll");+ await writeFile(path, peExportImage({ functions: [] }));+ const machoBytes = Buffer.alloc(64);+ machoBytes.writeUInt32LE(0xfeedfacf, 0);+ await writeFile(macho, machoBytes);+ await writeFile(malformed, Buffer.from("MZ not a PE image"));+ await symlink(path, alias);+ const service = createNativeExportsService();+ const failure = async (+ input: Record<string, unknown>,+ signal?: AbortSignal,+ ) => {+ const result = await service.inspect(+ input,+ signal === undefined ? undefined : { signal },+ );+ if (result.ok) throw new Error("Expected a failure");+ return result.error;+ };++ for (const [candidate, reason] of [+ [alias, "invalid_format"],+ [malformed, "invalid_format"],+ [join(root, "missing.dll"), "invalid_value"],+ ] as const)+ expect(await failure({ path: candidate })).toMatchObject({+ _tag: "AnalysisInputError",+ operation: "inspect_native_exports",+ issues: [{ path: ["path"], reason }],+ });+ expect(await failure({ path: macho })).toMatchObject({+ _tag: "AnalysisUnsupportedTargetError",+ reason: expect.stringContaining("inspect_macho"),+ });+ expect(await failure({ path, max_file_bytes: 64 })).toMatchObject({+ _tag: "AnalysisResourceConstraintError",+ });+ expect(+ await failure({ path }, AbortSignal.abort("caller stop")),+ ).toMatchObject({ _tag: "AnalysisCancelledError" });+ await service.close();+ });+});diff --git a/tests/boundary/mcp/absoluteLocalPathSchema.test.ts b/tests/boundary/mcp/absoluteLocalPathSchema.test.tsindex 536f2c3f2..d0a148988 100644--- a/tests/boundary/mcp/absoluteLocalPathSchema.test.ts+++ b/tests/boundary/mcp/absoluteLocalPathSchema.test.ts@@ -78,6 +78,7 @@ const standaloneAnalysisCases = ({ name: "inspect_evm_interface", input: { encoding: "hex" } },{ name: "inspect_sqlite_database", input: {} },{ name: "inspect_pe_resources", input: {} },+ { name: "inspect_native_exports", input: {} },{ name: "inspect_electron_fuses", input: {} },{ name: "inspect_packet_capture", input: { fields: ["ip.addr"] } },{diff --git a/tests/boundary/mcp/binaryDiagnosticsMcp.test.ts b/tests/boundary/mcp/binaryDiagnosticsMcp.test.tsindex 1131b45b0..9c83d87d0 100644--- a/tests/boundary/mcp/binaryDiagnosticsMcp.test.ts+++ b/tests/boundary/mcp/binaryDiagnosticsMcp.test.ts@@ -1,4 +1,4 @@-import { randomBytes } from "node:crypto";+import { createHash, randomBytes } from "node:crypto";import { writeFile } from "node:fs/promises";import { join } from "node:path";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";@@ -20,6 +20,8 @@ import {binaryLayoutFixture,BINARY_LAYOUT_TEST_PROVIDER,} from "../../fixtures/binaryDiagnostics/layout.js";+import { elfExportImage } from "../../fixtures/binaryDiagnostics/nativeExports.js";+import { parseNativeExports } from "../../../src/native/exports/NativeExportParser.js";it("advertises exact valid schemas and records inline layout without a binary target", async () => {const value = binaryLayoutFixture();@@ -181,3 +183,50 @@ it("profiles real bytes with exact offsets, valid advertised schemas and read-on).isError,).toBe(true);});++it("records a portable export inventory through MCP without a binary target", async () => {+ const root = await createTestTempDirectory("rea-native-exports-mcp-");+ const path = join(root, "libfixture.so");+ const bytes = elfExportImage({+ symbols: [{ name: "exported_fn" }, { name: "hidden_fn", visibility: 2 }],+ });+ await writeFile(path, bytes);+ const session = createTestBinarySession(() => {+ throw new Error("deep provider must not start");+ });+ const server = createServer({ kind: "session", session });+ const client = new Client({ name: "native-exports-contract", 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);+ const schemas = await advertisedMcpToolSchemas(+ client,+ "inspect_native_exports",+ );+ expect(schemas.ajv.validate(schemas.inputSchema, { path })).toBe(true);+ expect(+ schemas.ajv.validate(schemas.inputSchema, { path: "relative.so" }),+ ).toBe(false);+ const response = await client.callTool({+ name: "inspect_native_exports",+ arguments: { path },+ });+ assertRecordedMcpEvidence(+ response,+ "inspect_native_exports",+ schemas,+ session,+ parseNativeExports(bytes, {+ path,+ sha256: createHash("sha256").update(bytes).digest("hex"),+ bytes: bytes.length,+ }),+ "observed",+ );+});diff --git a/tests/fixtures/advertisedMcpTool.ts b/tests/fixtures/advertisedMcpTool.tsindex 55521941d..e10e603e4 100644--- a/tests/fixtures/advertisedMcpTool.ts+++ b/tests/fixtures/advertisedMcpTool.ts@@ -35,7 +35,8 @@ export const assertRecordedMcpEvidence = (name:| "inspect_wasm_artifact"| "inspect_binary_layout"- | "inspect_evm_interface",+ | "inspect_evm_interface"+ | "inspect_native_exports",schemas: Awaited<ReturnType<typeof advertisedMcpToolSchemas>>,session: BinarySession,expected: { readonly artifact: { readonly sha256: string } },diff --git a/tests/fixtures/binaryDiagnostics/nativeExports.ts b/tests/fixtures/binaryDiagnostics/nativeExports.tsnew file mode 100644index 000000000..7bada8dc7--- /dev/null+++ b/tests/fixtures/binaryDiagnostics/nativeExports.ts@@ -0,0 +1,336 @@+/** One PE export-address-table slot: code RVA, forwarder text, or unused. */+export type PeFixtureFunction =+ | { readonly rva: number }+ | { readonly forwarder: string }+ | null;++const SECTION_RVA = 0x1000;+const SECTION_OFFSET = 0x400;+const SECTION_BYTES = 0x400;+/** SizeOfHeaders; header RVAs map to the same file offsets. */+const HEADER_BYTES = 0x400;++/**+ * Minimal PE32/PE32+ image whose only section holds an export directory at+ * RVA 0x1000. Name entries point at `functions` by index.+ */+export const peExportImage = (options: {+ readonly bits?: 32 | 64;+ readonly ordinalBase?: number;+ readonly functions?: readonly PeFixtureFunction[];+ readonly names?: readonly { readonly name: string; readonly index: number }[];+ /** Replace one name's RVA, e.g. with an unmapped one. */+ readonly nameRvaOverride?: {+ readonly position: number;+ readonly rva: number;+ };+ readonly exportDirectory?: boolean;+ readonly declaredFunctions?: number;+ /** Store the export directory and its tables in the PE headers. */+ readonly inHeaders?: boolean;+}): Buffer => {+ const bits = options.bits ?? 64;+ const bytes = Buffer.alloc(SECTION_OFFSET + SECTION_BYTES);+ const wide = bits === 64;+ bytes.write("MZ", 0, "ascii");+ bytes.writeUInt32LE(128, 60);+ bytes.write("PE\0\0", 128, "ascii");+ bytes.writeUInt16LE(wide ? 0x8664 : 0x14c, 132);+ bytes.writeUInt16LE(1, 134);+ const directoriesAt = wide ? 112 : 96;+ const optionalSize = directoriesAt + 16 * 8;+ bytes.writeUInt16LE(optionalSize, 148);+ const optional = 152;+ bytes.writeUInt16LE(wide ? 0x20b : 0x10b, optional);+ if (wide) bytes.writeBigUInt64LE(0x180000000n, optional + 24);+ else bytes.writeUInt32LE(0x10000000, optional + 28);+ bytes.writeUInt32LE(16, optional + directoriesAt - 4);+ bytes.writeUInt32LE(HEADER_BYTES, optional + 60);+ const section = optional + optionalSize;+ bytes.write(".edata", section, "ascii");+ bytes.writeUInt32LE(SECTION_BYTES, section + 8);+ bytes.writeUInt32LE(SECTION_RVA, section + 12);+ bytes.writeUInt32LE(SECTION_BYTES, section + 16);+ bytes.writeUInt32LE(SECTION_OFFSET, section + 20);+ bytes.writeUInt32LE(0x40000040, section + 36);+ if (options.exportDirectory === false) return bytes;++ const at = (rva: number) =>+ rva < HEADER_BYTES ? rva : rva - SECTION_RVA + SECTION_OFFSET;+ const base = options.inHeaders === true ? 0x200 : SECTION_RVA;+ const functions = options.functions ?? [];+ const names = options.names ?? [];+ // Directory, address table, name table, ordinals, then strings; forwarders+ // stay inside the 0x200-byte declared directory range.+ const eat = base + 0x40;+ const nameTable = base + 0x80;+ const ordinalTable = base + 0xc0;+ let forwarderText = base + 0x100;+ let text = base + (options.inHeaders === true ? 0x180 : 0x200);+ const string = (value: string, inside: boolean): number => {+ const rva = inside ? forwarderText : text;+ bytes.write(`${value}\0`, at(rva), "latin1");+ if (inside) forwarderText += value.length + 1;+ else text += value.length + 1;+ return rva;+ };+ bytes.writeUInt32LE(base, optional + directoriesAt);+ bytes.writeUInt32LE(0x200, optional + directoriesAt + 4);+ const directory = at(base);+ bytes.writeUInt32LE(0x5f5e0ff, directory + 4);+ bytes.writeUInt32LE(string("fixture.dll", false), directory + 12);+ bytes.writeUInt32LE(options.ordinalBase ?? 1, directory + 16);+ bytes.writeUInt32LE(+ options.declaredFunctions ?? functions.length,+ directory + 20,+ );+ bytes.writeUInt32LE(names.length, directory + 24);+ bytes.writeUInt32LE(eat, directory + 28);+ bytes.writeUInt32LE(nameTable, directory + 32);+ bytes.writeUInt32LE(ordinalTable, directory + 36);+ functions.forEach((entry, index) => {+ const value =+ entry === null+ ? 0+ : "rva" in entry+ ? entry.rva+ : string(entry.forwarder, true);+ bytes.writeUInt32LE(value, at(eat) + index * 4);+ });+ names.forEach(({ name, index }, position) => {+ const rva =+ options.nameRvaOverride?.position === position+ ? options.nameRvaOverride.rva+ : string(name, false);+ bytes.writeUInt32LE(rva, at(nameTable) + position * 4);+ bytes.writeUInt16LE(index, at(ordinalTable) + position * 2);+ });+ return bytes;+};++/** One `.dynsym` entry; `version` is its raw `.gnu.version` half-word. */+export interface ElfFixtureSymbol {+ readonly name: string;+ readonly binding?: number;+ readonly type?: number;+ readonly visibility?: number;+ readonly section?: number;+ readonly value?: bigint;+ readonly size?: bigint;+ readonly version?: number;+ /** Replace the symbol's string-table offset. */+ readonly nameOffset?: number;+}++/**+ * Minimal ELF shared object with `.dynsym`, `.dynstr`, `.gnu.version` and+ * `.gnu.version_d`, laid out in order. Version definitions are indexed from 1.+ */+export const elfExportImage = (options: {+ readonly bits?: 32 | 64;+ readonly little?: boolean;+ readonly machine?: number;+ readonly symbols: readonly ElfFixtureSymbol[];+ readonly versionDefinitions?: readonly string[];+ /** Declare a `.gnu.version` table that is one entry short. */+ readonly truncatedVersions?: boolean;+ /** Point `.gnu.version` past the end of the file. */+ readonly versionsOutsideFile?: boolean;+ /** Declare a zero-byte `.dynsym`, without its null entry. */+ readonly emptyDynamicSymbols?: boolean;+ readonly sectionHeaders?: boolean;+ readonly dynamicSymbols?: boolean;+}): Buffer => {+ const bits = options.bits ?? 64;+ const little = options.little ?? true;+ const wide = bits === 64;+ const symbolWidth = wide ? 24 : 16;+ const sectionWidth = wide ? 64 : 40;+ const symbols = [null, ...options.symbols];+ const definitions = options.versionDefinitions ?? [];++ const dynstr: string[] = ["\0"];+ let dynstrBytes = 1;+ const strings = new Map<string, number>();+ const intern = (value: string): number => {+ const known = strings.get(value);+ if (known !== undefined) return known;+ const offset = dynstrBytes;+ strings.set(value, offset);+ dynstr.push(`${value}\0`);+ dynstrBytes += value.length + 1;+ return offset;+ };+ const definitionNames = definitions.map(intern);+ const symbolNames = symbols.map((symbol) =>+ symbol === null ? 0 : (symbol.nameOffset ?? intern(symbol.name)),+ );+ const shstrtab =+ "\0.dynsym\0.dynstr\0.gnu.version\0.gnu.version_d\0.shstrtab\0";+ let cursor = 0x100;+ const place = (size: number): number => {+ const offset = cursor;+ cursor = Math.ceil((cursor + size) / 16) * 16;+ return offset;+ };+ const dynsymAt = place(symbols.length * symbolWidth);+ const dynstrAt = place(dynstrBytes);+ const versymAt = place(symbols.length * 2);+ const verdefAt = place(definitions.length * 28);+ const shstrtabAt = place(shstrtab.length);+ const sectionAt = place(6 * sectionWidth);+ const bytes = Buffer.alloc(cursor);++ const u16 = (offset: number, value: number) =>+ little+ ? bytes.writeUInt16LE(value, offset)+ : bytes.writeUInt16BE(value, offset);+ const u32 = (offset: number, value: number) =>+ little+ ? bytes.writeUInt32LE(value, offset)+ : bytes.writeUInt32BE(value, offset);+ const word = (offset: number, value: bigint) => {+ if (!wide) u32(offset, Number(value));+ else if (little) bytes.writeBigUInt64LE(value, offset);+ else bytes.writeBigUInt64BE(value, offset);+ };+ bytes.set([0x7f, 0x45, 0x4c, 0x46, wide ? 2 : 1, little ? 1 : 2, 1]);+ u16(16, 3);+ u16(18, options.machine ?? (wide ? 62 : 40));+ u32(20, 1);+ u16(wide ? 52 : 40, wide ? 64 : 52);+ u16(wide ? 54 : 42, wide ? 56 : 32);+ u16(wide ? 58 : 46, sectionWidth);+ if (options.sectionHeaders === false) return bytes;++ symbols.forEach((symbol, index) => {+ if (symbol === null) return;+ const at = dynsymAt + index * symbolWidth;+ const info = ((symbol.binding ?? 1) << 4) | (symbol.type ?? 2);+ const other = symbol.visibility ?? 0;+ const value = symbol.value ?? BigInt(0x1000 + index * 16);+ u32(at, symbolNames[index]!);+ if (wide) {+ bytes[at + 4] = info;+ bytes[at + 5] = other;+ u16(at + 6, symbol.section ?? 1);+ word(at + 8, value);+ word(at + 16, symbol.size ?? 16n);+ } else {+ word(at + 4, value);+ word(at + 8, symbol.size ?? 16n);+ bytes[at + 12] = info;+ bytes[at + 13] = other;+ u16(at + 14, symbol.section ?? 1);+ }+ });+ Buffer.from(dynstr.join(""), "latin1").copy(bytes, dynstrAt);+ symbols.forEach((symbol, index) =>+ u16(versymAt + index * 2, symbol?.version ?? (index === 0 ? 0 : 1)),+ );+ definitions.forEach((_, index) => {+ const at = verdefAt + index * 28;+ u16(at, 1);+ u16(at + 2, index === 0 ? 1 : 0);+ u16(at + 4, index + 1);+ u16(at + 6, 1);+ u32(at + 12, 20);+ u32(at + 16, index === definitions.length - 1 ? 0 : 28);+ u32(at + 20, definitionNames[index]!);+ });+ bytes.write(shstrtab, shstrtabAt, "latin1");+ const sections = elfSectionRows(options, {+ dynsymAt,+ dynsym: symbols.length * symbolWidth,+ symbolWidth,+ dynstrAt,+ dynstrBytes,+ versymAt,+ versym: symbols.length * 2,+ verdefAt,+ definitions: definitions.length,+ shstrtabAt,+ shstrtab: shstrtab.length,+ end: cursor,+ });+ sections.forEach(([name, type, offset, size, link, info, entsize], index) => {+ const at = sectionAt + index * sectionWidth;+ u32(at, name);+ u32(at + 4, type);+ word(at + (wide ? 24 : 16), BigInt(offset));+ word(at + (wide ? 32 : 20), BigInt(size));+ u32(at + (wide ? 40 : 24), link);+ u32(at + (wide ? 44 : 28), info);+ word(at + (wide ? 56 : 36), BigInt(entsize));+ });+ word(wide ? 40 : 32, BigInt(sectionAt));+ u16(wide ? 60 : 48, sections.length);+ u16(wide ? 62 : 50, sections.length - 1);+ return bytes;+};++type ElfSectionRow = readonly [+ name: number,+ type: number,+ offset: number,+ size: number,+ link: number,+ info: number,+ entsize: number,+];++/** Section header rows for the fixture layout, with the requested defects. */+const elfSectionRows = (+ options: Parameters<typeof elfExportImage>[0],+ layout: {+ readonly dynsymAt: number;+ readonly dynsym: number;+ readonly symbolWidth: number;+ readonly dynstrAt: number;+ readonly dynstrBytes: number;+ readonly versymAt: number;+ readonly versym: number;+ readonly verdefAt: number;+ readonly definitions: number;+ readonly shstrtabAt: number;+ readonly shstrtab: number;+ readonly end: number;+ },+): readonly ElfSectionRow[] => [+ [0, 0, 0, 0, 0, 0, 0],+ ...(options.dynamicSymbols === false+ ? []+ : ([+ [+ 1,+ 11,+ layout.dynsymAt,+ options.emptyDynamicSymbols === true ? 0 : layout.dynsym,+ 2,+ 1,+ layout.symbolWidth,+ ],+ [9, 3, layout.dynstrAt, layout.dynstrBytes, 0, 0, 0],+ [+ 17,+ 0x6fffffff,+ options.versionsOutsideFile === true+ ? layout.end + 64+ : layout.versymAt,+ layout.versym - (options.truncatedVersions === true ? 2 : 0),+ 1,+ 0,+ 2,+ ],+ [+ 30,+ 0x6ffffffd,+ layout.verdefAt,+ layout.definitions * 28,+ 2,+ layout.definitions,+ 0,+ ],+ ] satisfies ElfSectionRow[])),+ [45, 3, layout.shstrtabAt, layout.shstrtab, 0, 0, 0],+];