feat(analysis): make resource budgets recoverable across CLI and MCP (#9706)

* refactor(analysis): centralize resource budgets and recovery facts

* feat(analysis): expose ASAR and Ghidra runtime admission controls

* feat(artifacts): expose reader admission and preserve limited recognition

* feat(javascript): expose recoverable semantic precision budgets

* feat(web): add recoverable source-map budgets and compact retained views

* feat(web): make historical capture decoding budgets recoverable

* fix(desktop): enforce selected view policies across capture and export

* feat(runtime): make Frida and LLDB retention budgets selectable

* feat(native): expose diagnostic budgets and preserve exhaustion causes

* feat(managed): expose recoverable snapshot and representation budgets

* feat(metadata): make Go and Rust inspection budgets recoverable

* feat(wasm): expose representation and producer admissions

* feat(evm): expose per-call worker resource budgets

* feat(android): make resource and string-pool omissions recoverable

* feat(producers): expose command and recorded-capture budgets

* docs(analysis): record recovery contracts and integrated validation

* fix(docs): link calibration oracle from published verification pages

* fix(docs): restore desktop task anchors and receipt links

* test(analysis): align fixtures with selectable budget contracts

* fix(analysis): remove source-location projector dependency cycle

* test(analysis): refresh budget recovery and verifier regressions

* test(analysis): preserve format and publication recovery expectations

* test(windows): align conformance with owned runtime admission

* fix(desktop): preserve selected alias kinds in exported state

* test(analysis): align provider fixtures with recoverable budgets

* test(desktop): validate emitted alias metadata structurally

* fix(ghidra): classify bounded Windows endpoint refusals

* test(cli): assert selectable artifact admission recovery

* fix(cli): preserve capture provenance in environment builds
This commit is contained in:
morluto authored and GitHub committed 2026-11-10 05:11:20 -05:00
1 parent 55b6d2ca20
commit cb4e5cfbff
515 files changed
+21066 -3637

No files matched your search

@@ -1,9 +1,16 @@
import {
desktopViewPolicy,
desktopViewPolicyInputSchema,
type DesktopViewPolicy,
type DesktopViewPolicyInput,
} from "../../domain/desktop/desktopViewPolicy.js";
import { writeFile } from "node:fs/promises";
import { join } from "node:path";
import { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
import { AnalysisError } from "../../domain/analysisErrorBase.js";
import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";
import {
desktopApplicationCaptureSchema,
type DesktopApplicationCapture,
@@ -63,6 +70,7 @@ export interface DesktopStateReaders {
readonly sqlite: (
database: string,
signal?: AbortSignal,
policy?: DesktopViewPolicy,
) => Promise<{ ok: true; view: JsonValue } | { ok: false; error: string }>;
readonly dconf: (
database: string,
@@ -130,6 +138,7 @@ interface ViewContext {
readonly names: ReadonlySet<string>;
readonly signal: AbortSignal | undefined;
readonly index: StateIndex;
readonly policy: DesktopViewPolicy;
}
const dconfGroups = (text: string, names: ReadonlySet<string>) => {
@@ -242,7 +251,11 @@ const sqliteView = async (
staged.push({ name: `state.db${sidecar.suffix}`, bytes: bytes.value });
}
return withStaged(staged, async ([database]) => {
const read = await context.readers.sqlite(database ?? "", context.signal);
const read = await context.readers.sqlite(
database ?? "",
context.signal,
context.policy,
);
return read.ok ? { view: read.view, error: null } : failed(read.error);
});
};
@@ -273,9 +286,11 @@ const viewOf = async (
case "json":
case "keyfile":
case "xml":
return outcomeOf(textualView(format, input.bytes));
return outcomeOf(textualView(format, input.bytes, context.policy));
case "zip":
return outcomeOf(await readZipView(input.bytes, context.signal));
return outcomeOf(
await readZipView(input.bytes, context.signal, context.policy),
);
case "dconf":
return dconfView(input, context);
case "sqlite":
@@ -341,7 +356,7 @@ const readVersion = async (
version.view_error = `retained content ${bytes.error}`;
return;
}
const document = openStateDocument(path, bytes.value);
const document = openStateDocument(path, bytes.value, context.policy);
version.format = document.format;
if (document.compression !== undefined)
version.compression = document.compression;
@@ -404,14 +419,15 @@ const describePath = async (
};
};
const STATE_LIMITATIONS = [
const stateLimitations = (policy: DesktopViewPolicy) => [
"Roles are inferred from state directories, open files, window titles, selected paths and dconf key names; a path can be misattributed.",
"Views cover retained content only; a file that existed before the capture but outside the content roots has no starting view.",
"SQLite views list at most 500 rows of at most 64 ordinary tables, text views at most 5,000 lines and XML views at most 5,000 nodes; changes between truncated views, or views with an unread table, are marked incomplete.",
"JSON and key file views read files of at most 4 MiB, JSON nested at most 500 levels and only numbers JavaScript holds exactly; other files of those formats have a view_error.",
`SQLite views list at most ${String(policy.sqlite_rows)} rows of ${String(policy.sqlite_tables)} ordinary tables, text views ${String(policy.text_lines)} lines and XML views ${String(policy.xml_nodes)} nodes; changes between truncated views, or views with an unread table, are marked incomplete. Increase the corresponding --view-policy budget and retry the same capture; no restart is needed.`,
`Each projected SQLite table view is bounded at sqlite_view_bytes=${String(policy.sqlite_view_bytes)} UTF-8 JSON bytes. A refused table keeps its error; other tables remain readable. Raise sqlite_view_bytes in --view-policy on the next call for that refusal. The separate SQLite worker reply and value/record limits may refuse earlier and are not raised by view policy.`,
`JSON and key file views read files of at most ${String(policy.parsed_bytes)} bytes and JSON nested at most ${String(policy.json_depth)} levels; only numbers JavaScript holds exactly are admitted. Increase parsed_bytes or json_depth in --view-policy for a budget refusal; byte budgets do not change numeric exactness or Evidence nesting.`,
"dconf views keep only groups whose path names the application.",
"Zip views list at most 1,000 entries and read an entry only when it is unencrypted, stored or deflated, at most 16 MiB and at most 100 times its compressed size, up to 64 MiB per archive; databases and archives inside an archive are not read.",
"A gzip file's view is its document's, read only when it is at most 16 MiB and at most 100 times the file's size; a database inside one is not read, nor a gzip file inside an archive.",
`Zip views list at most ${String(policy.zip_entries)} entries and read an entry only when unencrypted, stored or deflated, at most ${String(policy.zip_entry_bytes)} bytes and ${String(policy.zip_ratio)} times its compressed size, up to ${String(policy.zip_bytes)} bytes per archive. Increase the corresponding --view-policy budget for a resource refusal; databases and archives inside an archive are not read.`,
`A gzip file's view is its document's, read only when it is at most ${String(policy.zip_entry_bytes)} bytes and at most ${String(policy.zip_ratio)} times the file's size; a database inside one is not read, nor a gzip file inside an archive.`,
];
/** Read a capture folder into the application's state view. */
@@ -419,20 +435,46 @@ const inspectState = async (
folder: string,
readers: DesktopStateReaders,
signal: AbortSignal | undefined,
options: DesktopStateViewOptions,
): Promise<Evidence> => {
const policy = desktopViewPolicy(options.viewPolicy);
const { evidence, capture } = await readDesktopCapture(folder, signal);
const names = applicationNames(capture);
const facts = roleFacts(capture);
const index = indexState(capture);
const paths = await withRetainedContent(folder, async (content) => {
const context: ViewContext = { content, readers, names, signal, index };
const described: DesktopStatePath[] = [];
for (const path of statePaths(index))
described.push(await describePath(capture, path, facts, context));
return described;
});
const candidates = statePaths(index);
for (const selected of options.paths ?? [])
if (!candidates.includes(selected))
throw new AnalysisInputError(
OPERATION,
{
userMessage: `Captured path ${JSON.stringify(selected)} was not found.`,
remediationAction:
"Use an exact path from this capture's state view; no current filesystem path is substituted.",
},
[{ path: ["paths"], reason: "invalid_value" }],
);
const paths = await withRetainedContent(
folder,
async (content) => {
const context: ViewContext = {
content,
readers,
names,
signal,
index,
policy,
};
const described: DesktopStatePath[] = [];
for (const path of candidates)
if (options.paths === undefined || options.paths.includes(path))
described.push(await describePath(capture, path, facts, context));
return described;
},
policy.file_bytes,
);
const limitations = [
...STATE_LIMITATIONS,
...stateLimitations(policy),
...(capture.state.state_directories === undefined
? [
"The capture does not record its state directories as walked, so files in a symlinked state directory may be classed as documents.",
@@ -440,6 +482,7 @@ const inspectState = async (
: []),
];
const result: DesktopApplicationState = {
effective_view_policy: policy,
capture: {
evidence_id: evidence.evidence_id,
home: capture.host.home,
@@ -457,7 +500,13 @@ const inspectState = async (
return createEvidence(undefined, DESKTOP_PROVIDER, {
predicateType: "rea.desktop-application-state",
operation: OPERATION,
parameters: { capture_evidence_id: evidence.evidence_id },
parameters: {
capture_evidence_id: evidence.evidence_id,
...(options.viewPolicy === undefined
? {}
: { view_policy: { ...options.viewPolicy } }),
...(options.paths === undefined ? {} : { paths: [...options.paths] }),
},
result,
confidence: "inferred",
authority: "analyst-inference",
@@ -465,14 +514,35 @@ const inspectState = async (
});
};
export interface DesktopStateViewOptions {
readonly viewPolicy?: DesktopViewPolicyInput | undefined;
/** Exact original captured paths; omission examines every retained path. */
readonly paths?: readonly string[] | undefined;
}
/** Inspect one capture folder, returning its state view Evidence or a failure. */
export const inspectDesktopApplicationState = async (
folder: string,
readers: DesktopStateReaders,
signal?: AbortSignal,
options: DesktopStateViewOptions = {},
): Promise<Evidence | AnalysisError> => {
try {
return await inspectState(folder, readers, signal);
const admitted = desktopViewPolicyInputSchema.safeParse(
options.viewPolicy === undefined ? {} : options.viewPolicy,
);
if (!admitted.success)
return analysisInputErrorFromIssues(
OPERATION,
admitted.error.issues,
options.viewPolicy,
);
return await inspectState(folder, readers, signal, {
...options,
...(options.viewPolicy === undefined
? {}
: { viewPolicy: admitted.data }),
});
} catch (cause: unknown) {
return desktopOperationFailure(
cause,