Knowledge Graph

The Neo4j-backed attack graph that turns ephemeral findings into a queryable engagement record.

A long red team engagement produces hundreds of findings, credentials, hosts, services, and detection artifacts. Storing them as flat JSON loses the relationships that make red team output useful — which credential opened which host? which detection covers which technique? Decepticon stores them in a Neo4j graph instead.

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 through KGMiddleware, 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.

Agents never write raw Cypher in their prompts. Read paths go through the middleware’s typed summary projections (and through Skillogy for ATT&CK lookups); write paths go through 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:7474 with credentials from the onboarding wizard.
• CLI: decepticon kg-health runs 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:

1. A JSON export of all nodes and edges.
2. An ATT&CK Navigator layer derived from the graph.
3. A “blue spots” overlay — vulnerabilities the engagement found that the customer’s existing detections do not cover.
4. 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.

Querying the graph mid-engagement is one of the highest-leverage operator actions. A Cypher query like MATCH (a:Account)-[:OWNS]->(c:Credential)-[:AUTHENTICATES_TO]->(h:Host) WHERE NOT (h)-[:RESPONDS_TO]-() RETURN h finds every reachable host whose blue team has no detection.

Offensive Vaccine Pipeline

How DefenseAction nodes are produced by the Detector and Patcher agents.