TruffleHog 完整实战指南：从凭据发现到活性验证的密钥泄露扫描方案-平芜编程栈

TruffleHog 完整实战指南：从凭据发现到活性验证的密钥泄露扫描方案

【免费下载链接】trufflehogFind, verify, and analyze leaked credentials项目地址: https://gitcode.com/GitHub_Trending/tr/trufflehog

TruffleHog 是一款面向开发与安全团队的开源密钥（Secrets）扫描工具，核心能力覆盖凭据的**发现（Discovery）、分类（Classification）、验证（Validation）与分析（Analysis）**四个阶段。本文以本仓库 README.md 为主线，结合 pkg/engine、pkg/detectors、pkg/custom_detectors 等源码实现，系统讲解安装、CLI 使用、多来源扫描、结果过滤、CI/CD 集成与自定义正则检测器的完整方案。读完本文，你将能够独立完成 Git 仓库、GitHub 组织、S3/GCS 桶、Docker 镜像、Hugging Face 乃至 Postman/Jenkins/Elasticsearch 等场景的密钥扫描，并理解其底层"Source → Unit → Chunk → Detector"流水线与并发验证机制。

一、TruffleHog 是什么

TruffleHog 是用于密钥发现、分类、验证和分析的工具。这里的"密钥（secret）"指机器之间进行身份认证所使用的凭据，包括 API 密钥、数据库密码、私钥等。自 v3 起，TruffleHog 使用 Go 完整重写，内置超过 700 个（源码中实际 detector 目录已扩充至 800+ 类）支持对各自 API 进行活性验证的凭据检测器，并原生支持扫描 GitHub、GitLab、Docker、文件系统、S3、GCS、CircleCI、TravisCI 等来源。

1.1 四大核心能力

Discovery（发现）：可在 Git、聊天记录、Wiki、日志、API 测试平台、对象存储、文件系统等多种位置寻找密钥。
Classification（分类）：对发现的密钥进行归类，将其映射到具体的身份类型——是 AWS 密钥、Stripe 密钥、Cloudflare 密钥、Postgres 密码还是 SSL 私钥。
Validation（验证）：对每个可分类的密钥，尝试登录对应服务确认其是否"存活（live）"，从而判断是否存在现实的危险。
Analysis（分析）：对约 20 种最常见的泄露凭据类型，不只发送一次请求确认能否登录，而是发起多次请求，了解密钥的完整画像：由谁创建、能访问哪些资源、在这些资源上拥有什么权限（对应 pkg/analyzer 与trufflehog analyze命令）。

1.2 支持的扫描来源

TruffleHog 的每个数据来源对应一个子命令，完整的--help输出（见 README.md）显示支持：

git、github、gitlab、huggingface、docker、s3、filesystem、syslog、circleci、travisci、gcs、postman、jenkins、elasticsearch、stdin、multi-scan，以及实验性的github-experimental（对象发现）、json-enumerator与analyze。每个子命令都可用--help查看其专属选项。

二、安装与产物校验

2.1 多种安装方式

macOS（Homebrew）

brew install trufflehog

Docker（需先确保 Docker 引擎已启动）

Unix：

docker run --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys

Windows 命令提示符：

docker run --rm -it -v "%cd:/=\%:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys

Windows PowerShell：

docker run --rm -it -v "${PWD}:/pwd" trufflesecurity/trufflehog github --repo https://github.com/trufflesecurity/test_keys

M1/M2 Mac（指定 arm64 平台）：

docker run --platform linux/arm64 --rm -it -v "$PWD:/pwd" trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keys

二进制发行版：从官方 releases 页面下载对应平台的压缩包解压即可。

源码编译

git clone https://github.com/trufflesecurity/trufflehog.git cd trufflehog; go install

安装脚本（本仓库 scripts/install.sh）：

# 安装最新版 curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin # 校验 checksum 签名（需要已安装 cosign） curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -v -b /usr/local/bin # 安装指定版本（例如 v3.56.0） curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin v3.56.0

