CAMPAIGN GRAPH Docs — Unified Evidence DAG

Overview

CAMPAIGN GRAPH provides a single Ed25519-signed directed acyclic graph for evidence produced across all 120 NIGHTFALL tools. Each node is a finding from a tool report. Each edge is a causal, enabling, preceding, or corroborating relationship between findings. The final exported bundle contains the full hash chain and a single signature covering the entire engagement.

Tool: campaign-graph | Version: 1.0.0 | Gate: OPEN/FORGE/CORTEX | Tests: 279

Install

git clone https://github.com/RichardBarron27/red-specter-campaign-graph
cd red-specter-campaign-graph
pip install -e ".[dev]"        # core + dev extras
pip install -e ".[dev,viz]"    # + graphviz for DOT export
pip install -e ".[dev,cortex]" # + Anthropic SDK for aggressive link
campaign-graph --version

Quick Start

# 1. Generate operator Ed25519 key pair
campaign-graph keygen --out ./keys
export CAMPAIGN_GRAPH_PRIVATE_KEY=./keys/campaign_graph_priv.pem

# 2. Initialise campaign database
campaign-graph --db ops/campaign.db --clearance FORGE init

# 3. Ingest NIGHTFALL tool reports
campaign-graph --db ops/campaign.db --clearance FORGE ingest \
  reports/VLT-4A8BC201.json \
  reports/SHD-RPT-15E4EC76.json \
  reports/TBT-1A2B3C4D.json

# 4. Auto-link by shared entity
campaign-graph --db ops/campaign.db --clearance FORGE link auto

# 5. Query critical path
campaign-graph --db ops/campaign.db query critical-path --format json

# 6. Export signed bundle
campaign-graph --db ops/campaign.db export campaign-final.json

# 7. Verify anywhere
campaign-graph verify --file campaign-final.json --pub-key keys/campaign_graph_pub.pem

CLI Reference

keygen

campaign-graph keygen --out DIR [--force]

Flag	Description
`--out DIR`	Output directory for priv.pem and pub.pem
`--force`	Overwrite existing keys

init

campaign-graph --db PATH --clearance FORGE init [--description TEXT]

Creates a new SQLite-backed campaign database. Sets schema version, operator fingerprint, and creation timestamp.

ingest

campaign-graph --db PATH --clearance FORGE ingest FILE [FILE ...] [--allow-unsigned]

Flag	Description
`FILE`	One or more NIGHTFALL tool report JSON files
`--allow-unsigned`	Accept reports without Ed25519 signatures (marks provenance as UNVERIFIED)

Supported tool families: all 120 NIGHTFALL tools via adapter registry. Reports not matching a known adapter are ingested as RAW_JSON nodes.

link auto

campaign-graph --db PATH --clearance FORGE link auto [--edge-types CAUSES,ENABLES,PRECEDES]

Joins findings on exact entity match. Any two nodes sharing an entity are connected. Edge direction is inferred from timestamps: earlier node → later node.

link aggressive

campaign-graph --db PATH --clearance FORGE link aggressive [--model claude-sonnet-4-6]

Requires cortex extra and ANTHROPIC_API_KEY. Sends all node pairs to Claude claude-sonnet-4-6 for causal relationship reasoning. Infers edges that exact-match misses — e.g. "VAULT extracted embeddings containing an OAuth token that DELEGATE then used for scope escalation."

query

campaign-graph --db PATH query SUBCOMMAND [OPTIONS]

Subcommand	Description
`critical-path`	Longest weighted path by CVSS product score
`entity ENTITY_ID`	All findings touching a specific entity
`timeline`	All findings ordered by timestamp
`surface-summary`	Findings grouped by kill chain phase

merge

campaign-graph merge --src A.db --dst B.db --strategy NEWER_WINS|HIGHER_CVSS|MANUAL

Merges two campaign graphs. Deduplication on finding SHA-256 hash. Provenance from both sources is preserved.

export

campaign-graph --db PATH export OUTPUT [--format json|markdown|stix|dot]

Signs the full graph with the operator’s private key and writes to file. Default format is JSON. STIX 2.1 format is suitable for law enforcement and IETF disclosure. DOT format requires the viz extra.

verify

campaign-graph verify --file BUNDLE --pub-key PUB_PEM

Standalone verification. Confirms Ed25519 signature, SHA-256 hash chain integrity, and schema version compatibility. No private key required. Safe to run at the recipient’s site.

Gate System

Gate	Operations	Requirement
OPEN	keygen, verify, query (read-only)	None
FORGE	init, ingest, link auto, merge, export	CAMPAIGN_GRAPH_PRIVATE_KEY env var set to valid Ed25519 PEM key
CORTEX	link aggressive	FORGE requirements + ANTHROPIC_API_KEY

Entity Model

Entity Type	Identifier Format	Example
HOST	IP or FQDN	10.0.0.42, api.target.com
AGENT_ID	Deployment name or UUID	rag-agent-prod, 7f3a-...
MCP_URI	Full MCP endpoint URL	mcp://tools.target.com/filesystem
OAUTH_CLIENT	client_id:scope_hash	abc123:read:files,write:messages
MODEL_ID	registry/name:version	huggingface/org/model:v1.2
MEMORY_BACKEND	backend_type:connection_hash	redis:sha256:a1b2c3...
NHI_CRED	credential_type:prefix	openai_api_key:sk-proj-
A2A_CARD	Agent card URL	https://agent.target.com/.well-known/agent.json
VECTOR_STORE	db_type:host:collection	qdrant:10.0.0.5:docs

Output Formats

Format	Use Case	Schema
JSON	Machine processing, API ingestion	NIGHTFALL Campaign Bundle v1.0
Markdown	Human-readable engagement report	—
STIX 2.1	Law enforcement, IETF disclosure, CTI sharing	STIX 2.1 + NIGHTFALL extension
DOT	Graphviz visualisation (requires viz extra)	DOT language