Skip to main content

Evidence and AI-assisted triage

Vulkro's scan engine is fully deterministic and runs with no network access. It embeds no model. What it does instead is produce structured, machine-readable evidence that an external AI agent (or a human) can reason about with the scan result as ground truth. This guide ties together the four surfaces that make that possible: the evidence graph, proof harnesses, cross-repo aggregation, and the opt-in advisory triage lens.

The boundary is deliberate. Everything below except vulkro triage is offline and deterministic. vulkro triage is the only command that calls a model, and it never changes the deterministic finding output.

Evidence graph​

--format evidence-graph emits a stable, versioned JSON document (evidence-graph/1.0) that composes endpoints, taint source-to-sink flows, reachability verdicts, findings, and the dependency SBOM into one graph:

vulkro scan . --format evidence-graph > graph.json

The graph is designed to be handed to an external AI agent as deterministic ground truth: the agent brings its own model, and the graph tells it exactly what the scanner saw. vulkro discover . --format evidence-graph produces the same shape from the discovery pass when you only need the endpoint and flow structure.

Proof harnesses​

vulkro prove turns eligible findings into runnable test files that a developer can execute to confirm a finding is a true positive:

vulkro prove .

For each injection or broken-authorization finding it emits a harness: a fast-check property test plus a concrete proof-of-concept for JS/TS, a Hypothesis and pytest harness for Python, and a generated @isTest class for Apex (runnable inside a Salesforce org). Vulkro only writes the harness text. It never compiles or runs it. Findings with no runnable proof shape (config, inventory, code quality) or in a language without an emitter are listed with a reason rather than dropped silently.

Cross-repo aggregation​

A single repository rarely tells the whole story. vulkro aggregate links evidence-graph exports from several repositories to surface candidate cross-repo flows:

vulkro scan service-a . --format evidence-graph > a.json
vulkro scan service-b . --format evidence-graph > b.json
vulkro aggregate a.json b.json

The linker is deterministic: an outbound HTTP client call in one repo whose normalised route shape and method match an exposed endpoint in another repo is emitted as a candidate cross-repo link. The links are ground truth for an external agent to investigate, not a verdict.

Advisory triage​

vulkro triage is the one command that calls a model, and it is opt-in. Every verdict it prints is labelled advisory and non-deterministic, and none of it mutates the finding severity or the JSON output the benchmark consumes.

export VULKRO_TRIAGE_API_KEY=<your-anthropic-key>
vulkro triage .

It brings your own key: VULKRO_TRIAGE_API_KEY is required (ANTHROPIC_API_KEY is accepted as a fallback), and with neither set it exits 2 with guidance. Under VULKRO_OFFLINE it refuses to run, because it makes an outbound call, and exits 2 with a message. The deterministic scan is unaffected and stays fully offline. Exit codes: 0 when nothing needed triage, 1 when advisory verdicts were reported, 2 on error.

Feed a scan to an agent live​

vulkro mcp serve runs Vulkro as a Model Context Protocol server that Claude Desktop, Cursor, Windsurf, Continue, and other JSON-RPC MCP clients can call as a tool. This lets an agent request a scan and read the evidence during a coding session rather than after the fact.

vulkro mcp serve
Last updated on