2.2 验证产物签名与哈希

所有产物均附带 checksum 文件，并使用 cosign 对 checksum 文件签名。验证步骤：

从 releases 页面下载产物及三个配套文件：trufflehog_{version}_checksums.txt、trufflehog_{version}_checksums.txt.pem、trufflehog_{version}_checksums.txt.sig。
验证签名：

cosign verify-blob <path to trufflehog_{version}_checksums.txt> \ --certificate <path to trufflehog_{version}_checksums.txt.pem> \ --signature <path to trufflehog_{version}_checksums.txt.sig> \ --certificate-identity-regexp 'https://github\.com/trufflesecurity/trufflehog/\.github/workflows/.+' \ --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

签名确认有效后，校验 SHA256 是否与产物一致：

sha256sum --ignore-missing -c trufflehog_{version}_checksums.txt

将{version}替换为你下载的版本号。若使用安装脚本，加-v参数即可自动执行签名校验（需预先安装 Cosign）。

三、快速开始：19 个典型扫描场景

场景 1：扫描仓库，仅输出已验证密钥

trufflehog git https://github.com/trufflesecurity/test_keys --results=verified

预期输出格式（包含检测器类型、解码器类型、原始值、行号、提交、文件、邮箱、仓库、时间戳）：

🐷🔑🐷 TruffleHog. Unearth your secrets. 🐷🔑🐷 Found verified result 🐷🔑 Detector Type: AWS Decoder Type: PLAIN Raw result: AKIAYVP4CIPPERUVIFXG Line: 4 Commit: fbc14303ffbf8fb1c2c1914e8dda7d0121633aca File: keys Email: counter <counter@counters-MacBook-Air.local> Repository: https://github.com/trufflesecurity/test_keys Timestamp: 2022-06-16 10:17:40 -0700 PDT ...

场景 2-3：扫描 GitHub 组织，排除归档仓库

trufflehog github --org=trufflesecurity --results=verified trufflehog github --org=trufflesecurity --exclude-archived

场景 4：GitHub 仓库扫描并输出 JSON

trufflehog git https://github.com/trufflesecurity/test_keys --results=verified --json

JSON 输出包含 SourceMetadata（提交、文件、邮箱、仓库、时间戳、行号）、SourceID、SourceType、DetectorName、DecoderName、Verified、Raw、Redacted、ExtraData（如 AWS 的 account/arn/user_id）与 StructuredData 字段。

除--json外，还可用--sarif输出 SARIF 格式（SARIF 是 GitHub 原生支持的格式，上传后可让 Code Scanning 在 PR diff 与 Security 页内联展示结果，并在多次扫描间跟踪新增/修复）。注意：SARIF 要求单一 JSON 文档，因此结果会在内存中缓存至扫描结束再统一写出，超大结果集时内存占用会相应增加。

场景 5：扫描仓库及其 Issues 与 PR 评论

trufflehog github --repo=https://github.com/trufflesecurity/test_keys --issue-comments --pr-comments

场景 6-7：S3 桶扫描（高置信度结果 / IAM 角色）

trufflehog s3 --bucket=<bucket name> --results=verified,unknown trufflehog s3 --role-arn=<iam role arn>

场景 8：Docker 中通过 SSH 认证扫描

docker run --rm -v "$HOME/.ssh:/root/.ssh:ro" trufflesecurity/trufflehog:latest git ssh://github.com/trufflesecurity/test_keys

场景 9-10：文件系统与本地 Git 仓库

trufflehog filesystem path/to/file1.txt path/to/file2.txt path/to/dir

先克隆仓库，再从父目录扫描本地仓库：

git clone git@github.com:trufflesecurity/test_keys.git trufflehog git file://test_keys --results=verified,unknown

