mirror of
https://github.com/morluto/rea.git
synced 2026-11-19 21:23:45 +00:00
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:
1 parent
af062e7a2d
commit
e9c72dbd1f
100 files changed
+7137
-89
No files matched your search
@@ -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,
|
||||
);
|
||||
};
|
||||
Reference in new issue
Block a user