B0bTheSkull/vault-scan
GitHub: B0bTheSkull/vault-scan
一个轻量级Git仓库秘密扫描工具，通过正则模式匹配和香农熵值过滤检测代码及历史中泄露的API密钥、凭证和敏感信息，可嵌入CI流水线作为安全门禁使用。
Stars: 0 | Forks: 0
# vault-scan
## 它的功能
vault-scan 会遍历你的 git 历史（或仅当前工作区），并使用两种互补的检测策略找出泄露的秘密：
- **模式匹配** — 针对约 30 种服务的特定正则表达式，这些格式的特征非常明显，一旦匹配几乎总是真实的（如 AWS、GitHub、Stripe、Slack、Google、SendGrid、Twilio、NPM、PyPI、DigitalOcean、Shopify、Mailchimp 等）
- **熵值过滤** — 对于像 `API_KEY=...` 或 `password=...` 这样的宽泛模式，会对捕获的值进行香农熵评分，以过滤掉如 `password=changeme` 或 `API_KEY=YOUR_KEY_HERE` 这样的占位符
发现的结果会经过去重、标记严重性，并默认进行脱敏处理，以便你可以安全地将输出粘贴到聊天或工单中。
## 可检测的内容
| 类别 | 示例 |
|---|---|
| **云 / 基础设施** | AWS 访问密钥 + Secret、DigitalOcean PAT、Google API + OAuth Secret |
| **源代码托管平台** | GitHub PAT（经典、细粒度、OAuth、App）、GitLab PAT |
| **通讯** | Slack bot/user token |
| **支付** | Stripe 实例/测试 Secret + 可发布密钥 |
| **SaaS** | SendGrid、Twilio、Shopify、Mailchimp、NPM、PyPI |
| **私钥** | RSA、EC、OpenSSH、PGP、通用 PKCS8 |
| **JWTs** | 标准 3 段式 JSON Web Token |
| **数据库连接字符串** | MongoDB、Postgres、MySQL、Redis、AMQP/RabbitMQ |
| **通用** | `api_key=`、`secret=`、`password=`、`token=`（带有熵值过滤） |
包含模式和严重性的完整规则列表位于 [`rules.yaml`](rules.yaml) 中。
## 安装
```
git clone https://github.com/B0bTheSkull/vault-scan.git
cd vault-scan
pip install -r requirements.txt
```
## 使用
```
# 扫描当前目录 — 完整历史 + 工作树
python main.py
# 扫描特定仓库
python main.py --path /path/to/repo
# 仅限工作树 (跳过历史)
python main.py --no-history
# 用于 CI 流水线的 JSON 输出
python main.py --output json --no-color
# 筛选为严重及高级别
python main.py --severity high
# 仅限最近 50 次提交 (针对庞大的历史记录)
python main.py --max-commits 50
# 显示未遮盖的 secret 值 (请谨慎操作)
python main.py --show-secrets
# 降低熵阈值 (召回率更高，误报更多)
python main.py --entropy-threshold 3.8
```
### 退出码
| 代码 | 含义 |
|---|---|
| `0` | 未发现任何问题 |
| `1` | 存在发现结果（在 CI 中使用此代码以使构建失败） |
| `2` | 使用 / 配置错误 |
### 嵌入 GitHub Actions
```
- uses: actions/checkout@v4
with:
fetch-depth: 0 # need full history
- run: pip install -r path/to/vault-scan/requirements.txt
- run: python path/to/vault-scan/main.py --output json --no-color
```
## 示例输出
```
vault-scan /home/me/projects/myapp
Commits scanned: 47 | Files touched: 3
Found 2 finding(s):
────────────────────────────────────────────────────────────────────────
[CRITICAL] AWS Access Key ID
file : terraform/dev.tfvars:7
commit: 4f8b3c2a Alice 2024-08-12T10:42:11
match : AKIA****************AB12
ctx : aws_access_key = "AKIAIOSFODNN7EXAMPLE_AB12"
────────────────────────────────────────────────────────────────────────
[HIGH] Slack Bot Token
file : scripts/notify.py:23
commit: 9e1d4f06 Alice 2024-09-01T14:08:55
match : xoxb-****************************************-uVWxYz0123456789Abc
ctx : slack_token = "xoxb-1234567890-1234567890-..."
────────────────────────────────────────────────────────────────────────
Summary: [CRITICAL] 1 [HIGH] 1
```
## 忽略文件
在仓库根目录下放置一个 `.vaultscanignore` 文件。语法与 `.gitignore` 相同：
```
# 测试 fixtures
tests/fixtures/**
# Vendored 依赖项
vendor/
node_modules/
# 特定文件
docs/example-tokens.md
```
## 为什么会有这个项目
GitLeaks 和 TruffleHog 已经实现了这些功能——而且做得很好。vault-scan 刻意保持得更小巧。它是一个单文件 Python 脚本，仅包含一个 YAML 规则文件且零编译依赖，这使其：
- 易于从头到尾阅读（约 500 行代码）
- 易于嵌入已有 Python 环境的 CI 流水线
- 易于通过自定义规则进行扩展（只需编辑 `rules.yaml`）
如果你需要最全面的覆盖范围，请使用 TruffleHog。如果你想要一个能够在 10 分钟内理解、审计和调整的工具，请使用它。
## 路线图
- [ ] `--scan-secrets-from-stdin` 模式（扫描单个文本块，而非仓库）
- [ ] Pre-commit hook 集成
- [ ] 用于 GitHub 代码扫描的 SARIF 输出格式
- [ ] 根据厂商 API 进行验证（例如：这个 AWS 密钥当前是否有效？）
- [ ] 批量扫描远程仓库列表
## 许可证
MIT — 详见 [LICENSE](LICENSE)
标签：API密钥检测, DevSecOps, GitHub安全, Git历史分析, JWT, Python, RSA密钥, 上游代理, 代码泄露检测, 多平台, 安全助手, 数据库连接字符串, 无后门, 正则匹配, 熵值检测, 网络安全, 网络安全研究, 输入验证, 逆向工具, 隐私保护