TruffleHog 外部 Secret Detector 开发全指南从 DetectorType 枚举到验证测试的完整实战【免费下载链接】trufflehogFind, verify, and analyze leaked credentials项目地址: https://gitcode.com/GitHub_Trending/tr/trufflehog本指南完整讲解如何在 TruffleHog 中开发一个自定义 Secret Detector秘密探测器涵盖选择开发对象的标准、核心Detector接口职责、从零创建与代码生成、使用.env驱动五类测试用例、SecretParts结构化填充规范以及验证结果确定性判定等全部环节。读完本文你将能够独立完成一个通过单元测试与集成测试、可合入上游 PR 的高信噪比 Secret Detector。1. Secret Detector 的两大核心职责Secret Detector在代码中也常写作 Scanner是 TruffleHog 检出凭证的基本单元。根据 hack/docs/Adding_Detectors_external.md 的定义它承担两个主要功能从字节数据中提取疑似密钥——通常通过正则表达式regex完成向目标 API 验证密钥是否真实有效——通常通过 HTTP 客户端完成。其设计目标是以异常高的信噪比发现密钥误报率false positives不被接受。因此提取正则必须足够精确验证逻辑必须依赖真实 API 而非猜测。从源码看每个 Detector 需要实现 pkg/detectors/detectors.go 中定义的Detector接口type Detector interface { // FromData 扫描字节并可选地验证结果可被多个 goroutine 并发调用 FromData(ctx context.Context, verify bool, data []byte) ([]Result, error) // Keywords 用于对数据块做子串级预过滤应优先使用密钥中的唯一标识或提供商名 Keywords() []string // Type 返回 detector_type.proto 中定义的 DetectorType 枚举值 Type() detector_typepb.DetectorType // Description 返回该结果检测项的说明文字 Description() string }其中Keywords()非常关键TruffleHog 引擎会基于 Aho-Corasick 算法用关键词对海量数据块做预过滤只有命中关键词的块才会进入正则匹配从而大幅降低整体开销可参见 pkg/detectors/alchemy/alchemy_test.go 中ahocorasick.NewAhoCorasickCore的用法。当提供多个关键词时它们是并集关系——任一关键词出现即触发检测。2. 开发前的选型与准备2.1 Sourcing Guidelines什么服务值得接入为了控制维护成本与误报率TruffleHog 只对满足至少一项以下条件的服务开发 Detector托管数据该服务会存储用户提供的任何形式的数据提供付费服务拥有免费或试用层级也可以接受。如果认为某个服务应突破以上边界纳入需要主动与维护者沟通说明。这条原则确保了每个新增 Detector 都有真实的使用场景与用户基础。2.2 Development Guidelines开发规范在合理的前提下优先使用标准库net/http发起请求避免引入额外的 HTTP 依赖库尽可能使用common.SaneHttpClient作为http.Client。SaneHttpClient在 pkg/common/http.go 中实现它设置了 5 秒的DefaultResponseTimeout通过saneTransport约束连接、TLS 握手、空闲连接等超时参数并用NewInstrumentedTransport自动埋点 HTTP 指标请求数、延迟、响应体大小、非 200 状态码等方便 TruffleHog 观测各 Detector 的验证请求行为。测试中需要更短超时时可以用SaneHttpClientTimeOut(timeout)或ConstantResponseHttpClient(statusCode, body)模拟固定响应。2.3 Development Dependencies环境依赖Go 1.17项目基于现代 Go 编写当前仓库使用go.mod管理依赖Make用于执行make protos、make test等构建脚本见 Makefile。3. 为既有 Scanner 添加新 Token 格式Versioner 模式有些服务会更新自身的 Token 格式。此时在不新增 Detector的前提下可以通过实现Versioner接口来同时兼容新旧格式。接口定义在 pkg/detectors/detectors.go// Versioner 是可选的接口用于区分同一 DetectorType 的不同实例版本 type Versioner interface { Version() int }具体操作步骤创建v1与v2两个目录将既有 Detector 及其测试移入v1新增文件放在v2。例如packagename/old_files→packagename/v1/old_files、packagename/v2/new_files。注意务必同步更新测试中对 GSMGoogle Secret Manager里新密钥值的引用否则测试会失败。实现Versioner接口。仓库中的真实范例是 pkg/detectors/github/v1/github_old.goVersion()返回 1与 pkg/detectors/github/v2/github.goVersion()返回 2并额外实现了EndpointCustomizer、CloudProvider等可选接口。在既有与新版本 Detector 的ExtraData中均加入version字段用于标记结果来自哪个版本。在 pkg/engine/defaults/defaults.go 的 DefaultDetectors 中更新既有 Detector 的注册新增 v2 的 Scanner 条目。从创建新 Secret Detector的第 3 步代码生成继续往下走。4. 从零创建全新 Secret Detector 的完整步骤4.1 添加 DetectorType 枚举并重新生成 Protobuf在 proto/detector_type.proto 的DetectorType枚举列表中追加新枚举项例如SampleAPI。运行make protos重新生成对应的.pb文件pkg/pb/detector_typepb等。该命令由 scripts/gen_proto.sh 驱动内部依赖 Docker 容器执行 protoc 编译。4.2 用脚手架命令生成 Detector 骨架TruffleHog 提供代码生成器 hack/generate/generate.go它会以现有 alchemy 探测器的三个文件为模板做大小写与命名的占位替换生成你需要的初始文件go run hack/generate/generate.go detector DetectorType enum name # 例如 go run hack/generate/generate.go detector SampleAPI执行后会在pkg/detectors/detector_name/下生成三个文件detector_name.go——主实现模板来源 pkg/detectors/alchemy/alchemy.godetector_name_test.go——纯模式匹配的单测模板来源 pkg/detectors/alchemy/alchemy_test.godetector_name_integration_test.go——带//go:build detectors构建标签的集成测试模板来源 pkg/detectors/alchemy/alchemy_integration_test.go覆盖全部 5 类验证场景。4.3 注册到 DefaultDetectors将新 Detector 以import github.com/trufflesecurity/trufflehog/v3/pkg/detectors/detector_name的方式引入并在 pkg/engine/defaults/defaults.go 的 DefaultDetectors 切片中追加detector_name.Scanner{}。只有注册后默认扫描模式才会加载它。4.4 补全 Detector 实现脚手架生成的是可编译的样板 示例代码完成一个合格的 Detector 通常需要更新模式正则与关键词。可以在迭代时借助 regex101 等工具打磨表达式注意用\b等边界符包裹捕获组以降低误报。可参考 pkg/detectors/alchemy/alchemy.go正则使用detectors.PrefixRegex([]string{alchemy})该工具函数在 pkg/detectors/detectors.go保证关键词出现在捕获组前 40 个字符以内关键词列表返回{alchemy, alcht_}。更新验证器代码调用一个非破坏性的 API来判断密钥是否有效详见第 6 节验证不确定性。在每个Result上填充SecretParts详见第 7 节。为 Detector 编写测试详见第 5 节。再次确认已在 pkg/engine/defaults/defaults.go 注册。提交 Pull Request 供评审。4.5 FromData 的典型实现形态以 alchemy 为例pkg/detectors/alchemy/alchemy.go核心流程是把字节转字符串 → 用正则提取并去重→ 为每个匹配构造detectors.Result→ 若verify为真则调用验证函数写入Verified、ExtraData与验证错误。Tailscale 的验证器pkg/detectors/tailscale/tailscale.go则展示了另一种常见模式204 No Content视为验证成功、401视为确定性失败、其余状态码视为不确定性失败并SetVerificationError。5. 测试 Detector.env驱动五类用例为保证 PR 质量测试必须基于已核实的真实凭证运行。5.1 准备.env文件在新建 Detector 的目录下创建.env格式如下SECRET_TYPE_ONEvalue SECRET_TYPE_ONE_INACTIVEvlue其中_INACTIVE后缀的密钥应满足正则但不通过验证例如把密钥字符做一点改写使验证返回 401/403。目录结构如下├── tailscale │ ├── .env │ ├── tailscale.go │ └── tailscale_test.go5.2 导出环境变量export TEST_SECRET_FILE.env设置后测试代码即可从本地加载密钥。其机制见 pkg/common/secrets.goGetSecret会优先读取TEST_SECRET_FILE指向的 env 文件GetSecretFromEnv使用 godotenv 解析若未设置该变量则回退到从 GCP Secret Manager项目trufflehog-testing拉取测试密钥。这意味着本地开发时无需 GCP 权限即可跑集成测试。5.3 生成器自带的五类测试用例go run hack/generate/generate.go生成的集成测试文件已经覆盖以下 5 种情况对照 pkg/detectors/alchemy/alchemy_integration_test.go 逐条对应Found and verified使用.env中有效密钥验证成功Verified true、无验证错误Found and unverified确定性失败使用_INACTIVE密钥验证确定性失败Verified false、无验证错误Found and unverified因超时导致的不确定性失败注入一个超短超时的 client如common.SaneHttpClientTimeOut(1 * time.Microsecond)Verified false且存在验证错误Found and unverified因意外的 API 响应导致不确定性失败注入common.ConstantResponseHttpClient(404, )模拟意外响应Verified false且存在验证错误Not found输入不含任何密钥的文本期望返回空结果。生成器生成的测试质量较高多数情况下无需大改如不确定可参考覆盖全部 5 类用例的范本 pkg/detectors/browserstack/browserstack_test.go。断言时会用cmpopts.IgnoreFields忽略Raw与verificationError等易变字段见 pkg/detectors/alchemy/alchemy_integration_test.go。5.4 运行测试go test ./pkg/detectors/detector -tagsdetectors-tagsdetectors用于启用带//go:build detectors构建标签的集成测试文件不加该标签则只运行纯模式匹配的单测。测试全部通过后即可放心提交 PR。6. 验证不确定性Verification Indeterminacy如何正确区分两类失败密钥验证失败可能源于两种截然不同的原因候选字符串并非真实有效的密钥密钥本身无效验证过程中发生了与候选密钥无关的故障例如瞬时网络错误、请求超时、或 API 返回了非预期响应。在 TruffleHog 的术语中前者称为determinate确定性失败后者称为indeterminate不确定性失败。验证代码必须通过是否在结果结构中返回 error 对象来区分二者只有在不确定性失败时才返回 error凡是未被明确识别为确定性失败的状态都应返回 error 表示不确定性失败。一个典型范例假设某认证端点对有效凭证返回200 OK、对无效凭证返回403 Forbidden。验证器应如此决策响应码判定行为200或任意2xx验证成功Verified true403验证确定性失败Verified false不返回 error其他任意响应验证不确定性失败Verified false返回 errordetectors.Result中验证错误的设置入口是SetVerificationError(err, secrets...)见 pkg/detectors/detectors.go它会将错误消息中出现的敏感值替换为[REDACTED]后再存储避免在日志中泄露凭证。alchemy 的验证器pkg/detectors/alchemy/alchemy.go正是这一模式的完整实现200成功、401确定性失败、其余状态码fmt.Errorf(unexpected HTTP response status %d, ...)作为不确定性失败返回。7. Populating SecretParts结构化填充凭证组件SecretParts是 Detector 输出凭证组件的结构化事实来源。它定义在 pkg/detectors/detectors.go类型为map[string]string挂在detectors.Result上用描述性 key 存储凭证的每一部分。下游消费者——analyzers见 pkg/analyzer/analyzers、Secret Storage、以及未来工作Raw/RawV2映射层与去重哈希——都依赖它。硬性要求Detector 输出的每个Result都必须填充SecretParts无论该密钥是否验证通过。7.1 单组件凭证大多数 Detector 找到的是单一不透明 Token使用一个以key为键的条目即可——这是代码库中既定的约定s1 : detectors.Result{ DetectorType: detector_typepb.DetectorType_Example, Raw: []byte(match), SecretParts: map[string]string{key: match}, }7.2 多组件凭证当凭证包含多个组件时例如 AWS 的 access-key secret-access-key、OAuth 的 client-id client-secret、或绑定端点/主机的 Token每个组件各占一个条目并使用描述性键名s1 : detectors.Result{ DetectorType: detector_typepb.DetectorType_Example, Raw: []byte(accessKeyID), RawV2: []byte(accessKeyID secretAccessKey), SecretParts: map[string]string{ access_key_id: accessKeyID, secret_access_key: secretAccessKey, }, }7.3 键名规范与边界单组件统一使用key与pkg/detectors/下绝大多数既有 Detector 保持一致多组件选择描述性的小写snake_case键名例如client_id、client_secret、access_key_id、secret_access_key、username、password、domain、host、endpoint。如果该 Detector 在pkg/analyzer/analyzers/下有对应 analyzer键名必须与 analyzer 的期望完全一致因为 analyzer 直接读取这个 map边界只有能唯一标识该凭证的组件才应进入SecretParts无关的元数据应放进ExtraDataSecretParts是唯一标识一条凭证的事实来源。8. Windows 环境下生成 Protos 的注意事项make protos依赖类 Unix 环境Windows 开发者可按下述流程操作对应原文档 Addendum在 Microsoft Store 安装Ubuntu AppWSL 发行版安装Docker Desktop并在 Settings → Resources → WSL INTEGRATION 中启用对 Ubuntu 的集成打开 Ubuntu CLI安装dos2unixsudo apt install dos2unix定位 trufflehog 本地目录将 scripts/gen_proto.sh 转换为 Unix 行尾格式否则 Windows 的 CRLF 会导致脚本执行失败dos2unix ./scripts/gen_proto.sh编辑 proto/detector_type.proto 添加新枚举后保存确保 Docker 正在运行然后在 Ubuntu 命令行中执行make protos9. 提交前自检清单结合 pkg/detectors/detectors.go 中的可选接口Versioner、MaxSecretSizeProvider、StartOffsetProvider、MultiPartCredentialProvider、EndpointCustomizer、CloudProvider、CustomResultsCleaner提交 PR 前建议逐项确认正则与关键词是否精确到足以控制误报尽量配合PrefixRegex与\b边界符验证逻辑是否为非破坏性 API 调用且正确区分确定性/不确定性失败每个Result是否都填充了SecretParts单组件用key多组件用描述性 snake_case 键名.env已就位且TEST_SECRET_FILE已导出五类集成测试用例全部通过go test ./pkg/detectors/detector -tagsdetectors新枚举已加入 proto/detector_type.proto 并经make protos重新生成已在 pkg/engine/defaults/defaults.go 完成 DefaultDetectors 注册。完成上述所有环节后你的新 Detector 就具备了与仓库中 900 既有 Detector 相同的代码规范、验证语义与测试覆盖可以放心地提交 Pull Request 接受评审。【免费下载链接】trufflehogFind, verify, and analyze leaked credentials项目地址: https://gitcode.com/GitHub_Trending/tr/trufflehog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TruffleHog 外部 Secret Detector 开发全指南：从 DetectorType 枚举到验证测试的完整实战
TruffleHog 外部 Secret Detector 开发全指南从 DetectorType 枚举到验证测试的完整实战【免费下载链接】trufflehogFind, verify, and analyze leaked credentials项目地址: https://gitcode.com/GitHub_Trending/tr/trufflehog本指南完整讲解如何在 TruffleHog 中开发一个自定义 Secret Detector秘密探测器涵盖选择开发对象的标准、核心Detector接口职责、从零创建与代码生成、使用.env驱动五类测试用例、SecretParts结构化填充规范以及验证结果确定性判定等全部环节。读完本文你将能够独立完成一个通过单元测试与集成测试、可合入上游 PR 的高信噪比 Secret Detector。1. Secret Detector 的两大核心职责Secret Detector在代码中也常写作 Scanner是 TruffleHog 检出凭证的基本单元。根据 hack/docs/Adding_Detectors_external.md 的定义它承担两个主要功能从字节数据中提取疑似密钥——通常通过正则表达式regex完成向目标 API 验证密钥是否真实有效——通常通过 HTTP 客户端完成。其设计目标是以异常高的信噪比发现密钥误报率false positives不被接受。因此提取正则必须足够精确验证逻辑必须依赖真实 API 而非猜测。从源码看每个 Detector 需要实现 pkg/detectors/detectors.go 中定义的Detector接口type Detector interface { // FromData 扫描字节并可选地验证结果可被多个 goroutine 并发调用 FromData(ctx context.Context, verify bool, data []byte) ([]Result, error) // Keywords 用于对数据块做子串级预过滤应优先使用密钥中的唯一标识或提供商名 Keywords() []string // Type 返回 detector_type.proto 中定义的 DetectorType 枚举值 Type() detector_typepb.DetectorType // Description 返回该结果检测项的说明文字 Description() string }其中Keywords()非常关键TruffleHog 引擎会基于 Aho-Corasick 算法用关键词对海量数据块做预过滤只有命中关键词的块才会进入正则匹配从而大幅降低整体开销可参见 pkg/detectors/alchemy/alchemy_test.go 中ahocorasick.NewAhoCorasickCore的用法。当提供多个关键词时它们是并集关系——任一关键词出现即触发检测。2. 开发前的选型与准备2.1 Sourcing Guidelines什么服务值得接入为了控制维护成本与误报率TruffleHog 只对满足至少一项以下条件的服务开发 Detector托管数据该服务会存储用户提供的任何形式的数据提供付费服务拥有免费或试用层级也可以接受。如果认为某个服务应突破以上边界纳入需要主动与维护者沟通说明。这条原则确保了每个新增 Detector 都有真实的使用场景与用户基础。2.2 Development Guidelines开发规范在合理的前提下优先使用标准库net/http发起请求避免引入额外的 HTTP 依赖库尽可能使用common.SaneHttpClient作为http.Client。SaneHttpClient在 pkg/common/http.go 中实现它设置了 5 秒的DefaultResponseTimeout通过saneTransport约束连接、TLS 握手、空闲连接等超时参数并用NewInstrumentedTransport自动埋点 HTTP 指标请求数、延迟、响应体大小、非 200 状态码等方便 TruffleHog 观测各 Detector 的验证请求行为。测试中需要更短超时时可以用SaneHttpClientTimeOut(timeout)或ConstantResponseHttpClient(statusCode, body)模拟固定响应。2.3 Development Dependencies环境依赖Go 1.17项目基于现代 Go 编写当前仓库使用go.mod管理依赖Make用于执行make protos、make test等构建脚本见 Makefile。3. 为既有 Scanner 添加新 Token 格式Versioner 模式有些服务会更新自身的 Token 格式。此时在不新增 Detector的前提下可以通过实现Versioner接口来同时兼容新旧格式。接口定义在 pkg/detectors/detectors.go// Versioner 是可选的接口用于区分同一 DetectorType 的不同实例版本 type Versioner interface { Version() int }具体操作步骤创建v1与v2两个目录将既有 Detector 及其测试移入v1新增文件放在v2。例如packagename/old_files→packagename/v1/old_files、packagename/v2/new_files。注意务必同步更新测试中对 GSMGoogle Secret Manager里新密钥值的引用否则测试会失败。实现Versioner接口。仓库中的真实范例是 pkg/detectors/github/v1/github_old.goVersion()返回 1与 pkg/detectors/github/v2/github.goVersion()返回 2并额外实现了EndpointCustomizer、CloudProvider等可选接口。在既有与新版本 Detector 的ExtraData中均加入version字段用于标记结果来自哪个版本。在 pkg/engine/defaults/defaults.go 的 DefaultDetectors 中更新既有 Detector 的注册新增 v2 的 Scanner 条目。从创建新 Secret Detector的第 3 步代码生成继续往下走。4. 从零创建全新 Secret Detector 的完整步骤4.1 添加 DetectorType 枚举并重新生成 Protobuf在 proto/detector_type.proto 的DetectorType枚举列表中追加新枚举项例如SampleAPI。运行make protos重新生成对应的.pb文件pkg/pb/detector_typepb等。该命令由 scripts/gen_proto.sh 驱动内部依赖 Docker 容器执行 protoc 编译。4.2 用脚手架命令生成 Detector 骨架TruffleHog 提供代码生成器 hack/generate/generate.go它会以现有 alchemy 探测器的三个文件为模板做大小写与命名的占位替换生成你需要的初始文件go run hack/generate/generate.go detector DetectorType enum name # 例如 go run hack/generate/generate.go detector SampleAPI执行后会在pkg/detectors/detector_name/下生成三个文件detector_name.go——主实现模板来源 pkg/detectors/alchemy/alchemy.godetector_name_test.go——纯模式匹配的单测模板来源 pkg/detectors/alchemy/alchemy_test.godetector_name_integration_test.go——带//go:build detectors构建标签的集成测试模板来源 pkg/detectors/alchemy/alchemy_integration_test.go覆盖全部 5 类验证场景。4.3 注册到 DefaultDetectors将新 Detector 以import github.com/trufflesecurity/trufflehog/v3/pkg/detectors/detector_name的方式引入并在 pkg/engine/defaults/defaults.go 的 DefaultDetectors 切片中追加detector_name.Scanner{}。只有注册后默认扫描模式才会加载它。4.4 补全 Detector 实现脚手架生成的是可编译的样板 示例代码完成一个合格的 Detector 通常需要更新模式正则与关键词。可以在迭代时借助 regex101 等工具打磨表达式注意用\b等边界符包裹捕获组以降低误报。可参考 pkg/detectors/alchemy/alchemy.go正则使用detectors.PrefixRegex([]string{alchemy})该工具函数在 pkg/detectors/detectors.go保证关键词出现在捕获组前 40 个字符以内关键词列表返回{alchemy, alcht_}。更新验证器代码调用一个非破坏性的 API来判断密钥是否有效详见第 6 节验证不确定性。在每个Result上填充SecretParts详见第 7 节。为 Detector 编写测试详见第 5 节。再次确认已在 pkg/engine/defaults/defaults.go 注册。提交 Pull Request 供评审。4.5 FromData 的典型实现形态以 alchemy 为例pkg/detectors/alchemy/alchemy.go核心流程是把字节转字符串 → 用正则提取并去重→ 为每个匹配构造detectors.Result→ 若verify为真则调用验证函数写入Verified、ExtraData与验证错误。Tailscale 的验证器pkg/detectors/tailscale/tailscale.go则展示了另一种常见模式204 No Content视为验证成功、401视为确定性失败、其余状态码视为不确定性失败并SetVerificationError。5. 测试 Detector.env驱动五类用例为保证 PR 质量测试必须基于已核实的真实凭证运行。5.1 准备.env文件在新建 Detector 的目录下创建.env格式如下SECRET_TYPE_ONEvalue SECRET_TYPE_ONE_INACTIVEvlue其中_INACTIVE后缀的密钥应满足正则但不通过验证例如把密钥字符做一点改写使验证返回 401/403。目录结构如下├── tailscale │ ├── .env │ ├── tailscale.go │ └── tailscale_test.go5.2 导出环境变量export TEST_SECRET_FILE.env设置后测试代码即可从本地加载密钥。其机制见 pkg/common/secrets.goGetSecret会优先读取TEST_SECRET_FILE指向的 env 文件GetSecretFromEnv使用 godotenv 解析若未设置该变量则回退到从 GCP Secret Manager项目trufflehog-testing拉取测试密钥。这意味着本地开发时无需 GCP 权限即可跑集成测试。5.3 生成器自带的五类测试用例go run hack/generate/generate.go生成的集成测试文件已经覆盖以下 5 种情况对照 pkg/detectors/alchemy/alchemy_integration_test.go 逐条对应Found and verified使用.env中有效密钥验证成功Verified true、无验证错误Found and unverified确定性失败使用_INACTIVE密钥验证确定性失败Verified false、无验证错误Found and unverified因超时导致的不确定性失败注入一个超短超时的 client如common.SaneHttpClientTimeOut(1 * time.Microsecond)Verified false且存在验证错误Found and unverified因意外的 API 响应导致不确定性失败注入common.ConstantResponseHttpClient(404, )模拟意外响应Verified false且存在验证错误Not found输入不含任何密钥的文本期望返回空结果。生成器生成的测试质量较高多数情况下无需大改如不确定可参考覆盖全部 5 类用例的范本 pkg/detectors/browserstack/browserstack_test.go。断言时会用cmpopts.IgnoreFields忽略Raw与verificationError等易变字段见 pkg/detectors/alchemy/alchemy_integration_test.go。5.4 运行测试go test ./pkg/detectors/detector -tagsdetectors-tagsdetectors用于启用带//go:build detectors构建标签的集成测试文件不加该标签则只运行纯模式匹配的单测。测试全部通过后即可放心提交 PR。6. 验证不确定性Verification Indeterminacy如何正确区分两类失败密钥验证失败可能源于两种截然不同的原因候选字符串并非真实有效的密钥密钥本身无效验证过程中发生了与候选密钥无关的故障例如瞬时网络错误、请求超时、或 API 返回了非预期响应。在 TruffleHog 的术语中前者称为determinate确定性失败后者称为indeterminate不确定性失败。验证代码必须通过是否在结果结构中返回 error 对象来区分二者只有在不确定性失败时才返回 error凡是未被明确识别为确定性失败的状态都应返回 error 表示不确定性失败。一个典型范例假设某认证端点对有效凭证返回200 OK、对无效凭证返回403 Forbidden。验证器应如此决策响应码判定行为200或任意2xx验证成功Verified true403验证确定性失败Verified false不返回 error其他任意响应验证不确定性失败Verified false返回 errordetectors.Result中验证错误的设置入口是SetVerificationError(err, secrets...)见 pkg/detectors/detectors.go它会将错误消息中出现的敏感值替换为[REDACTED]后再存储避免在日志中泄露凭证。alchemy 的验证器pkg/detectors/alchemy/alchemy.go正是这一模式的完整实现200成功、401确定性失败、其余状态码fmt.Errorf(unexpected HTTP response status %d, ...)作为不确定性失败返回。7. Populating SecretParts结构化填充凭证组件SecretParts是 Detector 输出凭证组件的结构化事实来源。它定义在 pkg/detectors/detectors.go类型为map[string]string挂在detectors.Result上用描述性 key 存储凭证的每一部分。下游消费者——analyzers见 pkg/analyzer/analyzers、Secret Storage、以及未来工作Raw/RawV2映射层与去重哈希——都依赖它。硬性要求Detector 输出的每个Result都必须填充SecretParts无论该密钥是否验证通过。7.1 单组件凭证大多数 Detector 找到的是单一不透明 Token使用一个以key为键的条目即可——这是代码库中既定的约定s1 : detectors.Result{ DetectorType: detector_typepb.DetectorType_Example, Raw: []byte(match), SecretParts: map[string]string{key: match}, }7.2 多组件凭证当凭证包含多个组件时例如 AWS 的 access-key secret-access-key、OAuth 的 client-id client-secret、或绑定端点/主机的 Token每个组件各占一个条目并使用描述性键名s1 : detectors.Result{ DetectorType: detector_typepb.DetectorType_Example, Raw: []byte(accessKeyID), RawV2: []byte(accessKeyID secretAccessKey), SecretParts: map[string]string{ access_key_id: accessKeyID, secret_access_key: secretAccessKey, }, }7.3 键名规范与边界单组件统一使用key与pkg/detectors/下绝大多数既有 Detector 保持一致多组件选择描述性的小写snake_case键名例如client_id、client_secret、access_key_id、secret_access_key、username、password、domain、host、endpoint。如果该 Detector 在pkg/analyzer/analyzers/下有对应 analyzer键名必须与 analyzer 的期望完全一致因为 analyzer 直接读取这个 map边界只有能唯一标识该凭证的组件才应进入SecretParts无关的元数据应放进ExtraDataSecretParts是唯一标识一条凭证的事实来源。8. Windows 环境下生成 Protos 的注意事项make protos依赖类 Unix 环境Windows 开发者可按下述流程操作对应原文档 Addendum在 Microsoft Store 安装Ubuntu AppWSL 发行版安装Docker Desktop并在 Settings → Resources → WSL INTEGRATION 中启用对 Ubuntu 的集成打开 Ubuntu CLI安装dos2unixsudo apt install dos2unix定位 trufflehog 本地目录将 scripts/gen_proto.sh 转换为 Unix 行尾格式否则 Windows 的 CRLF 会导致脚本执行失败dos2unix ./scripts/gen_proto.sh编辑 proto/detector_type.proto 添加新枚举后保存确保 Docker 正在运行然后在 Ubuntu 命令行中执行make protos9. 提交前自检清单结合 pkg/detectors/detectors.go 中的可选接口Versioner、MaxSecretSizeProvider、StartOffsetProvider、MultiPartCredentialProvider、EndpointCustomizer、CloudProvider、CustomResultsCleaner提交 PR 前建议逐项确认正则与关键词是否精确到足以控制误报尽量配合PrefixRegex与\b边界符验证逻辑是否为非破坏性 API 调用且正确区分确定性/不确定性失败每个Result是否都填充了SecretParts单组件用key多组件用描述性 snake_case 键名.env已就位且TEST_SECRET_FILE已导出五类集成测试用例全部通过go test ./pkg/detectors/detector -tagsdetectors新枚举已加入 proto/detector_type.proto 并经make protos重新生成已在 pkg/engine/defaults/defaults.go 完成 DefaultDetectors 注册。完成上述所有环节后你的新 Detector 就具备了与仓库中 900 既有 Detector 相同的代码规范、验证语义与测试覆盖可以放心地提交 Pull Request 接受评审。【免费下载链接】trufflehogFind, verify, and analyze leaked credentials项目地址: https://gitcode.com/GitHub_Trending/tr/trufflehog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考