Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

feat(artifacts): add provider-neutral inspection

morlutod9977286f950
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<void> {
return Promise.resolve();
}
+
+ private async inspectArtifact(
+ parameters: Readonly<Record<string, JsonValue>>,
+ 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<Record<string, Readonly<Record<string, unknown>>>> = {
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<Record<string, number>>,
+): 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([