BloodTrace

Tagline

Find the fastest, most damaging paths to your Active Directory crown jewels — then fix them.

Description

BloodTrace is a self-hosted Active Directory attack-path analyzer for pentesters and blue teamers. It ingests BloodHound CE exports, maps high-value targets through a NetworkX attack graph, and ranks every path by risk so you know what to remediate first. Multi-provider AI turns each finding into an attack narrative and concrete remediation commands, exportable as a PDF report.

Features

• Attack-path detection — enumerates reachable paths to Domain Controllers, Domain Admins, KRBTGT, and other high-value targets.
• Risk scoring — every path is scored from target criticality, path length, edge severity, and exploitation-enabling tags, then classified into severity bands.
• Bottleneck analysis — correlates paths to rank the highest-leverage nodes to remediate, with estimated risk reduction.
• AI explanations — one-click attack walkthroughs and copy-paste remediation commands from the provider of your choice; results are cached locally so reloading a session costs nothing.
• PDF reports — one-click report generation with summary stats, findings table, path details, bottlenecks, and AI explanations.
• Session storage — analyses are saved locally with a 5-session cap; the oldest is replaced (with confirmation) when exceeded.
• Self-hosted — Dockerized, all data stays on disk; optional AI_MASTER_KEY encrypts stored API keys.

Requirements

• Docker + Docker Compose (recommended path), or
• Python 3.11+ and pip for a native run.
• A BloodHound CE / SharpHound JSON export (zip or raw JSON).
• An API key for at least one AI provider to use AI explanations (optional — a local mock fallback is used otherwise).

Installation

git clone https://github.com/yassertioursi/blood-trace
cd ad-blood-trace
docker compose up -d --build

For a native run:

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn backend.app.main:app --host 0.0.0.0 --port 8000

Usage (run in 1 command)

docker compose up -d --build

Then open http://localhost:8000, drop a BloodHound zip or JSON export onto the upload card, and hit Analyze. Findings, bottleneck analysis, AI explanations, and PDF reports are available from the Dashboard and Sessions views.

AI Provider Setup

Supported providers

Provider	Default model	Notes
Gemini	gemini-3.6-flash	Free tier works; retries on slow/empty responses
OpenAI	gpt-4o-mini	OpenAI-compatible API
Claude	claude-sonnet-4-20250514	Native Anthropic /v1/messages API
Groq	llama-3.3-70b-versatile	Fast OpenAI-compatible endpoints
OpenRouter	openai/gpt-4o-mini	Route to many models via one key
Ollama	llama3.1	Keyless, local (uses host.docker.internal)

How to add your API key

1. Open Settings → AI provider settings.
2. Pick a provider, paste your API key, and click Save settings.
3. Leave Model and Base URL blank to use the provider defaults (they auto-fill and are validated; wrong base URLs are corrected on save).
4. A live connection test runs automatically after saving.
5. Set the AI_MASTER_KEY environment variable before first use to encrypt stored keys at rest — otherwise keys are stored in plaintext in data/ai_providers.json.

BloodHound Collection Guide

Required SharpHound flags

SharpHound exports are consumed directly; session data is optional but improves edge quality:

# Full collection (recommended)
SharpHound.exe -c All --OutputDirectory C:\BH --ZipFilename bloodhound.zip

# Lean collection
SharpHound.exe -c Default

# Collection relevant for path analysis
SharpHound.exe -c Group,LocalAdmin,Session,RDP,DCOnly,Trusts

Supported file formats

• BloodHound CE / SharpHound JSON files: users.json, computers.json, groups.json, domains.json, gpos.json, ous.json, containers.json (upload individually).
• A zip archive containing any of the above (extracted securely server-side, guarded against zip-slip and zip-bomb payloads).

Project Structure

