trufflehog使用教程

trufflehog 是 Kali Linux 中一款专注于 敏感凭证检测的开源工具，核心功能是扫描各类数据源（如代码仓库、文件系统、云存储、Docker 镜像等），自动识别并提取其中的敏感信息（如 API 密钥、密码、令牌、私钥、访问密钥等），帮助开发者、安全测试人员发现"硬编码凭证"这类高危安全隐患，避免因凭证泄露导致的数据泄露或未授权访问。

其核心特性与优势如下：

• 多数据源支持：覆盖 Git 仓库（本地/远程）、GitHub/GitLab 平台、文件系统、S3/GCS 云存储、Docker 镜像、CircleCI 配置、系统日志等，适配多场景扫描需求。
• 高精度检测：内置大量凭证检测规则（Detector），支持验证检测结果（如测试 API 密钥是否有效），减少误报；可自定义包含/排除特定检测规则，灵活适配业务场景。
• 丰富输出格式：支持 JSON（含 legacy 旧格式）、GitHub Actions 格式输出，便于结果分析、自动化集成（如对接 SIEM 系统、CI/CD 流水线）。
• 性能可配置：支持并发扫描（自定义工作线程数）、归档文件大小/深度/超时限制，平衡扫描效率与资源占用。
• 易用性强：提供向导模式（Wizard）简化扫描操作，支持配置文件批量定义扫描规则，适合新手与进阶用户。

二、命令参数解析（表格形式）

1. 初始交互选项（What do you want to do?）

英文选项	中文翻译	功能说明
Scan a source using wizard	使用向导模式扫描数据源	通过交互式引导选择扫描类型、配置参数，适合新手操作
View help docs	查看帮助文档	查看完整工具说明、命令用法、参数细节
View open-source project	查看开源项目	跳转至 trufflehog 开源仓库（如 GitHub），获取源码、更新日志
Inquire about TruffleHog Enterprise	咨询 TruffleHog 企业版	了解企业版功能（如高级检测规则、多团队协作、更全面的数据源支持）
Quit	退出	退出 trufflehog 工具交互界面

2. 全局 Flags（通用参数）

参数	英文说明	中文解析	使用场景
--help	Show context-sensitive help (also try --help-long and --help-man)	显示上下文帮助信息（--help-long 查看详细说明，--help-man 查看手册格式）	忘记命令用法时查询
--debug	Run in debug mode	启用调试模式，输出详细运行日志（如扫描进度、检测规则触发情况）	排查扫描失败、结果异常等问题
--trace	Run in trace mode	启用跟踪模式，输出更细粒度的日志（如函数调用、数据流转）	深度调试工具运行逻辑
--profile	Enables profiling and sets a pprof and fgprof server on :18066	启用性能分析，在 18066 端口启动 pprof/fgprof 服务（用于分析 CPU、内存占用）	优化扫描性能、定位资源消耗瓶颈
-j, --json	Output in JSON format	以 JSON 格式输出扫描结果（便于后续自动化分析、存储）	对接脚本、SIEM 系统、数据报表工具
--json-legacy	Use the pre-v3.0 JSON format. Only works with git, gitlab, and github sources	使用 v3.0 之前的旧版 JSON 格式（仅支持 git、gitlab、github 数据源）	兼容旧版工具或脚本（依赖旧格式输出）
--github-actions	Output in GitHub Actions format	以 GitHub Actions 格式输出（在 GitHub 流水线中显示结构化结果）	集成到 GitHub CI/CD 流水线，触发告警或阻断流程
--concurrency=4	Number of concurrent workers	设置并发工作线程数（默认 4，可根据 CPU 核心数调整）	提升扫描速度（如 8 核 CPU 设为 --concurrency=8）
--no-verification	Don't verify the results	不验证检测结果（仅识别疑似凭证，不测试有效性）	追求扫描速度，暂时无需确认凭证是否可用
--only-verified	Only output verified results	仅输出已验证有效的凭证（过滤未通过验证的疑似结果）	需精准结果，减少误报（如生产环境安全审计）
--filter-unverified	Only output first unverified result per chunk per detector if there are more than one results	若同一数据块、同一检测规则下有多个未验证结果，仅输出第一个	平衡结果数量与可读性，避免未验证结果刷屏
--config=CONFIG	Path to configuration file	指定配置文件路径（批量定义扫描规则、数据源、检测规则等）	批量扫描、标准化扫描流程（如企业统一安全检测配置）
--print-avg-detector-time	Print the average time spent on each detector	输出每个检测规则（Detector）的平均耗时	分析检测规则性能，优化扫描效率
--no-update	Don't check for updates	不检查工具更新（避免扫描前的更新检测耗时）	离线环境或无需实时更新工具版本
--fail	Exit with code 183 if results are found	若检测到凭证，工具以 183 状态码退出（正常无结果退出码为 0）	集成到 CI/CD 流水线（如检测到凭证则阻断构建）
--verifier=VERIFIER ...	Set custom verification endpoints	设置自定义验证端点（用于测试非默认类型凭证的有效性）	检测自定义业务系统的凭证（如内部 API 密钥）
--archive-max-size=ARCHIVE-MAX-SIZE	Maximum size of archive to scan. (Byte units eg. 512B, 2KB, 4MB)	设置待扫描归档文件（如 .zip、.tar）的最大大小（支持 B/KB/MB 单位）	避免超大归档文件占用过多资源（如 --archive-max-size=10MB）
--archive-max-depth=ARCHIVE-MAX-DEPTH	Maximum depth of archive to scan	设置归档文件的最大扫描深度（如子目录层级）	限制归档文件内深层目录的扫描，提升效率
--archive-timeout=ARCHIVE-TIMEOUT	Maximum time to spend extracting an archive	设置归档文件提取的最大超时时间（避免无限等待）	处理可能损坏或提取缓慢的归档文件
--include-detectors="all"	Comma separated list of detector types to include. Protobuf name or IDs may be used, as well as ranges	指定需包含的检测规则（用逗号分隔，支持 Protobuf 名称、ID 或 ID 范围，默认 "all" 即所有规则）	仅扫描特定类型凭证（如 --include-detectors="AWS,Google" 只检测 AWS/Google 凭证）
--exclude-detectors=EXCLUDE-DETECTORS	Comma separated list of detector types to exclude. Protobuf name or IDs may be used, as well as ranges. IDs defined here take precedence over the include list	指定需排除的检测规则（格式同上，优先级高于 --include-detectors）	过滤无需检测的凭证类型（如 --exclude-detectors="Slack" 不检测 Slack 令牌）
--version	Show application version	显示工具版本号	确认工具版本，排查版本兼容性问题