安全说明：为防止本地扫描时遭遇恶意 git 配置（CVE-2025-41390），TruffleHog 会把本地仓库先克隆到临时目录再扫描，遵循 Git 官方安全实践。可用--clone-path指定克隆目标路径；若仓库可信并希望跳过克隆直接扫描，使用--trust-local-git-config标志。

场景 11：GCS 桶扫描

trufflehog gcs --project-id=<project-ID> --cloud-environment --results=verified

场景 12：Docker 镜像扫描

--image标志可多次使用以扫描多个镜像：

# 远程镜像仓库 trufflehog docker --image trufflesecurity/secrets --results=verified # 本地 Docker daemon trufflehog docker --image docker://new_image:tag --results=verified # tar 打包的镜像文件 trufflehog docker --image file://path_to_image.tar --results=verified

场景 13：CI 流水线扫描

用--since-commit指向合并基线分支（如 main），用--branch指向 PR 分支；该值可从 CI 环境变量动态获取（如 CircleCI 的CIRCLE_BRANCH、Travis 的TRAVIS_PULL_REQUEST_BRANCH）。若目标分支已在工作流中检出，--branch HEAD即可。--fail标志在发现有效凭据时返回退出码 183：

trufflehog git file://. --since-commit main --branch feature-1 --results=verified,unknown --fail

场景 14-16：Postman / Jenkins / Elasticsearch

trufflehog postman --token=<postman api token> --workspace-id=<workspace id> trufflehog jenkins --url https://jenkins.example.com --username admin --password admin

Elasticsearch 支持三种接入方式：

# 本地集群：用户名密码 trufflehog elasticsearch --nodes 192.168.14.3 192.168.14.4 --username truffle --password hog # 本地集群：服务令牌 trufflehog elasticsearch --nodes 192.168.14.3 192.168.14.4 --service-token 'AAEWVaWM...Rva2VuaSDZ' # Elastic Cloud：Cloud ID + API Key trufflehog elasticsearch \ --cloud-id 'search-prod:dXMtY2Vx...YjM1ODNlOWFiZGRlNjI0NA==' \ --api-key 'MlVtVjBZ...ZSYlduYnF1djh3NG5FQQ=='

场景 17：GitHub 跨 Fork 对象引用与已删除提交扫描（alpha）

trufflehog github-experimental --repo https://github.com/<USER>/<REPO>.git --object-discovery

该命令枚举仓库中已删除或隐藏的提交并扫描密钥。除常规输出外，会在新建的$HOME/.trufflehog目录下生成valid_hidden.txt（全部隐藏/已删除提交列表）与invalid.txt（状态跟踪）。加--delete-cached-data可扫描后自动删除这些文件。注意：完整枚举耗时约 20 分钟到数小时（取决于仓库规模），期间有进度条提示；真正的密钥扫描阶段非常快。

场景 18：Hugging Face 扫描

# 扫描单个资源 trufflehog huggingface \ --model <model_id> \ --dataset <dataset_id> \ --space <space_id> \ --bucket <bucket_id> # 扫描组织/用户下的全部资源 trufflehog huggingface --org <orgname> --user <username> # 跳过某类资源或某个具体资源 trufflehog huggingface --org <orgname> --skip-all-models --ignore-datasets <dataset_id> # 扫描讨论与 PR 评论 trufflehog huggingface --model <model_id> --include-discussions --include-prs

场景 19：stdin 管道输入

aws s3 cp s3://example/gzipped/data.gz - | gunzip -c | trufflehog stdin

四、CLI 全局选项详解

以下为trufflehog git --help展示的全局标志（适用于所有子命令）：

