sainakakkar2006/pii-secret-scanner

# secret-scanner-cli 作者：Saina Kakkar ### 项目描述 一款 DevSecOps 命令行工具，可在泄露的凭据进入公共仓库之前将其拦截。它会扫描代码库中类似于机密的内容（API 密钥、访问令牌、密码、私钥头部），在输出中对敏感值进行掩码处理，并返回对 CI 友好的退出代码，以便流水线能够自动拦截导致泄露的提交。 ``` graph LR A[Walk files] --> B[Detectors
regex + entropy] B --> C[Findings] C --> D[Mask values] D --> E[Text or JSON report
+ exit code for CI] ``` ## 检测内容 - 类似机密的环境变量赋值（`API_KEY=...`、`PASSWORD=...`） - 私钥头部（`-----BEGIN ... PRIVATE KEY-----`） - GitHub 风格和 Slack 风格的 token - AWS 风格的访问密钥 ID - 看起来像凭据的高熵长字符串 检测结果在设计上属于启发式判定。其目标是在推送前发出强烈的警告，而不是去证明某个字符串就是一个有效的凭据。 ## 快速开始 扫描内置的示例项目： ``` PYTHONPATH=src python -m secret_scanner scan examples/sample_project --no-fail ``` 生成 JSON 报告（用于 CI 产物或工具集成）： ``` PYTHONPATH=src python -m secret_scanner scan examples/sample_project --format json --out reports/findings.json ``` ### 示例输出 ``` 2 finding(s) examples/sample_project/.env.example:1 [MEDIUM] Environment assignment with secret-like name value: API_****************-key examples/sample_project/config.py:1 [MEDIUM] Environment assignment with secret-like name value: PASS*****************word ``` 注意，这些值已被掩码处理。这是刻意为之。如果秘密扫描器将完整的机密回显到终端或 CI 日志中，它本身就会成为一种泄露途径。我保留了开头和结尾的几个可见字符，这样你仍然可以分辨出它找到了哪个机密。 ## CLI 参考 只有一个子命令 `scan`。以下是它的所有选项： | 参数 | 默认值 | 功能说明 | |---|---|---| | `path` | （必填） | 要扫描的文件或目录（目录会被递归遍历） | | `--format` | `text` | 报告格式：`text` 或 `json` | | `--out` | 无 | 将报告写入文件，而不仅仅是输出到 stdout | | `--no-fail` | 关闭 | 始终以代码 0 退出，即使存在检测结果 | 退出代码：`0` 表示没有检测结果（或者设置了 `--no-fail`），非零表示存在检测结果。无需记住其他内容。 ## CI 集成 得益于退出代码机制，只需在流水线中添加一行代码即可拦截构建： ``` - run: PYTHONPATH=src python -m secret_scanner scan . ``` 使用 `--no-fail` 进行仅生成报告的运行，例如在一个夜间作业中，将 JSON 报告作为产物收集，而不会阻碍任何人的操作。 ## 项目布局 ``` src/secret_scanner/ cli.py argument parsing and the scan subcommand scanner.py file walking and running the rules over each line rules.py the detectors: env assignments, key headers, tokens, entropy reporting.py text / json formatters and value masking examples/sample_project/ a fake project with planted "secrets" to scan tests/ scanner, reporting, and CLI tests ``` `rules.py` 中的每条规则都是一个小巧且独立的匹配器。要添加新的检测器，你只需编写一个函数并将其注册即可。无需更改其他任何内容，这正是我在第一次尝试后所期望的结果。 ## 验证 ``` PYTHONPATH=src python -m unittest discover -s tests ``` ## 补充说明 - **调整熵值是最令人头疼的部分。** 一个能够捕获真实 token 的阈值也会误报 git 哈希和压缩过的代码。我最终决定将熵值与长度和上下文（字符串出现的位置）结合起来，而不是仅仅依靠熵值，这消除了我测试文件中的大部分干扰。 - **最初尝试的是使用一个巨大的正则表达式。** 它很快就变得难以阅读。现在，每条规则都是一个小巧且独立的匹配器，可以在不触碰扫描引擎的情况下进行添加或调整。我的 [mcpscan](https://github.com/sainakakkar2006/mcpscan) 项目后来直接重用了这些检测器，这证明这种拆分是正确的。 - **对失败模式进行测试。** 输出掩码和退出代码行为都经过了单元测试的边缘情况验证，而不是事后补充。对于安全工具而言，失败模式恰恰是测试最关键的地方。 ## 许可证 MIT。请参阅 [LICENSE](LICENSE) 文件。简而言之：只要保留许可证文本，你就可以使用、复制、修改和重新分发此代码，包括商业用途。不提供任何担保。

标签：DevSecOps, Python, StruQ, 上游代理, 敏感信息扫描, 文档结构分析, 无后门, 逆向工具