Files
reverse-engineering-anything/src/go/GoBinaryProvider.ts
T
morluto 2430b081c9 refactor(providers): bind provider refusals' per-call controls instead of naming CLI flags (#11455)
* refactor(native): bind producer_limits and max_input_bytes as the per-call controls of pwntools and Apple dispatch refusals

producerLimitControl in src/domain/producerResourceLimits.ts names one producer budget as producer_limits.<field>; the shared provider outcome classifier now carries a resource signal's limit. Pwntools file-size, CPU and output refusals and the Apple dispatch input refusal bind their control, and their remediation no longer names CLI flags.

* fix(native): report the selected output allowance as the omitted file_bytes default

* fix(native): bind producer_limits.diagnostic_bytes as the pwntools command output-limit control

* refactor(rust): bind producer_limits as the per-call control of Rust input and report refusals (#11458)

* refactor(rust): bind producer_limits as the per-call control of Rust input and report refusals

* test(rust): cover the complete-report refusal's producer_limits control

* refactor(browser): bind caller-selectable browser deadlines as per-call controls instead of naming CLI flags (#11466)

* refactor(rust): bind producer_limits as the per-call control of Rust input and report refusals

* test(rust): cover the complete-report refusal's producer_limits control

* refactor(browser): bind caller-selectable browser deadlines as per-call controls instead of naming CLI flags

deadlineParameterLimit in src/domain/analysisResourceLimits.ts owns the millisecond deadline control that nativeDeadlineRecovery and the browser recoveries share. CDP command and discovery, web bundle per-script and total, network capture and source-map decode deadlines now carry it; browserDeadlineIncrease no longer takes CLI flag text.

* fix(browser): record a per-script deadline's parameter control in partial web bundle results

* refactor(providers): bind Wabt, SQLite, EVMole, Apktool and Go controls instead of naming CLI commands (#11472)

* refactor(providers): bind Wabt, SQLite, EVMole and Apktool deadline and byte controls instead of naming CLI commands

These remediation strings named rea commands and flags through template text the cli-option guard did not count. Wabt byte refusals and output limits bind max_input_bytes, max_tool_bytes or max_output_bytes while a larger value is selectable; SQLite worker_timeout_ms, EVMole timeout_ms and Apktool decode_timeout_ms bind through deadlineParameterLimit; the shared provider outcome classifier now carries an output limit's control.

* refactor(go): bind Go analysis budgets as per-call controls instead of naming CLI flags

* fix(providers): keep the typed primary when Wabt, EVMole or pwntools command cleanup fails

* ci(guards): count template-built CLI option and command text outside the CLI layer (#11478)

* refactor(providers): bind Wabt, SQLite, EVMole and Apktool deadline and byte controls instead of naming CLI commands

These remediation strings named rea commands and flags through template text the cli-option guard did not count. Wabt byte refusals and output limits bind max_input_bytes, max_tool_bytes or max_output_bytes while a larger value is selectable; SQLite worker_timeout_ms, EVMole timeout_ms and Apktool decode_timeout_ms bind through deadlineParameterLimit; the shared provider outcome classifier now carries an output limit's control.

* refactor(go): bind Go analysis budgets as per-call controls instead of naming CLI flags

* fix(providers): keep the typed primary when Wabt, EVMole or pwntools command cleanup fails

* ci(guards): count template-built CLI option and command text outside the CLI layer

The cli-option-text-outside-cli pattern now also matches "(CLI ...", "on the CLI", "or use rea ..." and backticked `rea <command>` references, so remediation built from a template such as --${name} or rea inspect-... <path> is counted. Doctor.ts is exempt: setup and doctor run only through the CLI. The baseline records the newly counted pre-existing sites (22 -> 45 across 21 files).

* ci(guards): extract the CLI text matcher, exempt host-only commands with written reasons, and test each spelling

* ci(guards): exempt a host-only command and its own arguments in any matched CLI phrase

* fix(native): bind producer_limits.output_bytes for oversized pwndbg debugger replies through one owner

* fix(cli): name an Evidence target source failure's control by the source option that sets it

* feat(cli): render the flags of result-recorded controls in the full-output envelope (#11507)

* feat(cli): render the flags of result-recorded controls in the full-output envelope

* fix(cli): collect result controls only for a full-output envelope, in its requested format, past undefined values

* ci(guards): end a host-only command's arguments before the next CLI command

* refactor(reverse): record the output budget that stopped a one-shot command as a parameter control (#11528)

* fix(cli): read result controls only at positions the output schema declares as recorded controls

* refactor(providers): record the controls that bounded Rust compiler paths and kernel module text instead of naming CLI options (#11532)

* refactor(rust): record the control that bounded compiler-path coverage instead of naming CLI options

* refactor(native): record the controls that omitted kernel module .modinfo text instead of naming CLI options (#11534)

* fix(rust): describe compiler coverage from the retained result after report trimming

* refactor(providers): record managed representation and JavaScript semantic ceiling controls instead of naming CLI options (#11537)

* refactor(managed): record the representation budget on a resource-limit issue instead of naming its CLI option

* refactor(javascript): record the semantic retention ceilings that stopped a graph instead of naming CLI options (#11540)

* fix(cli): name a composed command's source options for the controls its result records

* fix(cli): read result controls from the delivered Evidence when a summary wraps it

* fix(rust): keep the report-byte control recorded when trimming omits every compiler path

When the complete-report allowance left room for no compiler path, rustc_commit became null and its coverage.limit was lost, so --full-output could not name the option that raises the allowance. The report now records rustc_commit_omission { reason, limit } outside the dropped record, and the summary view carries it.

* refactor(flutter): record the string-pool budgets that left a projection partial instead of naming the CLI option (#11541)

* refactor(flutter): record the string-pool budgets that left a projection partial instead of naming the CLI option

* test(flutter): assert the complete set of recorded string-pool budgets

* feat(cli): name the options of controls a failure's partial Evidence records (#11557)

meta.cli_controls was collected only from a successful result. A failure whose partial observation is Evidence of the command's own operation is now read the same way, at the positions the output schema declares as recorded controls; Evidence of another operation or a retained reference is not read. When --evidence_output publishes the partial, the delivery records it before replacing it.

* refactor(javascript): record the evaluator budgets that limited sources instead of naming the CLI option (#11564)

Per-value unknown reasons and the Electron wrapper limitation named --semantic-precision. The static examination now records the semantic_precision controls that limited a source (examination.controls), and analyze_javascript_application's semantic_graph.coverage.controls records every evaluator budget that limited any source (examination and semantic IR coverage), beside the retention ceilings. The CLI renders --semantic-precision from those records in meta.cli_controls; the reason texts name only the contract field.
2026-11-16 07:12:16 +08:00

388 lines
15 KiB
TypeScript

import type { AnalysisControlLimit } from "../domain/analysisSettings.js";
import { parseFailureAnalysisError } from "../domain/parseFailureAnalysisError.js";
import { jsonValueByteLength } from "../domain/jsonValueByteLength.js";
import { GO_BINARY_PROVIDER_IDENTITY } from "./GoBinaryProviderIdentity.js";
import {
projectSelectedArtifactFileFailure,
projectOwnedArtifactIdentityFailure,
projectStableArtifactFailure,
projectArtifactCloseFailure,
stableArtifactInputFailure,
type StableArtifactSnapshot,
readStableArtifact,
artifactFilePrimaryFacts,
type ArtifactFilePrimaryFacts,
assertArtifactReadActive,
ArtifactResourceScope,
ArtifactReaderFailure,
} from "../resources/index.js";
import type { ExecutionOptions } from "../ports/AnalysisProvider.js";
import type { GoBinaryPort } from "../ports/go/GoBinaryPort.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import {
AnalysisOutputError,
AnalysisResourceConstraintError,
} from "../domain/analysisErrorCore.js";
import {
goBinarySchema,
goAnalysisBudgets,
GO_ANALYSIS_BUDGET_DEFAULTS,
GO_ANALYSIS_BUDGET_MAXIMA,
type GoAnalysisBudgets,
type GoBinary,
type GoStringLiterals,
type InspectGoBinaryInput,
} from "../domain/go/goBinary.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { fixedAllowanceOptions } from "../domain/fixedAllowanceRemediation.js";
import { err, ok, type Result } from "../domain/result.js";
import { readGoBinaryImage, type GoBinaryImage } from "./GoBinaryImage.js";
import { requireSelectedNativeImage } from "../domain/apple/machoSliceSelection.js";
import { BinaryResourceFailure } from "../domain/binaryContainer.js";
import { errorMessage } from "../kernel/errorMessage.js";
const OPERATION = "inspect_go_binary";
const budgetRecovery = (
parameter: keyof GoAnalysisBudgets,
value: number,
): string =>
value < GO_ANALYSIS_BUDGET_MAXIMA[parameter]
? `Increase ${parameter} above ${String(value)} (maximum ${String(GO_ANALYSIS_BUDGET_MAXIMA[parameter])}) on the next inspect_go_binary request; no restart is required.`
: `${parameter} is at its runtime representation maximum ${String(value)}; no larger value is supported. Preserve the complete selected artifact and report this boundary rather than repeating the unchanged request.`;
/** The per-call control of an exhausted budget, while a larger value is selectable. */
const budgetLimit = (
parameter: keyof GoAnalysisBudgets,
value: number,
): { readonly limit?: AnalysisControlLimit } =>
value < GO_ANALYSIS_BUDGET_MAXIMA[parameter]
? {
limit: {
control_kind: "parameter",
parameter,
effective_value: value,
unit: parameter.endsWith("_bytes") ? "bytes" : "count",
minimum: 1,
maximum: GO_ANALYSIS_BUDGET_MAXIMA[parameter],
default_value: GO_ANALYSIS_BUDGET_DEFAULTS[parameter],
applies_at: "next_call",
},
}
: {};
const failureForPrimary = (
facts: ArtifactFilePrimaryFacts,
path: string,
budgets: GoAnalysisBudgets,
): AnalysisError => {
const { cause, origin } = facts;
if (origin === "owned-or-classified" && cause instanceof AnalysisError)
return cause;
const identityFailure = projectOwnedArtifactIdentityFailure(
facts,
OPERATION,
path,
);
if (identityFailure !== undefined) return identityFailure;
if (cause instanceof BinaryResourceFailure) {
const parameter =
cause.boundary === "search"
? "max_header_search_bytes"
: cause.boundary === "build-info"
? "max_build_info_bytes"
: undefined;
return new AnalysisResourceConstraintError(
OPERATION,
cause.boundary === "search" ? "cpu" : "memory",
`Selected artifact ${path}: ${cause.message}`,
{
boundary: cause.boundary,
maximum_bytes: cause.maximum_bytes,
...(parameter === undefined ? {} : { parameter, unit: "bytes" }),
},
{
cause,
...(parameter === undefined
? fixedAllowanceOptions(
"The Go structural decoding allowance",
"parser",
)
: {
retryable: false,
remediationAction: `${cause.boundary === "search" ? "The Go build-info header-search allowance" : "The Go build-info string allowance"} is ${String(budgets[parameter])} bytes. ${budgetRecovery(parameter, budgets[parameter])} Other byte and report budgets are independent. Repeating the unchanged request cannot raise this allowance.`,
...budgetLimit(parameter, budgets[parameter]),
}),
},
);
}
const formatFailure = parseFailureAnalysisError(OPERATION, path, cause);
if (formatFailure !== undefined) return formatFailure;
if (
origin === "owned-or-classified" &&
cause instanceof ArtifactReaderFailure
) {
if (cause.reason === "limit")
return new AnalysisResourceConstraintError(
OPERATION,
"file-size",
cause.message,
{
maximum_input_bytes: budgets.max_input_bytes,
parameter: "max_input_bytes",
unit: "bytes",
},
{
cause,
retryable: false,
remediationAction: `${budgetRecovery("max_input_bytes", budgets.max_input_bytes)} Report, build-info and structural allowances remain independent. Preserve the complete artifact; do not truncate required bytes.`,
...budgetLimit("max_input_bytes", budgets.max_input_bytes),
},
);
if (cause.reason === "path")
return stableArtifactInputFailure(cause, OPERATION);
}
const fileFailure = projectSelectedArtifactFileFailure(
cause,
OPERATION,
path,
"artifact",
);
if (fileFailure !== undefined) return fileFailure;
return new ProviderAdapterError(GO_BINARY_PROVIDER_IDENTITY.id, OPERATION, {
cause,
diagnostics: {
path,
reason: errorMessage(cause),
},
});
};
const failureFor = (
cause: unknown,
path: string,
budgets: GoAnalysisBudgets,
snapshot?: StableArtifactSnapshot,
): AnalysisError => {
const primary = failureForPrimary(
artifactFilePrimaryFacts(cause),
path,
budgets,
);
return projectStableArtifactFailure(
cause,
primary,
path,
GO_BINARY_PROVIDER_IDENTITY.id,
OPERATION,
snapshot,
);
};
const outputLimit = (path: string, maximumBytes: number) =>
new AnalysisResourceConstraintError(
OPERATION,
"transport",
`Complete Go metadata for ${path} exceeds the inline output budget; no partial success is returned.`,
{
maximum_output_bytes: maximumBytes,
parameter: "max_report_bytes",
unit: "bytes",
},
{
retryable: false,
remediationAction: `The Go complete-report allowance is ${String(maximumBytes)} bytes. ${budgetRecovery("max_report_bytes", maximumBytes)} This did not produce complete Evidence to page. MCP delivery limits remain independent.`,
...budgetLimit("max_report_bytes", maximumBytes),
},
);
/** Fixed reader boundaries plus unknowns left by the observed metadata. */
const limitationsFor = (
image: GoBinaryImage,
stringLiterals: GoStringLiterals | undefined,
budgets: GoAnalysisBudgets,
): string[] => {
const {
build_info: info,
section_names_limitation: sectionNamesLimitation,
macho_chained_fixups: machoChainedFixups,
} = image;
return [
"Embedded build metadata is observed file content, not proof of compiler identity, dependency authenticity or runtime behavior.",
stringLiterals === undefined
? "Only Go build information is inspected; function names, source mappings, type metadata and decompiled code are not recovered."
: "Only Go build information and inferred static (ptr, len) string-header candidates are inspected; function names, source mappings, type metadata and decompiled code are not recovered.",
`Resource guards use max_input_bytes=${String(budgets.max_input_bytes)}, max_header_search_bytes=${String(budgets.max_header_search_bytes)}, max_build_info_bytes=${String(budgets.max_build_info_bytes)} and max_report_bytes=${String(budgets.max_report_bytes)}; increase the named per-call budget for the next inspection when needed. Native structural table decoding retains its separate 16 MiB bound. These are not operating-system memory or CPU limits.`,
...(info !== null && (info.go_version === null || info.module_text === null)
? [
"Some embedded Go strings contain non-UTF8 bytes; undecodable text is null and exact source bytes are preserved as base64.",
]
: []),
...(info === null
? [
"No recognized Go build-info record was found in the inspected image; absent metadata does not establish that the binary is not Go.",
]
: []),
...(sectionNamesLimitation === undefined ? [] : [sectionNamesLimitation]),
...(info !== null && info.module.main === null
? [
"Dependency coverage is unknown because no main-module record was decoded from the embedded module information, as in GOPATH-mode builds. Decoded dependency records remain visible; an empty list does not establish the absence of dependencies.",
]
: []),
...(info?.module.complete === false
? [
"Some embedded module-text records could not be parsed completely; their original lines are preserved and additional metadata remains unknown.",
]
: []),
...(stringLiterals === undefined
? []
: [
"Recovered string_literals are inferred from pointer-aligned (ptr, len) pairs in non-executable mapped data pointing to printable UTF-8 slices within single read-only spans; compiler-inlined or stack-constructed strings without static headers, unapplied relocation addends and runtime reachability are not established.",
...(machoChainedFixups === true
? [
"This Mach-O declares LC_DYLD_CHAINED_FIXUPS; rebase-encoded pointer slots in writable data may not hold raw virtual addresses statically, so (ptr, len) recovery can miss writable-section string headers.",
]
: []),
...(stringLiterals.truncated
? [
`Recovered string_literals were truncated at ${stringLiterals.limits_reached?.map((parameter) => `${parameter}=${String(budgets[parameter])}`).join(", ") ?? "a configured recovery budget"}; increase the named per-call budget(s), then inspect the same complete artifact again. Additional static (ptr, len) candidates may exist. No restart is required.`,
]
: []),
]),
];
};
/** Locate image-relative build-info ranges in the selected file. */
const inFile = (
info: GoBinaryImage["build_info"],
fileOffset: number,
): GoBinaryImage["build_info"] =>
info === null || fileOffset === 0
? info
: {
...info,
header_offset: info.header_offset + fileOffset,
version_location: {
...info.version_location,
offset: info.version_location.offset + fileOffset,
},
module_location: {
...info.module_location,
offset: info.module_location.offset + fileOffset,
},
};
const inFileStringLiterals = (
literals: GoStringLiterals | undefined,
fileOffset: number,
): GoStringLiterals | undefined =>
literals === undefined || fileOffset === 0
? literals
: {
...literals,
items: literals.items.map((item) => ({
...item,
location: {
...item.location,
offset: item.location.offset + fileOffset,
},
first_header_offset: item.first_header_offset + fileOffset,
})),
};
/** Stable in-process metadata inspection without subprocesses, temporary files or Go installation. */
export class GoBinaryProvider implements GoBinaryPort {
readonly identity = GO_BINARY_PROVIDER_IDENTITY;
readonly #resources = new ArtifactResourceScope();
async close(): Promise<void> {
try {
await this.#resources.close();
} catch (cause: unknown) {
throw projectArtifactCloseFailure(
cause,
GO_BINARY_PROVIDER_IDENTITY.id,
OPERATION,
);
}
}
/** Read complete compiler/module metadata while preserving original byte identity and source ranges. */
async inspect(
input: Omit<InspectGoBinaryInput, "detail">,
options?: ExecutionOptions,
): Promise<Result<GoBinary, AnalysisError>> {
let snapshot: StableArtifactSnapshot | undefined;
const budgets = goAnalysisBudgets(input);
try {
return await this.#resources.run(async () => {
snapshot = await readStableArtifact(
input.path,
budgets.max_input_bytes,
options?.signal,
undefined,
this.#resources,
);
assertArtifactReadActive(options?.signal);
const selected = requireSelectedNativeImage(
OPERATION,
input.path,
snapshot.bytes,
input.architecture,
);
const image = readGoBinaryImage(selected.bytes, {
includeStringLiterals: input.include_string_literals === true,
budgets,
checkActive: () => assertArtifactReadActive(options?.signal),
});
const {
section_names_limitation: _sectionNamesLimitation,
macho_chained_fixups: _machoChainedFixups,
string_literals: rawStringLiterals,
...publicImage
} = image;
const info = inFile(image.build_info, selected.fileOffset);
const stringLiterals = inFileStringLiterals(
rawStringLiterals,
selected.fileOffset,
);
const report = {
...publicImage,
artifact: {
path: input.path,
sha256: snapshot.sha256,
bytes: snapshot.bytes.length,
},
...(selected.selection === null
? {}
: { selected_slice: selected.selection }),
build_info: info,
...(stringLiterals === undefined
? {}
: { string_literals: stringLiterals }),
limitations: [
...limitationsFor(image, stringLiterals, budgets),
...selected.limitations,
],
};
if (
jsonValueByteLength(report, budgets.max_report_bytes) >
budgets.max_report_bytes
)
throw outputLimit(input.path, budgets.max_report_bytes);
const parsed = goBinarySchema.safeParse(report);
if (!parsed.success)
throw new AnalysisOutputError(
OPERATION,
"Go reader produced invalid source ranges or report values.",
{ cause: parsed.error },
);
assertArtifactReadActive(options?.signal);
return ok(parsed.data);
});
} catch (cause: unknown) {
return err(failureFor(cause, input.path, budgets, snapshot));
}
}
}