ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
Python active-directorycloud-securitydefensive-validationfastapigood-first-issuemitre-attackopsecreactred-teamreportingsecurity
"""
ARES Attack Knowledge Graph
NetworkX-based directed graph of attack relationships.
Nodes = artifacts (hosts, users, credentials, permissions)
Edges = attack relationships (can_kerberoast, has_access, can_dcsync, owns)
Example graph after AD recon:
CORP.LOCAL (domain)
└─[has_user]──► svc_sql (user)
└─[has_spn]──► MSSQLSvc/db01 (service)
└─[kerberoastable]──► krb5tgs hash (hash)
CORP.LOCAL (domain)
└─[has_acl]──► svc_backup (user)
└─[writedacl_on]──► Domain Admins (group)
└─[dcsync_path]──► NTDS hashes (credential)
Attack path query:
graph.shortest_attack_path("low_priv_user", "domain_admin")
→ [user → WriteDACL → Domain Admins → DCSync → hash → crack → DA]
JSON export is compatible with D3.js force graph visualization.
"""
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any
from ares.core.logger import get_logger
from ares.normalize.artifacts import (
ArtifactStore,
CredentialArtifact,
HashArtifact,
HostArtifact,
PermissionArtifact,
UserArtifact,
)
try:
import networkx as nx
_NX_AVAILABLE = True
except ImportError:
_NX_AVAILABLE = False
logger = get_logger("ares.graph")
_GRAPH_SECRET_KEYS = {
"secret", "secret_enc", "password", "passwd", "token", "api_key",
"private_key", "hash_value", "nt_hash", "lm_hash", "cracked_value",
}
def _safe_graph_value(value: Any) -> Any:
"""Drop secret-bearing fields before graph data is persisted or returned."""
if isinstance(value, dict):
return {
str(key): _safe_graph_value(item)
for key, item in value.items()
if str(key).lower() not in _GRAPH_SECRET_KEYS
}
if isinstance(value, list):
return [_safe_graph_value(item) for item in value]
if isinstance(value, (str, int, float, bool)) or value is None:
return value
return str(value)
# ── Edge types ────────────────────────────────────────────────────────────────
class EdgeType(str):
HAS_USER = "has_user"
HAS_GROUP = "has_group"
HAS_HOST = "has_host"
MEMBER_OF = "member_of"
HAS_SPN = "has_spn"
KERBEROASTABLE = "kerberoastable"
ASREPROASTABLE = "asreproastable"
HAS_CRED = "has_credential"
ACE = "ace" # principal→right→target
DCSYNC_PATH = "dcsync_path"
CAN_ACCESS = "can_access"
OWNS = "owns"
ADMIN_ON = "admin_on"
HAS_SESSION = "has_session"
TRUST = "trust"
# ── Graph node ────────────────────────────────────────────────────────────────
@dataclass
class GraphNode:
node_id: str
label: str
node_type: str # host | user | group | credential | domain | hash | permission
properties: dict[str, Any] = field(default_factory=dict)
risk_score: float = 0.0
is_target: bool = False # high-value targets: DA, DC, krbtgt
@dataclass
class GraphEdge:
source: str
target: str
edge_type: str
label: str = ""
weight: float = 1.0 # lower weight = easier attack path
properties: dict[str, Any] = field(default_factory=dict)
# ── Attack graph ──────────────────────────────────────────────────────────────
class AttackGraph:
"""
Directed graph of attack relationships.
Built from normalized artifacts, queryable for attack paths.
Usage:
graph = AttackGraph()
graph.build_from_store(artifact_store)
paths = graph.attack_paths_to_domain_admin()
viz = graph.to_d3_json()
"""
# Node type → visual color (for dashboard/D3)
NODE_COLORS: dict[str, str] = {
"domain": "#ef4444", # red
"host": "#3b82f6", # blue
"user": "#10b981", # green
"group": "#f59e0b", # yellow
"credential": "#8b5cf6", # purple
"hash": "#ec4899", # pink
"permission": "#f97316", # orange
"cloud": "#06b6d4", # cyan
}
# High-value targets - finding a path to these is the goal
HIGH_VALUE_LABELS = {
"Domain Admins", "Enterprise Admins", "Schema Admins",
"Administrators", "krbtgt", "NTDS.dit",
}
def __init__(self) -> None:
if not _NX_AVAILABLE:
raise ImportError(
"networkx is required for attack graph: pip install networkx"
)
self._g: Any = nx.DiGraph()
self._nodes: dict[str, GraphNode] = {}
self._edges: list[GraphEdge] = []
@classmethod
def from_d3_json(cls, payload: dict[str, Any]) -> "AttackGraph":
"""Rehydrate a graph snapshot produced by :meth:`to_d3_json`."""
graph = cls()
graph.load_d3_json(payload)
return graph
def load_d3_json(self, payload: dict[str, Any]) -> "AttackGraph":
"""Load safe D3 graph metadata into this graph instance."""
for raw_node in payload.get("nodes", []):
if not isinstance(raw_node, dict) or not raw_node.get("id"):
continue
node = GraphNode(
node_id=str(raw_node["id"]),
label=str(raw_node.get("label") or raw_node["id"]),
node_type=str(raw_node.get("type") or "unknown"),
properties=_safe_graph_value(raw_node.get("properties", {})),
risk_score=float(raw_node.get("risk", 0.0) or 0.0),
is_target=bool(raw_node.get("is_target", False)),
)
self._add_node(node)
for raw_edge in payload.get("links", []):
if not isinstance(raw_edge, dict):
continue
source, target = raw_edge.get("source"), raw_edge.get("target")
if not source or not target:
continue
self._add_edge(GraphEdge(
source=str(source),
target=str(target),
edge_type=str(raw_edge.get("type") or "related"),
label=str(raw_edge.get("label") or ""),
weight=float(raw_edge.get("weight", 1.0) or 1.0),
properties=_safe_graph_value(raw_edge.get("properties", {})),
))
return self
def add_persisted_campaign_data(
self,
hosts: list[dict[str, Any]],
findings: list[dict[str, Any]],
credentials: list[dict[str, Any]],
) -> "AttackGraph":
"""Add durable host/finding/credential metadata without any secret values."""
host_ids: dict[str, str] = {}
for host in hosts:
ip = str(host.get("ip_address") or "")
if not ip:
continue
node_id = f"host:{ip}"
host_ids[ip.lower()] = node_id
hostname = str(host.get("hostname") or "").strip().lower()
if hostname:
host_ids[hostname] = node_id
if "." in hostname:
host_ids[hostname.split(".")[0]] = node_id
fqdn = str(host.get("fqdn") or "").strip().lower()
if fqdn:
host_ids[fqdn] = node_id
if "." in fqdn:
host_ids[fqdn.split(".")[0]] = node_id
label = str(host.get("hostname") or ip)
self._add_node(GraphNode(
node_id=node_id,
label=label,
node_type="domain_controller" if host.get("is_dc") else "host",
properties={
"ip": ip,
"hostname": host.get("hostname") or "",
"os": host.get("os") or "",
"domain": host.get("domain") or "",
"open_ports": host.get("open_ports_json") or [],
},
risk_score=4.0 if host.get("is_dc") else 2.0,
is_target=bool(host.get("is_dc")),
))
# Lateral movement paths between hosts in the environment
dc_ids = [f"host:{h.get('ip_address')}" for h in hosts if h.get("is_dc")]
ws_ids = [
f"host:{h.get('ip_address')}" for h in hosts
if not h.get("is_dc") and any(w in str(h.get("hostname", "")).lower() for w in ("ws", "pc", "client", "workstation"))
]
srv_ids = [
f"host:{h.get('ip_address')}" for h in hosts
if not h.get("is_dc") and any(s in str(h.get("hostname", "")).lower() for s in ("sql", "fs", "srv"))
]
for ws_id in ws_ids:
for srv_id in srv_ids:
if ws_id in self._g and srv_id in self._g and ws_id != srv_id:
self._add_edge(GraphEdge(
source=ws_id, target=srv_id,
edge_type="lateral", label="pivot", weight=1.5,
))
for srv_id in srv_ids:
for dc_id in dc_ids:
if srv_id in self._g and dc_id in self._g and srv_id != dc_id:
self._add_edge(GraphEdge(
source=srv_id, target=dc_id,
edge_type="lateral", label="domain_admin", weight=2.0,
))
for finding in findings:
finding_id = str(finding.get("id") or "")
title = str(finding.get("title") or "Finding")
node_id = f"finding:{finding_id or title[:80]}"
self._add_node(GraphNode(
node_id=node_id,
label=title,
node_type="finding",
properties={
"severity": finding.get("severity") or "info",
"module_id": finding.get("module_id") or "",
"cvss_score": finding.get("cvss_score") or 0.0,
"mitre_technique": finding.get("mitre_technique") or "",
"trace_id": finding.get("trace_id") or "",
},
risk_score=float(finding.get("cvss_score") or 0.0),
))
host = str(finding.get("host") or "").strip().lower()
target_host_node = host_ids.get(host)
if not target_host_node and "." in host:
target_host_node = host_ids.get(host.split(".")[0])
if not target_host_node and host and host not in ("localhost", "127.0.0.1"):
target_host_node = f"host:{host}"
host_ids[host] = target_host_node
self._add_node(GraphNode(
node_id=target_host_node,
label=host,
node_type="host",
properties={"ip": host, "hostname": host},
risk_score=2.0,
is_target=False,
))
if not target_host_node and len(host_ids) == 1:
target_host_node = list(host_ids.values())[0]
if target_host_node and target_host_node in self._g:
self._add_edge(GraphEdge(
source=target_host_node, target=node_id,
edge_type="finding", label="finding", weight=1.0,
))
for credential in credentials:
cred_id = str(credential.get("id") or "")
username = str(credential.get("username") or "credential")
domain = str(credential.get("domain") or "")
self._add_node(GraphNode(
node_id=f"credential:{cred_id or username}",
label=f"{domain}\\{username}" if domain else username,
node_type="credential",
properties={
"cred_type": credential.get("cred_type") or "",
"source_module": credential.get("source_module") or "",
"cracked": bool(credential.get("cracked", False)),
},
risk_score=2.0,
))
return self
# ── Build from artifact store ──────────────────────────────────────────
def build_from_store(self, store: ArtifactStore) -> "AttackGraph":
"""
Automatically build graph from all artifacts in a store.
This is the main entry point - call after a campaign run.
"""
for host in store.hosts():
self._add_host(host)
for user in store.users():
self._add_user(user)
for perm in store.permissions():
self._add_permission(perm)
for h in store.hashes():
self._add_hash(h)
for cred in store.credentials():
self._add_credential(cred)
logger.info(
"graph_built",
nodes=self._g.number_of_nodes(),
edges=self._g.number_of_edges(),
)
return self
def _add_host(self, host: HostArtifact) -> None:
nid = host.uid
self._add_node(GraphNode(
node_id=nid, label=host.hostname or host.ip_address,
node_type="host" if not host.is_dc else "domain_controller",
properties={"ip": host.ip_address, "os": host.os, "is_dc": host.is_dc},
risk_score=4.0 if host.is_dc else 2.0,
is_target=host.is_dc,
))
def _add_user(self, user: UserArtifact) -> None:
nid = user.uid
self._add_node(GraphNode(
node_id=nid, label=f"{user.domain}\\{user.username}",
node_type="user",
properties={
"username": user.username, "domain": user.domain,
"is_admin": user.is_admin, "enabled": user.enabled,
"spns": user.spns, "no_preauth": user.no_preauth,
},
risk_score=5.0 if user.is_admin else (3.0 if user.spns else 1.0),
is_target=user.is_admin or "Domain Admins" in user.member_of,
))
# User → group membership edges
for group in user.member_of:
group_nid = f"group:{user.domain}:{group}"
self._add_node(GraphNode(
node_id=group_nid, label=group,
node_type="group",
is_target=group in self.HIGH_VALUE_LABELS,
risk_score=5.0 if group in self.HIGH_VALUE_LABELS else 2.0,
))
self._add_edge(GraphEdge(
source=nid, target=group_nid,
edge_type=EdgeType.MEMBER_OF, label="member of",
weight=0.5,
))
# SPN → kerberoastable edge
if user.is_kerberoastable:
hash_nid = f"hash:krb5tgs:{user.uid}"
self._add_node(GraphNode(
node_id=hash_nid, label=f"TGS:{user.username}",
node_type="hash",
properties={"hashcat_mode": 13100, "hash_type": "krb5tgs"},
risk_score=3.5,
))
self._add_edge(GraphEdge(
source=nid, target=hash_nid,
edge_type=EdgeType.KERBEROASTABLE,
label="kerberoastable",
weight=1.0,
properties={"attack": "ad.kerberoast"},
))
# ASREPRoastable edge
if user.is_asreproastable:
hash_nid = f"hash:krb5asrep:{user.uid}"
self._add_node(GraphNode(
node_id=hash_nid, label=f"AS-REP:{user.username}",
node_type="hash",
properties={"hashcat_mode": 18200, "hash_type": "krb5asrep"},
risk_score=3.5,
))
self._add_edge(GraphEdge(
source=nid, target=hash_nid,
edge_type=EdgeType.ASREPROASTABLE,
label="asreproastable (no creds needed)",
weight=0.5, # lower = easier
properties={"attack": "ad.asreproast"},
))
def _add_permission(self, perm: PermissionArtifact) -> None:
if not perm.is_dangerous:
return
p_nid = f"user:{perm.domain}:{perm.principal}"
t_nid = f"object:{perm.domain}:{perm.target}"
# Ensure principal node exists
if p_nid not in self._nodes:
self._add_node(GraphNode(node_id=p_nid, label=perm.principal, node_type="user"))
# Target node
self._add_node(GraphNode(
node_id=t_nid, label=perm.target,
node_type="group" if "Admins" in perm.target else "object",
is_target=perm.target in self.HIGH_VALUE_LABELS,
))
self._add_edge(GraphEdge(
source=p_nid, target=t_nid,
edge_type=EdgeType.ACE,
label=perm.right,
weight=0.3, # ACL abuse is very powerful
properties={"right": perm.right, "attack": "ad.enum_acl"},
))
# WriteDACL / GenericAll → can reach DCSync
if perm.right in ("WriteDACL", "GenericAll", "DS-Replication-Get-Changes-All"):
dcsync_nid = f"hash:ntds:{perm.domain}"
self._add_node(GraphNode(
node_id=dcsync_nid, label=f"NTDS:{perm.domain}",
node_type="credential",
risk_score=5.0, is_target=True,
))
self._add_edge(GraphEdge(
source=t_nid, target=dcsync_nid,
edge_type=EdgeType.DCSYNC_PATH,
label="dcsync → all hashes",
weight=0.2,
properties={"attack": "ad.dcsync"},
))
def _add_hash(self, h: HashArtifact) -> None:
nid = h.uid
self._add_node(GraphNode(
node_id=nid, label=f"{h.hash_type}:{h.username}",
node_type="hash",
properties={"hashcat_mode": h.hashcat_mode, "domain": h.domain},
risk_score=3.0,
))
def _add_credential(self, cred: CredentialArtifact) -> None:
nid = cred.uid
self._add_node(GraphNode(
node_id=nid, label=f"CRED:{cred.domain}\\{cred.username}",
node_type="credential",
properties={"cred_type": cred.cred_type, "cracked": cred.cracked},
risk_score=4.5 if cred.cracked else 2.0,
))
# ── Graph internals ────────────────────────────────────────────────────
def _add_node(self, node: GraphNode) -> None:
self._nodes[node.node_id] = node
self._g.add_node(
node.node_id,
label=node.label,
node_type=node.node_type,
risk_score=node.risk_score,
is_target=node.is_target,
properties=node.properties,
)
def _add_edge(self, edge: GraphEdge) -> None:
self._edges.append(edge)
self._g.add_edge(
edge.source, edge.target,
edge_type=edge.edge_type,
label=edge.label,
weight=edge.weight,
properties=edge.properties,
)
# ── Attack path queries ────────────────────────────────────────────────
def attack_paths_to_domain_admin(self) -> list[list[str]]:
"""Find all attack paths leading to Domain Admin / high-value nodes."""
targets = [
nid for nid, data in self._g.nodes(data=True)
if data.get("is_target")
]
sources = [
nid for nid, data in self._g.nodes(data=True)
if not data.get("is_target") and data.get("node_type") == "user"
]
paths: list[list[str]] = []
for src in sources:
for tgt in targets:
try:
path = nx.shortest_path(self._g, src, tgt, weight="weight")
if len(path) > 1:
paths.append(path)
except nx.NetworkXNoPath:
pass
except nx.NodeNotFound:
pass
return sorted(paths, key=len) # shortest first
def shortest_attack_path(self, source_id: str, target_id: str) -> list[str] | None:
"""Dijkstra shortest path between two specific nodes."""
try:
return nx.dijkstra_path(self._g, source_id, target_id, weight="weight")
except (nx.NetworkXNoPath, nx.NodeNotFound):
return None
# ── Path finding (user-facing) ─────────────────────────────────────────
def find_path(self, source_label: str, target_label: str) -> list[str] | None:
"""
Find shortest attack path between two nodes identified by label (not ID).
More user-friendly than shortest_attack_path() which requires exact IDs.
Example:
graph.find_path("jsmith", "Domain Admins")
graph.find_path("10.0.0.5", "krbtgt")
"""
src_id = self._find_node_by_label(source_label)
tgt_id = self._find_node_by_label(target_label)
if not src_id or not tgt_id:
return None
return self.shortest_attack_path(src_id, tgt_id)
def _find_node_by_label(self, label: str) -> str | None:
"""Fuzzy label lookup - returns first matching node ID."""
label_lower = label.lower()
# Exact match first
for nid, data in self._g.nodes(data=True):
if data.get("label", "").lower() == label_lower:
return nid
# Partial match fallback
for nid, data in self._g.nodes(data=True):
if label_lower in data.get("label", "").lower():
return nid
return None
def score_path(self, path: list[str]) -> float:
"""
Compute total attack difficulty score for a path.
Lower score = easier path (attacker perspective).
Sum of edge weights along the path.
"""
if len(path) < 2:
return 0.0
total = 0.0
for i in range(len(path) - 1):
edge_data = self._g.get_edge_data(path[i], path[i + 1]) or {}
total += edge_data.get("weight", 1.0)
return round(total, 3)
def path_to_report(self, path: list[str]) -> dict[str, Any]:
"""
Convert a path (list of node IDs) into a human-readable report dict.
Includes node labels, edge attack modules, and total score.
Example output:
{
"path": ["jsmith → TGS:svc_sql → Domain Admins"],
"steps": [
{"from": "jsmith", "to": "TGS:svc_sql", "attack": "ad.kerberoast", "weight": 1.0},
...
],
"total_score": 1.2,
"attack_modules": ["ad.kerberoast", "ad.dcsync"],
}
"""
steps = []
modules_used: list[str] = []
for i in range(len(path) - 1):
src, tgt = path[i], path[i + 1]
edge_data = self._g.get_edge_data(src, tgt) or {}
src_node = self._nodes.get(src)
tgt_node = self._nodes.get(tgt)
attack = edge_data.get("properties", {}).get("attack", edge_data.get("edge_type", ""))
if attack and attack not in modules_used:
modules_used.append(attack)
steps.append({
"from": src_node.label if src_node else src,
"to": tgt_node.label if tgt_node else tgt,
"edge": edge_data.get("label", edge_data.get("edge_type", "")),
"attack": attack,
"weight": edge_data.get("weight", 1.0),
})
return {
"path_length": len(path),
"total_score": self.score_path(path),
"steps": steps,
"attack_modules": modules_used,
"start": self._nodes[path[0]].label if path and path[0] in self._nodes else (path[0] if path else ""),
"end": self._nodes[path[-1]].label if path and path[-1] in self._nodes else (path[-1] if path else ""),
}
def top_paths(self, n: int = 5) -> list[dict[str, Any]]:
"""
Return the top-N attack paths sorted by difficulty score (easiest first).
Each entry is the output of path_to_report().
"""
all_paths = self.attack_paths_to_domain_admin()
scored = []
for p in all_paths:
scored.append((self.score_path(p), p))
scored.sort(key=lambda x: x[0]) # lowest score = easiest
return [self.path_to_report(p) for _, p in scored[:n]]
def high_value_nodes(self) -> list[GraphNode]:
"""Return all high-value target nodes (DC, Domain Admins, krbtgt, etc.)."""
return [
self._nodes.get(
nid,
GraphNode(
node_id=nid,
label=str(data.get("label", nid)),
node_type=str(data.get("node_type", "unknown")),
properties=_safe_graph_value(data.get("properties", {})),
risk_score=float(data.get("risk_score", 0.0) or 0.0),
is_target=True,
),
)
for nid, data in self._g.nodes(data=True)
if data.get("is_target")
]
def riskiest_users(self, top_n: int = 10) -> list[GraphNode]:
"""Users sorted by risk score - best attack starting points."""
users = [
n for n in self._nodes.values()
if n.node_type in ("user", "service_account")
]
return sorted(users, key=lambda n: -n.risk_score)[:top_n]
def stats(self) -> dict[str, Any]:
dc_nodes = [
n for n, d in self._g.nodes(data=True)
if d.get("node_type") == "domain_controller" or d.get("is_dc")
]
owned_nodes = [
n for n, d in self._g.nodes(data=True)
if d.get("owned") or d.get("is_owned")
]
return {
"nodes": self._g.number_of_nodes(),
"edges": self._g.number_of_edges(),
"high_value": len(self.high_value_nodes()),
"attack_paths": len(self.attack_paths_to_domain_admin()),
"density": round(nx.density(self._g), 4),
"domain_controller_nodes": len(dc_nodes),
"owned_nodes": len(owned_nodes),
}
# ── Export ─────────────────────────────────────────────────────────────
def to_d3_json(self) -> dict[str, Any]:
"""
Export as D3.js force-directed graph JSON.
Plug directly into the dashboard's graph view.
Format:
{"nodes": [{id, label, type, color, risk, is_target}],
"links": [{source, target, label, type, weight}]}
"""
nodes = []
for nid, data in self._g.nodes(data=True):
ntype = data.get("node_type", "unknown")
nodes.append({
"id": nid,
"label": data.get("label", nid),
"type": ntype,
"color": self.NODE_COLORS.get(ntype, "#94a3b8"),
"risk": data.get("risk_score", 1.0),
"is_target": data.get("is_target", False),
"properties": _safe_graph_value(data.get("properties", {})),
})
links = []
for src, tgt, data in self._g.edges(data=True):
links.append({
"source": src,
"target": tgt,
"label": data.get("label", ""),
"type": data.get("edge_type", ""),
"weight": data.get("weight", 1.0),
"properties": _safe_graph_value(data.get("properties", {})),
})
return {"nodes": nodes, "links": links}
def to_graphml(self, path: str) -> None:
"""Export to GraphML (compatible with Gephi, yEd)."""
nx.write_graphml(self._g, path)
logger.info("graph_exported_graphml", path=path)
def to_dot(self, path: str) -> None:
"""Export to DOT format (compatible with Graphviz)."""
try:
from networkx.drawing.nx_pydot import write_dot
write_dot(self._g, path)
except ImportError:
# Manual DOT generation if pydot not available
lines = ["digraph ARES {"]
for nid, data in self._g.nodes(data=True):
label = data.get("label", nid).replace('"', '\\"')
ntype = data.get("node_type", "unknown")
lines.append(f' "{nid}" [label="{label}" type="{ntype}"];')
for src, tgt, data in self._g.edges(data=True):
elabel = data.get("label", "").replace('"', '\\"')
lines.append(f' "{src}" -> "{tgt}" [label="{elabel}"];')
lines.append("}")
with open(path, "w", encoding="utf-8") as f:
f.write("\n".join(lines))
logger.info("graph_exported_dot", path=path)
# ── Bloodhound JSON Ingest ────────────────────────────────────────────────
# ── Bloodhound Ingest Pipeline (Two-Pass Architecture) ────────────────────
def ingest_bloodhound(self, json_path: str) -> dict[str, int]:
"""
Import BloodHound/SharpHound collection into the ARES attack graph.
Supports BloodHound CE (v5+), legacy (v4) JSON formats, and SharpHound .zip archives.
Parses: computers, users, groups, domains, sessions, LocalAdmins, and ACLs/ACEs.
Uses a two-pass resolution pipeline to prevent SID vs. Name split-brain disconnection.
After ingest, use find_path() / top_paths() / shortest_path_to_da() to compute attack paths.
Args:
json_path: Path to BloodHound JSON file, .zip archive, or directory containing JSON files.
Returns:
dict with counts: {"nodes_added": N, "edges_added": N, "file_count": N}
"""
import json as _json
import zipfile
from pathlib import Path
if not _NX_AVAILABLE:
logger.warning("bloodhound_ingest_requires_networkx")
return {"nodes_added": 0, "edges_added": 0, "error": "networkx not installed"}
p = Path(json_path)
raw_payloads: list[tuple[str, dict]] = []
if p.is_file() and (p.suffix.lower() == ".zip" or zipfile.is_zipfile(p)):
try:
with zipfile.ZipFile(p, "r") as zf:
for name in sorted(zf.namelist()):
if name.lower().endswith(".json") and not name.startswith("__MACOSX"):
try:
with zf.open(name) as fh:
data = _json.loads(fh.read().decode("utf-8", errors="replace"))
raw_payloads.append((name, data))
except Exception as exc:
logger.warning("bloodhound_zip_member_error", member=name, error=str(exc)[:100])
except Exception as exc:
logger.warning("bloodhound_zip_read_error", file=str(p), error=str(exc)[:100])
return {"nodes_added": 0, "edges_added": 0, "error": f"Failed to read zip archive: {str(exc)[:100]}"}
elif p.is_dir():
for fp in sorted(p.glob("*.json")):
try:
with open(fp, encoding="utf-8", errors="replace") as fh:
raw_payloads.append((fp.name, _json.load(fh)))
except Exception as exc:
logger.warning("bloodhound_parse_error", file=str(fp), error=str(exc)[:100])
elif p.is_file():
try:
with open(p, encoding="utf-8", errors="replace") as fh:
raw_payloads.append((p.name, _json.load(fh)))
except Exception as exc:
logger.warning("bloodhound_parse_error", file=str(p), error=str(exc)[:100])
return {"nodes_added": 0, "edges_added": 0, "error": f"Failed to parse JSON file: {str(exc)[:100]}"}
else:
return {"nodes_added": 0, "edges_added": 0, "error": f"Path not found: {json_path}"}
if not raw_payloads:
return {"nodes_added": 0, "edges_added": 0, "file_count": 0}
nodes_before = self._g.number_of_nodes()
edges_before = self._g.number_of_edges()
# Two-pass parsing across all collected payloads
self._parse_bloodhound_datasets(raw_payloads)
nodes_added = self._g.number_of_nodes() - nodes_before
edges_added = self._g.number_of_edges() - edges_before
logger.info(
"bloodhound_ingest_complete",
nodes=nodes_added,
edges=edges_added,
files=len(raw_payloads),
)
return {
"nodes_added": nodes_added,
"edges_added": edges_added,
"file_count": len(raw_payloads),
}
def _parse_bloodhound_json(self, data: dict) -> None:
"""Backward-compatible single-payload ingest helper."""
self._parse_bloodhound_datasets([("data.json", data)])
def _parse_bloodhound_datasets(self, raw_payloads: list[tuple[str, dict]]) -> None:
"""Two-pass ingestion of BloodHound datasets to eliminate SID vs. Name split-brain."""
sid_to_id: dict[str, str] = {}
name_to_id: dict[str, str] = {}
normalized_items: list[tuple[str, dict]] = []
# ── PASS 1: Identify all entities, index SIDs and canonical Names ───────────
for _fname, data in raw_payloads:
if not isinstance(data, dict):
continue
meta = data.get("meta") or {}
bh_type = str(meta.get("type") or "").strip().lower()
items = data.get("data")
# Legacy fallback: top-level key detection
if items is None:
for key in ("computers", "users", "groups", "domains", "sessions", "ous", "gpos"):
if key in data and isinstance(data[key], list):
items = data[key]
bh_type = key
break
if not items or not isinstance(items, list):
continue
for item in items:
if not isinstance(item, dict):
continue
normalized_items.append((bh_type, item))
props = item.get("Properties") or item.get("properties") or {}
raw_name = str(props.get("name") or item.get("name") or "").strip()
name = raw_name.upper()
# Extract SIDs / ObjectIdentifiers
oid = str(
item.get("ObjectIdentifier")
or props.get("objectid")
or props.get("domainsid")
or ""
).strip().upper()
# Normalize category
entity_type = "object"
if bh_type in ("computers", "computer"):
entity_type = "computer"
elif bh_type in ("users", "user"):
entity_type = "user"
elif bh_type in ("groups", "group"):
entity_type = "group"
elif bh_type in ("domains", "domain"):
entity_type = "domain"
elif bh_type in ("ous", "ou"):
entity_type = "ou"
elif bh_type in ("gpos", "gpo"):
entity_type = "gpo"
elif bh_type in ("sessions", "session"):
continue
canonical_id = f"{entity_type}:{name}" if name else (f"{entity_type}:{oid}" if oid else "")
if not canonical_id:
continue
if oid:
sid_to_id[oid] = canonical_id
sid_to_id[f"{entity_type}:{oid}"] = canonical_id
if name:
name_to_id[name] = canonical_id
name_to_id[f"{entity_type}:{name}"] = canonical_id
if "@" in name:
name_to_id[name.split("@")[0]] = canonical_id
if "." in name:
name_to_id[name.split(".")[0]] = canonical_id
# Register canonical node in GraphNode dictionary and NetworkX
is_target = False
label = raw_name or oid
node_type = entity_type
if entity_type == "computer":
is_dc = bool(props.get("isdc", props.get("isDC", False)))
node_type = "domain_controller" if is_dc else "host"
is_target = is_dc
elif entity_type == "user":
is_admin = bool(props.get("admincount", False))
is_target = is_admin or ("ADMIN" in name)
elif entity_type == "group":
is_da = "DOMAIN ADMINS" in name or "ENTERPRISE ADMINS" in name or "ADMINISTRATORS" in name
is_target = is_da
elif entity_type == "domain":
is_target = True
self._add_node(GraphNode(
node_id=canonical_id,
label=label,
node_type=node_type,
properties={
"name": raw_name,
"sid": oid,
"domain": str(props.get("domain") or "").upper(),
"enabled": props.get("enabled", True),
"has_spn": props.get("hasspn", False),
"no_preauth": props.get("dontreqpreauth", False),
"os": props.get("operatingsystem", ""),
},
risk_score=5.0 if is_target else 1.0,
is_target=is_target,
))
# Helper to resolve any SID, Name, or typed reference to canonical node ID
def _resolve_node(ref: Any, default_type: str = "object") -> str:
if not ref or not isinstance(ref, (str, int)):
return ""
r_str = str(ref).strip()
r_upper = r_str.upper()
if r_upper in sid_to_id:
return sid_to_id[r_upper]
if r_upper in name_to_id:
return name_to_id[r_upper]
if ":" in r_str:
_pfx, rest = r_str.split(":", 1)
rest_upper = rest.strip().upper()
if rest_upper in sid_to_id:
return sid_to_id[rest_upper]
if rest_upper in name_to_id:
return name_to_id[rest_upper]
else:
for pfx in ("user", "computer", "group", "domain"):
pfx_key = f"{pfx}:{r_upper}"
if pfx_key in sid_to_id:
return sid_to_id[pfx_key]
if pfx_key in name_to_id:
return name_to_id[pfx_key]
# If not in registry, create dummy canonical node to preserve graph connectivity
fallback_id = r_str.lower() if ":" in r_str else f"{default_type}:{r_str}".lower()
if fallback_id not in self._nodes and fallback_id not in self._g:
self._add_node(GraphNode(
node_id=fallback_id,
label=r_str,
node_type=default_type or "object",
is_target=False,
))
return fallback_id
_DANGEROUS_RIGHTS = {
"GenericAll", "GenericWrite", "WriteOwner", "WriteDacl",
"AllExtendedRights", "ForceChangePassword", "AddMember",
"ReadLAPSPassword", "ReadGMSAPassword", "DCSync",
"Owns", "AddSelf", "AddAllowedToAct",
}
_RIGHT_WEIGHTS = {
"DCSync": 0.1,
"GenericAll": 0.15,
"WriteOwner": 0.2,
"WriteDacl": 0.2,
"Owns": 0.2,
"ForceChangePassword": 0.25,
"AddMember": 0.25,
"AllExtendedRights": 0.3,
"ReadLAPSPassword": 0.35,
"ReadGMSAPassword": 0.35,
"GenericWrite": 0.4,
"AddSelf": 0.4,
"AddAllowedToAct": 0.45,
}
# ── PASS 2: Stitch all edges across resolved canonical nodes ────────────────
for bh_type, item in normalized_items:
props = item.get("Properties") or item.get("properties") or {}
raw_name = str(props.get("name") or item.get("name") or "").strip()
name = raw_name.upper()
oid = str(item.get("ObjectIdentifier") or props.get("objectid") or "").strip().upper()
entity_type = "computer" if bh_type in ("computers", "computer") else (
"user" if bh_type in ("users", "user") else (
"group" if bh_type in ("groups", "group") else (
"domain" if bh_type in ("domains", "domain") else "object"
)
)
)
target_node = _resolve_node(oid or name, default_type=entity_type)
domain_name = str(props.get("domain") or "").strip().upper()
domain_node = _resolve_node(domain_name, default_type="domain") if domain_name else ""
# Domain hierarchy edges
if domain_node and target_node and domain_node != target_node:
rel_label = f"has_{entity_type}"
self._add_edge(GraphEdge(
source=domain_node,
target=target_node,
edge_type=rel_label,
label=rel_label,
weight=0.1,
))
# 1. Access Control Entries (ACEs)
aces = item.get("Aces") or item.get("aces") or []
for ace in aces:
if not isinstance(ace, dict):
continue
right = ace.get("RightName") or ace.get("rightname") or ""
principal_sid = ace.get("PrincipalSID") or ace.get("principalsid") or ""
ptype = str(ace.get("PrincipalType") or ace.get("principaltype") or "user").lower()
if right in _DANGEROUS_RIGHTS and principal_sid:
src_node = _resolve_node(principal_sid, default_type=ptype)
if src_node and target_node and src_node != target_node:
w = _RIGHT_WEIGHTS.get(right, 0.5)
self._add_edge(GraphEdge(
source=src_node,
target=target_node,
edge_type=EdgeType.ACE,
label=right.lower(),
weight=w,
properties={"right": right, "inherited": ace.get("IsInherited", False)},
))
# 2. Group Membership
if bh_type in ("groups", "group"):
members = item.get("Members") or item.get("members") or []
for m in members:
if not isinstance(m, dict):
continue
m_ref = m.get("MemberId") or m.get("ObjectIdentifier") or ""
m_type = str(m.get("MemberType") or m.get("ObjectType") or "user").lower()
src_member = _resolve_node(m_ref, default_type=m_type)
if src_member and target_node and src_member != target_node:
self._add_edge(GraphEdge(
source=src_member,
target=target_node,
edge_type=EdgeType.MEMBER_OF,
label="member_of",
weight=0.05,
))
# 3. Computer Local Admins & Permissions
if bh_type in ("computers", "computer"):
def _process_comp_members(data_field: str, rel_type: str, weight: float, item: Any = item, target_node: Any = target_node) -> None:
raw_block = item.get(data_field)
entries = raw_block.get("Results", []) if isinstance(raw_block, dict) else (
raw_block if isinstance(raw_block, list) else []
)
for entry in entries:
if not isinstance(entry, dict):
continue
e_ref = entry.get("ObjectIdentifier") or entry.get("MemberId") or ""
e_type = str(entry.get("ObjectType") or entry.get("MemberType") or "user").lower()
src = _resolve_node(e_ref, default_type=e_type)
if src and target_node and src != target_node:
self._add_edge(GraphEdge(
source=src,
target=target_node,
edge_type=rel_type,
label=rel_type,
weight=weight,
))
_process_comp_members("LocalAdmins", "admin_to", 0.2)
_process_comp_members("RemoteDesktopUsers", "can_rdp", 0.4)
_process_comp_members("DcomUsers", "execute_dcom", 0.4)
# Computer Sessions (Inside computer item)
raw_sess = item.get("Sessions")
sess_entries = raw_sess.get("Results", []) if isinstance(raw_sess, dict) else (
raw_sess if isinstance(raw_sess, list) else []
)
for s in sess_entries:
if not isinstance(s, dict):
continue
u_ref = s.get("UserId") or s.get("UserName") or ""
user_node = _resolve_node(u_ref, default_type="user")
if target_node and user_node and target_node != user_node:
# Compromising computer yields user credential session
self._add_edge(GraphEdge(
source=target_node,
target=user_node,
edge_type=EdgeType.HAS_SESSION,
label="has_session",
weight=0.3,
))
# 4. Standalone Sessions File
if bh_type in ("sessions", "session"):
c_ref = item.get("ComputerId") or item.get("ComputerName") or ""
u_ref = item.get("UserId") or item.get("UserName") or ""
c_node = _resolve_node(c_ref, default_type="computer")
u_node = _resolve_node(u_ref, default_type="user")
if c_node and u_node and c_node != u_node:
self._add_edge(GraphEdge(
source=c_node,
target=u_node,
edge_type=EdgeType.HAS_SESSION,
label="has_session",
weight=0.3,
))
def shortest_path_to_da(self, start_node: str | None = None) -> dict[str, Any] | None:
"""
Compute shortest attack path from start_node (or any user) to Domain Admins group.
Uses Dijkstra with edge weights (lower = easier to exploit).
Returns structured report dict with steps, weights, and techniques, or None if no path exists.
"""
if not _NX_AVAILABLE or not self._g.nodes:
return None
# Find DA group node
da_nodes = [
n for n, d in self._g.nodes(data=True)
if d.get("is_target") and any(
term in d.get("label", "").upper()
for term in ("DOMAIN ADMINS", "ENTERPRISE ADMINS", "ADMINISTRATORS")
)
]
if not da_nodes:
da_nodes = [n for n in self._g.nodes if "domain admin" in str(n).lower()]
if not da_nodes:
return None
# If start specified, resolve it via registry or labels
if start_node:
resolved_start = start_node
if start_node not in self._g:
# Try finding by label or suffix
for n, d in self._g.nodes(data=True):
if d.get("label") == start_node or str(n).upper() == start_node.upper():
resolved_start = n
break
start_nodes = [resolved_start] if resolved_start in self._g else []
else:
start_nodes = [
n for n, d in self._g.nodes(data=True)
if d.get("node_type") == "user" and not d.get("is_target")
]
best_path: list = []
best_cost = float("inf")
for src in start_nodes[:50]:
for da_target in da_nodes:
try:
cost = nx.shortest_path_length(self._g, src, da_target, weight="weight")
if cost < best_cost:
path = nx.shortest_path(self._g, src, da_target, weight="weight")
best_cost = cost
best_path = path
except (nx.NetworkXNoPath, nx.NodeNotFound):
continue
if not best_path:
return None
return self.path_to_report(best_path)