3. 核心 Commands（命令）

命令	英文说明	中文解析	基础用法示例
help [...]	Show help	查看指定命令的帮助信息（不指定则显示所有命令帮助）	trufflehog help git（查看 git 命令用法）
git []	Find credentials in git repositories	扫描 Git 仓库（本地路径或远程 URI，如 GitHub/GitLab 仓库地址）	trufflehog git https://github.com/example/repo.git（扫描远程 Git 仓库）
github []	Find credentials in GitHub repositories	扫描 GitHub 仓库（支持个人/组织仓库、指定分支/标签）	trufflehog github --org example-org（扫描 example-org 组织下的所有仓库）
gitlab --token=TOKEN []	Find credentials in GitLab repositories	扫描 GitLab 仓库（需 GitLab 访问令牌 --token，支持项目/群组仓库）	trufflehog gitlab --token=glpat-xxx --project 123（扫描 ID 为 123 的 GitLab 项目）
filesystem [] [...]	Find credentials in a filesystem	扫描文件系统（本地目录或文件路径，支持多个路径）	trufflehog filesystem /home/user/project（扫描指定本地目录）
s3 []	Find credentials in S3 buckets	扫描 AWS S3 存储桶（需 AWS 凭证，支持指定桶名、前缀）	trufflehog s3 --bucket my-bucket --prefix docs/（扫描 my-bucket 桶下 docs/ 前缀的文件）
gcs []	Find credentials in GCS buckets	扫描 Google Cloud Storage（GCS）存储桶（需 GCP 凭证，支持指定桶名、前缀）	trufflehog gcs --bucket my-gcs-bucket（扫描 my-gcs-bucket 存储桶）
syslog []	Scan syslog	扫描系统日志（支持本地日志文件、远程 syslog 服务）	trufflehog syslog /var/log/syslog（扫描本地 syslog 文件）
circleci --token=TOKEN	Scan CircleCI	扫描 CircleCI 配置（需 CircleCI 访问令牌 --token，检测配置中的敏感凭证）	trufflehog circleci --token=circleci-token-xxx（扫描当前账号下的 CircleCI 配置）
docker --image=IMAGE	Scan Docker Image	扫描 Docker 镜像（需指定镜像名 --image，检测镜像内文件中的敏感凭证）	trufflehog docker --image=ubuntu:22.04（扫描 ubuntu:22.04 镜像）

三、trufflehog 完整使用教程（全场景覆盖）

1. 前提准备：工具安装与环境确认