选项	说明
`-h, --help`	显示帮助（`--help-long`、`--help-man`查看更多）
`--log-level=0`	日志详细程度 0（info）到 5（trace），`-1`关闭
`--profile`	启用 pprof/fgprof 性能剖析服务（:18066）
`-j, --json`	JSON 格式输出
`--json-legacy`	v3.0 之前的 JSON 格式（仅 git/gitlab/github 来源）
`--github-actions`	GitHub Actions 格式输出
`--sarif`	SARIF 格式输出，用于上传 GitHub Code Scanning
`--concurrency=12`	并发 worker 数量
`--no-verification`	不验证结果
`--results=RESULTS`	输出结果类型：`verified`（API 确认有效）、`unknown`（验证出错）、`unverified`（检出但未验证）、`filtered_unverified`（本会被过滤的未验证结果），默认`verified,unverified,unknown`
`--no-color`	禁用彩色输出
`--allow-verification-overlap`	允许跨检测器对相似凭据重复验证
`--filter-unverified`	同一 chunk 内每个检测器只输出第一条未验证结果
`--filter-entropy=3.0`	用 Shannon 熵过滤未验证结果（建议从 3.0 起步）
`--config=CONFIG`	配置文件路径
`--print-avg-detector-time`	打印每个检测器平均耗时
`--no-update`	不检查更新
`--fail`	发现结果时以退出码 183 退出
`--fail-on-scan-errors`	扫描出错时以非零码退出
`--verifier=VERIFIER`	设置自定义验证端点（可多次）
`--custom-verifiers-only`	仅使用自定义验证端点
`--detector-timeout`	每个 chunk 在每个检测器上的最长耗时（如`30s`）
`--archive-max-size`	扫描的压缩包最大尺寸（字节单位，如`512B`、`2KB`、`4MB`）
`--archive-max-depth`	压缩包最大解压深度
`--archive-timeout`	解压压缩包最长耗时
`--include-detectors="all"`	包含的检测器列表，可用 Protobuf 名称、ID 或范围
`--exclude-detectors`	排除的检测器列表（优先于 include 列表）
`--no-verification-cache`	禁用验证缓存
`--force-skip-binaries`	强制跳过二进制文件
`--force-skip-archives`	强制跳过压缩包
`--skip-additional-refs`	跳过附加引用
`--user-agent-suffix`	追加到 User-Agent 的后缀
`--version`	显示版本号

4.1 退出码语义

0：无错误且未发现结果；
1：发生错误，来源可能未完成扫描；
183：无错误但发现了结果（仅在使用--fail时返回）。

五、配置：自定义正则检测器与多来源扫描

TruffleHog 通过--config标志加载配置文件，支持两类内容：自定义正则检测器（Custom Regex Detector，alpha）——可与任意子命令配合；多来源（sources）配置——仅用于multi-scan子命令。多来源配置的完整格式参见官方 source configuration 文档，此处给出一个 GitHub 来源示例：

sources: - connection: '@type': type.googleapis.com/sources.GitHub repositories: - https://github.com/trufflesecurity/test_keys.git unauthenticated: {} name: example config scan type: SOURCE_TYPE_GITHUB verify: true

multi-scan会并发扫描sources下定义的所有连接。

5.1 S3 IAM 角色扫描

除 IAM 用户外，S3 来源还支持**假定 IAM 角色（AssumeRole）**扫描，避免为每个 AWS 账号硬编码凭据。前提：TruffleHog 初始使用的 IAM 身份需要在各目标角色的信任策略中被授予AssumeRole权限。

# 使用本地凭据或 EC2 实例元数据扫描指定桶 trufflehog s3 --bucket=<bucket-name> # 使用假定角色扫描指定桶 trufflehog s3 --bucket=<bucket-name> --role-arn=<iam-role-arn> # 多个角色可分别传入，TruffleHog 会尝试扫描每个角色在 S3 API 中有权限列出的全部桶 trufflehog s3 --role-arn=<iam-role-arn-1> --role-arn=<iam-role-arn-2>

六、CI/CD 与 Git 钩子集成

6.1 TruffleHog GitHub Action

基础用法（扫描所有 PR 与 push 到 main 的变更提交）：

on: push: branches: - main pull_request: jobs: test: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 with: fetch-depth: 0 - name: Secret Scanning uses: trufflesecurity/trufflehog@main with: extra_args: --results=verified,unknown

