Why a Graph
Attack paths are graphs by nature. A pivot is a relationship; a credential is an edge between an account and a host; a defense brief connects a vulnerability to a detection. Modeling this as a graph means:- The orchestrator can query “which hosts can I reach from this credential?” in one Cypher query, not by re-reading conversation history.
- The defender’s deliverable is a structured graph, not a PDF — easy to overlay on existing detection coverage.
- Cross-engagement queries become possible: “did this CVE show up in any prior engagement against this customer?”
Node Types
| Node | Represents |
|---|---|
Host | A discovered host or asset (IP, hostname, OS) |
Service | A network service running on a host (port, protocol, banner, version) |
Account | A discovered identity (user, service, machine account) |
Credential | A captured secret (password, hash, token, key) |
Vulnerability | A confirmed weakness (CVE, misconfiguration) |
Finding | A verified observation produced by an agent |
DefenseAction | A detection rule, mitigation, or patch produced by the Vulnresearch pipeline (Detector, Patcher). The schema reserves room for the planned Defender component to write here once it ships. |
Edge Types
| Edge | Meaning |
|---|---|
RUNS_ON | Service runs on Host |
OWNS | Account owns Credential |
AUTHENTICATES_TO | Credential authenticates to Host or Service |
EXPLOITS | Finding exploits Vulnerability |
DETECTS | DefenseAction detects Finding’s technique |
MITIGATES | DefenseAction mitigates Vulnerability |
RESPONDS_TO | DefenseAction responds to Finding |
LATERAL_TO | Host pivots to Host (with credential or technique attribution) |
Tools the Agents Use
The graph is exposed to agents throughKGMiddleware, which builds two tools per attaching role and dispatches them through a shared KGStore (packages/decepticon/decepticon/middleware/kg_internal/):
| Tool | Purpose |
|---|---|
kg_record(observations) | Atomic batch write of nodes and edges. The middleware validates the engagement label, applies schema constraints, and wraps the call in a single transaction so partial writes never leave the graph in a torn state. |
kg_ingest(scanner_kind, path) | Dispatcher into the scanner adapter registry — nmap_xml, sarif, bloodhound_zip, slither_json, and any plugin-registered scanner. Reads the file, parses, and emits node/edge observations into the same atomic write path as kg_record. |
kg_record / kg_ingest. This keeps the engagement scope, schema validation, and migration-runner contract centralized so a buggy specialist can’t corrupt the graph.
The pre-middleware standalone @tool functions (kg_add_node, kg_add_edge, kg_query, kg_neighbors) are still importable from decepticon.tools.research.tools for transitional callers and emit a DeprecationWarning. New code should attach KGMiddleware and use the middleware-built surface.
Operator Access
The graph is also exposed to the operator:- Browser: Neo4j browser at
http://localhost:7474with credentials from the onboarding wizard. - CLI:
decepticon kg-healthruns diagnostics and surfaces orphan nodes or missing relationships. - Web Dashboard: The attack graph canvas in the Next.js dashboard renders the live engagement graph.
The Graph as Deliverable
At engagement out-brief, the graph becomes part of the deliverable. The blue team gets:- A JSON export of all nodes and edges.
- An ATT&CK Navigator layer derived from the graph.
- A “blue spots” overlay — vulnerabilities the engagement found that the customer’s existing detections do not cover.
- A “red spots” overlay — detections that fired against Decepticon’s actions, proving the SOC works.
Privacy and OPSEC
The graph is engagement-scoped. Customer data captured during the engagement (credential strings, service banners, sensitive paths) is encrypted at rest in Neo4j and purged when the engagement is closed unless explicitly retained for the deliverable.Offensive Vaccine Pipeline
How DefenseAction nodes are produced by the Detector and Patcher agents.