trufflehog 支持多种安装方式，Kali 推荐使用 Go 安装或直接下载二进制文件，确保工具版本为最新（功能更全面）：

1.1 安装方式（任选一种）

# 方式 1：Go 安装（需已安装 Go 1.20+）
go install github.com/trufflesecurity/trufflehog/v3/cmd/trufflehog@latest
# 验证：将 Go 二进制目录加入 PATH（如 echo 'export PATH=$PATH:$GOPATH/bin' >> ~/.bashrc），执行 trufflehog --version

# 方式 2：下载二进制文件（适合无 Go 环境）
# 查看最新版本：https://github.com/trufflesecurity/trufflehog/releases
wget https://github.com/trufflesecurity/trufflehog/releases/download/v3.x.x/trufflehog_3.x.x_linux_amd64.tar.gz
tar -zxvf trufflehog_3.x.x_linux_amd64.tar.gz
sudo mv trufflehog /usr/local/bin/
# 验证安装
trufflehog --version
# 输出类似 "trufflehog version 3.x.x" 即安装成功

1.2 环境依赖确认

• Git 仓库扫描 ：需安装 git 工具（Kali 默认预装，验证：git --version）；
• 云存储（S3/GCS）扫描 ：需配置对应云厂商凭证（如 AWS 配置 ~/.aws/credentials，GCP 配置 GOOGLE_APPLICATION_CREDENTIALS 环境变量）；
• Docker 镜像扫描 ：需安装 docker 并启动服务（sudo systemctl start docker），且当前用户有权限操作 docker（sudo usermod -aG docker $USER，需重启终端）。

2. 场景 1：向导模式扫描（新手友好）

场景描述：首次使用工具，通过交互式向导选择数据源（如本地目录、Git 仓库），无需手动输入复杂命令。

# 步骤 1：启动向导模式
trufflehog

# 步骤 2：选择扫描类型（通过方向键选择 "Scan a source using wizard"，按 Enter 确认）
# 输出交互提示："What source would you like to scan?"

# 步骤 3：选择数据源（如选择 "Filesystem"，按 Enter）
# 按提示输入本地目录路径（如 /home/user/test-project）

# 步骤 4：配置扫描参数（默认按 Enter 即可，或按需调整并发数、输出格式）
# 工具自动开始扫描，结果实时显示在终端

# 步骤 5：查看结果
# 扫描完成后，终端会列出检测到的敏感凭证（含类型、位置、是否验证通过）

3. 场景 2：扫描本地文件系统（检测硬编码凭证）

场景描述：扫描本地项目目录（如 /home/user/web-project），检测代码、配置文件中的 API 密钥、密码等。

# 基础扫描命令（默认所有检测规则，输出文本格式）
trufflehog filesystem /home/user/web-project

# 进阶命令（仅输出已验证凭证，JSON 格式保存结果）
trufflehog filesystem /home/user/web-project --only-verified -j > filesystem_results.json

# 参数解析
# --only-verified：过滤无效凭证，仅保留已验证有效的结果；
# -j：JSON 格式输出，重定向到文件便于后续分析；
# 结果文件查看：cat filesystem_results.json | jq（需安装 jq：sudo apt install jq）

# 常见过滤场景（仅检测 AWS 凭证，排除 Slack 凭证）
trufflehog filesystem /home/user/web-project --include-detectors="AWS" --exclude-detectors="Slack" -v
# -v：显示详细扫描过程（如当前扫描的文件路径）

4. 场景 3：扫描远程 Git 仓库（检测代码历史中的凭证）

场景描述：扫描 GitHub 远程仓库（如 https://github.com/example/test-repo），检测所有分支、提交历史中的敏感信息（含已删除但未清理的硬编码凭证）。

# 基础扫描（默认扫描所有分支，文本格式输出）
trufflehog git https://github.com/example/test-repo.git

# 进阶扫描（指定分支，并发 8 线程，结果输出到日志）
trufflehog git https://github.com/example/test-repo.git --branch main --concurrency=8 --debug > git_scan.log 2>&1

# 参数解析
# --branch main：仅扫描 main 分支（减少扫描范围，提升速度）；
# --concurrency=8：8 线程并发（匹配 8 核 CPU，避免资源浪费）；
# --debug：输出调试日志（便于排查扫描卡顿问题）；
# 2>&1：将错误日志也重定向到文件，完整记录扫描过程

# 扫描本地 Git 仓库（路径而非远程 URI）
trufflehog git /home/user/local-repo --depth=100
# --depth=100：仅扫描最近 100 次提交（适合大型仓库，减少扫描时间）

5. 场景 4：扫描 GitHub 组织/个人仓库（批量扫描）

