TruffleHog 是什么
TruffleHog 是密钥扫描工具，把 API Key、口令、Token 从 git 历史、文件系统、对象存储等位置找出来。v3 引入「验证」能力：对部分凭据类型实际发起认证探测，把「疑似泄露」降噪成「确认有效」，让处置队列更接近真实风险。发现结果时以非零退出码结束，可直接作为 CI 门禁使用。
基本信息
| 扫描源 | git 历史、文件系统、S3、GCS、Docker 镜像等 |
|---|---|
| 降噪开关 | --only-verified 只输出验证通过的凭据 |
| 输出格式 | 默认文本；--json 输出结构化结果便于接入安全流程 |
| CI 集成 | 发现结果返回非零退出码，可阻断流水线 |
| 典型用户 | 安全团队例行巡检、研发团队上线前自查 |
典型使用场景
- 仓库开源或交付前：确认 git 历史里没有残留的密钥
- 例行安全巡检：按仓库或目录周期扫描，汇总新增发现
- CI 门禁：在流水线中运行，阻止新增密钥被合并进主干
- 事件响应：收到泄露通报后快速定位影响范围与凭据类型
- 迁移审计：老仓库合并、转交或归档前做一次全历史排查
常用命令
常用命令
trufflehog git file://. --only-verified # 扫当前仓库全历史，只输出验证通过的凭据
trufflehog git file://. --json > findings.json # 完整结果落盘，方便过滤与二次处理
trufflehog filesystem /data/repos --only-verified # 扫描普通目录（非 git 项目同样适用）
trufflehog s3 --bucket=prod-backups --only-verified # 扫描对象存储，需对应读取权限结果字段速读
| 字段 | 含义 | 处置要点 |
|---|---|---|
| DetectorName | 命中的凭据类型（如 AWS、GitHub） | 决定验证方式与轮换流程 |
| Verified | 是否通过在线验证 | 为 true 的优先处置 |
| Raw | 凭据原文 | 报告流转前必须脱敏 |
| SourceMetadata | 发现位置：仓库、文件与提交 | 用于清理与排查引入时间 |
验证功能会对凭据所属系统发起真实调用：执行前与安全团队约定范围并配置告警豁免，避免触发风控或封禁。
扫描报告属于高敏数据：转工单前先脱敏；密钥一旦进入截图或文档，就应视为已泄露并安排轮换。