TruffleHog 完整实战指南从凭据发现到活性验证的密钥泄露扫描方案【免费下载链接】trufflehogFind, verify, and analyze leaked credentials项目地址: https://gitcode.com/GitHub_Trending/tr/trufflehogTruffleHog 是一款面向开发与安全团队的开源密钥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 多种安装方式macOSHomebrewbrew install trufflehogDocker需先确保 Docker 引擎已启动Unixdocker run --rm -it -v $PWD:/pwd trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keysWindows 命令提示符docker run --rm -it -v %cd:/\%:/pwd trufflesecurity/trufflehog:latest github --repo https://github.com/trufflesecurity/test_keysWindows PowerShelldocker run --rm -it -v ${PWD}:/pwd trufflesecurity/trufflehog github --repo https://github.com/trufflesecurity/test_keysM1/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.02.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 --resultsverified预期输出格式包含检测器类型、解码器类型、原始值、行号、提交、文件、邮箱、仓库、时间戳 TruffleHog. Unearth your secrets. Found verified result Detector Type: AWS Decoder Type: PLAIN Raw result: AKIAYVP4CIPPERUVIFXG Line: 4 Commit: fbc14303ffbf8fb1c2c1914e8dda7d0121633aca File: keys Email: counter countercounters-MacBook-Air.local Repository: https://github.com/trufflesecurity/test_keys Timestamp: 2022-06-16 10:17:40 -0700 PDT ...场景 2-3扫描 GitHub 组织排除归档仓库trufflehog github --orgtrufflesecurity --resultsverified trufflehog github --orgtrufflesecurity --exclude-archived场景 4GitHub 仓库扫描并输出 JSONtrufflehog git https://github.com/trufflesecurity/test_keys --resultsverified --jsonJSON 输出包含 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 --repohttps://github.com/trufflesecurity/test_keys --issue-comments --pr-comments场景 6-7S3 桶扫描高置信度结果 / IAM 角色trufflehog s3 --bucketbucket name --resultsverified,unknown trufflehog s3 --role-arniam role arn场景 8Docker 中通过 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 gitgithub.com:trufflesecurity/test_keys.git trufflehog git file://test_keys --resultsverified,unknown安全说明为防止本地扫描时遭遇恶意 git 配置CVE-2025-41390TruffleHog 会把本地仓库先克隆到临时目录再扫描遵循 Git 官方安全实践。可用--clone-path指定克隆目标路径若仓库可信并希望跳过克隆直接扫描使用--trust-local-git-config标志。场景 11GCS 桶扫描trufflehog gcs --project-idproject-ID --cloud-environment --resultsverified场景 12Docker 镜像扫描--image标志可多次使用以扫描多个镜像# 远程镜像仓库 trufflehog docker --image trufflesecurity/secrets --resultsverified # 本地 Docker daemon trufflehog docker --image docker://new_image:tag --resultsverified # tar 打包的镜像文件 trufflehog docker --image file://path_to_image.tar --resultsverified场景 13CI 流水线扫描用--since-commit指向合并基线分支如 main用--branch指向 PR 分支该值可从 CI 环境变量动态获取如 CircleCI 的CIRCLE_BRANCH、Travis 的TRAVIS_PULL_REQUEST_BRANCH。若目标分支已在工作流中检出--branch HEAD即可。--fail标志在发现有效凭据时返回退出码 183trufflehog git file://. --since-commit main --branch feature-1 --resultsverified,unknown --fail场景 14-16Postman / Jenkins / Elasticsearchtrufflehog postman --tokenpostman api token --workspace-idworkspace id trufflehog jenkins --url https://jenkins.example.com --username admin --password adminElasticsearch 支持三种接入方式# 本地集群用户名密码 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 CloudCloud ID API Key trufflehog elasticsearch \ --cloud-id search-prod:dXMtY2Vx...YjM1ODNlOWFiZGRlNjI0NA \ --api-key MlVtVjBZ...ZSYlduYnF1djh3NG5FQQ场景 17GitHub 跨 Fork 对象引用与已删除提交扫描alphatrufflehog github-experimental --repo https://github.com/USER/REPO.git --object-discovery该命令枚举仓库中已删除或隐藏的提交并扫描密钥。除常规输出外会在新建的$HOME/.trufflehog目录下生成valid_hidden.txt全部隐藏/已删除提交列表与invalid.txt状态跟踪。加--delete-cached-data可扫描后自动删除这些文件。注意完整枚举耗时约 20 分钟到数小时取决于仓库规模期间有进度条提示真正的密钥扫描阶段非常快。场景 18Hugging 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场景 19stdin 管道输入aws s3 cp s3://example/gzipped/data.gz - | gunzip -c | trufflehog stdin四、CLI 全局选项详解以下为trufflehog git --help展示的全局标志适用于所有子命令选项说明-h, --help显示帮助--help-long、--help-man查看更多--log-level0日志详细程度 0info到 5trace-1关闭--profile启用 pprof/fgprof 性能剖析服务:18066-j, --jsonJSON 格式输出--json-legacyv3.0 之前的 JSON 格式仅 git/gitlab/github 来源--github-actionsGitHub Actions 格式输出--sarifSARIF 格式输出用于上传 GitHub Code Scanning--concurrency12并发 worker 数量--no-verification不验证结果--resultsRESULTS输出结果类型verifiedAPI 确认有效、unknown验证出错、unverified检出但未验证、filtered_unverified本会被过滤的未验证结果默认verified,unverified,unknown--no-color禁用彩色输出--allow-verification-overlap允许跨检测器对相似凭据重复验证--filter-unverified同一 chunk 内每个检测器只输出第一条未验证结果--filter-entropy3.0用 Shannon 熵过滤未验证结果建议从 3.0 起步--configCONFIG配置文件路径--print-avg-detector-time打印每个检测器平均耗时--no-update不检查更新--fail发现结果时以退出码 183 退出--fail-on-scan-errors扫描出错时以非零码退出--verifierVERIFIER设置自定义验证端点可多次--custom-verifiers-only仅使用自定义验证端点--detector-timeout每个 chunk 在每个检测器上的最长耗时如30s--archive-max-size扫描的压缩包最大尺寸字节单位如512B、2KB、4MB--archive-max-depth压缩包最大解压深度--archive-timeout解压压缩包最长耗时--include-detectorsall包含的检测器列表可用 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 Detectoralpha——可与任意子命令配合多来源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: truemulti-scan会并发扫描sources下定义的所有连接。5.1 S3 IAM 角色扫描除 IAM 用户外S3 来源还支持**假定 IAM 角色AssumeRole**扫描避免为每个 AWS 账号硬编码凭据。前提TruffleHog 初始使用的 IAM 身份需要在各目标角色的信任策略中被授予AssumeRole权限。# 使用本地凭据或 EC2 实例元数据扫描指定桶 trufflehog s3 --bucketbucket-name # 使用假定角色扫描指定桶 trufflehog s3 --bucketbucket-name --role-arniam-role-arn # 多个角色可分别传入TruffleHog 会尝试扫描每个角色在 S3 API 中有权限列出的全部桶 trufflehog s3 --role-arniam-role-arn-1 --role-arniam-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/checkoutv4 with: fetch-depth: 0 - name: Secret Scanning uses: trufflesecurity/trufflehogmain with: extra_args: --resultsverified,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/checkoutv3 with: ref: ${{env.branch}} fetch-depth: ${{env.depth}} - uses: trufflesecurity/trufflehogmain with: extra_args: --resultsverified,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-sarifv3 with: sarif_file: results.sarif蜜罐检测TruffleHog 可静态检测 canarytokens.org 生成的蜜罐令牌。6.2 GitLab CI 示例以下流水线扫描仓库全部目录与文件仅在 MR 事件时触发允许失败设为 falsestages: - 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 --resultsverified,unknown --fail --json | jq rules: - if: $CI_PIPELINE_SOURCE merge_request_event6.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_COMMIT1会自动应用最优 pre-commit 参数#!/bin/sh export TRUFFLEHOG_PRE_COMMIT1 trufflehog git file://.需要自定义行为时可手动配置此时不要设置TRUFFLEHOG_PRE_COMMIT#!/bin/sh trufflehog git file://. --since-commit HEAD --resultsverified,unknown --fail --trust-local-git-configDocker 方式#!/bin/sh docker run --rm \ -v $(pwd):/workdir \ -e TRUFFLEHOG_PRE_COMMIT1 \ trufflesecurity/trufflehog:latest \ git file:///workdir方式二pre-commit 框架语言无关.pre-commit-config.yamlrepos: - 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 --resultsverified,unknown --fail --trust-local-git-config。随后执行pre-commit install安装钩子。方式三HuskyJavaScript/Node 项目npm install husky --save-dev # 或 yarn add husky --dev npx husky init echo trufflehog git file://. .husky/pre-commitDocker 用户替换为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 --resultsverified,unknown 2/dev/nullDocker 同理替换命令。pre-commit 框架用户审计时需加verbose: true否则钩子通过时看不到任何密钥钩子不执行检查chmod x .git/hooks/pre-commit、git config --get core.hooksPath误报处理用--resultsverified只显示已验证密钥或在已知误报行添加trufflehog:ignore注释。七、自定义正则检测器alphaTruffleHog 支持自定义正则的检测与验证。检测至少需要一个正则表达式与一个关键字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可选。配置后才会对检出密钥执行验证未配置则全部标记为 unverifiedsuccessRanges表示密钥存活的 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 --configpath_to_file/config.yaml7.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/analyzertrufflehog analyze十、底层原理扫描数据流与并发模型10.1 四级数据流管线pkg/engine 将扫描组织为清晰的四级流水线详见 docs/process_flow.mdSource Decomposition来源分解Source 是我们要在其中寻找密钥的顶层位置Git、GitHub、Filesystem、Postman 等Unit 是 Source 的自然细分但规模仍较大目录、Git 仓库Chunk 是最小分解单元并进入检测阶段文件内容、git log -p的 diff hunks、数据块。例如 git/github Source 本地克隆后经git log -p产出 diff hunk chunkfilesystem Source 直接产出文件内容 chunk而 Postman 等多数来源不使用 Unit 直接产出 chunk。Chunk to Detector Matchingchunk 到检测器的匹配基于Aho-Corasick 算法的关键字匹配见 pkg/engine/ahocorasick依据 chunk 中是否出现特定关键字将 chunk 匹配到对应检测器。Secret Detection密钥检测检测器真正检查 chunk 中是否存在密钥并可选验证De-Dupe-Detectors多个检测器关键字同时命中同一 chunk 时逻辑上裁定由哪个检测器执行验证避免对外部 API 的重复验证请求对应并发图中的 VerificationOverlapWorkersCollect 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投递给 VerificationOverlapWorkersVerificationOverlapWorkers裁决对重叠命中 chunk 执行哪些检测器再转入 detectableChunksChanDetectorWorkers运行检测发现密钥、可选验证、过滤与富化结果经e.results通道送交 NotifierWorkersstartDetectorWorkersNotifierWorkers将结果写出数量约为 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、UserIdpkg/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），仅供参考