ad-blood-trace/
├── backend/app/
│   ├── api/routes/         # upload, findings, sessions, settings, status
│   ├── models/contracts.py # Pydantic source-of-truth schemas
│   └── services/
│       ├── parser.py       # BloodHound JSON → normalized GraphDocument
│       ├── graph_builder.py# NetworkX attack graph
│       ├── path_finder.py  # shortest + simple paths → AttackPath
│       ├── scoring.py      # risk scores and severity bands
│       ├── correlator.py   # bottleneck / remediation ranking
│       ├── report.py       # fpdf2 PDF report generation
│       ├── session.py      # session metadata + 5-session cap
│       ├── jobs.py         # async analysis job queue
│       └── ai/             # provider abstraction, cache, settings
├── frontend/src/api/       # TypeScript contracts mirroring backend models
├── backend/app/static/     # served SPA (vanilla JS)
├── backend/tests/          # pytest suite (42 tests)
├── docker-compose.yml
├── Dockerfile
└── requirements.txt

How It Works

Pipeline overview (Parser → Graph → Scorer → Correlator → AI → Report)

1. Parser — SharpHound JSON (or zip) is validated and normalized into a GraphDocument of nodes and edges.
2. Graph — nodes and edges are typed and tagged (kerberoastable, unconstrained delegation, AD CS, etc.), and a directed NetworkX attack graph is built.
3. Path finder — reachable paths to high-value targets are enumerated (all simple paths up to a cutoff, deduplicated for overlaps).
4. Scorer — each AttackPath is scored from target tier, hop count, worst edge, and enrichment tags, then classified by severity.
5. Correlator — paths are correlated to identify bottlenecks: nodes whose remediation eliminates the most critical/high paths, with a computed risk-reduction percentage and remediation commands.
6. AI — on demand, each finding is sent to the configured provider for an attack walkthrough and PowerShell remediation commands; results are cached per session/provider with a 24h TTL and served instantly on reload.
7. Report — summary, findings table, path details, bottlenecks, and AI explanations are compiled into a downloadable PDF.

Scoring Methodology

A path score (0–100) is the sum of component scores, optionally multiplied by 1.25 when the source is owned (already compromised).

Score table

Component	Contribution	Notes
Target tier	20–40	KRBTGT 40, Domain Controller 38, Domain Admins 36, Enterprise Admins 35, CA Server 30, AdminCount=1 25, High-Value 20
Path length	3–30	1 hop = 30, down to 7 at 5 hops, 3 for 6+
Worst edge	5–20	DCSync/GenericAll 20, WriteDACL 18, WriteOwner 17, AllowedToDelegate 16 … down to CanRDP 5
Enrichment tags	5–12 each	unconstrained_delegation +12, kerberoastable +10, AD CS +10, AS-REP +8, SIDHistory +8, through_DC +5
Owned source	×1.25	Multiplier applied when the entry point is already compromised

Severity bands

Band	Range
Critical	≥ 85
High	65 – 84
Medium	45 – 64
Low	< 45

Roadmap

• Custom query / cypher input for path enumeration limits.
• Scheduled re-analysis and drift detection between exports.
• Exportable remediation playbooks (Markdown / CSV) alongside PDF.
• Authentication for multi-user deployments.
• CI/CD with end-to-end browser tests.

Contributing

Contributions are welcome. Please:

1. Open an issue for feature requests or bugs.
2. Keep backend Pydantic models the source of truth for schemas; mirror changes in frontend/src/api/types.ts.
3. Add tests under backend/tests/ (run with pytest) and keep the suite green before opening a PR.

License (MIT)

Released under the MIT License. You are free to use, modify, and distribute this software, provided the license notice is retained. See the repository license file for full terms.

Disclaimer

For authorized testing only. BloodTrace is a security analysis tool; use it exclusively on systems you own or are explicitly authorized to assess. Attack-path analysis and AI-generated remediation advice are heuristic and may be incomplete or incorrect — validate all findings and commands against your environment before acting. The authors are not liable for misuse or for any damage resulting from the use of this tool.