feat(artifacts): add provider-neutral inspection
This commit is contained in:
@@ -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 };
|
||||
|
||||
@@ -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: {
|
||||
|
||||
@@ -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,
|
||||
),
|
||||
),
|
||||
});
|
||||
};
|
||||
|
||||
@@ -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.",
|
||||
|
||||
@@ -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,
|
||||
);
|
||||
@@ -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)
|
||||
: [],
|
||||
});
|
||||
};
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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([
|
||||
|
||||
Reference in New Issue
Block a user