Credactor

发现秘密。修复它。干净提交。

秘密扫描器擅长拉响警报，但在扑灭警报方面却帮不上什么忙。它们把一份泄露凭据的清单交给你，然后清理工作就留给你自己了。Credactor 闭环了整个过程：它找到硬编码的秘密并就地重写，让泄露从检测到修复只需一条命令。

将凭据排除在源代码之外是一项基础安全实践，而非可选项。Credactor 让这一基础变得易于坚守——无论是在提交前于你的机器上，还是在合并前于 CI 中。你可以单独运行它，也可以与你已经信任的扫描器配合使用。

# Credactor 会发现这个：
db_password = "h8Tq2vKp9mRz4Wd"

# 默认情况下，它会将秘密重写为一个在运行时大声失败的哨兵值：
db_password = "REDACTED_BY_CREDACTOR"

# 使用 --replace-with env，它会写入一个从环境变量读取的引用：
db_password = os.environ["DB_PASSWORD"]

脱敏会重写你工作树中的文件。如果秘密已经被提交，请同时轮换密钥并清理历史记录（例如使用 git filter-repo）。重写文件并不能替代撤销已泄露的凭据。

为什么选择 Credactor

• 脱敏，而不仅仅是检测。 大多数扫描器止步于发现。Credactor 会就地替换秘密：默认是一个在运行时失败的响亮的 REDACTED_BY_CREDACTOR 哨兵值，或者是一个语言感知的环境变量引用（Python、JavaScript/TypeScript、Go、Java/Kotlin、Ruby、PHP 和 shell），例如 os.environ["KEY"]。替换后的内容是有效的代码。如果文件尚未包含相应的导入（例如 import os），请添加它。
• 默认安全。 原子写入、自动 .bak 备份、符号链接边界和文件权限防护，以及所有输出中的完整秘密掩码。如果无法写入安全备份，Credactor 会跳过该文件而不是盲目重写，并且写入中途崩溃也会保留原始文件完好无损。
• 零运行时依赖。 纯 Python 3.11+ 标准库，外加一个用于非 UTF-8 编码的可选扩展。
• 为流水线而生。 支持 GitHub Code Scanning 的 SARIF 输出、具有精确退出代码的只读 --ci 门禁、pre-commit 钩子（测试版），以及 Gitleaks 或 TruffleHog 报告的导入。用 Gitleaks 或 TruffleHog 检测，用 Credactor 修复。

安装

pip install credactor

需要 Python 3.11+。无其他依赖。支持 Linux、macOS 和 Windows（CI 已在 Linux 和 Windows 上测试）。

从源码安装：

git clone https://github.com/rxb06/credactor.git
cd credactor
pip install -e .

之后 credactor 即可从任何目录使用。

快速开始

先运行 --dry-run 并在脱敏前审查发现结果。误报是可能存在的，在 --fix-all 下误报会被重写。使用 # credactor:ignore 或 .credactorignore 条目来抑制已知安全的值。

credactor --dry-run .                 # 扫描，不更改任何内容
credactor .                           # 扫描，然后交互式脱敏（每个发现 y/n）
credactor --fix-all .                 # 一次确认后脱敏所有内容
credactor --fix-all --yes .           # 非交互式脱敏（CI / 脚本）
credactor --ci .                      # 只读门禁：有发现时退出码为 1
credactor --replace-with env .        # 脱敏为环境变量引用而非哨兵值

Pre-commit 钩子（测试版）

钩子集成处于测试阶段。在单独依赖它之前，请手动运行 credactor --dry-run .。

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rxb06/credactor
    rev: v2.6.0   # 固定到最新发布标签
    hooks:
      - id: credactor

检测

Credactor 检测最常泄露的凭据类型，并为每种类型分配严重级别，以便你一目了然地分诊。

确定性提供商令牌（上述前缀）无论熵值如何都会被标记。启发式检测器（JWT、连接字符串、十六进制、Base64）必须通过熵下限。独立的十六进制或 Base64 仅在带引号时才会被标记。未加引号的高熵值仅在凭据命名的变量上才会被捕获，这避免了误报 git SHA 和校验和。有关完整的检测和严重级别规则，请参阅手册。

Credactor 的原生规则集比专用扫描器更窄，某些提供商格式（例如 SendGrid、Twilio 和 Slack webhooks）不会被检测到。它的优势在于修复：将其与 Gitleaks 或 TruffleHog 配对以获得最广泛的检测，或单独运行它。

与其他扫描器配对，批量脱敏

Credactor 可以独立运行，也可以与同伴配合使用而更加强大。已经在运行 Gitleaks 或 TruffleHog？将它们的报告传给 Credactor，它会脱敏合并后的集合，并与其自身发现结果去重（重叠时，以较高严重级别为准）。一次修复即可覆盖你的扫描和它们的扫描：

gitleaks dir . -f json -r gitleaks.json
credactor --from-gitleaks gitleaks.json --fix-all --yes .

--from-gitleaks / --from-trufflehog（或 .credactor.toml 中的 [ingest] 表）需要目录目标——将 Credactor 指向扫描器运行过的同一根目录。报告路径相对于工作目录解析，报告是快照：在脱敏或更改目录树后重新生成它。请参阅 CI 集成指南。

更多功能

• 交互式或批量脱敏；通过 --replacement 自定义替换字符串；--scan-history 扫描 git 提交历史
• 安全备份：--secure-delete（覆盖并删除 .bak；提高对抗随意恢复的门槛，并非取证保证）或 --secure-backup-dir 将备份存储在仓库之外
• 内联 # credactor:ignore 和 .credactorignore 白名单（通配符、file:line、值字面量）
• 通过 .credactor.toml 进行每仓库配置
• 开箱即用支持 29 种源文件/配置文件/笔记文件类型（包括 .txt）；--scan-json 包含 JSON；--fail-on-error 在文件无法读取时失败

扫描的文件类型

.py .js .ts .jsx .tsx .sh .bash .env .cfg .ini .toml .yaml .yml .rb .go .java

外加 .env.* / .env-* 变体（.env.local、.env.production）以及 SSH / 私钥文件（id_rsa、id_dsa、id_ecdsa、id_ed25519），均按文件名而非扩展名匹配。JSON 默认被排除，因为 API 响应会产生较高的误报率；添加 --scan-json 以包含它。在命令行上直接指定的文件即使其扩展名不在列表中也会被扫描。

退出代码

供应链加固

安全工具不仅应该运行安全，还应该安装安全。Credactor 的构建和发布流水线已端到端加固；完整细节请参阅安全文档。

• 零运行时依赖。 默认的 pip install credactor 不会引入任何第三方包（仅可选 [encoding] 扩展），因此安装时无需审查任何内容。
• 哈希固定的工具链。 CI 和发布构建从 --require-hashes 锁文件安装，包括构建后端（针对固定 setuptools 的 python -m build --no-isolation），因此被篡改的依赖会导致构建失败。
• 产物与源码逐字节校验。 在每次推送和每次发布前，scripts/audit_wheel.py 将 wheel 和 sdist 与已提交的源码逐字节比较（sha256 对比 git HEAD）；任何新增、缺失或更改的文件都会导致门禁失败，因此构建步骤无法在无人察觉的情况下注入代码。
• SHA 固定、最小权限 CI。 GitHub Actions 固定到提交 SHA，工作流令牌保持狭窄——默认 contents: read，仅发布作业使用 id-token: write。

文档

许可证

Apache 2.0。请参阅 LICENSE。