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 .php .cs .kt .tf .hcl .conf .config .properties .xml .pem .key .crt .txt

外加 .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。