AI session security scanner -- detect secrets, unsafe code, and data leakage in your AI tool conversations.
151 rules · 70+ credential providers · 8 compliance frameworks
Quick Start · What It Scans · Scoring · Compliance · User Guide · Contributing
pip install hb-scan
hb-scanThat's it. hb-scan discovers AI tool sessions on your machine, scans them with 139 regex rules, and produces an AI hygiene report with a compliance-mapped score.
Want the full HTML report? hb-scan generates one automatically in your current directory. Open
hb-scan-report.htmlin any browser.
$ hb-scan --since 7d
hb-scan v0.1.0
[1/4] Searching for AI tool footprints...
✓ Found 100 sessions (Claude Code)
[2/4] Analysing conversations for secrets...
[3/4] Crunching the numbers...
[4/4] Building your report...
○ A few opportunities to improve.
┌──────────────────────── hb-scan — AI Hygiene Report ─────────────────────────┐
│ Mar 12 — Mar 19, 2026 │
└──────────────────────────────────────────────────────────────────────────────┘
Tool: Claude Code
Sessions scanned: 100
⚠ Credential Exposure — 1 active credential
✓ Sensitive Data — Clean
✓ Code Security — Clean
✓ Commands — Clean
✓ Package Safety — Clean
✓ IP / Trade Secret — Clean
◌ Regulatory Data — requires LLM judge
○ Human Oversight Index — HOI 0.97
┌───────────────────────── HYGIENE SCORE ──────────────────────────────────────┐
│ 80/100 (Grade B) │
└──────────────────────────────────────────────────────────────────────────────┘
Rules: 139/151 active (12 require LLM judge)
Nine threat classes backed by international standards. Each maps to specific controls in OWASP, NIST, ISO, CIS, MITRE, and the EU AI Act.
| ID | Threat Class | Rules | Detection | Key Standards |
|---|---|---|---|---|
| DH-01 | Secret Exposure | 104 | regex | OWASP LLM02, MITRE AML.T0051 |
| DH-02 | Unsafe Code Acceptance | 6 + 3 LLM | regex + llm | OWASP LLM05, NIST SP 800-218A |
| DH-03 | Dangerous Command Execution | 8 | regex | OWASP LLM06, SANS IDEsaster |
| DH-04 | Sensitive Data Sharing | 6 + 1 LLM | regex + llm | ISO 42001 A.7, MITRE AML.T0024 |
| DH-05 | Supply Chain Risk | 6 | regex | OWASP LLM03, ENISA Slopsquatting |
| DH-06 | Scope Violation | 5 | regex | OWASP Agentic ASI03, CIS Control 6 |
| DH-07 | IP / Trade Secret Leakage | 3 + 2 LLM | regex + llm | DTSA, EU Trade Secrets Directive |
| DH-08 | Regulatory Data Exposure | 0 + 6 LLM | llm only | GDPR, HIPAA, SOX, ABA Opinion 512 |
| DH-09 | Excessive Reliance | 1 | heuristic | EU AI Act Art. 14, NIST AI RMF |
104 credential patterns sourced from gitleaks and TruffleHog covering AWS, Azure, GCP, OpenAI, Anthropic, GitHub, Slack, Stripe, and 60+ more providers.
See docs/taxonomy.md for the full reference with standards citations.
hb-scan uses control-based scoring, not per-finding counting. This mirrors how ISO 42001 and CIS Controls work: each category is a control that either passes or fails.
Score = 100 - sum(category penalties)
Category penalty:
0 if clean (no findings)
100% if high-severity findings present
50% if medium-severity findings present
25% if low-severity findings present
| Category | Weight | What it means |
|---|---|---|
| Secret Exposure | 20 | Credentials found in AI conversations |
| Sensitive Data | 15 | Private files shared with AI tools |
| IP / Trade Secret | 15 | Proprietary content shared with AI |
| Regulatory Data | 15 | GDPR/HIPAA/SOX data in AI sessions |
| Code Security | 12 | Vulnerable AI-generated code accepted |
| Dangerous Commands | 10 | Risky shell commands via AI |
| Supply Chain | 8 | Unvetted packages installed via AI |
| Scope Violation | 5 | AI accessing files outside project |
10 leaked API keys = same score as 1 leaked API key. The control is failing either way.
The HTML report maps every finding to specific controls in 8 international frameworks:
|
AI-Specific Frameworks
|
General Security Frameworks
|
Each framework shows an alignment score with pass/fail/partial status per control. Use the report as an audit artifact.
The HOI score (0.0 - 1.0) measures how actively you supervise AI tool actions. Sessions with 50+ tool executions and fewer than 3 substantive user interactions are flagged as auto-pilot.
HOI 1.0 = Full oversight (all sessions supervised)
HOI 0.9+ = Good
HOI 0.7+ = Attention needed
HOI < 0.5 = Significant over-reliance
88% of accepted AI-generated code is retained without modification (GitHub/Accenture 2025). EU AI Act Article 14 requires awareness of "automation bias."
hb-scan
|
├── Discover ────── Find AI tool sessions on disk
| └── Claude Code (v1), Cursor, Aider... (plugins)
|
├── Normalize ───── Convert to common Session / Message / ToolCall schema
|
├── Match ────────── Run YAML rules against normalized sessions
| ├── 139 regex rules (active in Tier 1.1)
| └── 12 LLM rules (deferred to Tier 1.2)
|
├── Enrich ──────── JWT expiry detection, severity adjustments
|
├── Aggregate ───── Group findings into insight sections
|
├── Score ────────── Control-based posture calculation
|
└── Report ──────── Terminal summary + branded HTML report
hb-scan # Full scan, terminal + HTML report
hb-scan --since 7d # Last 7 days only
hb-scan --since 24h # Last 24 hours
hb-scan --tool claude-code # Specific tool only
hb-scan --project /path/to/repo # Specific project only
hb-scan --rules ./my-rules/ # Add custom YAML rules directory
hb-scan --format json # Machine-readable JSON output
hb-scan --output report.html # Custom report path
hb-scan --no-telemetry # Disable anonymous usage telemetry
hb-scan discover # List discovered AI tools
hb-scan rules # List all rules and their status| Tool | Status | Data Source |
|---|---|---|
| Claude Code | Supported | ~/.claude/projects/ (JSONL sessions) |
Support for additional AI tools (Cursor, GitHub Copilot, Aider, Continue.dev, ChatGPT Desktop, Windsurf, and others) is in progress. This list will grow as new discoverers are added.
Adding a new tool = one Python file implementing
BaseDiscoverer. See contributing guide.
|
Tier 1.1 -- Current Regex-based rules. Fully offline. Open source. pip install hb-scan
hb-scan |
Tier 1.2 -- Coming Bring your own LLM judge. Regulatory data detection. Semantic analysis. hb-scan --llm |
Tier 2 -- Platform Org-wide governance. Device fleet scanning. Posture dashboard. |
We welcome contributions in four areas:
- Rules -- detection patterns for new credential types or vulnerability patterns
- Discoverers -- support for new AI tools (Cursor, Aider, Continue.dev)
- Compliance -- control mappings from additional frameworks
- Core -- false positive improvements, scoring refinements, report enhancements
See docs/contributing.md for architecture, development setup, and PR guidelines.
AGPL-3.0. See LICENSE.
For organisation-wide AI governance, connect hb-scan to the Humanbound platform.