Content
# pathhound-mcp
An **MCP (Model Context Protocol) server** that lets an LLM reason over an Active
Directory attack graph **already collected by BloodHound** — shortest paths to
Tier 0, blast radius from a principal, the highest-leverage choke points to
remediate, and defender-facing remediation text — with every action scoped to an
authorized engagement and logged.
> **Authorized penetration-testing use only.** This server never touches a live
> domain, never collects data, and never runs attacks. Collection is done
> separately (SharpHound / `bloodhound-python`); this tool only *reads and
> reasons over* the resulting graph in Neo4j. See [SECURITY.md](SECURITY.md) for
> the full intended-use boundary.
## What it does
- **Turns a collected graph into explainable answers.** Ask "what are the
shortest paths to Domain Admins," "if I own this account what becomes
reachable," or "which edges should we fix first" and get structured results.
- **Read-only and scoped by design.** It refuses to start without an engagement
scope, refuses to query domains outside that scope, rejects write/destructive
Cypher, and appends every call to an audit log.
- **Defender-facing output.** `explain_edge` and `remediation_for_path` produce
report-ready remediation, not exploit commands.
### Tools
| Tool | What it returns |
| --- | --- |
| `list_domains()` | Domains/forests in the graph, with node counts and an in-scope flag. |
| `run_cypher(query, params)` | Rows from a **read-only** Cypher query. Write clauses are rejected unless `allow_writes` is set; destructive/external ops are always refused. Results are row-capped with a truncation flag. |
| `shortest_paths_to_tier0(start, max_paths)` | Shortest attack paths to Tier 0 / high-value targets — from `start` (an in-scope principal) or from every `owned` principal. Each path is an ordered list of `start —[edge]→ end` hops. |
| `reachable_from(principal, max_hops)` | Blast radius from a principal, summarized by node type, highlighting any Tier 0 reachability. |
| `find_choke_points(top_n)` | The edges appearing in the most distinct shortest paths to Tier 0, each with the number of paths removing it would break. |
| `explain_edge(edge_type)` | Plain-language reason a BloodHound edge (e.g. `GenericAll`, `AddKeyCredentialLink`, `DCSync`) is abusable, the technique name, a defender remediation, and reference pointers. |
| `remediation_for_path(path_id_or_cypher)` | For a path (given as a read-only Cypher query returning a path `p`), the specific ACE / delegation / membership change that breaks each hop, phrased for a report. |
| `engagement_summary()` | Headline counts for reporting: principals, owned, high-value, distinct paths to Tier 0, and the top choke points. |
### Resources
| Resource | Contents |
| --- | --- |
| `pathhound://engagement-scope` | The active scope (engagement id, authorization reference, allowed domains, write flag) and the Neo4j target with the password masked. |
| `pathhound://cypher-library` | A curated, versioned set of named read-only Cypher queries (Kerberoastable, unconstrained delegation, AS-REP roastable, paths to Domain Admins, ACL abuse from a principal, …), each validated read-only on load. |
### Optional write tools (off by default)
Two tools — `mark_owned(principal, confirm)` and `set_high_value(principal,
confirm)` — set BloodHound's owned / Tier 0 markers (and nothing else) so the
path tools treat those nodes accordingly. They only exist when `allow_writes:
true` is set in `scope.yaml`; each call also requires an explicit `confirm=true`,
an in-scope principal, and is audited. They never delete or drop. Leave
`allow_writes: false` (the default) for a strictly read-only deployment.
## Requirements
- Python 3.11+
- A **BloodHound CE** Neo4j instance reachable over Bolt (the graph is collected
and ingested separately — see the quickstart below)
## Install
```bash
# With uv (preferred):
uv venv && uv pip install -e ".[dev]"
# Or with pip:
python -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt && pip install -e .
```
## Configure
Two pieces of configuration: the **engagement scope** (a file) and the **Neo4j
connection** (environment variables — credentials are never hardcoded).
**1. Engagement scope** — copy the example and edit it:
```bash
cp scope.example.yaml scope.yaml
```
```yaml
# scope.yaml
engagement_id: "ENG-0001" # names the audit log file
authorization_ref: "SoW-2026-ACME-001 / JIRA-1234"
allowed_domains: # only these may be queried
- "CORP.LOCAL"
- "CHILD.CORP.LOCAL"
allow_writes: false # keep false unless you need the write-flag tools
max_rows: 500 # run_cypher row cap
```
The server **refuses to start** if `scope.yaml` is missing or `allowed_domains`
is empty — this is intentional; there are no unscoped queries. Domain names are
matched case-insensitively against BloodHound's uppercase FQDNs.
**2. Neo4j connection** — via environment variables (or a `.env`; see
`.env.example`):
```bash
export NEO4J_URI="bolt://127.0.0.1:7687"
export NEO4J_USER="neo4j"
export NEO4J_PASSWORD="…"
export NEO4J_DATABASE="neo4j" # optional, defaults to neo4j
# export PATHHOUND_SCOPE="/abs/path/scope.yaml" # optional; defaults to ./scope.yaml
```
## Run
As a standalone stdio MCP server:
```bash
pathhound-mcp # or: python -m pathhound_mcp.server
```
### Register with an MCP client
Point your client at the console script (use the absolute path from your venv,
e.g. `/path/to/pathhound-mcp/.venv/bin/pathhound-mcp`) and pass the connection +
scope through its environment. Example (Claude Desktop `claude_desktop_config.json`):
```json
{
"mcpServers": {
"pathhound": {
"command": "/path/to/pathhound-mcp/.venv/bin/pathhound-mcp",
"env": {
"NEO4J_URI": "bolt://127.0.0.1:7687",
"NEO4J_USER": "neo4j",
"NEO4J_PASSWORD": "…",
"PATHHOUND_SCOPE": "/path/to/pathhound-mcp/scope.yaml"
}
}
}
}
```
### Example questions to ask the LLM
Once connected, an operator can ask things like:
- *"List the domains in the graph and how big each is."* → `list_domains`
- *"Which accounts are Kerberoastable?"* → `run_cypher` with the `kerberoastable_users` library query
- *"Show the shortest attack paths to Tier 0."* → `shortest_paths_to_tier0`
- *"If I compromise `alice@corp.local`, what becomes reachable?"* → `reachable_from`
- *"What are the top 10 choke points we should fix first?"* → `find_choke_points`
- *"Why is `AddKeyCredentialLink` dangerous, and how do we fix it?"* → `explain_edge`
- *"Give me remediation steps for this attack path."* → `remediation_for_path`
- *"Summarize the engagement for the report."* → `engagement_summary`
## Quickstart: collect into BloodHound, then point this at Neo4j
This server only reads an **already-collected** graph; collection happens
separately and outside this tool.
1. **Collect** the domain with SharpHound or `bloodhound-python` during your
authorized engagement. You get a set of JSON files (or a zip) — from a lab
like [GOAD](https://github.com/Orange-Cyberdefense/GOAD) (GOAD-Light ~16 GB,
full GOAD ~32 GB) or a real engagement.
2. **Stand up BloodHound CE and ingest the data.** The official compose stack
runs Neo4j (Bolt on `127.0.0.1:7687`), Postgres, and the BloodHound UI on
`:8080`:
```bash
docker compose -f /path/to/docker-compose.yml up -d
# open http://localhost:8080, log in, and upload the collection zip
# (Administration → File Ingest). Wait for ingest + post-processing.
```
If the Neo4j volume is already ingested, you can start just the graph:
`docker compose -f /path/to/docker-compose.yml up -d graph-db`.
3. **Point pathhound-mcp at that Neo4j** (see [Configure](#configure)) and run
it. Your `allowed_domains` in `scope.yaml` should match the domains in the
collection (e.g. `CORP.LOCAL`).
### BloodHound schema compatibility
Newer BloodHound CE tags **Tier 0 with the `Tag_Tier_Zero` node label** and
**owned principals with `Tag_Owned`**, while older versions used the `highvalue`
/ `owned` properties (and CE also sets `system_tags: admin_tier_0`). pathhound
recognizes all of these, so Tier 0 / owned reasoning works across versions.
## Tests
```bash
pytest # unit tests — guardrails, scope, audit, Cypher guard, tool logic
```
The suite is fully **database-free**: the read-only guardrail, scope enforcement,
audit logging, row-capping, and path/reporting logic are all exercised against
stubs, so `pytest` runs in a fraction of a second with no Neo4j. (The tools have
also been validated end-to-end against a real BloodHound CE graph.)
## Project layout
```
src/pathhound_mcp/
├── server.py # FastMCP app: tool/resource registration + startup guard
├── config.py # loads/validates scope.yaml (pydantic); Neo4j from env
├── guardrails.py # read-only Cypher guard + scope enforcement
├── audit.py # append-only JSONL audit logger (@audited decorator)
├── graph.py # Neo4j connection + read helpers (the only DB access)
├── schema.py # attack-edge set + Tier 0 / owned predicates
├── models.py # pydantic result models
├── cypher_library.json / edge_library.json # curated read-only queries + edge KB
└── tools/ # inventory, query, paths, reporting, edges
```
`audit/`, `scope.yaml`, and `.env` are gitignored — treat the audit log and the
collected graph as engagement-sensitive.
## Safety model
See [SECURITY.md](SECURITY.md) for the intended-use boundary and the guarantees:
scope-at-startup, read-only by default, scope enforcement, append-only audit log,
and no live-domain capability.
## License
MIT — see [LICENSE](LICENSE).
