rmkanda/trufflehog

truffleHog 镜像文档

镜像概述和主要用途

truffleHog是一个专注于在git仓库中搜索敏感信息的工具，能够深入扫描提交历史和所有分支，通过正则表达式匹配和熵值分析两种方式，有效发现意外提交的密钥、API凭证、私钥等敏感数据。该工具旨在帮助开发团队和安全审计人员在代码部署前识别潜在的安全风险，防止敏感信息泄露。

核心功能和特性

• 双检测机制：支持高信号正则表达式检查和熵值分析（可单独启用或禁用）
• 路径过滤：通过--include_paths和--exclude_paths选项，使用正则表达式文件定义扫描范围，减少噪音
• 自定义规则：允许通过JSON文件添加自定义正则表达式规则，适应特定场景需求
• 灵活扫描范围：支持从指定提交哈希开始扫描（--since_commit）和限制提交深度（--max_depth）
• 多种输出格式：支持标准文本输出和JSON格式输出（--json），便于集成到自动化工具中

使用场景和适用范围

• 代码安全审计：在代码审查过程中扫描仓库历史，确保无敏感信息提交
• CI/CD管道集成：作为持续集成流程的一部分，自动扫描代码仓库，防止敏感信息进入部署环节
• 第三方仓库评估：在使用第三方开源项目前，扫描其仓库是否包含泄露的敏感信息
• 内部安全合规检查：定期扫描公司内部代码仓库，确保符合数据安全政策

使用方法和配置说明

基本使用（Docker命令）

bash
# 扫描远程Git仓库（启用正则检查，禁用熵检查）
docker run dxa4481/trufflehog --regex --entropy=False https://github.com/example/repo.git

# 扫描本地Git仓库
docker run -v /path/to/local/repo:/repo dxa4481/trufflehog file:///repo

路径过滤示例

创建包含路径过滤规则的文件：

include-patterns.txt（仅扫描匹配的路径）：

ini
src/
# 注释行以"#"开头
gradle/
(?i).*\.(properties|conf|ini|txt|y(a)?ml)$  # 匹配特定格式文件（不区分大小写）
(.*/)?id_[rd]sa$  # 匹配SSH私钥文件

exclude-patterns.txt（排除匹配的路径）：

ini
(.*/)?\.classpath$  # 排除.classpath文件
.*\.jmx$  # 排除.jmx文件
(.*/)?test/(.*/)?resources/  # 排除测试资源目录

使用过滤规则扫描：

bash
docker run -v /path/to/rules:/rules -v /path/to/local/repo:/repo dxa4481/trufflehog \
  --include_paths /rules/include-patterns.txt \
  --exclude_paths /rules/exclude-patterns.txt \
  file:///repo

自定义规则

创建自定义规则JSON文件（custom-rules.json）：

json
{
  "Azure API Key": "AZURE_KEY_[A-Za-z0-9]{32}",
  "Twilio Auth Token": "SK[a-z0-9]{32}"
}

使用自定义规则扫描：

bash
docker run -v /path/to/custom-rules.json:/rules.json dxa4481/trufflehog \
  --regex --rules /rules.json \
  https://github.com/example/repo.git

详细参数说明

查看帮助信息

bash
docker run dxa4481/trufflehog --help

工作原理

truffleHog通过以下步骤扫描Git仓库：

1. 遍历指定仓库的所有分支和提交历史（可通过--since_commit和--max_depth限制范围）
2. 对每个提交的差异（diff）进行分析：
   • 正则检查：使用内置或自定义正则表达式匹配已知敏感信息格式（如API密钥、私钥等）
   • 熵值分析：计算Base64和十六进制字符集的香农熵，识别高熵字符串（通常为随机生成的密钥）
3. 对匹配到的敏感信息，输出相关文件路径、提交哈希、敏感内容等信息

注意事项

• 当前GitPython存在兼容性问题，镜像已包含临时修复，可直接使用dxa4481/trufflehog镜像
• 扫描大型仓库时建议使用--max_depth限制深度，或通过--include_paths缩小范围以提高效率
• 自定义规则应确保正则表达式具有高信号（低误报率），避免过多噪音