hb-scan 0.1.0

hb-scan

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

Quick Start

pip install hb-scan
hb-scan

That'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.html in any browser.

What It Does

$ 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)

What It Scans

Nine threat classes backed by international standards. Each maps to specific controls in OWASP, NIST, ISO, CIS, MITRE, and the EU AI Act.

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.

Scoring

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

10 leaked API keys = same score as 1 leaked API key. The control is failing either way.

Compliance

The HTML report maps every finding to specific controls in 8 international frameworks:

Each framework shows an alignment score with pass/fail/partial status per control. Use the report as an audit artifact.

Human Oversight Index

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."

Architecture

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

CLI Reference

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

Supported AI Tools

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.

Tiers

pip install hb-scan
hb-scan

hb-scan --llm

Contributing

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.

License

Apache 2.0. See LICENSE.

humanbound.ai · GitHub

_{For organisation-wide AI governance, connect hb-scan to the Humanbound platform.}