浅克隆加速：若该工作流仅用于 TruffleHog 扫描，可用fetch-depth动态计算提交数 +2（多出的 1 个基础提交用于对照变更），显著缩短 checkout 时间：

- shell: bash run: | if [ "${{ github.event_name }}" == "push" ]; then echo "depth=$(($(jq length <<< '${{ toJson(github.event.commits) }}') + 2))" >> $GITHUB_ENV echo "branch=${{ github.ref_name }}" >> $GITHUB_ENV fi if [ "${{ github.event_name }}" == "pull_request" ]; then echo "depth=$((${{ github.event.pull_request.commits }}+2))" >> $GITHUB_ENV echo "branch=${{ github.event.pull_request.head.ref }}" >> $GITHUB_ENV fi - uses: actions/checkout@v3 with: ref: ${{env.branch}} fetch-depth: ${{env.depth}} - uses: trufflesecurity/trufflehog@main with: extra_args: --results=verified,unknown

高级用法：Action 支持path、base（对应--since-commit）、head（对应--branch）、extra_args、version、image（默认ghcr.io/trufflesecurity/trufflehog，可指向镜像仓库镜像）等输入，具体实现在 action.yml 中：它解析BASE/HEAD提交，针对 push、pull_request、workflow_dispatch、schedule 事件自动确定扫描区间，最终通过 Docker 以--fail --no-update --github-actions运行trufflehog git file:///tmp/。仅在默认行为不满足特定需求时，才建议手动指定base/head。扫描整个分支时可将base置空、head指向${{ github.ref_name }}。

上传到 GitHub Code Scanning：

- name: TruffleHog run: trufflehog filesystem . --sarif --no-verification > results.sarif - name: Upload SARIF results uses: github/codeql-action/upload-sarif@v3 with: sarif_file: results.sarif

蜜罐检测：TruffleHog 可静态检测 canarytokens.org 生成的蜜罐令牌。

6.2 GitLab CI 示例

以下流水线扫描仓库全部目录与文件，仅在 MR 事件时触发（允许失败设为 false）：

stages: - security security-secrets: stage: security allow_failure: false image: alpine:latest variables: SCAN_PATH: "." # 设置要扫描的仓库相对路径 before_script: - apk add --no-cache git curl jq - curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin script: - trufflehog filesystem "$SCAN_PATH" --results=verified,unknown --fail --json | jq rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

6.3 Pre-commit 钩子（三道防线）

TruffleHog 可作为 pre-commit 钩子在凭据离开本机前将其拦截，支持 Git 原生 hooksPath、pre-commit 框架与 Husky 三种方式，完整步骤见 PreCommit.md。

方式一：Git 全局 hooksPath——设置一次，全部仓库生效：

mkdir -p ~/.git-hooks touch ~/.git-hooks/pre-commit chmod +x ~/.git-hooks/pre-commit git config --global core.hooksPath ~/.git-hooks

钩子脚本（推荐自动配置，TruffleHog 检测到TRUFFLEHOG_PRE_COMMIT=1会自动应用最优 pre-commit 参数）：

#!/bin/sh export TRUFFLEHOG_PRE_COMMIT=1 trufflehog git file://.

需要自定义行为时可手动配置（此时不要设置TRUFFLEHOG_PRE_COMMIT）：

#!/bin/sh trufflehog git file://. --since-commit HEAD --results=verified,unknown --fail --trust-local-git-config

Docker 方式：

#!/bin/sh docker run --rm \ -v "$(pwd):/workdir" \ -e "TRUFFLEHOG_PRE_COMMIT=1" \ trufflesecurity/trufflehog:latest \ git file:///workdir

方式二：pre-commit 框架（语言无关，.pre-commit-config.yaml）：

repos: - repo: local hooks: - id: trufflehog name: TruffleHog description: Detect secrets in your data. entry: bash -c 'trufflehog git file://.' language: system stages: ["pre-commit", "pre-push"]

