mirror of
https://github.com/morluto/rea.git
synced 2026-11-21 06:04:03 +00:00
Add offline ELF separate-debug linkage inspection with explicit candidate verification, bounded streaming, canonical parser limits and preserved complete/partial Evidence provenance. Assisted-by: Suika (gensokyo-skills:suika-scatter-gather-planning) Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
404 lines
13 KiB
TypeScript
404 lines
13 KiB
TypeScript
import {
|
|
isParseLimit,
|
|
parseFailureAnalysisError,
|
|
parseLimitConstraint,
|
|
} from "../../domain/parseFailureAnalysisError.js";
|
|
import { decodeLimit } from "../../domain/parseFailure.js";
|
|
import {
|
|
projectArtifactCloseFailure,
|
|
projectOwnedArtifactIdentityFailure,
|
|
projectSelectedArtifactFileFailure,
|
|
projectStableArtifactFailure,
|
|
stableArtifactInputFailure,
|
|
ArtifactReaderFailure,
|
|
completedStableArtifactStream,
|
|
readStableArtifact,
|
|
streamStableArtifact,
|
|
type StableArtifactSnapshot,
|
|
type StableArtifactStream,
|
|
artifactFilePrimaryFacts,
|
|
type ArtifactFilePrimaryFacts,
|
|
ArtifactResourceScope,
|
|
} from "../../resources/index.js";
|
|
import type { ExecutionOptions } from "../../ports/AnalysisProvider.js";
|
|
import type { ElfDebugLinkPort } from "../../ports/binaryDiagnostics/ElfDebugLinkPort.js";
|
|
import { ArtifactOperationError } from "../../domain/artifactOperationError.js";
|
|
import { fixedAllowanceOptions } from "../../domain/fixedAllowanceRemediation.js";
|
|
import {
|
|
ELF_DEBUG_LINK_CANDIDATE_INCOMPLETE_LIMITATION,
|
|
MAX_ELF_DEBUG_CANDIDATE_BYTES,
|
|
MAX_INSPECT_ELF_DEBUG_LINK_ENTRIES,
|
|
MAX_INSPECT_ELF_DEBUG_LINK_FILE_BYTES,
|
|
type ElfDebugLink,
|
|
type InspectElfDebugLinkInput,
|
|
} from "../../domain/native/elfDebugLink.js";
|
|
import { err, ok } from "../../domain/result.js";
|
|
import type { AnalysisPartialObservation } from "../../domain/analysisErrorBase.js";
|
|
import { ELF_DEBUG_LINK_PROVIDER } from "../../domain/investigationProviders.js";
|
|
import {
|
|
binaryResourceCeiling,
|
|
BinaryResourceFailure,
|
|
} from "../../domain/binaryContainer.js";
|
|
import {
|
|
continueGnuDebuglinkCrc32,
|
|
parseElfDebugLink,
|
|
unreadableElfDebugCandidate,
|
|
verifyElfDebugCandidate,
|
|
} from "./ElfDebugLink.js";
|
|
import {
|
|
ELF_NOTE_TEXT_ALLOWANCE,
|
|
elfNoteSectionNameBudget,
|
|
} from "./ElfNoteParser.js";
|
|
|
|
const OPERATION = "inspect_elf_debug_link";
|
|
|
|
type SelectedField = "path" | "candidate_path";
|
|
|
|
/** Portable parser over one bounded ELF and an optional caller-selected candidate. */
|
|
export class ElfDebugLinkProvider implements ElfDebugLinkPort {
|
|
readonly identity = ELF_DEBUG_LINK_PROVIDER;
|
|
readonly #resources = new ArtifactResourceScope();
|
|
|
|
async close(): Promise<void> {
|
|
try {
|
|
await this.#resources.close();
|
|
} catch (cause: unknown) {
|
|
throw projectArtifactCloseFailure(
|
|
cause,
|
|
ELF_DEBUG_LINK_PROVIDER.id,
|
|
OPERATION,
|
|
);
|
|
}
|
|
}
|
|
|
|
async inspect(input: InspectElfDebugLinkInput, options?: ExecutionOptions) {
|
|
let field: SelectedField = "path";
|
|
let candidatePhase: CandidatePhase | undefined;
|
|
let crc32 = 0;
|
|
let snapshot: StableArtifactSnapshot | undefined;
|
|
try {
|
|
return await this.#resources.run(async () => {
|
|
field = "path";
|
|
snapshot = await readStableArtifact(
|
|
input.path,
|
|
input.max_file_bytes,
|
|
options?.signal,
|
|
undefined,
|
|
this.#resources,
|
|
);
|
|
const image = parseElfDebugLink(
|
|
snapshot.bytes,
|
|
{
|
|
path: input.path,
|
|
sha256: snapshot.sha256,
|
|
bytes: snapshot.bytes.length,
|
|
},
|
|
input,
|
|
);
|
|
if (input.candidate_path === undefined) return ok(image);
|
|
field = "candidate_path";
|
|
candidatePhase = { report: image, path: input.candidate_path };
|
|
let candidate;
|
|
try {
|
|
// Stream the whole candidate for the debuglink CRC32 and SHA-256.
|
|
// Only a file within max_file_bytes is retained for ELF decoding;
|
|
// a larger one keeps just its ELF header.
|
|
candidate = await streamStableArtifact(
|
|
input.candidate_path,
|
|
MAX_ELF_DEBUG_CANDIDATE_BYTES,
|
|
{
|
|
retainBytes: (size) =>
|
|
size <= input.max_file_bytes ? size : ELF_HEADER_PREFIX_BYTES,
|
|
onChunk: (chunk) => {
|
|
crc32 = continueGnuDebuglinkCrc32(crc32, chunk);
|
|
},
|
|
signal: options?.signal,
|
|
resourceScope: this.#resources,
|
|
},
|
|
);
|
|
} catch (cause) {
|
|
if (!candidateUnreadable(cause)) throw cause;
|
|
return ok(unreadableElfDebugCandidate(image));
|
|
}
|
|
return ok(verifiedCandidate(candidatePhase, candidate, crc32, input));
|
|
});
|
|
} catch (cause) {
|
|
return err(
|
|
elfDebugLinkFailure(
|
|
cause,
|
|
input,
|
|
field,
|
|
candidatePhase === undefined
|
|
? { imageSnapshot: snapshot }
|
|
: {
|
|
retained: candidatePhaseObservation(
|
|
candidatePhase,
|
|
cause,
|
|
crc32,
|
|
input,
|
|
),
|
|
},
|
|
),
|
|
);
|
|
}
|
|
}
|
|
}
|
|
|
|
type CandidatePhase = { readonly report: ElfDebugLink; readonly path: string };
|
|
|
|
const verifiedCandidate = (
|
|
phase: CandidatePhase,
|
|
candidate: StableArtifactStream,
|
|
crc32: number,
|
|
input: InspectElfDebugLinkInput,
|
|
): ElfDebugLink =>
|
|
verifyElfDebugCandidate(
|
|
phase.report,
|
|
{
|
|
path: phase.path,
|
|
sha256: candidate.sha256,
|
|
bytes: candidate.size,
|
|
crc32,
|
|
prefix: candidate.prefix,
|
|
},
|
|
input,
|
|
);
|
|
|
|
/**
|
|
* The decoded image survives a failed candidate phase. A candidate stream that
|
|
* completed before cancellation or a failed close keeps its full comparison;
|
|
* otherwise only the image linkage is retained, without any comparison.
|
|
*/
|
|
const candidatePhaseObservation = (
|
|
phase: CandidatePhase,
|
|
cause: unknown,
|
|
crc32: number,
|
|
input: InspectElfDebugLinkInput,
|
|
): AnalysisPartialObservation => {
|
|
const completed = completedStableArtifactStream(cause);
|
|
return completed === undefined
|
|
? {
|
|
...phase.report,
|
|
limitations: [
|
|
...phase.report.limitations,
|
|
ELF_DEBUG_LINK_CANDIDATE_INCOMPLETE_LIMITATION,
|
|
],
|
|
}
|
|
: verifiedCandidate(phase, completed, crc32, input);
|
|
};
|
|
|
|
/** Enough retained bytes for an ELF32 or ELF64 fixed header. */
|
|
const ELF_HEADER_PREFIX_BYTES = 64;
|
|
|
|
/**
|
|
* A candidate that is missing, unreadable, fails a data read, changed while
|
|
* streamed, or is above the whole-file ceiling cannot be compared. Path-shape refusals, cancellation,
|
|
* and descriptor close failures, including a close that failed after an
|
|
* integrity or limit refusal, still fail the call.
|
|
*/
|
|
const candidateUnreadable = (cause: unknown): boolean => {
|
|
// A failed close keeps the original reason beside the cleanup observation;
|
|
// it must stay a failure so the pending handle remains visible.
|
|
if (cause instanceof ArtifactReaderFailure)
|
|
return (
|
|
cause.cleanup === undefined &&
|
|
(cause.reason === "integrity" || cause.reason === "limit")
|
|
);
|
|
if (!(cause instanceof Error) || !("code" in cause)) return false;
|
|
return (
|
|
cause.code === "ENOENT" ||
|
|
cause.code === "ENOTDIR" ||
|
|
cause.code === "EACCES" ||
|
|
cause.code === "EPERM" ||
|
|
cause.code === "EIO"
|
|
);
|
|
};
|
|
|
|
const inputLabel = (field: SelectedField): string =>
|
|
field === "candidate_path" ? "candidate" : "image";
|
|
|
|
const inputBudgetRemediation = (
|
|
boundary: "file-size" | "capacity",
|
|
input: InspectElfDebugLinkInput,
|
|
field: SelectedField,
|
|
): string => {
|
|
const label = inputLabel(field);
|
|
return boundary === "file-size"
|
|
? input.max_file_bytes >= MAX_INSPECT_ELF_DEBUG_LINK_FILE_BYTES
|
|
? `The ${label} exceeds the ${String(MAX_INSPECT_ELF_DEBUG_LINK_FILE_BYTES)}-byte input ceiling this operation accepts; select a smaller ${label}.`
|
|
: `Raise max_file_bytes above ${String(input.max_file_bytes)} bytes or select a smaller ${label}; the limit is the caller-selected input read budget.`
|
|
: input.max_entries >= MAX_INSPECT_ELF_DEBUG_LINK_ENTRIES
|
|
? `The ${label} exceeds the ${String(MAX_INSPECT_ELF_DEBUG_LINK_ENTRIES)}-entry note-table ceiling this operation accepts; select a smaller ${label}.`
|
|
: `Raise max_entries above ${String(input.max_entries)} or select a smaller ${label}; the limit is the caller-selected note entry budget.`;
|
|
};
|
|
|
|
const sectionNameBudgetRemediation = (
|
|
required: bigint,
|
|
field: SelectedField,
|
|
): string => {
|
|
const label = inputLabel(field);
|
|
return required <= BigInt(MAX_INSPECT_ELF_DEBUG_LINK_FILE_BYTES)
|
|
? `Raise max_file_bytes to at least ${String(required)} bytes to admit the ${label} and its decoded ELF section names.`
|
|
: `The ${label} and its decoded ELF section names require ${String(required)} bytes, above this operation's ${String(MAX_INSPECT_ELF_DEBUG_LINK_FILE_BYTES)}-byte maximum; select a ${label} with a smaller section-name table.`;
|
|
};
|
|
|
|
const selectedPath = (
|
|
input: InspectElfDebugLinkInput,
|
|
field: SelectedField,
|
|
): string =>
|
|
field === "candidate_path"
|
|
? (input.candidate_path ?? input.path)
|
|
: input.path;
|
|
|
|
const elfDebugLinkFailurePrimary = (
|
|
facts: ArtifactFilePrimaryFacts,
|
|
input: InspectElfDebugLinkInput,
|
|
field: SelectedField,
|
|
) => {
|
|
const { cause, origin } = facts;
|
|
const path = selectedPath(input, field);
|
|
const sectionNameBudget = elfNoteSectionNameBudget(cause);
|
|
if (isParseLimit(cause, "elf") && sectionNameBudget !== undefined)
|
|
return parseLimitConstraint(OPERATION, "memory", cause, {
|
|
retryable: false,
|
|
remediationAction: sectionNameBudgetRemediation(
|
|
sectionNameBudget.required,
|
|
field,
|
|
),
|
|
});
|
|
if (cause instanceof BinaryResourceFailure)
|
|
return parseLimitConstraint(
|
|
OPERATION,
|
|
"memory",
|
|
cause,
|
|
fixedAllowanceOptions(
|
|
"The ELF structural decoding allowance",
|
|
"parser",
|
|
binaryResourceCeiling(cause),
|
|
),
|
|
);
|
|
if (isParseLimit(cause, "elf-notes")) {
|
|
const entryBudget = cause.failure.limit.name === "max_entries";
|
|
return parseLimitConstraint(
|
|
OPERATION,
|
|
entryBudget ? "capacity" : "memory",
|
|
cause,
|
|
entryBudget
|
|
? {
|
|
retryable: false,
|
|
remediationAction: inputBudgetRemediation("capacity", input, field),
|
|
}
|
|
: fixedAllowanceOptions(ELF_NOTE_TEXT_ALLOWANCE, "parser", {
|
|
limit: cause.failure.limit.maximum,
|
|
unit: "bytes",
|
|
}),
|
|
);
|
|
}
|
|
const formatFailure = parseFailureAnalysisError(
|
|
OPERATION,
|
|
path,
|
|
cause,
|
|
field,
|
|
);
|
|
if (formatFailure !== undefined) return formatFailure;
|
|
const identityFailure = projectOwnedArtifactIdentityFailure(
|
|
facts,
|
|
OPERATION,
|
|
path,
|
|
);
|
|
if (identityFailure !== undefined) return identityFailure;
|
|
if (
|
|
origin === "owned-or-classified" &&
|
|
cause instanceof ArtifactReaderFailure
|
|
) {
|
|
if (cause.reason === "limit") {
|
|
const candidate = field === "candidate_path";
|
|
return parseLimitConstraint(
|
|
OPERATION,
|
|
"file-size",
|
|
decodeLimit(
|
|
"elf-debug-link",
|
|
cause.message,
|
|
{
|
|
name: candidate ? "candidate_bytes" : "max_file_bytes",
|
|
maximum: candidate
|
|
? MAX_ELF_DEBUG_CANDIDATE_BYTES
|
|
: input.max_file_bytes,
|
|
},
|
|
{ cause },
|
|
),
|
|
candidate
|
|
? fixedAllowanceOptions(
|
|
"The whole-file debug candidate read allowance",
|
|
"input",
|
|
{
|
|
limit: MAX_ELF_DEBUG_CANDIDATE_BYTES,
|
|
unit: "bytes",
|
|
},
|
|
)
|
|
: {
|
|
retryable: false,
|
|
remediationAction: inputBudgetRemediation(
|
|
"file-size",
|
|
input,
|
|
field,
|
|
),
|
|
},
|
|
);
|
|
}
|
|
if (cause.reason === "path" || cause.reason === "format")
|
|
return stableArtifactInputFailure(cause, OPERATION, field);
|
|
}
|
|
const fileFailure = projectSelectedArtifactFileFailure(
|
|
cause,
|
|
OPERATION,
|
|
path,
|
|
field === "candidate_path" ? "debug file candidate" : "ELF image",
|
|
field,
|
|
);
|
|
if (fileFailure !== undefined) return fileFailure;
|
|
return new ArtifactOperationError(
|
|
OPERATION,
|
|
origin === "owned-or-classified" && cause instanceof ArtifactReaderFailure
|
|
? cause.reason
|
|
: "io",
|
|
undefined,
|
|
cause instanceof Error
|
|
? cause.message
|
|
: "ELF debug-link inspection failed.",
|
|
{ cause },
|
|
);
|
|
};
|
|
|
|
const elfDebugLinkFailure = (
|
|
cause: unknown,
|
|
input: InspectElfDebugLinkInput,
|
|
field: SelectedField,
|
|
{
|
|
retained,
|
|
imageSnapshot,
|
|
}: {
|
|
// The decoded report from a failed candidate phase.
|
|
readonly retained?: AnalysisPartialObservation;
|
|
// A fully read image whose ELF decoding then failed keeps its identity.
|
|
readonly imageSnapshot?: StableArtifactSnapshot | undefined;
|
|
},
|
|
) => {
|
|
const primary = elfDebugLinkFailurePrimary(
|
|
artifactFilePrimaryFacts(cause),
|
|
input,
|
|
field,
|
|
);
|
|
// Retained before stable-read projection so the decoded report, which
|
|
// already carries any completed candidate identity, takes precedence.
|
|
if (retained !== undefined) primary.retainPartialObservation(retained);
|
|
return projectStableArtifactFailure(
|
|
cause,
|
|
primary,
|
|
selectedPath(input, field),
|
|
ELF_DEBUG_LINK_PROVIDER.id,
|
|
OPERATION,
|
|
imageSnapshot,
|
|
);
|
|
};
|