绝对不是!
在这个 LLM 炒作的时代,DeepSecrets 仍然完全在你的机器上运行——离线、安全且免费地为你提供出色的结果。
大多数现有扫描器实际上并不“理解”代码。它们只是解析文本,覆盖率很差。
DeepSecrets 弥合了经典正则扫描器与全规模商业 SAST 工具之间的差距。它扩展了经典基于正则的扫描策略,大量依赖语义代码分析、危险变量检测和上下文感知的熵分析。 密钥候选来自代码所表达的内容、其名称、赋值和调用,而不仅仅是文本。DeepSecrets 使用约 600 种语言和格式的词法分析器(Pygments)读取代码,并通过针对 14 种语言的检测规则以及适用于其余语言的通用规则来查找变量。
DeepSecrets 还引入了一种零知识查找凭据的新方法:HashedSecret 引擎。只需提供你已知生产密钥的哈希值,该工具就会在你的代码中找到以明文形式暴露的这些密钥。
DeepSecrets 2.3 于 2026 年 11 月在 SecretBench 基准上进行了评估:扫描了每个文件,统计了每一行带标签的数据。
按照 2026 年 6 月评估的统计方式,在其自身的数据行集合上统计,2.3 的召回率为 94%,精确率为 85%(2026 年 6 月的 2.0:93% 和 67%)。
这些数字来自 dsbench,这是一个开源基准测试框架,它将扫描器作为黑盒在带标签的语料库上运行,并统计其报告的结果。借助 SecretBench(可向其作者索取)和 dsbench,任何人都可以复现上述逐行数字以及下面的对比:
dsbench prepare # load SecretBench's labels and the corpus listing
dsbench run --tool-ref v2.3.0 # DeepSecrets 2.3.0 from its tag, in a venv from its own poetry.lock
dsbench tools fetch # the pinned gitleaks and Betterleaks releases, checked by SHA-256
dsbench run --tool gitleaks
dsbench run --tool betterleaks
dsbench compare RUN RUN ... # side by side, with 95% intervals
每次运行都会扫描每个文件,并关闭各工具的路径排除设置。June-way 的数据还需要 2026 年 6 月评估的行表,以及超出标签范围的密钥计数,这需要我们的判定结论;两者均未公开,因为二者都指向泄露的凭据。
(你可以在我的 HackerNoon 文章此处阅读完整的底层故事和基准测试细分)
通过 pip 从 Github 安装
$ pip install git+https://github.com/ntoskernel/deepsecrets.git
来自 PyPi
$ pip install deepsecrets
DeepSecrets 需要 Python 3.11 或更高版本。
运行扫描最简单的方式:
$ deepsecrets --target-dir /path/to/your/code --outformat dojo-sarif --outfile report.json
这将对 /path/to/your/code 使用默认配置运行一次扫描:
SARIF 格式的报告(兼容 DefectDojo 和 GitHub Security)将保存到 report.json。
--help 命令随时可以为你提供指引,但以下是你可用来让扫描适配自身环境的关键标志:
--regex-rules /path/to/rules.json:提供你自己的自定义正则规则集。--hashed-values /path/to/hashes.json:提供一份预先哈希的已知生产密钥列表,以便安全地搜索它们。--excluded-paths /path/to/exclusions.json:覆盖或扩展扫描期间默认忽略的路径。--deep-max-size BYTES:大于此值(默认 250,000 字节)的文件会进行快速分析:正则规则和变量搜索,不使用语言词法分析器。大文件大多是生成或压缩的,词法分析器在这类文件上耗费了大部分扫描时间,而且很少能发现更多内容。0 表示对每个文件都进行完整分析。--skip-bundles:在其他路径排除项之外,完全跳过压缩的 JavaScript、source map 和 bundle(*.min.js、*.map、*.bundle.js)。--confidence-level {all,low,medium,high,very-high}:要报告的最低置信度(默认 low,即所有发现)。medium、high 和 very-high 分别保留置信度 5、6 和 9 及以上的发现,即同名及更高 SARIF 层级的发现;all 还会报告扫描器判定并非密钥的正则匹配(占位符、示例),并带有 -INFO 规则 id。--min-confidence N:报告置信度为 N 或以上的发现,N 从 0 到 10:任意截断值,而 --confidence-level 提供的是各层级的阈值。与除 all 之外的每个级别一样,它会排除被判定并非密钥的正则匹配。请使用其中一个标志,不要同时使用两者。--exclude-tags TAG [TAG ...]:排除带有这些标签中任意一个的发现。标签说明发现属于哪种密钥,而置信度说明它有多大可能是密钥:weak-password(密码类名称下的弱值)、publishable(用于发布给客户端的密钥:reCAPTCHA 及其他站点密钥、Stripe pk_ 密钥、Mapbox pk. 令牌、播放器、分析和地图密钥)、test-context(相对于目标目录的测试、spec、fixture、mock、example 或 sample 路径)、recorded-traffic(VCR 磁带、会话录制、HAR 文件)、identifier(AWS 用户、角色或策略的 id,不授予任何权限)以及 web-page(HTML 页面)。默认情况下每个发现仍会被报告;例如,当你搜寻真实密钥时使用 --exclude-tags test-context。--report-diagnostics:将目标下找到的每个文件添加到 SARIF 报告中,并附上其状态、扫描时间、跳过原因和分析深度。--regex-candidate-scoring-rules /path/to/rules.json:提供你自己的规则,用于在报告正则匹配之前对其进行判定。不给该标志赋值,则报告未经判定的正则匹配。--multiprocessing-context {forkserver,spawn,fork}:工作进程的启动方式。在平台支持的情况下(Linux、macOS),默认是 forkserver:工作进程共享已在服务器进程中加载的扫描器。Windows 使用 spawn。三者产生的发现相同。--disable-masking:在输出报告中保持潜在密钥不被打码 (见下方注意事项)。--ci / --no-ci:开启或关闭 CI 模式。CI 模式每 30 秒打印一行纯文本进度,而不是实时进度显示。它在 CI 服务(GitHub Actions、GitLab CI、Jenkins 等)内部以及输出不是终端时会自动开启。例如 .github/workflows/deepsecrets.yml
name: DeepSecrets Scan
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.14'
- name: Install DeepSecrets
run: pip install deepsecrets
- name: Run Scan
run: deepsecrets --target-dir . --outformat dojo-sarif --outfile report.sarif
continue-on-error: true
- name: Upload SARIF report
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: report.sarif
自 v1.3.0 起,报告中的潜在机密会被自动掩蔽,以保护你的流水线产物。如有必要,可通过 --disable-masking 标志关闭此功能。
掩蔽不会破坏下游平台(如 Github)的去重逻辑,因为报告中的 partialFingerprints 部分是基于原始数据正确填充的。
[!Caution]
如果你在禁用掩蔽的情况下将 DeepSecrets 集成到 CI 流水线中,你很可能会在 CI 日志和产物中再次泄露你的机密。
每个发现都会获得一个置信度分数。然而,不同的安全平台对 SARIF 指标的解析方式各不相同。为确保与现代 ASPM 仪表板的兼容性,DeepSecrets 采取以下措施:
虚拟子规则(rules[]):按置信度层级动态生成规则,从 S105-LOW(置信度 0 到 4)到 -MEDIUM(5)、-HIGH(6 到 8)、S105-VERY-HIGH(9 和 10),以及用于 --confidence-level all 报告中被拒绝匹配的 -INFO。这会促使 GitHub Security 和 DefectDojo 正确映射语义精确度的差异,同时不破坏原生解析器。
确定性的结果级别:该工具始终在 results[] 模型中显式设置 level: error。这为 CI/CD 流水线和较旧的 SAST 解析器提供了通用回退机制,确保无论各条规则如何解读,暴露的机密都能可靠地使构建失败或阻止 Pull Request。
标签:每个结果都会在 SARIF 标准的 properties.tags 数组中携带其标签(如果有的话)(weak-password、publishable、test-context、recorded-traffic、identifier、web-page)。规则 ID、严重性和指纹不依赖于这些标签。
上下文消息:将原始数值置信度分数原生注入到 result.message.text 中,以便安全分析师能在其仪表板上立即看到。
用于正则检查的内置规则集位于 /deepsecrets/rules/regexes.json。你可以自由遵循该格式并创建自定义规则集。
用于哈希检查的示例规则集位于 /tests/fixtures/hashed_secrets.json。你可以自由遵循该格式并创建自定义规则集。
要在不在仓库中以明文暴露的情况下查找已知的生产机密,请提供一个包含其哈希值的 JSON:
[
{
"name": "KNOWN-PROD-DATABASE-PASSWORD",
"hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"length": 12,
"algorithm": "sha1"
}
]
使用 --hashed-values /path/to/hashes.json 运行。DeepSecrets 会在词法分析阶段自动对字符串候选进行哈希处理,以便与它们匹配。
呃,它还是基于正则表达式的吗?
是也不是。当然,它像其他工具一样使用正则表达式来查找有类型的密钥。但语言理解(词法分析阶段)和变量检测在底层同样使用正则表达式。正则表达式是一种工具,而不是问题所在。问题在于脱离语义上下文盲目地应用正则表达式。
那 Semgrep Secrets 呢?看起来你是在抄袭他们的东西。
DeepSecrets 最初于 2023 年 4 月发布——比 Semgrep Secrets 推出早了六个月。我们共享相似的原则,但 DeepSecrets 是 100% 免费/开源的,并且利用了显著更广泛的多语言跟踪面。
其他工具只扫描它们已知的内容,而 DeepSecrets 利用词法分析器。这使它能够发现稀有配置格式和自定义代码块中隐藏的危险凭据,而这些是基准测试可能没有数据集的。
| 功能 / 能力 | DeepSecrets 2.3 | Gitleaks 8.30 | Betterleaks 1.8 | TruffleHog | Semgrep Secrets |
|---|---|---|---|---|---|
| SecretBench 准确率 | 93% 召回率 91% 精确率 | 85% 召回率 70% 精确率 | 85% 召回率 61% 精确率 | 未重新测量 | 未评估 |
| 价格与许可 | 免费 / 开源 | 免费 / 开源 | 免费 / 开源 | 免费 / 开源 | 商业 / 付费 |
| 分析类型 | 语义 / 正则 | 纯文本正则 / 熵 | 纯文本正则 / 熵 | 纯文本正则 / 熵 | 语义 |
| 语言支持 | 约 600 种词法分析 (14 种支持变量) | 上下文无关(文本) | 上下文无关(文本) | 上下文无关(文本) | 有限子集 |
| 预哈希验证 | 是(通过 Hashed Engine) | 否 | 否 | 否 | 否 |
| 上下文感知熵 | 是(已赋值) | 否(整个文件文本) | 否(整个文件文本) | 否(整个文件文本) | 是 |
| 高级 SARIF 输出 | 是(置信度层级与标签) | 基础 | 基础 | 基础 | 是 |
SecretBench,扫描每个文件,统计每个带标签的行,使用 dsbench(参见复现这些数字)。DeepSecrets 2.3、Gitleaks 8.30.1 和 Betterleaks 1.8.1 于 2026 年 10 月和 11 月在相同的测试框架上测量,Gitleaks 和 Betterleaks 使用其默认规则并移除了全局路径允许列表,以便像 DeepSecrets 一样扫描每个文件。TruffleHog 于 2026 年 6 月通过另一种方法测量(52% 召回率,6% 精确率),此后未再测量。
你为什么不构建真正的抽象语法树?这在学术上更正确!