框架环境下 TruffleHog 也会自动识别并应用最优设置；如未自动识别，可在 entry 中手动加上--since-commit HEAD --results=verified,unknown --fail --trust-local-git-config。随后执行pre-commit install安装钩子。

方式三：Husky（JavaScript/Node 项目）：

npm install husky --save-dev # 或 yarn add husky --dev npx husky init echo "trufflehog git file://." > .husky/pre-commit

Docker 用户替换为：

echo 'docker run --rm -v "$(pwd):/workdir" -i --rm trufflesecurity/trufflehog:latest git file:///workdir' > .husky/pre-commit

最佳实践与排障：

将git add与git commit分开执行，避免git commit -am绕过钩子漏扫未暂存修改；
紧急跳过钩子：git commit --no-verify -m "Your commit message"；
审计模式：不加--fail（钩子恒通过）并丢弃 stderr，只观察输出。本地二进制：trufflehog git file://. --since-commit HEAD --results=verified,unknown 2>/dev/null；Docker 同理替换命令。pre-commit 框架用户审计时需加verbose: true，否则钩子通过时看不到任何密钥；
钩子不执行：检查chmod +x .git/hooks/pre-commit、git config --get core.hooksPath；
误报处理：用--results=verified只显示已验证密钥，或在已知误报行添加trufflehog:ignore注释。

七、自定义正则检测器（alpha）

TruffleHog 支持自定义正则的检测与验证。检测至少需要一个正则表达式与一个关键字（keyword）——关键字是出现在待匹配文本中或附近的固定字面量标识。验证则通过 webhook 完成：TruffleHog 将正则匹配结果以 JSON POST 发送到配置的端点，端点返回200 OK即视为已验证；验证因网络/API 错误失败则标记为 unknown。

由于verify段可选，Custom Detector 也可以不配 webhook，仅用于标记通用硬编码密钥（如*.password=、*.secret=）——这类出现在.properties、.env、.yaml配置中的密钥，内置的"已验证型"检测器往往不会命中。注意：该功能处于 alpha 阶段，接口可能变化。

完整配置语法与验证服务器示例见 pkg/custom_detectors/CUSTOM_DETECTORS.md，仓库内置三个可直接参考的示例：基础版 examples/generic.yml、面向配置文件的 examples/generic_config_secrets.yml、带过滤器的 examples/generic_with_filters.yml。

7.1 基础模板与运行方式

# config.yaml detectors: - name: HogTokenDetector keywords: - hog regex: token: '[^A-Za-z0-9+\/]{0,1}([A-Za-z0-9+\/]{40})[^A-Za-z0-9+\/]{0,1}' verify: - endpoint: http://localhost:8000/ # 'unsafe' 必须设为 true（端点使用 HTTP 时） unsafe: true headers: - "Authorization: super secret authorization header"

字段说明：

name：检测器唯一标识；
keywords：字符串数组，任一关键字出现即触发正则搜索；
regex：一个或多个命名正则，每个命名正则都必须匹配到才算检测成功；正则中的捕获组()用于提取具体片段并上报；
verify：可选。配置后才会对检出密钥执行验证，未配置则全部标记为 unverified：
- successRanges：表示密钥"存活"的 HTTP 状态码/区间（如"200"或"200-202"），命中则标记 verified；该字段与rotatedRanges均省略时，仅200视为已验证（向后兼容）；
- rotatedRanges：表示密钥"已轮换失效"的状态码/区间，命中则明确标记 unverified；
- 只配置其中一个时，未命中视为相反状态；两者都配置但都不命中时，视为 unknown/inconclusive。

例如200表示密钥存活需轮换，401/403表示已轮换失效，其它响应视为不确定：

verify: - endpoint: http://localhost:8000/ unsafe: true headers: - "Authorization: super secret authorization header" successRanges: - "200" rotatedRanges: - "401" - "403"

运行方式：

trufflehog filesystem <path_to_folder_or_file> --config=<path_to_file>/config.yaml

