feat(mcp): select views of retained analysis results (#1180)

Add explicit summary, facet, item and paged views of retained analysis Evidence without repeating analysis. Preserve captured observations, graph validation, artifact identity, coverage and complete default results.

Fixes #1050

Verified with focused source, CLI, pinned-SDK schema and MCP tests, serial static checks, and one complete native Windows Notion ASAR workflow. Real Hopper/Ghidra verification was not performed for this provider-independent projection change.

Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
This commit is contained in:
Matt Van Horn
2026-10-09 12:45:48 +08:00
committed by GitHub
co-authored by Matt Van Horn
parent 911152a04d
commit db675f1d52
39 changed files with 2609 additions and 30 deletions
@@ -0,0 +1,176 @@
import { expect, it } from "vitest";
import { JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE } from "../../contracts/javascript/javascriptRuntimeReconciliationExample.js";
import { createEvidence, parseEvidence } from "../../domain/evidence.js";
import {
analysisViewJavaScriptAnalysisWithSource,
analysisViewJavaScriptEvidence,
analysisViewLayoutEvidence,
} from "../../../tests/fixtures/analysisView.js";
import { inspectAnalysisView } from "./AnalysisViewService.js";
it("projects inline layout Evidence and retains a derived view record", () => {
const parent = analysisViewLayoutEvidence();
const result = inspectAnalysisView({
source: { kind: "inline", evidence: parent },
view: {
kind: "item",
collection: "sections",
selector: { index: 2 },
},
});
if (!result.ok) throw result.error;
const evidence = parseEvidence(result.value);
expect(evidence.operation).toBe("inspect_analysis_view");
expect(evidence.predicate_type).toBe("rea.analysis-view");
expect(evidence.confidence).toBe("derived");
expect(evidence.evidence_links).toEqual([parent.evidence_id]);
expect(evidence.normalized_result).toMatchObject({
kind: "item",
parent_evidence_id: parent.evidence_id,
item: { name: { display: ".data" } },
});
});
it("resolves same-session retained JavaScript Evidence without re-running analysis", () => {
const parent = analysisViewJavaScriptEvidence(
analysisViewJavaScriptAnalysisWithSource(),
);
const lookup = (evidenceId: string) =>
evidenceId === parent.evidence_id ? parent : undefined;
const summary = inspectAnalysisView(
{
source: {
kind: "retained-evidence",
evidence_id: parent.evidence_id,
},
view: { kind: "summary" },
},
lookup,
);
if (!summary.ok) throw summary.error;
expect(summary.value.normalized_result).toMatchObject({
kind: "summary",
parent_evidence_id: parent.evidence_id,
parent_operation: "analyze_javascript_application",
});
expect(summary.value.normalized_result).not.toHaveProperty(
"summary.semantic_graph",
);
const item = inspectAnalysisView(
{
source: {
kind: "retained-evidence",
evidence_id: parent.evidence_id,
},
view: {
kind: "item",
collection: "modules",
selector: { path: "renderer.js" },
},
},
lookup,
);
if (!item.ok) throw item.error;
expect(JSON.stringify(item.value.normalized_result)).toContain(
"export const secret = 1;",
);
});
it("rejects stale retained IDs and unsupported parent operations", () => {
const missing = inspectAnalysisView(
{
source: {
kind: "retained-evidence",
evidence_id: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE.evidence_id,
},
view: { kind: "summary" },
},
() => undefined,
);
expect(missing).toMatchObject({
ok: false,
error: {
_tag: "EvidenceIntegrityError",
evidenceId: JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE.evidence_id,
},
});
const unsupported = createEvidence(
undefined,
{ id: "fixture", name: "Fixture", version: "1" },
{
operation: "inspect_recorded_crash",
parameters: {},
result: { path: "/artifacts/crash.core" },
},
);
const rejected = inspectAnalysisView({
source: { kind: "inline", evidence: unsupported },
view: { kind: "summary" },
});
expect(rejected).toMatchObject({
ok: false,
error: { _tag: "AnalysisUnsupportedTargetError" },
});
expect(
inspectAnalysisView({
source: { kind: "inline", evidence: analysisViewLayoutEvidence() },
view: { kind: "summary", approval: true },
}),
).toMatchObject({
ok: false,
error: { _tag: "AnalysisInputError" },
});
});
it("preserves an absent parent subject instead of guessing its format", () => {
const analysis = analysisViewJavaScriptAnalysisWithSource();
const original = analysisViewJavaScriptEvidence(analysis);
const parent = createEvidence(undefined, original.provider, {
operation: original.operation,
parameters: {},
result: original.normalized_result,
limitations: original.limitations,
});
const result = inspectAnalysisView(
{
source: { kind: "retained-evidence", evidence_id: parent.evidence_id },
view: { kind: "summary" },
},
() => parent,
);
if (!result.ok) throw result.error;
expect(result.value.subject).toBeNull();
expect(result.value.locations).toEqual([
{ kind: "artifact-path", path: analysis.input_path },
]);
});
it("rejects contradictory subject and analysis artifact digests", () => {
const analysis = analysisViewJavaScriptAnalysisWithSource();
const original = analysisViewJavaScriptEvidence(analysis);
const parent = createEvidence(
{
path: analysis.input_path,
format: analysis.format,
sha256: "d".repeat(64),
},
original.provider,
{
operation: original.operation,
parameters: {},
result: original.normalized_result,
},
);
const result = inspectAnalysisView(
{
source: { kind: "retained-evidence", evidence_id: parent.evidence_id },
view: { kind: "summary" },
},
() => parent,
);
expect(result).toMatchObject({
ok: false,
error: { _tag: "EvidenceIntegrityError" },
});
});
@@ -0,0 +1,132 @@
import { z } from "zod";
import { ANALYSIS_VIEW_PROVIDER } from "../InvestigationProviders.js";
import type { EvidenceLookup } from "../EvidenceInputResolver.js";
import { resolveEvidenceInput } from "../EvidenceInputResolver.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";
import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
import {
createEvidence,
parseEvidence,
type Evidence,
} from "../../domain/evidence.js";
import {
INSPECT_ANALYSIS_VIEW_OPERATION,
inspectAnalysisViewInputSchema,
projectAnalysisView,
type AnalysisViewResult,
type InspectAnalysisViewInput,
} from "../../domain/analysisView/analysisView.js";
import { jsonValueSchema } from "../../domain/jsonValue.js";
import { err, ok, type Result } from "../../domain/result.js";
/** Authenticate a selected-view request and project already completed Evidence. */
export const inspectAnalysisView = (
rawInput: unknown,
lookup?: EvidenceLookup,
): Result<Evidence, AnalysisError> => {
const parsed = inspectAnalysisViewInputSchema.safeParse(rawInput);
if (!parsed.success)
return err(
analysisInputErrorFromIssues(
INSPECT_ANALYSIS_VIEW_OPERATION,
parsed.error.issues,
rawInput,
{ cause: parsed.error },
),
);
return inspectAnalysisViewValidated(parsed.data, lookup);
};
/** Project a view from input already parsed by a trusted adapter. */
export const inspectAnalysisViewValidated = (
input: InspectAnalysisViewInput,
lookup?: EvidenceLookup,
): Result<Evidence, AnalysisError> => {
const resolved = resolveAnalysisViewSource(input.source, lookup);
if (!resolved.ok) return resolved;
const parent = resolved.value;
const projected = projectAnalysisView(
{
evidenceId: parent.evidence_id,
operation: parent.operation,
normalizedResult: parent.normalized_result,
limitations: parent.limitations,
},
input.view,
);
if (!projected.ok) return projected;
if (
parent.subject !== null &&
parent.subject.digest.sha256 !== projected.value.artifact.sha256
)
return err(
new EvidenceIntegrityError(
`Parent subject SHA-256 ${parent.subject.digest.sha256} differs from analysis artifact SHA-256 ${projected.value.artifact.sha256}.`,
),
);
return ok(createAnalysisViewEvidence(input, parent, projected.value));
};
const resolveAnalysisViewSource = (
source: InspectAnalysisViewInput["source"],
lookup: EvidenceLookup | undefined,
): Result<Evidence, AnalysisError> => {
if (source.kind === "retained-evidence")
return resolveEvidenceInput(source, lookup);
try {
return ok(parseEvidence(source.evidence));
} catch (cause: unknown) {
if (cause instanceof z.ZodError)
return err(
analysisInputErrorFromIssues(
INSPECT_ANALYSIS_VIEW_OPERATION,
cause.issues,
source.evidence,
{ cause },
),
);
if (cause instanceof TypeError)
return err(
new EvidenceIntegrityError(
cause.message,
cause.message.length > 0 ? { userMessage: cause.message } : undefined,
),
);
throw cause;
}
};
const createAnalysisViewEvidence = (
input: InspectAnalysisViewInput,
parent: Evidence,
result: AnalysisViewResult,
): Evidence => {
const target =
parent.subject === null
? undefined
: {
path: parent.subject.local_path,
sha256: parent.subject.digest.sha256,
format: parent.subject.format,
...(parent.subject.architecture === null
? {}
: { architecture: parent.subject.architecture }),
};
return createEvidence(target, ANALYSIS_VIEW_PROVIDER, {
predicateType: "rea.analysis-view",
operation: INSPECT_ANALYSIS_VIEW_OPERATION,
parameters: {
parent_evidence_id: parent.evidence_id,
view: jsonValueSchema.parse(input.view),
},
result: jsonValueSchema.parse(result),
rawResult: null,
confidence: "derived",
authority: parent.authority,
limitations: result.limitations,
locations: [{ kind: "artifact-path", path: result.artifact.path }],
evidenceLinks: [parent.evidence_id],
});
};