场景描述：扫描 GitHub 个人账号或组织下的所有仓库（需 GitHub 个人访问令牌，获取地址：https://github.com/settings/tokens，权限勾选 repo、read:org）。

# 步骤 1：设置 GitHub 令牌（临时环境变量）
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 步骤 2：扫描个人账号下所有仓库
trufflehog github --user my-github-username --only-verified -j > github_user_results.json

# 步骤 3：扫描组织下所有仓库（如 example-org）
trufflehog github --org example-org --exclude-forks --archive-max-size=5MB
# 参数解析
# --exclude-forks：排除 Fork 的仓库（仅扫描组织原生仓库）；
# --archive-max-size=5MB：跳过超过 5MB 的归档文件（避免超大文件拖慢速度）

# 扫描指定 GitHub 仓库的特定标签（如 v1.0）
trufflehog github --repo example-org/test-repo --tag v1.0

6. 场景 5：扫描 GitLab 项目（需 GitLab 令牌）

场景描述：扫描 GitLab 私有项目（ID 为 123），需 GitLab 访问令牌（获取地址：https://gitlab.com/-/profile/personal_access_tokens，权限勾选 api）。

# 基础扫描（指定项目 ID，输出文本结果）
trufflehog gitlab --token=glpat-xxxxxxxxxxxxxxxxxxxx --project 123

# 进阶扫描（扫描 GitLab 群组下所有项目，验证凭证并保存日志）
trufflehog gitlab --token=glpat-xxxxxxxxxxxxxxxxxxxx --group 456 --only-verified --debug > gitlab_group_scan.log
# 参数解析
# --group 456：扫描 ID 为 456 的 GitLab 群组下所有项目；
# 其他参数与 GitHub 扫描一致

# 扫描 GitLab 项目的特定分支（如 dev 分支）
trufflehog gitlab --token=glpat-xxxxxxxxxxxxxxxxxxxx --project 123 --branch dev

7. 场景 6：扫描 Docker 镜像（检测镜像内敏感信息）

场景描述：扫描本地或远程 Docker 镜像（如 ubuntu:22.04、私有仓库镜像），检测镜像内文件（如配置文件、脚本）中的凭证。

# 步骤 1：确保 Docker 服务启动
sudo systemctl start docker

# 步骤 2：扫描本地 Docker 镜像（如 ubuntu:22.04）
trufflehog docker --image=ubuntu:22.04 -v

# 步骤 3：扫描远程私有仓库镜像（需先登录 Docker 仓库）
sudo docker login my-private-registry.com
trufflehog docker --image=my-private-registry.com/app:v1.0 --archive-max-depth=3
# 参数解析
# --archive-max-depth=3：归档文件扫描深度限制为 3 层（避免深层目录过度扫描）；
# 扫描结果会显示镜像内包含敏感凭证的文件路径（如 /etc/config.ini）

# 扫描 Docker 镜像并输出 JSON 结果
trufflehog docker --image=nginx:latest -j > docker_scan_results.json

8. 场景 7：扫描 AWS S3 存储桶（检测云存储凭证）

场景描述：扫描 AWS S3 存储桶（如 my-app-bucket），检测桶内文件（如 CSV、配置文件）中的敏感信息，需先配置 AWS 凭证。

# 步骤 1：配置 AWS 凭证（两种方式任选）
# 方式 1：手动编辑凭证文件
echo -e "[default]\naws_access_key_id = AKIAXXXXXXXXXXXXXX\naws_secret_access_key = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" > ~/.aws/credentials
chmod 600 ~/.aws/credentials

# 方式 2：设置环境变量
export AWS_ACCESS_KEY_ID="AKIAXXXXXXXXXXXXXX"
export AWS_SECRET_ACCESS_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 步骤 2：基础扫描（扫描整个 S3 桶）
trufflehog s3 --bucket=my-app-bucket

# 步骤 3：进阶扫描（指定桶内前缀，限制归档大小）
trufflehog s3 --bucket=my-app-bucket --prefix=prod/config/ --archive-max-size=10MB --only-verified
# 参数解析
# --prefix=prod/config/：仅扫描桶内 prod/config/ 路径下的文件；
# --only-verified：仅输出已验证有效的凭证（如 AWS 密钥可正常调用 API）

# 扫描结果保存到文件
trufflehog s3 --bucket=my-app-bucket -j > s3_scan_results.json

9. 场景 8：集成到 CI/CD 流水线（阻断凭证泄露）

场景描述：在 GitHub Actions 流水线中集成 trufflehog，若代码提交中包含敏感凭证，自动阻断构建流程（需在项目根目录创建 .github/workflows 目录）。

