aihound 3.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. aihound-3.2.1/LICENSE +21 -0
  2. aihound-3.2.1/PKG-INFO +271 -0
  3. aihound-3.2.1/README.md +240 -0
  4. aihound-3.2.1/aihound/__init__.py +3 -0
  5. aihound-3.2.1/aihound/__main__.py +7 -0
  6. aihound-3.2.1/aihound/cli.py +456 -0
  7. aihound-3.2.1/aihound/core/__init__.py +0 -0
  8. aihound-3.2.1/aihound/core/mcp.py +297 -0
  9. aihound-3.2.1/aihound/core/permissions.py +185 -0
  10. aihound-3.2.1/aihound/core/platform.py +203 -0
  11. aihound-3.2.1/aihound/core/redactor.py +112 -0
  12. aihound-3.2.1/aihound/core/scanner.py +131 -0
  13. aihound-3.2.1/aihound/mcp_server.py +312 -0
  14. aihound-3.2.1/aihound/notifications.py +184 -0
  15. aihound-3.2.1/aihound/output/__init__.py +0 -0
  16. aihound-3.2.1/aihound/output/html_report.py +336 -0
  17. aihound-3.2.1/aihound/output/json_export.py +60 -0
  18. aihound-3.2.1/aihound/output/opengraph_export.py +664 -0
  19. aihound-3.2.1/aihound/output/table.py +208 -0
  20. aihound-3.2.1/aihound/output/watch_formatters.py +199 -0
  21. aihound-3.2.1/aihound/remediation.py +105 -0
  22. aihound-3.2.1/aihound/scanners/__init__.py +30 -0
  23. aihound-3.2.1/aihound/scanners/aider.py +138 -0
  24. aihound-3.2.1/aihound/scanners/amazon_q.py +147 -0
  25. aihound-3.2.1/aihound/scanners/browser_sessions.py +519 -0
  26. aihound-3.2.1/aihound/scanners/chatgpt.py +118 -0
  27. aihound-3.2.1/aihound/scanners/claude_code.py +333 -0
  28. aihound-3.2.1/aihound/scanners/claude_desktop.py +60 -0
  29. aihound-3.2.1/aihound/scanners/claude_sessions.py +564 -0
  30. aihound-3.2.1/aihound/scanners/cline.py +64 -0
  31. aihound-3.2.1/aihound/scanners/continue_dev.py +141 -0
  32. aihound-3.2.1/aihound/scanners/cursor.py +62 -0
  33. aihound-3.2.1/aihound/scanners/docker.py +319 -0
  34. aihound-3.2.1/aihound/scanners/envvars.py +139 -0
  35. aihound-3.2.1/aihound/scanners/gemini.py +190 -0
  36. aihound-3.2.1/aihound/scanners/git_credentials.py +238 -0
  37. aihound-3.2.1/aihound/scanners/github_copilot.py +196 -0
  38. aihound-3.2.1/aihound/scanners/huggingface.py +97 -0
  39. aihound-3.2.1/aihound/scanners/jupyter.py +341 -0
  40. aihound-3.2.1/aihound/scanners/lm_studio.py +274 -0
  41. aihound-3.2.1/aihound/scanners/ml_platforms.py +209 -0
  42. aihound-3.2.1/aihound/scanners/network_exposure.py +132 -0
  43. aihound-3.2.1/aihound/scanners/ollama.py +299 -0
  44. aihound-3.2.1/aihound/scanners/openai_cli.py +234 -0
  45. aihound-3.2.1/aihound/scanners/openclaw.py +419 -0
  46. aihound-3.2.1/aihound/scanners/persistent_env.py +453 -0
  47. aihound-3.2.1/aihound/scanners/powershell.py +287 -0
  48. aihound-3.2.1/aihound/scanners/shell_history.py +286 -0
  49. aihound-3.2.1/aihound/scanners/shell_rc.py +316 -0
  50. aihound-3.2.1/aihound/scanners/vscode_extensions.py +231 -0
  51. aihound-3.2.1/aihound/scanners/windsurf.py +129 -0
  52. aihound-3.2.1/aihound/utils/__init__.py +0 -0
  53. aihound-3.2.1/aihound/utils/credman.py +65 -0
  54. aihound-3.2.1/aihound/utils/keychain.py +90 -0
  55. aihound-3.2.1/aihound/utils/vscdb.py +80 -0
  56. aihound-3.2.1/aihound/watch.py +308 -0
  57. aihound-3.2.1/aihound.egg-info/PKG-INFO +271 -0
  58. aihound-3.2.1/aihound.egg-info/SOURCES.txt +62 -0
  59. aihound-3.2.1/aihound.egg-info/dependency_links.txt +1 -0
  60. aihound-3.2.1/aihound.egg-info/entry_points.txt +2 -0
  61. aihound-3.2.1/aihound.egg-info/requires.txt +6 -0
  62. aihound-3.2.1/aihound.egg-info/top_level.txt +1 -0
  63. aihound-3.2.1/pyproject.toml +45 -0
  64. aihound-3.2.1/setup.cfg +4 -0
