TruffleHog 自定义检测器Custom Detector配置实战指南从 config.yaml 到验证服务器【免费下载链接】trufflehogFind, verify, and analyze leaked credentials项目地址: https://gitcode.com/GitHub_Trending/tr/trufflehogTruffleHog 内置了数百种针对知名服务的密钥检测器但每个团队总有自己特有的密钥格式、内部令牌前缀或私有平台的凭据模式。本文以 pkg/custom_detectors/CUSTOM_DETECTORS.md 为核心系统讲解如何通过config.yaml自定义检测器定义关键词与正则、配置可选的状态码验证范围、编写验证服务器Python 或 Go并结合 pkg/custom_detectors/custom_detectors.go 的源码与测试用例把从写配置到跑扫描的完整链路讲透。读完本文你将能独立为一个项目编写可验证、可过滤误报的自定义检测规则。自定义检测器是什么TruffleHog 的自定义检测器Custom Detector基于CustomRegex模型实现用户以 YAML 形式描述命中哪些关键词后触发哪些正则TruffleHog 在扫描时将其编译为CustomRegexWebhook检测器以CustomRegex类型参与检测见 pkg/custom_detectors/custom_detectors.go 中的接口断言与Type()方法返回的detector_typepb.DetectorType_CustomRegex。它适用于以下场景检测项目内部特有的密钥格式例如HogTokenDetector这类带有私有前缀的令牌在.env、.properties、.yaml等配置文件中识别硬编码的*.password、*.secret类通用密钥无需验证服务器详见后文复用并改造 gitleaks 等社区公开的通用密钥正则快速补齐企业级扫描策略。从底层模型看每个自定义检测器的完整字段由 proto/custom_detectors.proto 定义name、keywords、regex命名正则映射、verify验证服务器配置列表、description、exclude_regexes_capture、exclude_words、entropy、exclude_regexes_match、primary_regex_name以及validations。下文将逐一展开。第一步创建配置文件TruffleHog 使用一个配置文件通常命名为config.yaml管理所有自定义检测器。如果系统里还没有该文件直接新建即可。文件顶层是一个detectors列表每个元素对应一个自定义检测器# config.yaml detectors: - name: HogTokenDetector # ... 具体配置见下文该结构对应CustomDetectors消息中的repeated CustomRegex detectors见 proto/custom_detectors.proto测试用例 pkg/custom_detectors/custom_detectors_test.go 验证了完整的detectors列表 YAML 可以被严格解析protoyaml.UnmarshalStrict。第二步定义一个自定义检测器以文档中的模板为例一个最小的自定义检测器如下# 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 must be set to true if the endpoint uses HTTP unsafe: true headers: - Authorization: super secret authorization header各字段含义如下name自定义检测器的唯一标识。它会出现在扫描结果的Detector Name中并在验证请求中作为 JSON 的顶层键名见下文验证服务器示例。keywords字符串数组。当被扫描内容中出现任意一个关键词时才触发对应正则的搜索多个关键词只要命中其一即可启动正则匹配。TruffleHog 在初始化时会通过 pkg/custom_detectors/validation.go 的ValidateKeywords校验关键词列表非空且不含空字符串。regex一个或多个命名正则的映射。进行检测时每个命名正则都必须至少匹配一次检测才算成功源码中会对所有命名正则做笛卡尔积排列组合详见下文多正则的组合匹配。正则中的捕获组()用于提取匹配文本中的特定片段检测器会对该片段进行处理与上报——没有捕获组时上报整个匹配有捕获组时上报第 1 个捕获组见 pkg/custom_detectors/custom_detectors.go。verify 与验证状态判定verify是可选部分用于校验已检测到的密钥是否真实有效。配置了verify检测结果才会被标记为 verified / unverified未配置时所有检测到的密钥一律标记为 unverified。verify 的每个条目包含endpoint验证服务器地址。TruffleHog 会以POST请求向该地址发送 JSON。初始化时通过ValidateVerifyEndpointpkg/custom_detectors/validation.go校验endpoint 不能为空且若使用http://明文协议必须设置unsafe: true否则直接报错。unsafe布尔值。HTTP 端点必须为trueHTTPS 端点不受限制。headers随验证请求携带的请求头列表每个元素形如Authorization: xxx。校验规则要求每个 header 必须包含冒号ValidateVerifyHeaders发送时按:切分为键值并自动补全缺失的Content-Type: application/json见 pkg/custom_detectors/custom_detectors.go。successRangesHTTP 状态码或区间列表表示密钥仍然有效live。验证服务器返回匹配的状态码时该密钥被标记为 verified。每个条目可以是单个状态码200或闭区间200-202。若该项与rotatedRanges均省略则采用向后兼容行为——只有200视为有效。rotatedRangesHTTP 状态码或区间列表表示密钥已被轮换/作废rotated。返回匹配的状态码时该密钥被明确标记为 unverified。两字段的搭配逻辑这也是文档中特别强调、容易被忽略的行为规则配置情况返回匹配 successRanges返回匹配 rotatedRanges返回都不匹配仅配置successRanges有效verified视为已轮换unverified视为已轮换仅配置rotatedRanges视为有效已轮换unverified视为有效两者都配置有效已轮换结果未知/不确定inconclusive并设置验证错误两者都不配置旧版行为仅200有效非 200 视为verifier 说不非 200 视为确定性否定两者都配置但都不匹配时源码会为结果设置验证错误verification response status code did not match any configured successRanges or rotatedRanges见 pkg/custom_detectors/custom_detectors.go测试用例TestVerificationWithConfigurableRangespkg/custom_detectors/custom_detectors_test.go逐条覆盖了这些分支。此外若配置了多个验证端点TruffleHog 会依次尝试直到某个端点给出确定性结论definitive混合使用带范围验证器与旧版验证器也是允许的——见TestVerificationMixedRangedAndLegacyVerifierspkg/custom_detectors/custom_detectors_test.go。状态码区间在初始化时会通过ValidateVerifyRangespkg/custom_detectors/validation.go严格校验单个码与区间上下界都必须是合法 HTTP 状态码100599区间格式必须为低-高且低界不得大于高界。运行时匹配由StatusCodeMatchesRangespkg/custom_detectors/validation.go完成支持单码与闭区间。以下是带可配置验证范围的完整示例# 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 headers: - Authorization: super secret authorization header successRanges: - 200 rotatedRanges: - 401 - 403该示例中验证服务器返回200表示密钥仍然有效、需要轮换返回401或403表示密钥已被轮换、不再有效返回其他任何状态码则视为结果不确定。测试用例 pkg/custom_detectors/custom_detectors_test.go 验证了successRanges/rotatedRanges中单码与403-404这类区间的 YAML 解析。其他允许的配置参数除了上述基础字段CustomRegex还支持以下高级参数可用于精调匹配行为、过滤误报primary_regex_name当regex下定义了多个命名正则时用该参数指定主正则。命中后主正则的完整匹配文本含前缀后缀的 full match会被用于精确定位行号。值必须是regex中已存在的名称之一未提供时按排序后的第一个正则名作为主正则ensurePrimaryRegexNameSet见 pkg/custom_detectors/custom_detectors.go。之所以保存完整匹配而非仅捕获组是为了避免同一捕获组文本在数据中多次出现时行号定位产生歧义——参见 pkg/custom_detectors/custom_detectors.go 及测试TestDetectorPrimarySecretFullMatchpkg/custom_detectors/custom_detectors_test.go。exclude_regexes_capture正则列表。若捕获组提取出的密钥片段命中其中任一正则该条结果被排除。它作用于捕获值而非整个匹配串。exclude_regexes_match正则列表。若整个匹配文本命中其中任一正则则该条结果整体不报。注意它与exclude_regexes_capture的作用对象不同前者针对整条匹配后者针对提取出的密钥本身源码中excludeRegexes.MatchString(values[0])对比excludeSecret.MatchString(secret)见 pkg/custom_detectors/custom_detectors.go。entropy信息熵阈值用于评估检测字符串的随机性。高熵通常意味着字符串可能是 API Key 或密码之类的密钥从而过滤误报。entropy: 3可作起点但应根据项目数据特征调整。实现上通过detectors.StringShannonEntropy(secret) float64(entropy)跳过低熵匹配pkg/custom_detectors/custom_detectors.go。exclude_words字符串列表。检测到的密钥片段中若包含任一单词子串匹配不强制单词边界则该条结果被忽略。注意它只作用于 token捕获值不作用于完整匹配。validations为每个命名正则追加的额外校验规则用于弥补 Go RE2 引擎不支持 lookahead 等特性的局限在正则匹配后进一步降低误报。可用规则contains_digit匹配必须包含至少一个数字0-9适合必须带数字的 API Key 或令牌contains_lowercase匹配必须包含至少一个小写字母a-z常见于密码与混合大小写令牌contains_uppercase匹配必须包含至少一个大写字母A-Z用于符合混合大小写约定的令牌contains_special_char匹配必须包含至少一个特殊字符字符集为!#$%^*()_-[]{}|;:,.?适合复杂密码或编码令牌。校验实现见 pkg/custom_detectors/validation.go在 pkg/custom_detectors/custom_detectors.go 中按命名正则对应的ValidationConfig逐条启用。测试用例TestDetectorValidationspkg/custom_detectors/custom_detectors_test.go覆盖了每条规则通过/不通过、多条规则组合、以及针对错误正则名的 validations 被忽略等情形。仓库 examples/generic_with_filters.yml 给出了综合使用validations、entropy、exclude_regexes_match、exclude_words的完整示例其中exclude_words内置了数百个常见误报词examples/generic_config_secrets.yml 则展示了通过exclude_regexes_capture排除${VAR}、{{VAR}}、process.env.XXX、vault://等占位符/引用模式并用exclude_words剔除changeme、placeholder、dummy等示例值从而在.properties、.env、.yaml等配置文件里精准标记硬编码密钥。第三步运行 TruffleHog 并指定配置文件使用--config参数运行扫描对指定的目录或文件生效trufflehog filesystem path_to_folder_or_file --configpath_to_file/config.yamlpath_to_folder_or_file要扫描的目录或文件路径path_to_fileconfig.yaml的路径。TruffleHog 会加载该文件中的全部自定义检测器并结合内置检测器一起执行扫描。第四步完整示例演示使用上文模板配置扫描一个文件。假设/tmp/data.txt内容如下// this is a custom example this file has some random text and maybe a secret hog token: pOIAj9x47WT5qElx5JrI3e7O714HgaAIz2ck9sVn // end of file文件中出现了关键词hog触发正则搜索字符串pOIAj9x47WT5qElx5JrI3e7O714HgaAIz2ck9sVn匹配[^A-Za-z0-9\/]{0,1}([A-Za-z0-9\/]{40})[^A-Za-z0-9\/]{0,1}因此会被检出。运行trufflehog filesystem /tmp --configconfig.yaml输出大致如下 TruffleHog. Unearth your secrets. Found verified result Detector Type: CustomRegex Decoder Type: PLAIN Raw result: pOIAj9x47WT5qElx5JrI3e7O714HgaAIz2ck9sVn File: /tmp/data.txt Line: 3其中Raw result是被匹配到的字符串File是检出密钥的文件名Line是密钥所在的精确行号由主正则的完整匹配定位见前文primary_regex_name说明。编写验证服务器Python 与 Go 实现若不运行验证服务器自定义检测器检出的密钥将一律是 unverified 状态。下面给出与上文config.yaml对应的 Python 与 Go 验证服务器实现。两者都需要监听 8000 端口、校验Authorization头、解析 JSON 请求体并根据业务逻辑返回200有效或403已轮换。Python 实现import json from http.server import BaseHTTPRequestHandler, HTTPServer AUTH_HEADER super secret authorization header class Verifier(BaseHTTPRequestHandler): def do_GET(self): self.send_response(405) self.end_headers() def do_POST(self): try: if self.headers[Authorization] ! AUTH_HEADER: self.send_response(401) self.end_headers() return length int(self.headers[Content-Length]) request json.loads(self.rfile.read(length)) self.log_message(%s, request) if not validateTokens(request[HogTokenDetector][token]): self.send_response(200) self.end_headers() else: self.send_response(403) self.end_headers() except Exception: self.send_response(400) self.end_headers() def validateTokens(token): return False # Implement actual validation logic with HTTPServer((, 8000), Verifier) as server: try: server.serve_forever() except KeyboardInterrupt: passGo 实现package main import ( encoding/json fmt io log net/http ) const authHeader super secret authorization header type HogTokenDetector struct { Token string json:token } type RequestBody struct { HogTokenDetector HogTokenDetector json:HogTokenDetector } func validateTokens(token string) bool { return false // Implement actual validation logic } func verifierHandler(w http.ResponseWriter, r *http.Request) { if r.Method ! http.MethodPost { http.Error(w, Method Not Allowed, http.StatusMethodNotAllowed) return } if r.Header.Get(Authorization) ! authHeader { http.Error(w, Unauthorized, http.StatusUnauthorized) return } body, err : io.ReadAll(r.Body) if err ! nil { http.Error(w, Bad Request, http.StatusBadRequest) return } defer r.Body.Close() var requestBody RequestBody if err : json.Unmarshal(body, requestBody); err ! nil { http.Error(w, Bad Request, http.StatusBadRequest) return } log.Printf(Received Request: %v, requestBody) if validateTokens(requestBody.HogTokenDetector.Token) { http.Error(w, Forbidden, http.StatusForbidden) } else { w.WriteHeader(http.StatusOK) } } func main() { http.HandleFunc(/, verifierHandler) serverAddr : :8000 fmt.Printf(Starting server on %s...\n, serverAddr) if err : http.ListenAndServe(serverAddr, nil); err ! nil { log.Fatalf(Server failed: %s, err) } }验证请求格式与模板变量两个示例都说明了验证请求的 JSON 结构TruffleHog 将请求体序列化为{检测器name: {命名正则名: [完整匹配, 捕获组...]}}见 pkg/custom_detectors/custom_detectors.go。因此上例中request[HogTokenDetector][token]取到的就是token正则的匹配数组。此外pkg/custom_detectors/regex_varstring.go 支持在endpoint与headers中使用{name.group}模板变量例如http://localhost:8000/{id_pat_example}或Authorization: Bearer {secret_pat_example.0}{name}省略.group时默认为捕获组 0。变量名仅允许字母、数字、连字符与下划线group为非负整数。测试 pkg/custom_detectors/custom_detectors_test.go 验证了这类模板解析并覆盖了successRanges中的200-250区间写法。无需验证服务器的通用密钥检测场景由于verify是可选项自定义检测器也可以完全不配置 webhook仅用于标记.properties、.env、.yaml等配置文件中的通用硬编码密钥如*.password、*.secret此时检出的结果全部为 unverified。仓库中的 examples/generic_config_secrets.yml 正是为此场景调优的配置——它覆盖了secret、password、passwd、pwd、apikey、token、credential、auth等关键词通过捕获组提取 6150 位的值并组合使用entropy: 2.5、exclude_regexes_capture与exclude_words过滤占位符和示例值。底层实现原理从关键词到结果的完整流程理解源码有助于你写出更可靠的规则。CustomRegexWebhook.FromDatapkg/custom_detectors/custom_detectors.go的完整处理链如下预编译将exclude_regexes_capture、exclude_regexes_match与所有命名正则编译为 Goregexp.Regexp任一正则非法都会返回错误ValidateRegex在初始化时已拦截大部分。匹配对每个命名正则执行FindAllStringSubmatch收集全部完整匹配与捕获组。排列组合permutateMatches对多个命名正则的匹配结果做笛卡尔积——例如foo命中 2 处、bar命中 1 处会产生 2 组候选这正是每个命名正则都必须匹配才算一次检测成功的底层体现。组合总数受maxTotalMatches 100上限保护pkg/custom_detectors/custom_detectors.go防止过宽正则导致扫描器做过多无用功相关测试见TestProductIndicesMax。过滤依次执行熵检查entropy、exclude_words子串检查不区分大小写、整条匹配排除exclude_regexes_match、捕获值排除exclude_regexes_capture、以及validations校验任一环节不满足即跳过该候选。验证若verify为真按前文规则向各验证端点发送POST请求并依据successRanges/rotatedRanges判定验证响应的 body 会截取前 200 字节存入结果的ExtraData[response]storeResponseBody。并发验证通过errgroup执行单个端点失败会被跳过而不阻断其他结果。输出结果以CustomRegex类型返回ExtraData[name]记录检测器名称每个自定义检测器的最大密钥长度为 1000 字节MaxSecretSize()见 pkg/custom_detectors/custom_detectors.go。提示若想在本仓库中继续深入研究可阅读 pkg/custom_detectors/custom_detectors.go核心实现、pkg/custom_detectors/validation.go全部校验规则、pkg/custom_detectors/custom_detectors_test.go覆盖验证范围、validations、primary regex 等行为的测试以及 proto/custom_detectors.proto配置模型定义examples/generic.yml、examples/generic_config_secrets.yml、examples/generic_with_filters.yml 三个示例可直接作为编写规则的起点。【免费下载链接】trufflehogFind, verify, and analyze leaked credentials项目地址: https://gitcode.com/GitHub_Trending/tr/trufflehog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考