# 步骤 1：创建 GitHub Actions 配置文件（.github/workflows/trufflehog.yml）
cat > .github/workflows/trufflehog.yml << EOF
name: TruffleHog Scan
on: [push, pull_request]  # 推送代码、创建 PR 时触发扫描

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # 拉取所有提交历史（便于完整扫描）
          
      - name: Install TruffleHog
        run: |
          wget https://github.com/trufflesecurity/trufflehog/releases/download/v3.x.x/trufflehog_3.x.x_linux_amd64.tar.gz
          tar -zxvf trufflehog_3.x.x_linux_amd64.tar.gz
          sudo mv trufflehog /usr/local/bin/
          
      - name: Run TruffleHog Scan
        run: trufflehog filesystem . --fail  # --fail 检测到凭证时退出码 183，阻断流水线
EOF

# 步骤 2：提交配置文件到 GitHub
git add .github/workflows/trufflehog.yml
git commit -m "Add TruffleHog CI scan"
git push origin main

# 效果说明
# 当代码提交中包含敏感凭证（如 API 密钥），流水线会失败并显示检测结果；
# 需修复凭证泄露问题（如删除硬编码、使用环境变量）后，重新提交才能通过构建。

四、常见问题与解决方案

常见问题	可能原因	解决方案
"command not found: trufflehog"	1. 工具未安装或安装路径未加入 PATH；2. 二进制文件权限不足	1. 确认安装路径（如 Go 安装路径 GOPATH/bin，二进制安装路径 /usr/local/bin），执行 `export PATH=PATH:$GOPATH/bin；2. 赋予权限：sudo chmod +x /usr/local/bin/trufflehog`
Git 仓库扫描提示"fatal: could not read Username for 'https://github.com': No such device or address"	远程 Git 仓库为私有仓库，需身份验证（未配置凭证或令牌）	1. 使用带凭证的仓库 URL（如 https://username:token@github.com/example/repo.git）；2. 提前执行 git config --global credential.helper store 保存凭证
Docker 镜像扫描提示"permission denied while trying to connect to the Docker daemon socket"	当前用户无 Docker 操作权限	1. 执行 sudo usermod -aG docker $USER 将用户加入 docker 组；2. 重启终端或重新登录，验证：docker ps（无需 sudo 即可执行）
S3 扫描提示"access denied"	1. AWS 凭证无效或权限不足；2. S3 桶策略限制访问	1. 验证凭证有效性（执行 aws s3 ls s3://my-app-bucket 测试）；2. 确保凭证拥有 s3:ListBucket、s3:GetObject 权限；3. 检查 S3 桶策略是否允许当前 IP 访问
扫描结果存在大量误报（如识别普通字符串为凭证）	1. 未启用结果验证（--no-verification 默认关闭）；2. 检测规则过于宽泛	1. 加入 --only-verified 参数，仅保留已验证有效的结果；2. 使用 --exclude-detectors 排除易误报的规则（如 --exclude-detectors="GenericPassword"）
扫描速度极慢（大型 Git 仓库或 S3 桶）	1. 并发数过低；2. 扫描范围过广（如全部分支、深层归档）；3. 网络延迟（远程数据源）	1. 提升并发数（--concurrency=CPU 核心数，如 8 核设为 8）；2. 缩小扫描范围（Git 用 --branch/--depth，S3 用 --prefix，归档用 --archive-max-size）；3. 本地克隆远程仓库后扫描（减少网络依赖）

五、注意事项与安全规范

• 凭证安全处理 ：扫描结果包含敏感凭证，需加密存储（如用 gpg -c results.json 加密），避免结果文件泄露导致二次安全风险；扫描完成后建议及时清理临时凭证（如环境变量、配置文件）。
• 扫描范围控制：避免扫描生产环境核心数据源（如生产 S3 桶、核心 Git 仓库）时影响业务，建议先在测试环境验证扫描规则，再批量应用到生产环境。
• 法律与合规：仅可扫描合法授权的数据源（如企业内部项目、客户签署授权书的第三方仓库），未经授权扫描他人或公共平台的私有数据，涉嫌违反《网络安全法》《数据安全法》，需承担法律责任。
• 工具更新 ：trufflehog 检测规则会定期更新（新增凭证类型、修复误报），建议定期执行 trufflehog --version 检查版本，通过 Go 或二进制方式更新到最新版。
• 自定义规则：若业务中存在特殊格式的凭证（如内部系统 API 密钥），可通过配置文件（--config）自定义检测规则（参考官方文档：https://docs.trufflesecurity.com/trufflehog/configuration），提升检测精准度。