📦 secrets-audit — 密钥审计

扫描任何项目目录以发现暴露的密钥、硬编码凭证和数据泄露。生成带有修复步骤的严重性分级报告。

快速开始

# 完整项目扫描
python3 scripts/scan_secrets.py /path/to/project
# 扫描并检查git历史
python3 scripts/scan_secrets.py /path/to/project --git-history
# 仅扫描特定文件类型
python3 scripts/scan_secrets.py /path/to/project --extensions .py,.js,.ts,.env,.yml,.json
# JSON输出用于CI集成
python3 scripts/scan_secrets.py /path/to/project --format json

检测内容

高严重性

• API密钥（AWS、GCP、Azure、OpenAI、Stripe等）
• 带凭证的数据库连接字符串
• 私钥（RSA、SSH、PGP）
• OAuth令牌和刷新令牌
• JWT密钥和签名密钥
• 带字面值的密码字段

中严重性

• 包含密钥的.env文件
• 带凭证的配置文件（database.yml、settings.py等）
• 带嵌入式认证的硬编码URL（user:pass@host）
• 带令牌的Webhook URL
• 赋值上下文中的通用高熵字符串

低严重性

• 提及密钥的TODO/FIXME注释
• 占位符凭证（admin/admin、test/test）
• 文档中的示例API密钥
• 已注释掉的凭证

忽略（减少误报）

• 锁文件（package-lock.json、yarn.lock等）
• 二进制文件
• 压缩的JS/CSS
• 明确标记为假数据的测试fixture
• node_modules、.git、vendor目录

扫描输出

扫描器生成结构化报告：

=== Secrets Audit Report ===
Project: /path/to/project
Scanned: 247 files | Skipped: 1,203 files
Time: 2.3s
--- HIGH SEVERITY (3 findings) ---
[H1] AWS Access Key ID
File: src/config/aws.js:14
Match: AKIA...EXAMPLE
Context: const accessKey = "AKIA..."
Fix: Move to environment variable AWS_ACCESS_KEY_ID
[H2] Database Password
File: config/database.yml:8
Match: password: "pr0duction_p@ss"
Fix: Use DATABASE_URL env var or secrets manager
--- MEDIUM SEVERITY (5 findings) ---
...
--- SUMMARY ---
High: 3 | Medium: 5 | Low: 2 | Total: 10
Recommendation: Rotate all HIGH severity credentials immediately

工作流程

1. 扫描

针对目标目录运行scripts/scan_secrets.py。脚本会：

• 递归遍历目录树
• 跳过二进制文件、锁文件和依赖目录
• 应用references/secret-patterns.md中的40多个正则模式
• 计算潜在密钥的熵
• 对发现结果去重

2. 审查

按严重性分组展示发现结果。对于每个发现：

• 显示文件、行号和周围上下文
• 解释发现的是哪种类型的密钥
• 评估是真实密钥还是误报

3. 修复

对于每个确认的发现，提供具体的修复指导：

• 使用哪个环境变量
• 如何添加到.gitignore
• 密钥是否需要轮换（如果已提交到git）
• 显示修复的示例代码

4. 验证

修复后：

• 重新运行扫描以确认修复
• 如果密钥曾被提交，检查git历史
• 建议添加pre-commit钩子以防止未来泄露

Git历史扫描

使用--git-history标志时，脚本还会检查：

• 曾包含密钥的已删除文件
• 密钥被移除的文件先前版本
• 提交消息中包含"secret"、"password"、"key"的提交

重要提示：如果密钥曾被提交到git，即使后来被移除，也必须进行轮换——它存在于git历史中。

CI集成

脚本返回用于CI流水线的退出码：

• 0 — 无发现
• 1 — 仅低/中严重性发现
• 2 — 高严重性发现（应阻止部署）

JSON输出（--format json）可被CI工具解析以进行自动报告。

Pre-commit钩子设置

审计后，建议设置pre-commit钩子。请参阅references/prevention-guide.md了解钩子的安装和配置。