From d9977286f95090b5db3afab78573fa29841f7e90 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Fri, 24 Jul 2026 13:14:24 +0000 Subject: [PATCH] feat(artifacts): add provider-neutral inspection --- src/application/DirectAnalysis.ts | 10 +- src/artifacts/ArtifactProvider.ts | 151 ++++++-- src/cli/artifactCommands.ts | 51 +++ src/contracts/artifactToolContracts.ts | 29 ++ src/domain/artifactInspection.ts | 476 +++++++++++++++++++++++++ src/server/registerArtifactTools.ts | 11 +- tests/artifactMcp.test.ts | 60 +++- tests/artifactProvider.test.ts | 40 +++ 8 files changed, 798 insertions(+), 30 deletions(-) create mode 100644 src/domain/artifactInspection.ts diff --git a/src/application/DirectAnalysis.ts b/src/application/DirectAnalysis.ts index b3d65d031..2ceac7128 100644 --- a/src/application/DirectAnalysis.ts +++ b/src/application/DirectAnalysis.ts @@ -40,6 +40,7 @@ import { workflowAnalysisProfile, } from "./InvestigationProviders.js"; import type { AnalysisProviderSelector } from "../contracts/providerSelection.js"; +import { artifactInspectionResultSchema } from "../domain/artifactInspection.js"; export { runCapabilityStatus, @@ -144,7 +145,7 @@ const authorizeAnalysis = async ( ); } if ( - tool === "inventory_artifact" && + ["inventory_artifact", "inspect_artifact"].includes(tool) && arguments_.native_mount_approved === true ) { const result = await authority.authorize( @@ -155,7 +156,7 @@ const authorizeAnalysis = async ( environment_names: [], network: "none", mount: true, - operation_identity: "inventory_artifact:native_mount", + operation_identity: `${tool}:native_mount`, }, "read", ); @@ -381,6 +382,11 @@ const executeAnalysisTool = async (input: { rawResult: result.value.rawResult, limitations: result.value.limitations, locations: result.value.locations, + evidenceLinks: + tool === "inspect_artifact" + ? artifactInspectionResultSchema.parse(result.value.result) + .evidence_links + : [], }, ); return { output: evidence, evidence }; diff --git a/src/artifacts/ArtifactProvider.ts b/src/artifacts/ArtifactProvider.ts index e0ef5729f..eefcf5851 100644 --- a/src/artifacts/ArtifactProvider.ts +++ b/src/artifacts/ArtifactProvider.ts @@ -11,6 +11,7 @@ import { inventoryArtifact } from "../application/ArtifactInventory.js"; import { extractArtifact } from "../application/ArtifactExtraction.js"; import { ARTIFACT_TOOL_CONTRACTS, + artifactInspectionInputSchema, artifactInventoryInputSchema, artifactExtractionInputSchema, type ArtifactToolName, @@ -28,6 +29,8 @@ import { type ArtifactLimits, } from "./ArtifactReader.js"; import { ARTIFACT_GRAPH_PROVIDER } from "../application/InvestigationProviders.js"; +import { createEvidence } from "../domain/evidence.js"; +import { createArtifactInspection } from "../domain/artifactInspection.js"; const IDENTITY: ProviderIdentity = Object.freeze(ARTIFACT_GRAPH_PROVIDER); @@ -47,7 +50,10 @@ export class ArtifactProvider implements AnalysisProvider { outputContractVersion: 1, available: true as const, reason: null, - pagination: "offset" as const, + pagination: + contract.name === "inspect_artifact" + ? ("none" as const) + : ("offset" as const), exhaustive: false, effects: Object.freeze({ mutatesArtifact: false, @@ -111,6 +117,10 @@ class ArtifactClient implements AnalysisClient { ), ); try { + if (operation === "inspect_artifact") { + const inspected = await this.inspectArtifact(parameters, options); + return inspected; + } if (operation === "extract_artifact") { const parsed = artifactExtractionInputSchema.parse(parameters); const result = await extractArtifact( @@ -143,31 +153,7 @@ class ArtifactClient implements AnalysisClient { ); } const parsed = artifactInventoryInputSchema.parse(parameters); - const result = await inventoryArtifact( - this.target.sourcePath ?? this.target.path, - limitsFrom(parsed), - { - nodeOffset: parsed.node_offset, - nodeLimit: parsed.node_limit, - occurrenceOffset: parsed.occurrence_offset, - occurrenceLimit: parsed.occurrence_limit, - edgeOffset: parsed.edge_offset, - edgeLimit: parsed.edge_limit, - }, - { - ...(options?.signal === undefined ? {} : { signal: options.signal }), - nativeMount: { - nativeMountApproved: parsed.native_mount_approved === true, - nativeMountEnabled: this.nativeMountEnabled, - }, - integrity: { - mode: parsed.integrity_policy, - approved: parsed.integrity_continue_approved === true, - enabled: this.integrityContinueEnabled, - maxMismatches: parsed.max_integrity_mismatches, - }, - }, - ); + const result = await this.inventory(parsed, options); return ok( createAnalysisExecution(result, IDENTITY, { rawResult: null, @@ -190,6 +176,119 @@ class ArtifactClient implements AnalysisClient { close(): Promise { return Promise.resolve(); } + + private async inspectArtifact( + parameters: Readonly>, + options?: ExecutionOptions, + ) { + const parsed = artifactInspectionInputSchema.parse(parameters); + const inventoryParameters = artifactInventoryInputSchema.parse({ + node_offset: 0, + node_limit: parsed.max_observations, + occurrence_offset: 0, + occurrence_limit: parsed.max_observations, + edge_offset: 0, + edge_limit: parsed.max_relationships, + native_mount_approved: parsed.native_mount_approved, + integrity_policy: parsed.integrity_policy, + integrity_continue_approved: parsed.integrity_continue_approved, + max_integrity_mismatches: parsed.max_integrity_mismatches, + max_entries: parsed.max_entries, + max_total_bytes: parsed.max_total_bytes, + max_entry_bytes: parsed.max_entry_bytes, + max_compression_ratio: parsed.max_compression_ratio, + max_depth: parsed.max_depth, + max_path_bytes: parsed.max_path_bytes, + }); + await options?.progress?.report({ + phase: "inspect_artifact.inventory", + completed: 0, + total: 1, + message: "inventory substep started", + }); + const inventory = await this.inventory(inventoryParameters, options); + const subject = subjectFor( + this.target.sourcePath ?? this.target.path, + inventory.manifest, + ); + const locations = inventory.occurrences.items.map( + ({ logical_path: path }) => ({ + kind: "artifact-path" as const, + path, + }), + ); + const inventoryEvidence = createEvidence(subject, IDENTITY, { + operation: "inventory_artifact", + parameters: inventoryParameters, + result: inventory, + rawResult: null, + limitations: inventory.limitations, + locations, + }); + const result = createArtifactInspection(inventoryEvidence, parsed); + await options?.progress?.report({ + phase: "inspect_artifact.inventory", + completed: 1, + total: 1, + message: "inventory substep completed", + }); + return ok( + createAnalysisExecution(result, IDENTITY, { + rawResult: null, + limitations: result.limitations, + subject, + locations, + }), + ); + } + + private inventory( + parsed: { + readonly node_offset: number; + readonly node_limit: number; + readonly occurrence_offset: number; + readonly occurrence_limit: number; + readonly edge_offset: number; + readonly edge_limit: number; + readonly native_mount_approved: boolean; + readonly integrity_policy: "fail" | "record-and-continue"; + readonly integrity_continue_approved: boolean; + readonly max_integrity_mismatches: number; + readonly max_entries: number; + readonly max_total_bytes: number; + readonly max_entry_bytes: number; + readonly max_compression_ratio: number; + readonly max_depth: number; + readonly max_path_bytes: number; + }, + options?: ExecutionOptions, + ) { + return inventoryArtifact( + this.target.sourcePath ?? this.target.path, + limitsFrom(parsed), + { + nodeOffset: parsed.node_offset, + nodeLimit: parsed.node_limit, + occurrenceOffset: parsed.occurrence_offset, + occurrenceLimit: parsed.occurrence_limit, + edgeOffset: parsed.edge_offset, + edgeLimit: parsed.edge_limit, + }, + { + ...(options?.signal === undefined ? {} : { signal: options.signal }), + nativeMount: { + nativeMountApproved: parsed.native_mount_approved === true, + nativeMountEnabled: this.nativeMountEnabled, + }, + integrity: { + mode: parsed.integrity_policy, + approved: parsed.integrity_continue_approved === true, + enabled: this.integrityContinueEnabled, + maxMismatches: parsed.max_integrity_mismatches, + }, + }, + ); + } } const limitsFrom = (input: { diff --git a/src/cli/artifactCommands.ts b/src/cli/artifactCommands.ts index b172e0b94..1704c5dcf 100644 --- a/src/cli/artifactCommands.ts +++ b/src/cli/artifactCommands.ts @@ -10,6 +10,12 @@ export const registerArtifactCommands = ( cli: CliInstance, logger: Logger, ): void => { + registerInventoryCommand(cli, logger); + registerInspectionCommand(cli, logger); + registerExtractionCommand(cli, logger); +}; + +const registerInventoryCommand = (cli: CliInstance, logger: Logger): void => { cli.command(CLI_COMMANDS.inventoryArtifact, { description: "Build a bounded deterministic artifact graph", args: z.object({ @@ -76,6 +82,9 @@ export const registerArtifactCommands = ( ), ), }); +}; + +const registerExtractionCommand = (cli: CliInstance, logger: Logger): void => { cli.command(CLI_COMMANDS.extractArtifact, { description: "Extract explicitly selected artifact occurrences safely", args: z.object({ @@ -103,3 +112,45 @@ export const registerArtifactCommands = ( ), }); }; + +const registerInspectionCommand = (cli: CliInstance, logger: Logger): void => { + cli.command(CLI_COMMANDS.inspectArtifact, { + description: + "Inspect one artifact with bounded observations and explicit next probes", + args: z.object({ + path: z.string().describe("Application or package path"), + }), + options: z.object({ + maxObservations: z + .number() + .int() + .min(1) + .max(500) + .default(100) + .describe("Maximum retained observations"), + maxRelationships: z + .number() + .int() + .min(1) + .max(500) + .default(100) + .describe("Maximum retained derived relationships"), + }), + alias: { + maxObservations: "max-observations", + maxRelationships: "max-relationships", + }, + run: ({ args, options }) => + logCliCommand(logger, "inspect-artifact", () => + runProviderAnalysis( + args.path, + "inspect_artifact", + { + max_observations: options.maxObservations, + max_relationships: options.maxRelationships, + }, + logger, + ), + ), + }); +}; diff --git a/src/contracts/artifactToolContracts.ts b/src/contracts/artifactToolContracts.ts index 7ada8bcdb..66ac62698 100644 --- a/src/contracts/artifactToolContracts.ts +++ b/src/contracts/artifactToolContracts.ts @@ -4,6 +4,7 @@ import type { ToolContract } from "./toolContracts.js"; import { artifactOutputSchemas } from "./toolOutputSchemas.js"; import { jsonValueSchema } from "../domain/jsonValue.js"; import { toolContractMetadata } from "./toolEffects.js"; +import { artifactInspectionLimitsSchema } from "../domain/artifactInspection.js"; const pageInput = { node_offset: z.number().int().min(0).default(0), @@ -68,9 +69,32 @@ export const artifactExtractionInputSchema = z.object({ ...traversalLimitsInput, }); +/** Bounded provider-neutral inspection using one atomic inventory substep. */ +export const artifactInspectionInputSchema = z + .object({ + native_mount_approved: z.boolean().default(false), + integrity_policy: z.enum(["fail", "record-and-continue"]).default("fail"), + integrity_continue_approved: z.boolean().default(false), + max_integrity_mismatches: z.number().int().min(1).max(100).default(10), + ...artifactInspectionLimitsSchema.shape, + ...traversalLimitsInput, + }) + .superRefine((input, context) => { + if ( + input.integrity_policy === "record-and-continue" && + input.integrity_continue_approved !== true + ) + context.addIssue({ + code: "custom", + path: ["integrity_continue_approved"], + message: "record-and-continue requires explicit approval", + }); + }); + const exampleInputSchema = z.record(z.string(), jsonValueSchema); const examples: Readonly>>> = { inventory_artifact: {}, + inspect_artifact: {}, extract_artifact: { approved: true, output_root: "/tmp/rea-extracted", @@ -109,6 +133,11 @@ export const ARTIFACT_TOOL_CONTRACTS = [ "Inventory the active application or package as a deterministic, content-addressed artifact graph. Returns bounded node and edge pages without extracting or mounting by default.", artifactInventoryInputSchema, ), + artifact( + "inspect_artifact", + "Inspect the active artifact through one bounded, cancellable inventory substep. Returns the full substep Evidence and its ID, observations, derived relationships, hypotheses, contradictions, unexplored branches, limitations, and format-specific next probes. Any substep failure fails the whole call.", + artifactInspectionInputSchema, + ), artifact( "extract_artifact", "Extract selected graph artifacts beneath an explicit output root. Requires approval, rejects traversal and symlink escapes, never overwrites, enforces bomb limits, and verifies cleanup.", diff --git a/src/domain/artifactInspection.ts b/src/domain/artifactInspection.ts new file mode 100644 index 000000000..89a84c90e --- /dev/null +++ b/src/domain/artifactInspection.ts @@ -0,0 +1,476 @@ +import { createHash } from "node:crypto"; + +import canonicalize from "canonicalize"; +import { z } from "zod"; + +import { + artifactInventoryResultSchema, + type ArtifactInventoryResult, +} from "./artifactGraph.js"; +import { evidenceSchema, parseEvidence, type Evidence } from "./evidence.js"; +import { jsonValueSchema } from "./jsonValue.js"; + +const boundedTextSchema = z.string().min(1).max(4_096); +const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u); +const artifactIdSchema = z.string().regex(/^art_[a-f0-9]{64}$/u); + +const inspectionLimitsSchema = z.strictObject({ + max_observations: z.number().int().min(1).max(500).default(100), + max_relationships: z.number().int().min(1).max(500).default(100), + max_hypotheses: z.number().int().min(1).max(100).default(20), + max_unexplored_branches: z.number().int().min(1).max(100).default(20), + max_next_probes: z.number().int().min(1).max(50).default(20), + max_substeps: z.literal(1).default(1), +}); + +export const artifactInspectionLimitsSchema = inspectionLimitsSchema; + +const inspectionObservationSchema = z.strictObject({ + observation_id: z.string().regex(/^aio_[a-f0-9]{64}$/u), + kind: z.enum(["root-manifest", "artifact", "occurrence", "integrity"]), + subject: boundedTextSchema, + value: jsonValueSchema, + evidence_id: evidenceIdSchema, +}); + +const inspectionRelationshipSchema = z.strictObject({ + relationship_id: z.string().regex(/^air_[a-f0-9]{64}$/u), + relation: z.enum([ + "contains", + "extracts", + "slice-of", + "embeds", + "loads", + "maps-source", + "derived-from", + ]), + source_artifact_id: artifactIdSchema, + target_artifact_id: artifactIdSchema, + occurrence_id: z.string().regex(/^occ_[a-f0-9]{64}$/u), + logical_path: boundedTextSchema.nullable(), + evidence_id: evidenceIdSchema, +}); + +const inspectionHypothesisSchema = z.strictObject({ + hypothesis_id: z.string().regex(/^aih_[a-f0-9]{64}$/u), + statement: boundedTextSchema, + confidence: z.enum(["medium", "low"]), + basis_evidence_ids: z.array(evidenceIdSchema).min(1).max(8), + limitation: boundedTextSchema, +}); + +const inspectionContradictionSchema = z.strictObject({ + contradiction_id: z.string().regex(/^aic_[a-f0-9]{64}$/u), + statement: boundedTextSchema, + occurrence_id: z.string().regex(/^occ_[a-f0-9]{64}$/u), + declared_sha256: z.string().regex(/^[a-f0-9]{64}$/u), + observed_sha256: z.string().regex(/^[a-f0-9]{64}$/u), + evidence_id: evidenceIdSchema, +}); + +const nextProbeSchema = z.strictObject({ + operation: z.string().min(1).max(128), + rationale: boundedTextSchema, + authority: z.enum([ + "artifact-bytes", + "managed-static-analysis", + "native-analysis-provider", + "ast-static-analysis", + ]), +}); + +const unexploredBranchSchema = z.strictObject({ + branch_id: z.string().regex(/^aib_[a-f0-9]{64}$/u), + reason: z.enum([ + "page-limit", + "format-specific-analysis-required", + "unknown-format", + ]), + detail: boundedTextSchema, + next_probe: nextProbeSchema.nullable(), + evidence_id: evidenceIdSchema, +}); + +/** Provider-neutral inspection result with its atomic source Evidence. */ +export const artifactInspectionResultSchema = z.strictObject({ + schema_version: z.literal(1), + inspection_id: z.string().regex(/^ai_[a-f0-9]{64}$/u), + subject: z.strictObject({ + manifest_id: z.string().regex(/^agm_[a-f0-9]{64}$/u), + root_artifact_id: artifactIdSchema, + root_sha256: z.string().regex(/^[a-f0-9]{64}$/u), + root_format: z.string().min(1).max(128), + }), + substeps: z + .array( + z.strictObject({ + substep_id: z.string().regex(/^ais_[a-f0-9]{64}$/u), + operation: z.literal("inventory_artifact"), + status: z.literal("completed"), + evidence_id: evidenceIdSchema, + evidence: evidenceSchema, + }), + ) + .min(1) + .max(1), + observations: z.array(inspectionObservationSchema).max(500), + derived_relationships: z.array(inspectionRelationshipSchema).max(500), + hypotheses: z.array(inspectionHypothesisSchema).max(100), + contradictions: z.array(inspectionContradictionSchema).max(100), + unexplored_branches: z.array(unexploredBranchSchema).max(100), + next_probes: z.array(nextProbeSchema).max(50), + coverage: z.strictObject({ + status: z.enum(["complete-within-substeps", "partial", "truncated"]), + substeps_completed: z.literal(1), + observations_retained: z.number().int().min(0), + observations_omitted: z.number().int().min(0), + relationships_retained: z.number().int().min(0), + relationships_omitted: z.number().int().min(0), + hypotheses_retained: z.number().int().min(0), + hypotheses_omitted: z.number().int().min(0), + unexplored_branches_retained: z.number().int().min(0), + unexplored_branches_omitted: z.number().int().min(0), + next_probes_retained: z.number().int().min(0), + next_probes_omitted: z.number().int().min(0), + }), + evidence_links: z.array(evidenceIdSchema).min(1).max(1), + limitations: z.array(boundedTextSchema).max(1_000), +}); + +export type ArtifactInspectionLimits = z.infer< + typeof artifactInspectionLimitsSchema +>; +export type ArtifactInspectionResult = z.infer< + typeof artifactInspectionResultSchema +>; + +/** Project one successful inventory Evidence record into an inspection report. */ +export const createArtifactInspection = ( + inventoryInput: unknown, + limits: ArtifactInspectionLimits, +): ArtifactInspectionResult => { + const inventoryEvidence = parseInventoryEvidence(inventoryInput); + const inventory = artifactInventoryResultSchema.parse( + inventoryEvidence.normalized_result, + ); + const observations = allObservations( + inventory, + inventoryEvidence.evidence_id, + ); + const relationships = allRelationships( + inventory, + inventoryEvidence.evidence_id, + ); + const hypotheses = allHypotheses(inventory, inventoryEvidence.evidence_id); + const nextProbes = probesFor(inventory); + const branches = allUnexploredBranches( + inventory, + inventoryEvidence.evidence_id, + nextProbes, + ); + const retained = { + observations: observations.slice(0, limits.max_observations), + relationships: relationships.slice(0, limits.max_relationships), + hypotheses: hypotheses.slice(0, limits.max_hypotheses), + branches: branches.slice(0, limits.max_unexplored_branches), + probes: nextProbes.slice(0, limits.max_next_probes), + }; + const omissions = { + observations: observations.length - retained.observations.length, + relationships: relationships.length - retained.relationships.length, + hypotheses: hypotheses.length - retained.hypotheses.length, + branches: branches.length - retained.branches.length, + probes: nextProbes.length - retained.probes.length, + }; + const semantic = { + schema_version: 1 as const, + subject: { + manifest_id: inventory.manifest.manifest_id, + root_artifact_id: inventory.manifest.root_artifact_id, + root_sha256: inventory.manifest.root_sha256, + root_format: inventory.manifest.root_format, + }, + substeps: [ + { + substep_id: `ais_${digestCanonical({ + operation: "inventory_artifact", + evidence_id: inventoryEvidence.evidence_id, + })}`, + operation: "inventory_artifact" as const, + status: "completed" as const, + evidence_id: inventoryEvidence.evidence_id, + evidence: inventoryEvidence, + }, + ], + observations: retained.observations, + derived_relationships: retained.relationships, + hypotheses: retained.hypotheses, + contradictions: contradictions(inventory, inventoryEvidence.evidence_id), + unexplored_branches: retained.branches, + next_probes: retained.probes, + coverage: { + status: inspectionCoverage(inventory, omissions), + substeps_completed: 1 as const, + observations_retained: retained.observations.length, + observations_omitted: omissions.observations, + relationships_retained: retained.relationships.length, + relationships_omitted: omissions.relationships, + hypotheses_retained: retained.hypotheses.length, + hypotheses_omitted: omissions.hypotheses, + unexplored_branches_retained: retained.branches.length, + unexplored_branches_omitted: omissions.branches, + next_probes_retained: retained.probes.length, + next_probes_omitted: omissions.probes, + }, + evidence_links: [inventoryEvidence.evidence_id], + limitations: uniqueSorted([ + ...inventory.limitations, + "Inspection derives bounded static hypotheses and next probes; it does not execute the artifact or claim format-specific semantics.", + ]), + }; + return artifactInspectionResultSchema.parse({ + ...semantic, + inspection_id: `ai_${digestCanonical(semantic)}`, + }); +}; + +const parseInventoryEvidence = (input: unknown): Evidence => { + const evidence = parseEvidence(input); + if (evidence.operation !== "inventory_artifact") + throw new TypeError( + "Artifact inspection substep requires inventory_artifact Evidence", + ); + return evidence; +}; + +const allObservations = ( + inventory: ArtifactInventoryResult, + evidenceId: string, +): ArtifactInspectionResult["observations"] => [ + observation( + "root-manifest", + inventory.manifest.root_artifact_id, + inventory.manifest, + evidenceId, + ), + ...inventory.nodes.items.map((node) => + observation("artifact", node.artifact_id, node, evidenceId), + ), + ...inventory.occurrences.items.map((occurrence) => + observation("occurrence", occurrence.occurrence_id, occurrence, evidenceId), + ), + ...inventory.integrity_contradictions.map((value) => + observation("integrity", value.contradiction_id, value, evidenceId), + ), +]; + +const observation = ( + kind: ArtifactInspectionResult["observations"][number]["kind"], + subject: string, + value: unknown, + evidenceId: string, +): ArtifactInspectionResult["observations"][number] => { + const semantic = { + kind, + subject, + value: jsonValueSchema.parse(value), + evidence_id: evidenceId, + }; + return { observation_id: `aio_${digestCanonical(semantic)}`, ...semantic }; +}; + +const allRelationships = ( + inventory: ArtifactInventoryResult, + evidenceId: string, +): ArtifactInspectionResult["derived_relationships"] => + inventory.edges.items.map((edge) => { + const semantic = { + relation: edge.relation, + source_artifact_id: edge.parent_artifact_id, + target_artifact_id: edge.child_artifact_id, + occurrence_id: edge.occurrence_id, + logical_path: edge.logical_path, + evidence_id: evidenceId, + }; + return { + relationship_id: `air_${digestCanonical(semantic)}`, + ...semantic, + }; + }); + +const allHypotheses = ( + inventory: ArtifactInventoryResult, + evidenceId: string, +): ArtifactInspectionResult["hypotheses"] => { + const statements = + inventory.manifest.root_format === "pe" + ? [ + "The PE artifact may contain managed CLI metadata or native code; inventory bytes alone do not distinguish them.", + ] + : ["asar", "javascript-bundle"].includes(inventory.manifest.root_format) + ? [ + "The artifact may contain a recoverable JavaScript application graph.", + ] + : []; + return statements.map((statement) => { + const semantic = { + statement, + confidence: "low" as const, + basis_evidence_ids: [evidenceId], + limitation: + "Format classification proposes a bounded follow-up; it is not semantic proof.", + }; + return { hypothesis_id: `aih_${digestCanonical(semantic)}`, ...semantic }; + }); +}; + +const contradictions = ( + inventory: ArtifactInventoryResult, + evidenceId: string, +): ArtifactInspectionResult["contradictions"] => + inventory.integrity_contradictions.map((value) => { + const semantic = { + statement: `Declared integrity for ${value.logical_path} contradicts observed bytes.`, + occurrence_id: value.occurrence_id, + declared_sha256: value.declared_sha256, + observed_sha256: value.observed_sha256, + evidence_id: evidenceId, + }; + return { + contradiction_id: `aic_${digestCanonical(semantic)}`, + ...semantic, + }; + }); + +const probesFor = ( + inventory: ArtifactInventoryResult, +): ArtifactInspectionResult["next_probes"] => { + const format = inventory.manifest.root_format; + if (["asar", "javascript-bundle", "directory"].includes(format)) + return [ + { + operation: "analyze_javascript_application", + rationale: + "Recover bounded JavaScript modules, source maps, Electron boundaries, and application relationships.", + authority: "ast-static-analysis", + }, + ]; + if (format === "pe") + return [ + { + operation: "inspect_managed_artifact", + rationale: + "Check execution-free CLI metadata before choosing a deep native provider.", + authority: "managed-static-analysis", + }, + { + operation: "open_binary", + rationale: + "Open as native code only when managed inspection reports a native or mixed boundary.", + authority: "native-analysis-provider", + }, + ]; + if (["mach-o", "mach-o-universal", "elf"].includes(format)) + return [ + { + operation: "open_binary", + rationale: + "Bind one deep native provider before function-level analysis.", + authority: "native-analysis-provider", + }, + ]; + if (format === "plist") + return [ + { + operation: "inspect_plist", + rationale: "Parse property-list values without executing the artifact.", + authority: "artifact-bytes", + }, + ]; + return []; +}; + +const allUnexploredBranches = ( + inventory: ArtifactInventoryResult, + evidenceId: string, + nextProbes: ArtifactInspectionResult["next_probes"], +): ArtifactInspectionResult["unexplored_branches"] => { + const pages = [ + ["nodes", inventory.nodes.next_offset], + ["occurrences", inventory.occurrences.next_offset], + ["relationships", inventory.edges.next_offset], + ] as const; + const branches = pages.flatMap(([collection, nextOffset]) => + nextOffset === null + ? [] + : [ + branch( + "page-limit", + `${collection} continue at offset ${String(nextOffset)}.`, + null, + evidenceId, + ), + ], + ); + branches.push( + ...nextProbes.map((probe) => + branch( + "format-specific-analysis-required", + `${probe.operation} was not run by provider-neutral artifact inspection.`, + probe, + evidenceId, + ), + ), + ); + if (inventory.manifest.root_format === "unknown") + branches.push( + branch( + "unknown-format", + "Artifact bytes did not match an admitted format classifier.", + null, + evidenceId, + ), + ); + return branches; +}; + +const branch = ( + reason: ArtifactInspectionResult["unexplored_branches"][number]["reason"], + detail: string, + nextProbe: ArtifactInspectionResult["next_probes"][number] | null, + evidenceId: string, +): ArtifactInspectionResult["unexplored_branches"][number] => { + const semantic = { + reason, + detail, + next_probe: nextProbe, + evidence_id: evidenceId, + }; + return { branch_id: `aib_${digestCanonical(semantic)}`, ...semantic }; +}; + +const inspectionCoverage = ( + inventory: ArtifactInventoryResult, + omissions: Readonly>, +): ArtifactInspectionResult["coverage"]["status"] => { + if (Object.values(omissions).some((count) => count > 0)) return "truncated"; + return [ + inventory.nodes.next_offset, + inventory.occurrences.next_offset, + inventory.edges.next_offset, + ].some((offset) => offset !== null) + ? "partial" + : "complete-within-substeps"; +}; + +const digestCanonical = (value: unknown): string => { + const encoded = canonicalize(value); + if (encoded === undefined) + throw new TypeError("Artifact inspection could not canonicalize"); + return createHash("sha256").update(encoded).digest("hex"); +}; + +const uniqueSorted = (values: readonly string[]): string[] => + [...new Set(values)].sort((left, right) => + left < right ? -1 : left > right ? 1 : 0, + ); diff --git a/src/server/registerArtifactTools.ts b/src/server/registerArtifactTools.ts index 2cf7a5844..092ab0c32 100644 --- a/src/server/registerArtifactTools.ts +++ b/src/server/registerArtifactTools.ts @@ -7,6 +7,7 @@ import type { BinaryTarget } from "../domain/binaryTarget.js"; import type { Logger } from "../logger.js"; import { registerEvidenceTools } from "./registerEvidenceTools.js"; import type { PermissionAuthority } from "../application/PermissionAuthority.js"; +import { artifactInspectionResultSchema } from "../domain/artifactInspection.js"; /** Register deterministic artifact inventory and safe extraction operations. */ export const registerArtifactTools = ( @@ -19,5 +20,13 @@ export const registerArtifactTools = ( readonly permissionAuthority?: PermissionAuthority; }, ): void => { - registerEvidenceTools(server, analysis, ARTIFACT_TOOL_CONTRACTS, options); + registerEvidenceTools(server, analysis, ARTIFACT_TOOL_CONTRACTS, { + ...options, + sourceEvidence: (operation, result) => + operation === "inspect_artifact" + ? artifactInspectionResultSchema + .parse(result) + .substeps.map(({ evidence }) => evidence) + : [], + }); }; diff --git a/tests/artifactMcp.test.ts b/tests/artifactMcp.test.ts index 230f01446..8a030ee84 100644 --- a/tests/artifactMcp.test.ts +++ b/tests/artifactMcp.test.ts @@ -196,6 +196,26 @@ describe("artifact graph MCP integration", () => { }), ]), ); + const inspected = await client.callTool({ + name: "inspect_artifact", + arguments: { + integrity_policy: "record-and-continue", + integrity_continue_approved: true, + }, + }); + expect(inspected.isError).not.toBe(true); + expect(compactResult(inspected.structuredContent).result).toMatchObject({ + contradictions: [ + expect.objectContaining({ occurrence_id: expect.any(String) }), + expect.objectContaining({ occurrence_id: expect.any(String) }), + ], + substeps: [ + expect.objectContaining({ + operation: "inventory_artifact", + status: "completed", + }), + ], + }); const compared = await client.callTool({ name: "compare_artifacts", arguments: { @@ -326,6 +346,44 @@ describe("artifact graph MCP integration", () => { arguments: { path: archive }, }); expect(opened.isError).not.toBe(true); + const inspected = await client.callTool({ + name: "inspect_artifact", + arguments: { max_observations: 1, max_relationships: 1 }, + }); + expect(inspected.isError).not.toBe(true); + const inspectionResult = compactResult(inspected.structuredContent); + const inspectionEvidence = session.evidenceById( + inspectionResult.evidence_id, + ); + if (inspectionEvidence === undefined) + throw new Error("missing inspection Evidence"); + const inspection = z + .object({ + substeps: z.array( + z.object({ + evidence_id: z.string(), + status: z.literal("completed"), + }), + ), + coverage: z.object({ + status: z.literal("truncated"), + substeps_completed: z.literal(1), + }), + unexplored_branches: z.array(z.object({ reason: z.string() })), + }) + .parse(inspectionResult.result); + expect(inspection.substeps).toHaveLength(1); + expect( + session.evidenceById(inspection.substeps[0]?.evidence_id ?? ""), + ).toMatchObject({ operation: "inventory_artifact" }); + expect(inspectionEvidence.evidence_links).toEqual([ + inspection.substeps[0]?.evidence_id, + ]); + expect(inspection.unexplored_branches).toEqual( + expect.arrayContaining([ + expect.objectContaining({ reason: "page-limit" }), + ]), + ); const inventory = await client.callTool({ name: "inventory_artifact", arguments: {}, @@ -381,7 +439,7 @@ describe("artifact graph MCP integration", () => { const envelope = z .object({ result: evidenceBundleSchema }) .parse(exported.structuredContent); - expect(envelope.result.records).toHaveLength(4); + expect(envelope.result.records).toHaveLength(6); expect(envelope.result.artifacts).toContainEqual({ digest: { sha256: evidence.subject?.digest.sha256 }, format: "ipa", diff --git a/tests/artifactProvider.test.ts b/tests/artifactProvider.test.ts index 0a72c5307..d3852aebb 100644 --- a/tests/artifactProvider.test.ts +++ b/tests/artifactProvider.test.ts @@ -23,6 +23,7 @@ import { } from "../src/artifacts/ArtifactPaths.js"; import { artifactExtractionInputSchema, + artifactInspectionInputSchema, artifactInventoryInputSchema, } from "../src/contracts/artifactToolContracts.js"; import type { BinaryTarget } from "../src/domain/binaryTarget.js"; @@ -34,6 +35,7 @@ import { artifactExtractionResultSchema, artifactInventoryResultSchema, } from "../src/domain/artifactGraph.js"; +import { artifactInspectionResultSchema } from "../src/domain/artifactInspection.js"; describe("artifact graph provider", () => { it("inventories app trees deterministically without following symlinks", async () => { @@ -124,6 +126,28 @@ describe("artifact graph provider", () => { provider: { id: "rea-artifact-graph" }, subject: { format: "apk" }, }); + const inspectionEvidence = parseEvidence( + await runProviderAnalysis(zipPath, "inspect_artifact", { + max_observations: 2, + max_relationships: 1, + }), + ); + const inspection = artifactInspectionResultSchema.parse( + inspectionEvidence.normalized_result, + ); + expect(inspection).toMatchObject({ + substeps: [ + { + operation: "inventory_artifact", + status: "completed", + evidence_id: expect.stringMatching(/^ev_[a-f0-9]{64}$/u), + }, + ], + coverage: { status: "truncated", substeps_completed: 1 }, + }); + expect(inspectionEvidence.evidence_links).toEqual( + inspection.evidence_links, + ); const cancellation = new AbortController(); cancellation.abort(); await expect( @@ -135,6 +159,15 @@ describe("artifact graph provider", () => { cancellation.signal, ), ).resolves.toMatchObject({ code: "cancelled" }); + await expect( + runProviderAnalysis( + zipPath, + "inspect_artifact", + {}, + undefined, + cancellation.signal, + ), + ).resolves.toMatchObject({ code: "cancelled" }); const source = join(root, "asar-source"); await mkdir(source); @@ -177,6 +210,13 @@ describe("artifact graph provider", () => { }, }, }); + const failedInspection = await new ArtifactProvider() + .createClient(target(unpackedPath, "asar")) + .execute("inspect_artifact", artifactInspectionInputSchema.parse({})); + expect(failedInspection).toMatchObject({ + ok: false, + error: { _tag: "ArtifactOperationError", reason: "integrity" }, + }); }); it.each([