# hanchuntao/keyhound architecture

> Architecture diagram of the GitHub repository hanchuntao/keyhound, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hanchuntao/keyhound
- Repository: https://github.com/hanchuntao/keyhound

## Overview

KeyHound is a local-first Git secret scanner. A user submits a repository or Docker image through the CLI; the tool gathers source and history, detects and filters candidate secrets, optionally pairs and verifies findings, then presents or exports results. Its documented scope also includes Kubernetes/Helm, CI logs, and multiple SaaS/cloud credential families. The graph captures the principal flow and major capabilities; several specialized scanners and report paths are represented at directory or module level because their implementations were not excerpted.

Main entry points: [`keyhound/cli.py`](https://github.com/hanchuntao/keyhound/blob/main/keyhound/cli.py) (CLI workflow), [`keyhound/scanner/rule_engine.py`](https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/rule_engine.py) (Rule engine), [`keyhound/scanner/cloud_sign.py`](https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/cloud_sign.py) (Cloud signatures), [`keyhound/scanner/git_traversal.py`](https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/git_traversal.py) (Git history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Input and orchestration"]
  node_cli["CLI workflow<br/>[cli.py]"]
  node_git["Git history<br/>[git_traversal.py]"]
  node_docker["Docker scans<br/>[docker_scan.py]"]
  node_config["Scan config<br/>[config.py]"]
end

subgraph group_detection["Detection and analysis"]
  node_rules["Rule engine<br/>[rule_engine.py]"]
  node_filters["Noise filters<br/>[filters.py]"]
  node_entropy["Entropy analysis<br/>[entropy.py]"]
  node_finding["Finding model<br/>[finding.py]"]
  node_association["Credential pairing<br/>[association.py]"]
  node_specialized["Specialized scans"]
  node_archive["Archive scans<br/>[archive_scan.py]"]
end

subgraph group_validation["Validation and review"]
  node_verification["SaaS verification<br/>[verify.py]"]
  node_cloudsign["Cloud signatures<br/>[cloud_sign.py]"]
  node_ai["AI review<br/>[ai_review.py]"]
end

subgraph group_outputs["Results and learning"]
  node_reports["HTML report<br/>[html_report.py]"]
  node_formats["CI report formats"]
  node_learn[("Learning library<br/>[learn.py]")]
end

node_user(("Engineer"))
node_cloudapis{{"Cloud provider APIs"}}
node_saasapis{{"SaaS endpoints"}}
node_aiapi{{"AI service"}}

node_user -->|"runs scan"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"scans history"| node_git
node_cli -->|"scans image"| node_docker
node_cli -->|"scans content"| node_rules
node_git -->|"scans archives"| node_archive
node_rules -->|"creates findings"| node_finding
node_rules -->|"checks entropy"| node_entropy
node_rules -->|"filters matches"| node_filters
node_rules -->|"detects formats"| node_specialized
node_cli -->|"pairs findings"| node_association
node_association -->|"checks key pairs"| node_cloudsign
node_cli -->|"verifies findings"| node_verification
node_verification -->|"sends requests"| node_saasapis
node_cli -->|"verifies cloud keys"| node_cloudsign
node_cloudsign -->|"signs requests"| node_cloudapis
node_cli -->|"reviews findings"| node_ai
node_ai -->|"requests review"| node_aiapi
node_cli -->|"writes HTML"| node_reports
node_cli -->|"exports reports"| node_formats
node_cli -->|"records findings"| node_learn
node_learn -->|"summarizes findings"| node_finding

click node_cli "https://github.com/hanchuntao/keyhound/blob/main/keyhound/cli.py"
click node_git "https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/git_traversal.py"
click node_docker "https://github.com/hanchuntao/keyhound/blob/main/keyhound/docker_scan.py"
click node_config "https://github.com/hanchuntao/keyhound/blob/main/keyhound/config.py"
click node_rules "https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/rule_engine.py"
click node_filters "https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/filters.py"
click node_entropy "https://github.com/hanchuntao/keyhound/blob/main/keyhound/utils/entropy.py"
click node_finding "https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/finding.py"
click node_association "https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/association.py"
click node_specialized "https://github.com/hanchuntao/keyhound/tree/main/keyhound/scanner"
click node_archive "https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/archive_scan.py"
click node_verification "https://github.com/hanchuntao/keyhound/blob/main/keyhound/verify.py"
click node_cloudsign "https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/cloud_sign.py"
click node_ai "https://github.com/hanchuntao/keyhound/blob/main/keyhound/ai_review.py"
click node_reports "https://github.com/hanchuntao/keyhound/blob/main/keyhound/report/html_report.py"
click node_formats "https://github.com/hanchuntao/keyhound/tree/main/keyhound"
click node_learn "https://github.com/hanchuntao/keyhound/blob/main/keyhound/learn.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_git,node_docker,node_config toneBlue
class node_rules,node_filters,node_entropy,node_finding,node_association,node_specialized,node_archive toneAmber
class node_verification,node_cloudsign,node_ai,node_cloudapis toneMint
class node_reports,node_formats,node_learn toneRose
class node_user,node_saasapis,node_aiapi toneIndigo
```

## Components

### Input and orchestration

- [CLI workflow](https://github.com/hanchuntao/keyhound/blob/main/keyhound/cli.py): `keyhound/cli.py`
- [Git history](https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/git_traversal.py): `keyhound/scanner/git_traversal.py`
- [Docker scans](https://github.com/hanchuntao/keyhound/blob/main/keyhound/docker_scan.py): `keyhound/docker_scan.py`
- [Scan config](https://github.com/hanchuntao/keyhound/blob/main/keyhound/config.py): `keyhound/config.py`

### Detection and analysis

- [Rule engine](https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/rule_engine.py): `keyhound/scanner/rule_engine.py`
- [Noise filters](https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/filters.py): `keyhound/scanner/filters.py`
- [Entropy analysis](https://github.com/hanchuntao/keyhound/blob/main/keyhound/utils/entropy.py): `keyhound/utils/entropy.py`
- [Finding model](https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/finding.py): `keyhound/scanner/finding.py`
- [Credential pairing](https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/association.py): `keyhound/scanner/association.py`
- [Specialized scans](https://github.com/hanchuntao/keyhound/tree/main/keyhound/scanner): `keyhound/scanner`
- [Archive scans](https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/archive_scan.py): `keyhound/scanner/archive_scan.py`

### Validation and review

- [SaaS verification](https://github.com/hanchuntao/keyhound/blob/main/keyhound/verify.py): `keyhound/verify.py`
- [Cloud signatures](https://github.com/hanchuntao/keyhound/blob/main/keyhound/scanner/cloud_sign.py): `keyhound/scanner/cloud_sign.py`
- [AI review](https://github.com/hanchuntao/keyhound/blob/main/keyhound/ai_review.py): `keyhound/ai_review.py`

### Results and learning

- [HTML report](https://github.com/hanchuntao/keyhound/blob/main/keyhound/report/html_report.py): `keyhound/report/html_report.py`
- [CI report formats](https://github.com/hanchuntao/keyhound/tree/main/keyhound): `keyhound`
- [Learning library](https://github.com/hanchuntao/keyhound/blob/main/keyhound/learn.py): `keyhound/learn.py`

### Other components

- **Engineer**
- **Cloud provider APIs**
- **SaaS endpoints**
- **AI service**

## Connections

- Engineer → CLI workflow: runs scan (evidence: `README.md`)
- CLI workflow → Scan config: loads settings (evidence: `keyhound/cli.py`)
- CLI workflow → Git history: scans history (evidence: `keyhound/cli.py`)
- CLI workflow → Docker scans: scans image (evidence: `keyhound/cli.py`)
- CLI workflow → Rule engine: scans content (evidence: `keyhound/cli.py`)
- Git history → Archive scans: scans archives (evidence: `keyhound/scanner/git_traversal.py`)
- Rule engine → Finding model: creates findings (evidence: `keyhound/scanner/rule_engine.py`)
- Rule engine → Entropy analysis: checks entropy (evidence: `keyhound/scanner/rule_engine.py`)
- Rule engine → Noise filters: filters matches (evidence: `README.md`)
- Rule engine → Specialized scans: detects formats (evidence: `README.md`)
- CLI workflow → Credential pairing: pairs findings (evidence: `keyhound/cli.py`)
- Credential pairing → Cloud signatures: checks key pairs (evidence: `keyhound/scanner/association.py`)
- CLI workflow → SaaS verification: verifies findings (evidence: `keyhound/cli.py`)
- SaaS verification → SaaS endpoints: sends requests (evidence: `keyhound/verify.py`)
- CLI workflow → Cloud signatures: verifies cloud keys (evidence: `README.md`)
- Cloud signatures → Cloud provider APIs: signs requests (evidence: `keyhound/scanner/cloud_sign.py`)
- CLI workflow → AI review: reviews findings (evidence: `keyhound/cli.py`)
- AI review → AI service: requests review (evidence: `keyhound/ai_review.py`)
- CLI workflow → HTML report: writes HTML (evidence: `keyhound/cli.py`)
- CLI workflow → CI report formats: exports reports (evidence: `README.md`)
- CLI workflow → Learning library: records findings (evidence: `README.md`)
- Learning library → Finding model: summarizes findings (evidence: `keyhound/learn.py`)