Skip to content

Commit 0dfcca3

Browse files
dfirdeferreddfirdeferred
authored
Add files via upload
1 parent 61701b8 commit 0dfcca3

2 files changed

Lines changed: 63 additions & 40 deletions

File tree

‎docs/BLOODHOUND_GUIDE.md‎

Lines changed: 32 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -15,43 +15,47 @@ AIHound scans your machine for AI credentials (API keys, OAuth tokens, MCP serve
1515

1616
---
1717

18-
## Step 1: Register Custom Node Types & Saved Queries (One Time Only)
18+
## Step 1: Register Schema & Import Queries (One Time Only)
1919

20-
Before BloodHound can display AI credential nodes with proper icons, you need to register AIHound's custom node types. The script also imports 29 pre-built Cypher queries into BloodHound's **Saved Queries** panel. **You only need to do this once per BloodHound instance.**
20+
Before BloodHound can display AI credential nodes with proper icons, you need to register AIHound's OpenGraph extension schema and import the saved Cypher queries. **You only need to do this once per BloodHound instance.**
2121

2222
```bash
23-
python3 docs/register_ai_nodes.py \
24-
-s http://localhost:8080 \
25-
-u admin \
26-
-p <your-bloodhound-password>
23+
python3 -m aihound --import-queries \
24+
--bloodhound-server http://localhost:8080 \
25+
--bloodhound-user admin \
26+
--bloodhound-password <your-bloodhound-password>
2727
```
2828

2929
You should see:
3030

3131
```
32-
Authenticated as admin
33-
Registered 14 custom node kinds:
34-
key AICredential AI API key, OAuth token, or session credential
35-
cloud AIService AI platform or service (OpenAI, Anthropic, AWS, etc.)
36-
plug MCPServer Model Context Protocol server instance
37-
...
32+
Registered AIHound extension schema (node kinds, icons, colors)
3833
Saved queries: 29 created, 0 already existed
39-
40-
Done! You can now import AIHound OpenGraph JSON files into BloodHound CE.
4134
```
4235

43-
### Registration script options
36+
This registers 14 custom node kinds with icons/colors via the OpenGraph extension schema (`extension/schema.json`) and imports 29 saved Cypher queries from `extension/queries.json`.
37+
38+
### Import options
4439

4540
| Flag | Description |
4641
|------|-------------|
47-
| *(no flags)* | Register node kinds + saved queries (skips if already registered) |
48-
| `--reset` | Delete all AIHound node kinds and saved queries, then re-register |
49-
| `--unregister` | Delete all AIHound node kinds and saved queries, then exit |
50-
| `--no-queries` | Skip importing saved Cypher queries |
42+
| `--bloodhound-server URL` | BloodHound CE server URL (required) |
43+
| `--bloodhound-user USER` | BloodHound username (use with `--bloodhound-password`) |
44+
| `--bloodhound-password PASS` | BloodHound password |
45+
| `--bloodhound-token-id UUID` | API token ID (alternative to username/password) |
46+
| `--bloodhound-token-key KEY` | API token key |
47+
| `--queries-file PATH` | Custom queries JSON file (default: bundled `extension/queries.json`) |
5148
| `--no-verify-ssl` | Disable SSL certificate verification |
52-
| `--list` | List node kinds that would be registered and exit |
5349

54-
> **Tip:** If you need to re-register (e.g., after a BloodHound reset or AIHound update), use `--reset` to clear old kinds and queries first.
50+
> **Tip:** Running `--import-queries` again is safe — it skips queries that already exist and re-registers the schema.
51+
52+
### Legacy method
53+
54+
The `docs/register_ai_nodes.py` script still works for manual node registration if needed:
55+
56+
```bash
57+
python3 docs/register_ai_nodes.py -s http://localhost:8080 -u admin -p <password>
58+
```
5559

5660
---
5761

@@ -125,7 +129,7 @@ Click any node to see its properties in the right panel:
125129
126130
## Step 5: Run Cypher Queries
127131
128-
If you ran `register_ai_nodes.py` in Step 1, all 29 queries below are already in BloodHound's **Saved Queries** panel. Click the **Saved Queries** button in the Cypher tab, search for "AIHound", and click any query to load and run it.
132+
If you ran `--import-queries` in Step 1, all 29 queries below are already in BloodHound's **Saved Queries** panel. Click the **Saved Queries** button in the Cypher tab, search for "AIHound", and click any query to load and run it.
129133
130134
You can also paste queries directly into the **Cypher query bar** (toggle to Cypher mode in the search bar).
131135
@@ -258,10 +262,12 @@ Then upload the new file to BloodHound CE (Step 3). New nodes/edges will be merg
258262
The full set of 29 pre-built queries is in:
259263

260264
```
261-
docs/cypher_queries.cy
265+
extension/queries.json
262266
```
263267

264-
If you ran `register_ai_nodes.py`, these are already imported into BloodHound's **Saved Queries** panel — search "AIHound" to find them. You can also open the file in any text editor and paste queries into BloodHound's Cypher query bar.
268+
If you ran `--import-queries`, these are already imported into BloodHound's **Saved Queries** panel — search "AIHound" to find them. The queries are also available in `docs/cypher_queries.cy` for manual copy/paste into BloodHound's Cypher query bar.
269+
270+
The queries follow the [SpecterOps Query Library format](https://queries.specterops.io) and can be browsed at that site if you host `queries.json` at a public URL.
265271

266272
---
267273

@@ -341,13 +347,12 @@ AIService (Perplexity)
341347

342348
| Problem | Solution |
343349
|---------|----------|
344-
| Nodes show as generic circles | Run `register_ai_nodes.py` again (Step 1) |
350+
| Nodes show as generic circles | Run `--import-queries` again (Step 1) to re-register the schema |
345351
| "No results" on a query | Check spelling — node properties are lowercase |
346352
| Upload fails | Ensure BloodHound CE is v9.x (OpenGraph support required) |
347353
| Can't find Cypher input | Look for the "Cypher" tab in the search bar area |
348354
| Can't find Saved Queries | Click the "Saved Queries" button above the Cypher editor, then search "AIHound" |
349355
| Graph looks empty | Make sure the scan found credentials: run `python3 -m aihound` first to check |
350-
| Registration script fails with 401 | Check your BloodHound password or use `--token-id` / `--token-key` instead |
351-
| Registration fails with 409 | Node kinds already registered — use `--reset` to clear and re-register |
356+
| Import fails with 401 | Check your BloodHound password or use `--bloodhound-token-id` / `--bloodhound-token-key` instead |
352357
| Search shows "?" icons for custom nodes | This is a BHCE limitation — custom node icons render correctly in the Cypher graph view but show as `?` in the Search tab dropdown. Use the Cypher tab or Saved Queries instead |
353358
| "Invalid Node Kind" error in search | Re-run the AIHound scan and re-upload — older exports had colons in node names that conflicted with BHCE's search syntax |

‎docs/Full-Documentation.md‎

Lines changed: 31 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -404,20 +404,25 @@ ConfigFile (.credentials.json)
404404

405405
### Setup
406406

407-
**1. Register custom node types and saved queries** (once per BloodHound instance):
407+
**1. Register extension schema and import saved queries** (once per BloodHound instance):
408408

409409
```bash
410-
python3 docs/register_ai_nodes.py -s http://localhost:8080 -u admin -p <password>
410+
python3 -m aihound --import-queries \
411+
--bloodhound-server http://localhost:8080 \
412+
--bloodhound-user admin \
413+
--bloodhound-password <password>
411414
```
412415

413-
This registers 14 custom node kinds with Font Awesome icons and imports 29 pre-built Cypher queries into BloodHound's **Saved Queries** panel.
416+
This registers 14 custom node kinds with icons/colors via the OpenGraph extension schema (`extension/schema.json`) and imports 29 saved Cypher queries from `extension/queries.json`. Running it again is safe — it skips existing queries and re-registers the schema.
414417

415418
| Flag | Description |
416419
|------|-------------|
417-
| *(no flags)* | Register node kinds + saved queries (skips if already exist) |
418-
| `--reset` | Delete all AIHound node kinds and saved queries, then re-register |
419-
| `--unregister` | Remove all AIHound node kinds and saved queries |
420-
| `--no-queries` | Skip importing saved Cypher queries |
420+
| `--bloodhound-server URL` | BloodHound CE server URL (required) |
421+
| `--bloodhound-user USER` | BloodHound username (use with `--bloodhound-password`) |
422+
| `--bloodhound-password PASS` | BloodHound password |
423+
| `--bloodhound-token-id UUID` | API token ID (alternative to username/password) |
424+
| `--bloodhound-token-key KEY` | API token key |
425+
| `--queries-file PATH` | Custom queries JSON file (default: bundled `extension/queries.json`) |
421426
| `--no-verify-ssl` | Disable SSL certificate verification |
422427

423428
**2. Run scan and export:**
@@ -428,32 +433,32 @@ aihound --bloodhound output.json
428433

429434
**3. Upload** `output.json` to BloodHound CE via Quick Upload.
430435

431-
**4. Query attack paths** — open the **Saved Queries** panel in the Cypher tab and search "AIHound", or paste from `cypher_queries.cy`:
436+
**4. Query attack paths** — open the **Saved Queries** panel in the Cypher tab and search "AIHound", or paste queries manually:
432437

433438
```cypher
434439
// Full graph — all AI credential relationships
435440
MATCH path = (a:AIHound)-[r]->(b:AIHound) RETURN path
436441
437442
// Blast radius from critical credentials
438-
MATCH path = (c:AICredential)-[*1..4]->(target)
443+
MATCH path = (c:AIHound_AICredential)-[*1..4]->(target)
439444
WHERE c.risk_level = "critical"
440445
RETURN path
441446
442447
// MCP server attack chain
443-
MATCH path = (t:AITool)-[:UsesMCPServer]->(m:MCPServer)-[:RequiresCredential]->(c:AICredential)-[:Authenticates]->(s:AIService)
448+
MATCH path = (t:AIHound_AITool)-[:AIHound_UsesMCPServer]->(m:AIHound_MCPServer)-[:AIHound_RequiresCredential]->(c:AIHound_AICredential)-[:AIHound_Authenticates]->(s:AIHound_AIService)
444449
RETURN path
445450
446451
// Same secret in multiple locations
447-
MATCH path = (c1:AICredential)-[:SameSecret]->(c2:AICredential)
452+
MATCH path = (c1:AIHound_AICredential)-[:AIHound_SameSecret]->(c2:AIHound_AICredential)
448453
RETURN path
449454
450455
// What breaks if I rotate this key?
451-
MATCH path = (t:AITool)-[:UsesMCPServer]->(m:MCPServer)-[:RequiresCredential]->(c:AICredential)
456+
MATCH path = (t:AIHound_AITool)-[:AIHound_UsesMCPServer]->(m:AIHound_MCPServer)-[:AIHound_RequiresCredential]->(c:AIHound_AICredential)
452457
WHERE c.credential_type CONTAINS "PERPLEXITY"
453458
RETURN path
454459
```
455460

456-
See `BLOODHOUND_GUIDE.md` for the full step-by-step walkthrough. All 29 queries from `cypher_queries.cy` are auto-imported into BloodHound's Saved Queries when you run `register_ai_nodes.py`.
461+
See `BLOODHOUND_GUIDE.md` for the full step-by-step walkthrough. The queries follow the [SpecterOps Query Library format](https://queries.specterops.io) — all 29 are in `extension/queries.json`.
457462

458463
---
459464

@@ -482,6 +487,14 @@ All flags are the same across all three versions:
482487
| `--min-risk LEVEL` | Minimum risk to emit as watch events (default: `info`) |
483488
| `--debounce SECONDS` | Suppress duplicate events within window (default: 10) |
484489
| `--mcp` | Run as MCP stdio server (requires `pip install aihound[mcp]`) |
490+
| `--import-queries` | Register schema and import saved queries into BloodHound CE, then exit |
491+
| `--bloodhound-server URL` | BloodHound CE server URL (for `--import-queries`) |
492+
| `--bloodhound-user USER` | BloodHound username |
493+
| `--bloodhound-password PASS` | BloodHound password |
494+
| `--bloodhound-token-id UUID` | BloodHound API token ID |
495+
| `--bloodhound-token-key KEY` | BloodHound API token key |
496+
| `--queries-file PATH` | Custom queries JSON file (default: `extension/queries.json`) |
497+
| `--no-verify-ssl` | Disable SSL certificate verification for BloodHound connection |
485498

486499
---
487500

@@ -884,10 +897,15 @@ aihound/
884897
│ ├── json_export.py # JSON report
885898
│ ├── html_report.py # Self-contained HTML report with embedded banner
886899
│ └── opengraph_export.py # BloodHound CE OpenGraph JSON export
900+
├── bloodhound.py # BloodHound CE API client (schema registration + query import)
887901
└── utils/
888902
├── keychain.py # macOS Keychain queries
889903
├── credman.py # Windows Credential Manager queries
890904
└── vscdb.py # VS Code SQLite state.vscdb reader
905+
906+
extension/
907+
├── schema.json # OpenGraph extension schema (node kinds, icons, colors, relationships)
908+
└── queries.json # 29 pre-built Cypher queries in SpecterOps Query Library format
891909
```
892910

893911
---

0 commit comments

Comments
 (0)