CredSweeper
Samsung/CredSweeper加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
2021年，国内某知名云服务商被曝出内部代码仓库意外公开，大量 API 密钥和数据库密码直接暴露在 GitHub 公开仓库中。事后溯源发现，这些凭证在代码里躺了整整两年，没有人察觉。这是 Credential Sweeper（凭证清扫器）诞生的背景——一款由三星电子安全团队开发的开源工具，专门用于在代码库、配置文件甚至二进制文件中"扫出"不该出现的密钥、密码、令牌等敏感凭证。
三星工程师在日常代码审计中发现，传统安全扫描工具要么误报率高得离谱，要么对压缩包、PDF、Word 文档等"非代码文件"束手无策。他们决定自己动手，做一个既能深度扫描各类文件格式、又能借助机器学习压低误报率的全能选手。2021年10月，CredSweeper 以 MIT 许可证正式开源，迅速成为三星内部代码审查流程的标配工具，并被 OpenSSF（Open Source Security Foundation）纳入最佳实践项目。
CredSweeper 最核心的价值，是它对扫描对象的广泛覆盖。大多数同类工具只能处理纯文本源码，而 CredSweeper 能扫描以下"非常规"目标：
之所以能覆盖如此多的格式，是因为 CredSweeper 内置了一个名为 deep_scanner 的模块，包含超过 30 种专项扫描器，每种扫描器负责解析一种特定文件格式。当遇到压缩包时，它会递归解压后再扫描内容；当遇到 Excel 文件时，它能解析单元格中的公式和字符串值。
CredSweeper 的检测逻辑分为三层，层层递进，逐步筛选：
第一层：规则匹配（Rule-based）
内置了 40+ 条检测规则，涵盖 AWS Access Key、Azure Token、GitHub Token、Slack Token、Discord Bot Token、Database Password、API Key、Private Key 等常见凭证类型。每条规则定义了正则表达式模式、验证逻辑和严重等级（high/medium/low/info）。这些规则定义在 credsweeper/rules/config.yaml 中，用户可自行扩展。
第二层：熵值计算（Entropy-based）
密钥和随机字符串具有高信息熵的特点。CredSweeper 对每条可疑候选进行 Base64、Base32、Hex 等编码的熵值分析，过滤掉普通文本描述（如"请输入密码"）和低熵的普通字符串。这一步极大减少了误报。
第三层：机器学习验证（ML Validation）
项目内置了一个 ONNX 格式的轻量级神经网络模型（ml_model/ml_model.onnx），接收可疑行的特征向量（熵值、字符分布、位置特征等），输出一个置信度分数。只有当 ML 模型也认为"这条大概率是凭证"时，才输出最终报告。CredSweeper 团队还开源了配套数据集 CredData，包含 3700+ 条真实凭证样本和 1900 万条负样本，用于模型训练和基准评测。
在 CredData 基准测试中，CredSweeper 取得了 F1=0.859 的成绩，精确率 91.7%，召回率 80.8%，显著优于其他开源凭证扫描工具。
如果说 ML 模型是第一道智能防线，那 filters 目录下的 50+ 个过滤器就是精密的"筛选流水线"。每个过滤器负责一种特定误报场景的排除：
value_blocklist_check：黑名单过滤，常见测试值（如 password123、test_key）直接排除value_camel_case_check：驼峰命名法的变量名（如 myPassword）不是密码value_base64_data_check：纯 Base64 编码的数据块不是密钥value_github_check：GitHub 仓库 URL 中的 token 片段格式验证value_length_check：过短或过长的值不是有效密钥这套过滤器体系是 CredSweeper 区别于简单正则匹配工具的关键——它积累了三星工程师多年代码审计经验，对真实代码库中的误报模式进行了系统性归纳。
CredSweeper 的安装极其简单：
pip install credsweeper
credsweeper --path ./src --save-json output.json
扫描结果默认输出 JSON 格式，包含凭证类型、严重等级、ML 置信度、所在文件路径和行号。项目还提供了官方 GitHub Action (action.yml)，可零配置集成到 GitHub Actions 流水线中，在每次代码提交时自动扫描。新增的 --hashed 参数默认对报告中的凭证值做哈希处理，避免扫描结果本身泄露敏感信息。
支持 Python 3.10 到 3.14，覆盖主流 Python 版本。依赖中没有 C 扩展，macOS 和 Linux 用户可直接 pip 安装，Windows 用户也只需安装 GitPython 时附带一个轻量级 C 库。
项目采用标准 Python 包结构：
credsweeper/scanner/：扫描器核心，定义了不同粒度的扫描策略（文件级、行级）credsweeper/deep_scanner/：30+ 种文件格式的专项解析器，递归处理嵌套格式credsweeper/filters/：50+ 个过滤器，逐层过滤误报候选credsweeper/ml_model/：ONNX 机器学习验证模型credsweeper/rules/：检测规则配置（YAML）credsweeper/common/：通用常量和工具函数代码质量方面，项目使用 pytest 做单元测试（覆盖率较高），配合 mypy 静态类型检查、flake8 代码风格检查、pylint 代码质量分析，以及 pre-commit 钩子保证提交质量。CII Best Practices 银牌认证和 OpenSSF Scorecard 评分证明了其在安全实践上的投入。
不支持 Windows 深度扫描：在 Windows 环境下，部分压缩格式（如 SquashFS、RPM）的解析库无法工作，扫描能力会有所下降。
ML 模型需额外下载：ONNX 模型文件较大，首次安装时作为单独资源下载，国内网络环境下可能遇到困难。
规则覆盖有边界：对于非英文代码库中出现的本土化密钥格式，或企业内部自定义的凭证模式，默认规则可能漏报，需要自行编写扩展规则。
CredSweeper 填补了开源凭证扫描领域的一个重要空白——在保证低误报的前提下，对现代代码仓库中形形色色的文件格式进行全面扫描。三星安全团队的工程实践背书，加上 OpenSSF 和 CII Best Practices 的认证，使其成为目前最可靠的代码凭证泄露检测工具之一。对于任何有代码安全合规需求的团队，将 CredSweeper 集成到 CI/CD 流水线，是一个投入产出比极高的安全加固选择。
项目亮点：