开发安全利器：detect-secrets 敏感信息扫描工具实战指南

在现代软件开发流程中，代码安全已成为不可忽视的重要环节。尤其是在 DevSecOps 的理念逐渐普及的今天，如何在开发早期就发现并消除潜在的安全隐患，成为每一个开发者和安全工程师必须面对的问题。其中，敏感信息泄露（Secrets Leakage）是最常见也最危险的安全问题之一。

本文将介绍一款由 Yelp 开源的敏感信息扫描工具 ------ detect-secrets，它如何帮助我们在代码提交前发现潜在的密钥、密码、令牌等敏感信息，并结合实际使用场景，分享其在自动化流水线和本地开发中的应用方式。

---

一、为什么需要敏感信息扫描？

在日常开发中，开发者可能会不小心将 API 密钥、数据库密码、OAuth token 等敏感信息硬编码进代码中，并提交到 Git 仓库。这些信息一旦泄露，可能导致严重的安全事故。

根据 OWASP 的 DSOMM（DevSecOps Maturity Model）要求，部分产品需达到 Level 1 或 Level 2 的安全成熟度，其中就包括对敏感信息的自动化检测与防护。detect-secrets 正是为此而生。

---

二、detect-secrets 工具简介

detect-secrets 是一个基于 Python 的命令行工具，支持插件化扩展，能够扫描 Git 仓库或任意目录中的文件，识别潜在的敏感信息。它的核心优势包括：

• 持续维护：每年发布多个新版本，最新版本为 v1.5.0（2024年5月发布）
• 开源协议：采用 Apache-2.0 许可
• 广泛适配：支持 Git 仓库和非 Git 目录
• 性能优化：通过 diff 和正则匹配识别新增 secrets，避免全量扫描

此外，它还支持与 pre-commit 框架集成，实现开发者本地提交前的自动扫描。

---

三、与其他工具对比

detect-secrets 与 Coverity、MS CredScan、GitLeaks、VDOO 等工具并列。相比之下，detect-secrets 具有以下优势：

工具名称	特点
Coverity	C/C++ 需启用 HARDCODED_CREDENTIALS 检查器
MS CredScan	已于 2023 年 9 月弃用，推荐使用 GitHub Advanced Security
GitLeaks	使用 Go 编写，以 Docker 镜像形式发布
VDOO	仅提供第三方二进制，无源码
detect-secrets	免费、开源、支持插件、性能优异

---

四、detect-secrets 使用指南

1. 准备工作

detect-secrets source code: https://github.com/Yelp/detect-secrets

1. 安装工具：

   pip install detect-secrets

2. 创建 baseline 文件（扫描结果）：

   detect-secrets scan > .secrets.baseline

3. 扫描非 Git 文件夹：

   detect-secrets -C /path/to/directory scan > /path/to/directory/.secrets.baseline

注意：.secrets.baseline 文件需为 ANSI 格式，否则后续命令可能报错。

---

2. 集成 Pre-commit 钩子

detect-secrets 支持两种方式集成到开发流程中：

• 开发者本地钩子：在提交前自动扫描
• Jenkins 自动化钩子：结合 CI/CD 流程进行扫描

配置步骤如下：

1. 安装 pre-commit：

   pip install pre-commit

2. 在项目根目录创建 .pre-commit-config.yaml 文件，添加 detect-secrets 配置

3. 安装钩子：

   pre-commit install

4. 执行扫描：

   pre-commit run --all-files

---

3. 审计与报告

detect-secrets 提供审计功能，用于分析 baseline 文件中的内容：

• 查看审计结果：

  detect-secrets audit .secrets.baseline

• 生成报告：

  detect-secrets audit --report .secrets.baseline > SecretReport.txt

• 仅输出真实 secrets：

  detect-secrets audit --report --only-real .secrets.baseline > SecretReport.txt

• 查看统计信息：

  detect-secrets audit --stats .secrets.baseline > status.txt

---

五、插件与过滤器机制

detect-secrets 的强大之处在于其插件和过滤器系统：

• 插件：用于识别不同类型的 secrets（如 AWS 密钥、Slack token 等）
• 过滤器：用于排除误报，提高准确率

你可以通过以下命令查看和管理插件：

detect-secrets scan --list-all-plugins
detect-secrets scan --disable-plugin AWSKeyDetector

此外，还支持自定义插件和过滤器，满足特定业务需求。详细文档可参考：

• 插件开发指南
• 过滤器开发指南

---

六、总结与建议

detect-secrets 是一款轻量级、高性能、可扩展的敏感信息扫描工具，适合集成到 DevSecOps 流程中，帮助开发团队在代码提交前发现并消除潜在的安全隐患。

建议开发团队在以下场景中使用 detect-secrets：

• 本地开发阶段，结合 pre-commit 实现自动扫描
• 自动化流水线中，结合 Jenkins 或 GitHub Actions 实现持续检测
• 安全审计阶段，生成 secrets 报告并进行合规检查

安全无小事，从每一次提交做起。detect-secrets，让你的代码更安全。