Skip to main content

vulkro aggregate

Link evidence-graph exports from several repositories to surface candidate cross-repo flows.

Each input is a JSON document produced by vulkro scan <repo> --format evidence-graph (or vulkro discover <repo> --format evidence-graph). 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.

Vulkro embeds no model. The surfaced links are ground truth that an external AI agent then reasons about. Vulkro decides what matches; the agent decides whether a matched flow is a real risk.

Usage​

vulkro aggregate <GRAPH_JSON> <GRAPH_JSON> [MORE...] [FLAGS]

Two or more evidence-graph JSON files are required (one per repository). One graph has nothing to link against.

Flags​

FlagDescriptionDefault
--format, -f <FMT>json emits the full evidence-aggregate/1.0 document. table prints a human-readable summary of the candidate links.json

Exit codes​

CodeMeaning
0No cross-repo links found.
1One or more candidate links reported.
2Error: bad argument, unreadable file, fewer than two graphs, or bad JSON.

How the linker matches​

For every outbound call in every repo, the linker looks for endpoints in other repos whose normalised route shape matches and whose HTTP method is compatible (equal, or either side is ANY). Each match becomes one CrossRepoLink carrying:

  • the caller repo, call id, URL, file, and line;
  • the callee repo, endpoint id, path, file, and line;
  • the shared route shape and method;
  • the callee endpoint's auth posture, so an agent can see at a glance whether a cross-repo caller reaches an unauthenticated surface;
  • the deterministic match_reasons the linker paired the two on. These are never a verdict.

The aggregate summary rolls up the repo count, the total number of cross-repo links, and how many of those links reach an unauthenticated callee endpoint (the ones most worth an agent's attention first).

Evidence-graph workflow​

aggregate is the multi-repo half of the deterministic, AI-usable evidence-graph workflow:

  1. Export one evidence graph per repo with vulkro scan <repo> --format evidence-graph > <repo>.json.
  2. Run vulkro aggregate a.json b.json c.json to link them.
  3. Hand the aggregate document to an AI agent as ground truth to investigate.

The same two steps are also available as MCP tools (evidence_graph and aggregate) on vulkro mcp serve, so an agent already speaking MCP can pull and link graphs without shelling out.

Examples​

# Export a graph per repo.
vulkro scan ../api      --format evidence-graph > api.json
vulkro scan ../frontend --format evidence-graph > frontend.json

# Link them and read the summary.
vulkro aggregate api.json frontend.json --format table

# Full JSON document for an agent or a pipeline.
vulkro aggregate api.json frontend.json > cross-repo.json

Command reference​

Generated from vulkro help aggregate on vulkro 0.26.0. This block is the authoritative flag, usage, and exit-code reference for this command; the prose above is the friendly explanation. Do not edit this block by hand; run npm run docs:cli after a release.

[Pro] Link scan exports from several repositories to spot data flows that cross repo boundaries.

Link evidence-graph exports from several repositories to surface candidate cross-repo flows for an AI agent to investigate.

Each input is a JSON document produced by `vulkro scan <repo> --format evidence-graph` (or `vulkro discover <repo> --format evidence-graph`). 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 `CrossRepoLink`. Vulkro embeds no model; the surfaced links are ground truth an external AI agent then reasons about. See `docs/ai-tool/` for the schema and workflow.

Exit codes: `0` no cross-repo links found, `1` one or more candidate links reported, `2` arg error, unreadable file, or bad JSON.

Usage: vulkro aggregate [OPTIONS] <GRAPH_JSON>...

Arguments:
  <GRAPH_JSON>...
          Two or more evidence-graph JSON files, one per repository

Options:
  -f, --format <FORMAT>
          Output format: `json` (the full aggregate document, default) or `table` (a human-readable summary of the candidate links)

          Possible values:
          - json:  The full `evidence-aggregate/1.0` JSON document (default)
          - table: Human-readable summary of the candidate cross-repo links
          
          [default: json]

      --offline
          Hard-disable every outbound network call for this run (sets VULKRO_OFFLINE=1). Blocks the CVE feed, the license heartbeat, the update check, webhooks, and any cloud AI endpoint; a loopback model (http://127.0.0.1, http://localhost) is still allowed. Equivalent to exporting VULKRO_OFFLINE=1, and the flag wins when both are set

  -h, --help
          Print help (see a summary with '-h')
Last updated on