aihound-3.2.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Darryl G. Baker
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
aihound-3.2.1/PKG-INFO ADDED
@@ -0,0 +1,271 @@
1
+ Metadata-Version: 2.1
2
+ Name: aihound
3
+ Version: 3.2.1
4
+ Summary: AIHound - AI Credential & Secrets Scanner
5
+ Author: Darryl Baker
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/netwrix/AIHound
8
+ Project-URL: Documentation, https://github.com/netwrix/AIHound/tree/main/docs
9
+ Project-URL: Repository, https://github.com/netwrix/AIHound
10
+ Project-URL: Issues, https://github.com/netwrix/AIHound/issues
11
+ Keywords: security,credentials,ai,llm,mcp,aihound,secrets-scanner,ai-security,bloodhound,offensive-security
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Information Technology
15
+ Classifier: Intended Audience :: System Administrators
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Topic :: Security
23
+ Classifier: Topic :: System :: Systems Administration
24
+ Requires-Python: >=3.10
25
+ Description-Content-Type: text/markdown
26
+ License-File: LICENSE
27
+ Provides-Extra: pretty
28
+ Requires-Dist: rich>=13.0; extra == "pretty"
29
+ Provides-Extra: mcp
30
+ Requires-Dist: mcp>=1.0; extra == "mcp"
31
+
32
+ <div align="center">
33
+
34
+ # AIHound
35
+
36
+ ### AI Credential & Secrets Scanner
37
+
38
+ <p>
39
+ <img src="aihound.png" alt="AIHound" width="500">
40
+ </p>
41
+
42
+ [![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
43
+ [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white)](#prerequisites)
44
+ [![Version](https://img.shields.io/badge/version-3.2.1-green?style=flat-square)](#)
45
+ [![Scanners](https://img.shields.io/badge/AI_tool_scanners-29-brightgreen?style=flat-square)](#step-5-scan-specific-tools)
46
+ [![Platforms](https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux%20%7C%20WSL-blueviolet?style=flat-square)](#wsl-users)
47
+ [![Outputs](https://img.shields.io/badge/outputs-HTML%20%7C%20JSON%20%7C%20BloodHound-orange?style=flat-square)](#step-4-generate-reports)
48
+ [![BloodHound](https://img.shields.io/badge/BloodHound_CE-compatible-red?style=flat-square)](#bloodhound-attack-path-graph)
49
+ [![MCP Server](https://img.shields.io/badge/MCP_Server-enabled-9cf?style=flat-square)](docs/Full-Documentation.md)
50
+ [![GitHub stars](https://img.shields.io/github/stars/netwrix/AIHound?style=flat-square)](https://github.com/netwrix/AIHound/stargazers)
51
+ [![GitHub forks](https://img.shields.io/github/forks/netwrix/AIHound?style=flat-square)](https://github.com/netwrix/AIHound/network/members)
52
+ [![Last Commit](https://img.shields.io/github/last-commit/netwrix/AIHound?style=flat-square)](https://github.com/netwrix/AIHound/commits/main)
53
+ [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](CONTRIBUTING.md)
54
+
55
+ **29 AI tool scanners · 4 platforms · BloodHound attack path export · MCP server mode · Watch mode**
56
+
57
+ [Get Started](#step-1-get-aihound) · [Reports](#step-4-generate-reports) · [BloodHound](#bloodhound-attack-path-graph) · [Scan Tools](#step-5-scan-specific-tools) · [Documentation](https://github.com/netwrix/AIHound/tree/main/docs)
58
+
59
+ </div>
60
+
61
+ ---
62
+
63
+ AIHound is an AI Assistant credential and secrets scanner that detects exposed API keys, OAuth tokens, MCP server secrets, and session credentials across 29 AI tools on Windows, macOS, Linux, and WSL. Beyond one-shot scanning with terminal, it offers a watch mode for continuous monitoring that alerts on new, changed, or escalated credentials in real time.
64
+
65
+ AIHound includes an MCP server mode that lets AI assistants like Claude Code scan for and remediate credential issues programmatically.
66
+
67
+ AIHound can export to **SpectorOps' BloodHound**. Scan results export as OpenGraph JSON that can be ingested into BloodHound to visualize attack paths, showing compromised credential chains through MCP servers, AI services, and datastores. I've included 29 pre-built Cypher queries for blast radius analysis, same-secret detection, and lateral movement mapping.
68
+
69
+ > This is a security research tool. Credentials are **redacted by default** so output is safe to share in reports and screenshots.
70
+
71
+ Get scanning in under 2 minutes.
72
+
73
+ ## **PyInstaller Precompiled .exe version can be found [Here](https://github.com/netwrix/AIHound/tree/main/Other%20Versions/pyinstaller/dist)**
74
+ ## **Go Precompiled .exe version can be found [Here](https://github.com/netwrix/AIHound/tree/main/Other%20Versions/Go/dist)**
75
+
76
+ AIHound can be run four ways: from Python source, using the Go runtime. as a compiled Go binary, or as a standalone Windows executable.
77
+
78
+ ### Full Documentation located [Here](https://github.com/netwrix/AIHound/tree/main/docs)
79
+
80
+ ## Prerequisites
81
+
82
+ - Python 3.10 or higher
83
+ - That's it. No pip install required for basic scanning.
84
+
85
+ ## Step 1: Get AIHound
86
+
87
+ ```bash
88
+ git clone https://github.com/netwrix/AIHound.git
89
+ cd AIHound
90
+ ```
91
+
92
+ ## Step 2: Run Your First Scan
93
+
94
+ ```bash
95
+ python3 -m aihound
96
+ ```
97
+
98
+ You'll see output like this:
99
+
100
+ ```
101
+ ╔══════════════════════════════════════════════════════════════╗
102
+ ║ AIHound - AI Credential & Secrets Scanner ║
103
+ ╚══════════════════════════════════════════════════════════════╝
104
+
105
+ Platform: wsl
106
+ WSL detected - scanning both Linux and Windows credential paths
107
+
108
+ Tool Credential Type Storage Location Risk
109
+ -------------------------------------------------------------------------------------------------
110
+ Claude Code CLI oauth_access_token plaintext... ~/.claude/.credentials.json CRITICAL
111
+ Value: sk-ant-oat01-Z...eAAA
112
+ Claude Code CLI oauth_refresh_token plaintext... ~/.claude/.credentials.json HIGH
113
+ Value: sk-ant-ort01-r...ygAA
114
+
115
+ Summary: 2 findings | 1 CRITICAL | 1 HIGH
116
+ ```
117
+
118
+ All secret values are automatically redacted. The tool is read-only and doesn't touch your credentials.
119
+
120
+ ## Step 3: Get More Detail
121
+
122
+ Add `-v` for verbose output — shows file permissions (with human-readable descriptions), ownership, expiry times, and notes:
123
+
124
+ ```bash
125
+ python3 -m aihound -v
126
+ ```
127
+
128
+ ```
129
+ Claude Code CLI oauth_access_token plaintext... ~/.claude/.credentials.json CRITICAL
130
+ Value: sk-ant-oat01-Z...eAAA
131
+ Note: Expires: 2026-03-09 23:30 UTC
132
+ Perms: 0777 (world-writable, world-readable, DANGEROUS) Owner: ull
133
+ ```
134
+
135
+ ## Step 4: Generate Reports
136
+
137
+ ### HTML Report
138
+
139
+ Creates a self-contained HTML file with the AIHound banner, dark theme, and color-coded risk table:
140
+
141
+ ```bash
142
+ python3 -m aihound --html-file report.html
143
+ ```
144
+
145
+ Open `report.html` in your browser. Great for sharing with your team or including in assessments.
146
+
147
+ ### JSON Report
148
+
149
+ For automation, pipelines, or feeding into other tools:
150
+
151
+ ```bash
152
+ # Write to file
153
+ python3 -m aihound --json-file report.json
154
+
155
+ # Pipe to stdout
156
+ python3 -m aihound --json | jq '.summary'
157
+ ```
158
+
159
+ ### BloodHound Attack Path Graph
160
+
161
+ Export to [BloodHound CE](https://github.com/SpecterOps/BloodHound) for interactive attack path visualization — see how credentials chain together across tools, services, and data stores:
162
+
163
+ ```bash
164
+ python3 -m aihound --bloodhound aihound-bloodhound.json
165
+ ```
166
+
167
+ Then upload `aihound-bloodhound.json` to BloodHound CE (v9.x) via **Quick Upload** or **Data Collection > File Ingest**.
168
+
169
+ **First time?** Register custom node types and saved Cypher queries (once per BloodHound instance):
170
+ >register_ai_nodes.py script located in docs folder.
171
+
172
+ ```bash
173
+ python3 docs/register_ai_nodes.py -s http://<bloodhound IP>:8080 -u admin -p <password>
174
+ ```
175
+
176
+ This registers 14 custom node kinds with icons and imports 29 saved Cypher queries into BloodHound's Saved Queries panel. Use `--reset` to re-register, `--unregister` to remove everything, or `--no-queries` to skip query import.
177
+
178
+ Example Cypher queries (also available in Saved Queries after registration):
179
+
180
+ ```cypher
181
+ // Show the full credential graph
182
+ MATCH path = (a:AIHound)-[r]->(b:AIHound) RETURN path
183
+
184
+ // Blast radius from critical credentials
185
+ MATCH path = (c:AICredential)-[*1..4]->(target)
186
+ WHERE c.risk_level = "critical"
187
+ RETURN path
188
+
189
+ // MCP server attack chain: tool -> server -> credential -> service
190
+ MATCH path = (t:AITool)-[:UsesMCPServer]->(m:MCPServer)-[:RequiresCredential]->(c:AICredential)-[:Authenticates]->(s:AIService)
191
+ RETURN path
192
+ ```
193
+
194
+ See `BLOODHOUND_GUIDE.md` located [Here](https://github.com/netwrix/AIHound/tree/main/docs) for the full walkthrough and `cypher_queries.cy` for all 29 pre-built queries.
195
+
196
+ <img width="1768" height="937" alt="Screenshot 2026-05-12 135945" src="https://github.com/user-attachments/assets/72d00b53-662b-40a4-be8d-cd95be86eee7" />
197
+
198
+ ### All at once
199
+
200
+ ```bash
201
+ python3 -m aihound -v --html-file report.html --json-file report.json --bloodhound bloodhound.json
202
+ ```
203
+
204
+ ## Step 5: Scan Specific Tools
205
+
206
+ List what's available:
207
+
208
+ ```bash
209
+ python3 -m aihound --list-tools
210
+ ```
211
+
212
+ ```
213
+ Available scanners:
214
+ amazon-q Amazon Q / AWS Applicable: yes
215
+ chatgpt ChatGPT Desktop Applicable: yes
216
+ claude-code Claude Code CLI Applicable: yes
217
+ claude-desktop Claude Desktop Applicable: yes
218
+ cline Cline (VS Code) Applicable: yes
219
+ continue-dev Continue.dev Applicable: yes
220
+ cursor Cursor IDE Applicable: yes
221
+ envvars Environment Variables Applicable: yes
222
+ gemini Gemini CLI / GCloud Applicable: yes
223
+ github-copilot GitHub Copilot Applicable: yes
224
+ windsurf Windsurf Applicable: yes
225
+ ```
226
+
227
+ Scan only specific tools by slug:
228
+
229
+ ```bash
230
+ python3 -m aihound --tools claude-code claude-desktop envvars
231
+ ```
232
+
233
+ ## What Does Each Risk Level Mean?
234
+
235
+ | Level | What It Means | What To Do |
236
+ |---|---|---|
237
+ | **CRITICAL** | Plaintext secret in a world-readable file | Fix file permissions immediately (`chmod 600`) |
238
+ | **HIGH** | Plaintext secret, only owner can read | Acceptable for some tools, but consider using OS keychain |
239
+ | **MEDIUM** | OS credential store or environment variable | Standard practice, but be aware of the exposure |
240
+ | **LOW** | Encrypted storage | Generally acceptable |
241
+ | **INFO** | Metadata, not an actual secret | No action needed |
242
+
243
+ ## WSL Users
244
+
245
+ If you're running on WSL, AIHound automatically detects it and scans **both**:
246
+ - Linux-native paths (`~/.claude/`, `~/.aws/`, etc.)
247
+ - Windows paths via `/mnt/c/Users/<you>/AppData/...`
248
+
249
+ This often reveals credentials in Windows app data that have overly permissive permissions (e.g., `0777`) when viewed from WSL.
250
+
251
+ ## Common Findings & What They Mean
252
+
253
+ ### "oauth_access_token" / "oauth_refresh_token" — Claude Code
254
+ Claude Code stores OAuth tokens in `~/.claude/.credentials.json`. The access token is short-lived (hours), but the **refresh token is long-lived** and can be used to generate new access tokens.
255
+
256
+ ### "mcp_env:ADO_MCP_AUTH_TOKEN" — MCP Servers
257
+ MCP server configurations often embed auth tokens directly in JSON config files. If you see inline secrets here, consider using environment variable references (`${VAR_NAME}`) instead.
258
+
259
+ ### "api_key (anthropic)" — Continue.dev
260
+ Continue.dev stores API keys in plaintext in `~/.continue/config.json`. Use the `${ENV_VAR}` syntax in the config to avoid this.
261
+
262
+ ### AWS credentials
263
+ `~/.aws/credentials` contains long-lived access keys. Consider using SSO/IAM Identity Center instead of static keys.
264
+
265
+ ## Next Steps
266
+
267
+ - Review findings and fix any CRITICAL/HIGH issues
268
+ - Generate an HTML report for your team: `python3 -m aihound --html-file report.html`
269
+ - Export to BloodHound for attack path visualization: `python3 -m aihound --bloodhound bloodhound.json`
270
+ - See `BLOODHOUND_GUIDE.md` for the full BloodHound walkthrough
271
+ - Check the full Documentation [Here](https://github.com/netwrix/AIHound/tree/main/docs) for watch mode, MCP server mode, and advanced usage
@@ -0,0 +1,240 @@
1
+ <div align="center">
2
+
3
+ # AIHound
4
+
5
+ ### AI Credential & Secrets Scanner
6
+
7
+ <p>
8
+ <img src="aihound.png" alt="AIHound" width="500">
9
+ </p>
10
+
11
+ [![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
12
+ [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white)](#prerequisites)
13
+ [![Version](https://img.shields.io/badge/version-3.2.1-green?style=flat-square)](#)
14
+ [![Scanners](https://img.shields.io/badge/AI_tool_scanners-29-brightgreen?style=flat-square)](#step-5-scan-specific-tools)
15
+ [![Platforms](https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux%20%7C%20WSL-blueviolet?style=flat-square)](#wsl-users)
16
+ [![Outputs](https://img.shields.io/badge/outputs-HTML%20%7C%20JSON%20%7C%20BloodHound-orange?style=flat-square)](#step-4-generate-reports)
17
+ [![BloodHound](https://img.shields.io/badge/BloodHound_CE-compatible-red?style=flat-square)](#bloodhound-attack-path-graph)
18
+ [![MCP Server](https://img.shields.io/badge/MCP_Server-enabled-9cf?style=flat-square)](docs/Full-Documentation.md)
19
+ [![GitHub stars](https://img.shields.io/github/stars/netwrix/AIHound?style=flat-square)](https://github.com/netwrix/AIHound/stargazers)
20
+ [![GitHub forks](https://img.shields.io/github/forks/netwrix/AIHound?style=flat-square)](https://github.com/netwrix/AIHound/network/members)
21
+ [![Last Commit](https://img.shields.io/github/last-commit/netwrix/AIHound?style=flat-square)](https://github.com/netwrix/AIHound/commits/main)
22
+ [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](CONTRIBUTING.md)
23
+
24
+ **29 AI tool scanners · 4 platforms · BloodHound attack path export · MCP server mode · Watch mode**
25
+
26
+ [Get Started](#step-1-get-aihound) · [Reports](#step-4-generate-reports) · [BloodHound](#bloodhound-attack-path-graph) · [Scan Tools](#step-5-scan-specific-tools) · [Documentation](https://github.com/netwrix/AIHound/tree/main/docs)
27
+
28
+ </div>
29
+
30
+ ---
31
+
32
+ AIHound is an AI Assistant credential and secrets scanner that detects exposed API keys, OAuth tokens, MCP server secrets, and session credentials across 29 AI tools on Windows, macOS, Linux, and WSL. Beyond one-shot scanning with terminal, it offers a watch mode for continuous monitoring that alerts on new, changed, or escalated credentials in real time.
33
+
34
+ AIHound includes an MCP server mode that lets AI assistants like Claude Code scan for and remediate credential issues programmatically.
35
+
36
+ AIHound can export to **SpectorOps' BloodHound**. Scan results export as OpenGraph JSON that can be ingested into BloodHound to visualize attack paths, showing compromised credential chains through MCP servers, AI services, and datastores. I've included 29 pre-built Cypher queries for blast radius analysis, same-secret detection, and lateral movement mapping.
37
+
38
+ > This is a security research tool. Credentials are **redacted by default** so output is safe to share in reports and screenshots.
39
+
40
+ Get scanning in under 2 minutes.
41
+
42
+ ## **PyInstaller Precompiled .exe version can be found [Here](https://github.com/netwrix/AIHound/tree/main/Other%20Versions/pyinstaller/dist)**
43
+ ## **Go Precompiled .exe version can be found [Here](https://github.com/netwrix/AIHound/tree/main/Other%20Versions/Go/dist)**
44
+
45
+ AIHound can be run four ways: from Python source, using the Go runtime. as a compiled Go binary, or as a standalone Windows executable.
46
+
47
+ ### Full Documentation located [Here](https://github.com/netwrix/AIHound/tree/main/docs)
48
+
49
+ ## Prerequisites
50
+
51
+ - Python 3.10 or higher
52
+ - That's it. No pip install required for basic scanning.
53
+
54
+ ## Step 1: Get AIHound
55
+
56
+ ```bash
57
+ git clone https://github.com/netwrix/AIHound.git
58
+ cd AIHound
59
+ ```
60
+
61
+ ## Step 2: Run Your First Scan
62
+
63
+ ```bash
64
+ python3 -m aihound
65
+ ```
66
+
67
+ You'll see output like this:
68
+
69
+ ```
70
+ ╔══════════════════════════════════════════════════════════════╗
71
+ ║ AIHound - AI Credential & Secrets Scanner ║
72
+ ╚══════════════════════════════════════════════════════════════╝
73
+
74
+ Platform: wsl
75
+ WSL detected - scanning both Linux and Windows credential paths
76
+
77
+ Tool Credential Type Storage Location Risk
78
+ -------------------------------------------------------------------------------------------------
79
+ Claude Code CLI oauth_access_token plaintext... ~/.claude/.credentials.json CRITICAL
80
+ Value: sk-ant-oat01-Z...eAAA
81
+ Claude Code CLI oauth_refresh_token plaintext... ~/.claude/.credentials.json HIGH
82
+ Value: sk-ant-ort01-r...ygAA
83
+
84
+ Summary: 2 findings | 1 CRITICAL | 1 HIGH
85
+ ```
86
+
87
+ All secret values are automatically redacted. The tool is read-only and doesn't touch your credentials.
88
+
89
+ ## Step 3: Get More Detail
90
+
91
+ Add `-v` for verbose output — shows file permissions (with human-readable descriptions), ownership, expiry times, and notes:
92
+
93
+ ```bash
94
+ python3 -m aihound -v
95
+ ```
96
+
97
+ ```
98
+ Claude Code CLI oauth_access_token plaintext... ~/.claude/.credentials.json CRITICAL
99
+ Value: sk-ant-oat01-Z...eAAA
100
+ Note: Expires: 2026-03-09 23:30 UTC
101
+ Perms: 0777 (world-writable, world-readable, DANGEROUS) Owner: ull
102
+ ```
103
+
104
+ ## Step 4: Generate Reports
105
+
106
+ ### HTML Report
107
+
108
+ Creates a self-contained HTML file with the AIHound banner, dark theme, and color-coded risk table:
109
+
110
+ ```bash
111
+ python3 -m aihound --html-file report.html
112
+ ```
113
+
114
+ Open `report.html` in your browser. Great for sharing with your team or including in assessments.
115
+
116
+ ### JSON Report
117
+
118
+ For automation, pipelines, or feeding into other tools:
119
+
120
+ ```bash
121
+ # Write to file
122
+ python3 -m aihound --json-file report.json
123
+
124
+ # Pipe to stdout
125
+ python3 -m aihound --json | jq '.summary'
126
+ ```
127
+
128
+ ### BloodHound Attack Path Graph
129
+
130
+ Export to [BloodHound CE](https://github.com/SpecterOps/BloodHound) for interactive attack path visualization — see how credentials chain together across tools, services, and data stores:
131
+
132
+ ```bash
133
+ python3 -m aihound --bloodhound aihound-bloodhound.json
134
+ ```
135
+
136
+ Then upload `aihound-bloodhound.json` to BloodHound CE (v9.x) via **Quick Upload** or **Data Collection > File Ingest**.
137
+
138
+ **First time?** Register custom node types and saved Cypher queries (once per BloodHound instance):
139
+ >register_ai_nodes.py script located in docs folder.
140
+
141
+ ```bash
142
+ python3 docs/register_ai_nodes.py -s http://<bloodhound IP>:8080 -u admin -p <password>
143
+ ```
144
+
145
+ This registers 14 custom node kinds with icons and imports 29 saved Cypher queries into BloodHound's Saved Queries panel. Use `--reset` to re-register, `--unregister` to remove everything, or `--no-queries` to skip query import.
146
+
147
+ Example Cypher queries (also available in Saved Queries after registration):
148
+
149
+ ```cypher
150
+ // Show the full credential graph
151
+ MATCH path = (a:AIHound)-[r]->(b:AIHound) RETURN path
152
+
153
+ // Blast radius from critical credentials
154
+ MATCH path = (c:AICredential)-[*1..4]->(target)
155
+ WHERE c.risk_level = "critical"
156
+ RETURN path
157
+
158
+ // MCP server attack chain: tool -> server -> credential -> service
159
+ MATCH path = (t:AITool)-[:UsesMCPServer]->(m:MCPServer)-[:RequiresCredential]->(c:AICredential)-[:Authenticates]->(s:AIService)
160
+ RETURN path
161
+ ```
162
+
163
+ See `BLOODHOUND_GUIDE.md` located [Here](https://github.com/netwrix/AIHound/tree/main/docs) for the full walkthrough and `cypher_queries.cy` for all 29 pre-built queries.
164
+
165
+ <img width="1768" height="937" alt="Screenshot 2026-05-12 135945" src="https://github.com/user-attachments/assets/72d00b53-662b-40a4-be8d-cd95be86eee7" />
166
+
167
+ ### All at once
168
+
169
+ ```bash
170
+ python3 -m aihound -v --html-file report.html --json-file report.json --bloodhound bloodhound.json
171
+ ```
172
+
173
+ ## Step 5: Scan Specific Tools
174
+
175
+ List what's available:
176
+
177
+ ```bash
178
+ python3 -m aihound --list-tools
179
+ ```
180
+
181
+ ```
182
+ Available scanners:
183
+ amazon-q Amazon Q / AWS Applicable: yes
184
+ chatgpt ChatGPT Desktop Applicable: yes
185
+ claude-code Claude Code CLI Applicable: yes
186
+ claude-desktop Claude Desktop Applicable: yes
187
+ cline Cline (VS Code) Applicable: yes
188
+ continue-dev Continue.dev Applicable: yes
189
+ cursor Cursor IDE Applicable: yes
190
+ envvars Environment Variables Applicable: yes
191
+ gemini Gemini CLI / GCloud Applicable: yes
192
+ github-copilot GitHub Copilot Applicable: yes
193
+ windsurf Windsurf Applicable: yes
194
+ ```
195
+
196
+ Scan only specific tools by slug:
197
+
198
+ ```bash
199
+ python3 -m aihound --tools claude-code claude-desktop envvars
200
+ ```
201
+
202
+ ## What Does Each Risk Level Mean?
203
+
204
+ | Level | What It Means | What To Do |
205
+ |---|---|---|
206
+ | **CRITICAL** | Plaintext secret in a world-readable file | Fix file permissions immediately (`chmod 600`) |
207
+ | **HIGH** | Plaintext secret, only owner can read | Acceptable for some tools, but consider using OS keychain |
208
+ | **MEDIUM** | OS credential store or environment variable | Standard practice, but be aware of the exposure |
209
+ | **LOW** | Encrypted storage | Generally acceptable |
210
+ | **INFO** | Metadata, not an actual secret | No action needed |
211
+
212
+ ## WSL Users
213
+
214
+ If you're running on WSL, AIHound automatically detects it and scans **both**:
215
+ - Linux-native paths (`~/.claude/`, `~/.aws/`, etc.)
216
+ - Windows paths via `/mnt/c/Users/<you>/AppData/...`
217
+
218
+ This often reveals credentials in Windows app data that have overly permissive permissions (e.g., `0777`) when viewed from WSL.
219
+
220
+ ## Common Findings & What They Mean
221
+
222
+ ### "oauth_access_token" / "oauth_refresh_token" — Claude Code
223
+ Claude Code stores OAuth tokens in `~/.claude/.credentials.json`. The access token is short-lived (hours), but the **refresh token is long-lived** and can be used to generate new access tokens.
224
+
225
+ ### "mcp_env:ADO_MCP_AUTH_TOKEN" — MCP Servers
226
+ MCP server configurations often embed auth tokens directly in JSON config files. If you see inline secrets here, consider using environment variable references (`${VAR_NAME}`) instead.
227
+
228
+ ### "api_key (anthropic)" — Continue.dev
229
+ Continue.dev stores API keys in plaintext in `~/.continue/config.json`. Use the `${ENV_VAR}` syntax in the config to avoid this.
230
+
231
+ ### AWS credentials
232
+ `~/.aws/credentials` contains long-lived access keys. Consider using SSO/IAM Identity Center instead of static keys.
233
+
234
+ ## Next Steps
235
+
236
+ - Review findings and fix any CRITICAL/HIGH issues
237
+ - Generate an HTML report for your team: `python3 -m aihound --html-file report.html`
238
+ - Export to BloodHound for attack path visualization: `python3 -m aihound --bloodhound bloodhound.json`
239
+ - See `BLOODHOUND_GUIDE.md` for the full BloodHound walkthrough
240
+ - Check the full Documentation [Here](https://github.com/netwrix/AIHound/tree/main/docs) for watch mode, MCP server mode, and advanced usage
@@ -0,0 +1,3 @@
1
+ """AIHound - AI Credential & Secrets Scanner."""
2
+
3
+ __version__ = "3.2.1"
@@ -0,0 +1,7 @@
1
+ """Entry point for python -m aihound."""
2
+
3
+ import sys
4
+ from aihound.cli import main
5
+
6
+ if __name__ == "__main__":
7
+ sys.exit(main())