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

+16
View File
@@ -3,6 +3,22 @@ import type { AnalysisError } from "../domain/analysisErrorBase.js";
import { cancelledBy } from "../domain/analysisErrorCore.js";
import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
import { err, ok, type Result } from "../domain/result.js";
import { isRecord } from "../kernel/isRecord.js";
/** Keep top-level caller selections separate from defaults resolved for execution. */
export const callerAnalysisParameters = (rawInput: unknown) => {
const selected = new Set(
isRecord(rawInput)
? Object.keys(rawInput).filter((name) => rawInput[name] !== undefined)
: [],
);
return <Input extends object>(resolved: Input): Partial<Input> => {
const parameters = { ...resolved };
for (const name of Object.keys(parameters))
if (!selected.has(name)) Reflect.deleteProperty(parameters, name);
return parameters;
};
};
/** Validate an application request, honoring cancellation before admission when supplied. */
export const parseAnalysisInput = <T>(
@@ -1,12 +1,14 @@
import { expect, it } from "vitest";
import { ElfNotesService } from "./ElfNotesService.js";
import { KernelModuleService } from "./KernelModuleService.js";
import { ElfDependenciesService } from "./ElfDependenciesService.js";
import { PeCertificatesService } from "./PeCertificatesService.js";
import { PeImportsService } from "./PeImportsService.js";
import { WindowsShortcutService } from "./WindowsShortcutService.js";
import {
ELF_NOTES_PROVIDER,
KERNEL_MODULE_PROVIDER,
ELF_DEPENDENCIES_PROVIDER,
PE_CERTIFICATES_PROVIDER,
PE_IMPORTS_PROVIDER,
WINDOWS_SHORTCUT_PROVIDER,
@@ -38,6 +40,14 @@ it.each([
() =>
new KernelModuleService({ identity: KERNEL_MODULE_PROVIDER, inspect }),
],
[
"ELF dependencies",
() =>
new ElfDependenciesService({
identity: ELF_DEPENDENCIES_PROVIDER,
inspect,
}),
],
[
"Windows shortcut",
() =>
@@ -0,0 +1,185 @@
import { expect, it } from "vitest";
import { ElfDependenciesService } from "./ElfDependenciesService.js";
import { ELF_DEPENDENCIES_PROVIDER } from "../../domain/investigationProviders.js";
import type { ElfDependencies } from "../../domain/native/elfDependencies.js";
import { ok } from "../../domain/result.js";
import { parseEvidence } from "../../domain/evidence.js";
import {
AnalysisCancelledError,
AnalysisInputError,
AnalysisOutputError,
} from "../../domain/analysisErrorCore.js";
const identity = ELF_DEPENDENCIES_PROVIDER;
const digest = "a".repeat(64);
const report: ElfDependencies = {
artifact: { path: "/artifacts/program", sha256: digest, bytes: 512 },
format: "elf64",
byte_order: "little",
machine: 62,
architecture: "amd64",
type: 3,
type_name: "shared",
interpreter: { status: "absent", path: null, location: null },
dynamic: {
status: "absent",
location: null,
soname: null,
rpath: null,
runpath: null,
flags: null,
flags_1: null,
},
needed: [],
version_requirements: { status: "absent", location: null, files: [] },
version_definitions: { status: "absent", location: null, names: [] },
derived_version_maxima: [],
imports: [],
coverage: {
status: "complete",
reason: null,
examined_needed: 0,
examined_versions: 0,
examined_imports: 0,
},
issues: [],
limitations: [
"No PT_DYNAMIC program header was declared. That is an observed empty load-time dependency inventory, not proof another overlay or container carried dynamic linking metadata.",
],
};
it("rejects a relative path and extra arguments before reading", async () => {
let calls = 0;
const service = new ElfDependenciesService({
identity,
inspect: () => {
calls += 1;
return Promise.resolve(ok(report));
},
});
const relative = await service.inspect({ path: "program" });
const extra = await service.inspect({
path: report.artifact.path,
extra: true,
});
expect(relative.ok).toBe(false);
expect(extra.ok).toBe(false);
if (!relative.ok) expect(relative.error).toBeInstanceOf(AnalysisInputError);
if (!extra.ok) expect(extra.error).toBeInstanceOf(AnalysisInputError);
expect(calls).toBe(0);
});
it("records an empty PT_DYNAMIC inventory and its x86_64 architecture", async () => {
const result = await new ElfDependenciesService({
identity,
inspect: () => Promise.resolve(ok(report)),
}).inspect({ path: report.artifact.path });
if (!result.ok) throw result.error;
expect(result.value).toMatchObject({
confidence: "observed",
subject: {
identity: {
kind: "file",
format: "elf",
architecture: "x86_64",
sha256: report.artifact.sha256,
},
local_path: report.artifact.path,
},
normalized_result: report,
});
});
it.each([undefined, 1024, 2])(
"preserves caller budget selection (%s) separately from execution defaults",
async (maxNeeded) => {
let resolved: number | undefined;
const rawInput = {
path: report.artifact.path,
...(maxNeeded === undefined ? {} : { max_needed: maxNeeded }),
};
const result = await new ElfDependenciesService({
identity,
inspect: (input) => {
resolved = input.max_needed;
return Promise.resolve(ok(report));
},
}).inspect(rawInput);
if (!result.ok) throw result.error;
expect(resolved).toBe(maxNeeded ?? 1024);
expect(result.value.parameters).toEqual(rawInput);
},
);
it("rejects a report whose needed coverage does not match retained rows", async () => {
const result = await new ElfDependenciesService({
identity,
inspect: () =>
Promise.resolve(
ok({
...report,
coverage: { ...report.coverage, examined_needed: 1 },
}),
),
}).inspect({ path: report.artifact.path });
expect(result.ok).toBe(false);
if (!result.ok) expect(result.error).toBeInstanceOf(AnalysisOutputError);
});
it("rejects complete coverage that still retains table issues", async () => {
const result = await new ElfDependenciesService({
identity,
inspect: () =>
Promise.resolve(
ok({
...report,
issues: [
{
code: "name_unreadable",
location: "DT_SONAME",
message: "unterminated",
},
],
}),
),
}).inspect({ path: report.artifact.path });
expect(result.ok).toBe(false);
if (!result.ok) expect(result.error).toBeInstanceOf(AnalysisOutputError);
});
it("retains a completed observation if the caller cancels while the provider completes", async () => {
const controller = new AbortController();
const reason = { request: "late ELF dependency cancellation" };
const service = new ElfDependenciesService({
identity,
inspect: () => {
controller.abort(reason);
return Promise.resolve(ok(report));
},
});
const late = await service.inspect(
{ path: report.artifact.path },
{ signal: controller.signal },
);
expect(late).toMatchObject({
ok: false,
error: { _tag: "AnalysisCancelledError" },
});
if (late.ok) throw new Error("Expected late cancellation");
expect(late.error).toBeInstanceOf(AnalysisCancelledError);
expect(late.error.cause).toBe(reason);
expect(parseEvidence(late.error.partialObservation)).toMatchObject({
operation: "inspect_elf_dependencies",
confidence: "observed",
subject: {
identity: {
kind: "file",
format: "elf",
architecture: "x86_64",
sha256: report.artifact.sha256,
},
local_path: report.artifact.path,
},
normalized_result: report,
});
});
@@ -0,0 +1,138 @@
import { isAbsolute } from "node:path";
import type { ExecutionOptions } from "../../ports/AnalysisProvider.js";
import type { ElfDependenciesPort } from "../../ports/binaryDiagnostics/ElfDependenciesPort.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import {
AnalysisInputError,
AnalysisOutputError,
} from "../../domain/analysisErrorCore.js";
import { createEvidence, type Evidence } from "../../domain/evidence.js";
import {
elfDependenciesSchema,
inspectElfDependenciesInputSchema,
type ElfDependencies,
type InspectElfDependenciesInput,
} from "../../domain/native/elfDependencies.js";
import { BINARY_ARCHITECTURES } from "../../domain/binaryTargetTypes.js";
import { elfArchitecture } from "../../domain/elfFixedHeader.js";
import { err, type Result } from "../../domain/result.js";
import { completeProviderEvidence } from "../ProviderOperationExecution.js";
import {
callerAnalysisParameters,
parseAnalysisInput,
} from "../AnalysisInput.js";
const OPERATION = "inspect_elf_dependencies";
/** Shared caller validation, output parsing and Evidence provenance for CLI/MCP. */
export class ElfDependenciesService {
constructor(readonly provider: ElfDependenciesPort) {}
close(): Promise<void> {
return this.provider.close?.() ?? Promise.resolve();
}
async inspect(
rawInput: unknown,
options?: ExecutionOptions,
): Promise<Result<Evidence, AnalysisError>> {
const input = parseAnalysisInput(
OPERATION,
rawInput,
inspectElfDependenciesInputSchema,
options?.signal,
);
if (!input.ok) return input;
if (!isAbsolute(input.value.path))
return err(
new AnalysisInputError(OPERATION, undefined, [
{
path: ["path"],
reason: "invalid_format",
message: "Expected an absolute filesystem path on this host.",
},
]),
);
const parameters = callerAnalysisParameters(rawInput)(input.value);
const result = await this.provider.inspect(input.value, options);
if (!result.ok) return result;
const report = elfDependenciesSchema.safeParse(result.value);
if (
!report.success ||
report.data.artifact.path !== input.value.path ||
!validReport(report.data, input.value)
)
return err(
new AnalysisOutputError(
OPERATION,
"ELF dependency provider returned malformed output or changed artifact identity.",
),
);
const value = report.data;
const mapped = elfArchitecture(value.machine);
const architecture = BINARY_ARCHITECTURES.find(
(supported) => supported === mapped,
);
return completeProviderEvidence(
createEvidence(
{
path: value.artifact.path,
format: "elf",
sha256: value.artifact.sha256,
...(architecture === undefined ? {} : { architecture }),
},
this.provider.identity,
{
operation: OPERATION,
parameters,
result: value,
confidence: "observed",
limitations: value.limitations,
locations: [
{ kind: "artifact-path", path: value.artifact.path },
...rangesOf(value).map((range) => ({
kind: "file-offset-range" as const,
start: range.offset,
end: range.offset + range.bytes,
})),
],
},
),
options?.signal,
);
}
}
const rangesOf = (
report: ElfDependencies,
): { offset: number; bytes: number }[] => {
const found: { offset: number; bytes: number }[] = [];
const add = (
range: { offset: number; bytes: number } | null | undefined,
): void => {
if (range !== null && range !== undefined) found.push(range);
};
add(report.interpreter.location);
add(report.dynamic.location);
add(report.version_requirements.location);
add(report.version_definitions.location);
return found;
};
const validReport = (
report: ElfDependencies,
input: InspectElfDependenciesInput,
): boolean => {
if (
report.artifact.bytes > input.max_file_bytes ||
report.needed.length > input.max_needed ||
report.imports.length > input.max_imports ||
report.coverage.examined_versions > input.max_versions
)
return false;
const fileBytes = report.artifact.bytes;
return rangesOf(report).every(
(range) =>
range.bytes <= fileBytes && range.offset <= fileBytes - range.bytes,
);
};
+6 -3
View File
@@ -16,7 +16,10 @@ import {
import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
import type { NativeToolName } from "../contracts/native/nativeToolContracts.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { parseAnalysisInput } from "./AnalysisInput.js";
import {
callerAnalysisParameters,
parseAnalysisInput,
} from "./AnalysisInput.js";
import { ok } from "../domain/result.js";
/** Operations the direct workflow can perform without a persistent session. */
@@ -104,8 +107,8 @@ export const admitOneShotOperation = <Name extends OneShotOperation>(
// Admission owns the selected request: preserve top-level omissions for
// Evidence and snapshot identity while carrying each selected parsed value.
// Nested defaults remain in the owning field's parsed value.
const selected = Object.fromEntries(
Object.entries(parsed.value).filter(([key]) => Object.hasOwn(input, key)),
const selected = callerAnalysisParameters(input)(
parsed.value,
) as SelectedInput;
return ok({ name, input: selected });
};