BHPathExplain

BHPathExplain is a lightweight explanation and reasoning layer for BloodHound attack paths.

It transforms BloodHound-style attack paths into operator-friendly notes using a YAML knowledge base, chain-aware reasoning, and capability-state tracking.

BHPathExplain does not collect data, perform pathfinding, or replace BloodHound. It focuses on explaining known attack paths.

Features

• BloodHound path explanation

• YAML-based knowledge base

• Primitive and playbook mapping

• Chain-aware reasoning

• State-aware capability tracking

• Final impact summaries

• KB validation

• Chain coverage analysis

Installation

pip install -r requirements.txt

Basic Usage

Explain a path:

python3 -m bhpathexplain.cli \    
"User:alice -> ReadGMSAPassword -> Computer:SQLSvc$ -> GenericAll -> Group:Domain Admins"

Write Markdown output:

python3 -m bhpathexplain.cli \    
"User:alice -> ReadGMSAPassword -> Computer:SQLSvc$ -> GenericAll -> Group:Domain Admins" \    
-o notes.md

Read a path from a file:

python3 -m bhpathexplain.cli \    
--path-file sample_path.txt \    
-o notes.md

Generate JSON:

python3 -m bhpathexplain.cli \   
--format json \   
--path-file sample_path.txt \   
-o report.json

Explanation

--path-file   Read path input from a file

--format json Output structured JSON instead of Markdown

-o            Write output to a file

Validate Knowledge Bases

python3 -m bhpathexplain.cli --validate-kb

Coverage Analysis

Identify observed path transitions that do not yet have chain reasoning rules:

python3 tools/find_uncovered_transitions.py report.json

Example output:

Observed unique transitions: 12    
Covered transitions: 10    
Missing transitions: 2    
Observed coverage: 83.33%

Knowledge Base Layout

BHPathExplain_KBs/    
├── edge_kb/    
├── primitive_kb/    
├── playbook_kb/    
├── report_kb/    
└── chain_kb/

Capability State Tracking

BHPathExplain tracks path capabilities across attack steps, including:

• controlled identities

• effective memberships

• controlled hosts

• controlled objects

• credential material

• delegation paths

• certificate impersonation paths

• domain compromise

• tier zero exposure

Project Status

Current status: Beta

The core of the tool is complete. Current development is focused on expanding knowledge-base coverage and improving chain-aware reasoning using real-world BloodHound paths. A kind of grow-as-you-go method.

---

Roadmap

Planned improvements:

• Distinguish operator-useful relationships from informational graph relationships
• Generate recommended next actions based on discovered capabilities
• Support multiple output modes (summary, report, full)
• Add high-signal summary mode for rapid attack path triage
• Highlight capability transitions between path steps
• Improve impact analysis for common Active Directory attack primitives
• Generate remediation-focused summaries for defensive review
• Improve target-aware reasoning and edge-specific playbook selection
• Export path analysis as Markdown, HTML, and report-ready formats

---

License

BHPathExplain was created by Evan DeWeese (FrankieBFG) as a lightweight explanation and reasoning layer for BloodHound attack paths.

MIT License. See LICENSE for details.