7.2 过滤与校验参数

primary_regex_name：多正则时指定主正则（用于确定行号），必须是 regex 段中已声明的名称；未指定时默认取按排序后的第一个正则名；
exclude_regexes_capture：从检出密钥中排除命中该正则的片段；
exclude_regexes_match：对整个匹配串（而非仅令牌）应用排除，命中则整条不上报；
entropy：对检出串计算 Shannon 熵并过滤低随机性字符串，阈值 3 可作起点，需按项目数据特点调整；
exclude_words：检出串（有捕获组时取捕获组，无则取整个匹配）包含列表中的词则忽略，子串匹配、不强制词边界；
validations：针对每个命名正则的附加规则，用于弥补 Go RE2 引擎不支持 lookahead 的缺陷，降低误报。可用项：contains_digit（含数字）、contains_lowercase（含小写）、contains_uppercase（含大写）、contains_special_char（含!@#$%^&*()_+-=[]{}|;:,.<>?中任一特殊字符）。

以 examples/generic_config_secrets.yml 为例，它针对.env类配置文件：entropy: 2.5过滤低熵值；exclude_regexes_capture排除${...}、{{...}}、%XXX%、$VAR及process.env.、os.environ、getenv(、vault://、kms://等环境变量/密钥管理引用；exclude_words排除changeme、placeholder、dummy、redacted、null、false等占位值。examples/generic_with_filters.yml 则展示了validations（如contains_digit、contains_special_char）、exclude_regexes_match（排除access_key、key_id、endpoint、public_token等常见非密钥字段）与大型exclude_words词表组合使用的完整形态。

7.3 验证服务器参考实现

仓库给出了 Python 与 Go 两版验证服务器（均监听:8000，校验 Authorization 头后解析请求体中HogTokenDetector.token字段并返回 200/403）。Go 版核心结构：

type RequestBody struct { HogTokenDetector HogTokenDetector `json:"HogTokenDetector"` }

webhook 收到的 JSON 顶层键即检测器name，其下为各命名正则的匹配值——自定义验证服务需按此格式解析。

八、通用 JWT 检测

TruffleHog 支持对找到的部分通用 JWT 进行检测与验证：当 JWT 使用公钥密码学（而非 HMAC）且能够获取公钥时，即可判断该 JWT 是否仍处于存活状态。

九、Analyze：凭据深层分析

trufflehog analyze命令可对凭据做更深入的分析，查看其权限与可访问的资源（实现位于 pkg/analyzer）：

trufflehog analyze

十、底层原理：扫描数据流与并发模型

10.1 四级数据流管线

pkg/engine 将扫描组织为清晰的四级流水线（详见 docs/process_flow.md）：

Source Decomposition（来源分解）：Source 是"我们要在其中寻找密钥的顶层位置"（Git、GitHub、Filesystem、Postman 等）；Unit 是 Source 的自然细分但规模仍较大（目录、Git 仓库）；Chunk 是最小分解单元并进入检测阶段（文件内容、git log -p的 diff hunks、数据块）。例如 git/github Source 本地克隆后经git log -p产出 diff hunk chunk，filesystem Source 直接产出文件内容 chunk，而 Postman 等多数来源不使用 Unit 直接产出 chunk。
Chunk to Detector Matching（chunk 到检测器的匹配）：基于Aho-Corasick 算法的关键字匹配（见 pkg/engine/ahocorasick），依据 chunk 中是否出现特定关键字，将 chunk 匹配到对应检测器。
Secret Detection（密钥检测）：检测器真正检查 chunk 中是否存在密钥并（可选）验证：
- De-Dupe-Detectors：多个检测器关键字同时命中同一 chunk 时，逻辑上裁定由哪个检测器执行验证，避免对外部 API 的重复验证请求（对应并发图中的 VerificationOverlapWorkers）；
- Collect Matches：对匹配的 chunk 运行检测器专属正则，产出 unverified 密钥；
- Verify Matches：可选步骤，通过尝试调用真实服务验证观测到的密钥。
Result Notification（结果通知）：已验证或未验证的结果发送到 Dispatcher，再分发到输出目标（通常是命令行）。

10.2 并发 worker 模型

docs/concurrency.md 用序列图描述了引擎的四类 worker（对应 pkg/engine/engine.go 中startWorkers的实现）：

ScannerWorkers：负责枚举与切分来源（startScannerWorkers），产出 chunk 后先解码并做关键字匹配，随后通过e.detectableChunksChan投递给 DetectorWorkers；当同一 chunk 命中多个检测器时，通过e.verificationOverlapChunksChan投递给 VerificationOverlapWorkers；
VerificationOverlapWorkers：裁决对重叠命中 chunk 执行哪些检测器，再转入 detectableChunksChan；
DetectorWorkers：运行检测（发现密钥）、可选验证、过滤与富化，结果经e.results通道送交 NotifierWorkers（startDetectorWorkers）；
NotifierWorkers：将结果写出（数量约为 scanner worker 的 1/4，见 engine.go 中startNotifierWorkers的注释）。

通道缓冲按defaultChannelBuffer的倍数分配：detectableChunksChanMultiplier = 50、verificationOverlapChunksChanMultiplier = 25、results 通道与前者相同，以在高并发下容纳多组 worker 的生产速率而不互相阻塞。全局--concurrency标志（默认 12）即控制这些 worker 的数量。

10.3 验证的实现机制：以 AWS 为例

"验证"的关键在于对每个检测器都实现了针对其所属 API 的程序化校验。以 AWS 检测器为例，pkg/detectors/aws 中的实现会对 AWS API 发起GetCallerIdentity调用以确认 AWS 凭据是否有效（pkg/detectors/aws/access_keys/accesskey.go），从响应中解析Account、Arn、UserId（pkg/detectors/aws/common.go），这些信息最终成为输出 JSON 中的ExtraData。这也解释了快速开始场景 4 的 JSON 输出中为何会带有account、arn、user_id字段。

10.4 三类结果状态

验证消除误报并提供三种状态：

verified：通过 API 测试确认凭据有效且活跃；
unverified：已检出但未确认有效（可能无效、过期或验证被禁用）；
unknown：尝试验证但因网络或 API 错误失败。

FAQ 中对此有补充说明：报告"私有密钥已验证"意味着 TruffleHog 已通过真实服务（如 SSH/SSL 认证）确认该密钥可用；GitHub 组织扫描缓慢通常是未认证扫描的速率限制所致，可用--token传入个人访问令牌改善；只看到启动横幅即退出表示未发现任何密钥；对支持行号的来源，可在含密钥的行添加trufflehog:ignore注释以忽略该条结果（逻辑位于 pkg/engine/engine.go 的 chunk 解析处）。

十一、使用边界与注意事项

本仓库--help输出、README 中的退出码、场景命令均以当前仓库版本为准，不同版本参数可能存在差异；
github-experimental --object-discovery与 Custom Regex Detector 均标记为 alpha/实验特性；
本地 git 扫描默认先克隆到临时目录（可--clone-path指定路径，可信仓库可用--trust-local-git-config跳过）；
SARIF 输出会整体缓存于内存，超大结果集会显著增加内存占用；
库（Library）形式使用方面，README 明确声明当前 API 仍处于快速迭代期，不保证稳定性；
v3.0 起项目采用 AGPL-3.0 许可（见 LICENSE），不再接受 v2 的贡献，但 v2 代码保留在仓库v2分支。

对于希望扩展检测能力的开发者，仓库提供了新增检测器的外部指南 hack/docs/Adding_Detectors_external.md 与内部指南 hack/docs/Adding_Detectors_Internal.md，可按需参考。

【免费下载链接】trufflehogFind, verify, and analyze leaked credentials项目地址: https://gitcode.com/GitHub_Trending/tr/trufflehog

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考