找到密钥。修复它。干净提交。
密钥扫描器擅长拉响警报，却不太能帮你把火扑灭。它们丢给你一份泄露凭据的清单，剩下的清理工作全归你。Credactor 补上了这个闭环：它找到硬编码的密钥并就地重写，让一次泄露从检测到修复只需一条命令。
让凭据远离源代码是一项基线安全实践，而非可选项。Credactor 让守住这条基线变得成本低廉——无论是在提交前的本机上，还是在合并前的 CI 中。你可以单独运行它，也可以与已经信任的扫描器搭配使用。
# Credactor 找到这个：
db_password = "h8Tq2vKp9mRz4Wd"
# 默认情况下，它会把密钥重写为一个在运行时大声失败的哨兵值：
db_password = "REDACTED_BY_CREDACTOR"
# 使用 --replace-with env 时，它会写入一个从环境读取的引用：
db_password = os.environ["DB_PASSWORD"]
脱敏会重写你工作树中的文件。如果密钥已经被提交，请轮换密钥并同时清理历史记录（例如使用
git filter-repo）。重写文件不能替代吊销已泄露的凭据。
REDACTED_BY_CREDACTOR 哨兵值，或者是一个语言感知的环境变量引用（Python、JavaScript/TypeScript、Go、Java/Kotlin、Ruby、PHP 和 shell），例如 os.environ["KEY"]。替换结果是有效代码。如果文件中尚未包含相应的导入（例如 import os），请自行添加。.bak 备份、符号链接边界和文件权限防护，以及所有输出中的完整密钥掩码。如果无法写入安全备份，Credactor 会跳过该文件，而不是盲目重写；写入中途崩溃也会让原文件保持完好。--ci 门禁、pre-commit 钩子，以及导入 Gitleaks、TruffleHog 或 Betterleaks 报告。用你已经在运行的扫描器检测，用 Credactor 修复。pip install credactor
需要 Python 3.11+。无其他依赖。可在 Linux、macOS 和 Windows 上运行（CI 已在 Linux 和 Windows 上测试）。
在 macOS 和 Linux 上，你也可以改用 Homebrew 安装：
brew install rxb06/tap/credactor
该 formula 会安装到它自己的 virtualenv 中，并包含可选的
[encoding] 附加项，因此通过 Homebrew 安装也能检测非 UTF-8
文件中的密钥。普通的 pip install credactor 不包含该附加项；如果你想要同样的覆盖范围，请用
pip install 'credactor[encoding]' 添加它。
从源码安装：
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 . # 脱敏为环境变量引用而非哨兵值
该钩子只对暂存内容进行门禁，因此已经提交的密钥不会被 再次标记。使用
credactor --scan-history .检查仓库中已有的内容。
# .pre-commit-config.yaml
repos:
- repo: https://github.com/rxb06/credactor
rev: v2.7.4 # 固定到最新的发布标签
hooks:
- id: credactor
- uses: rxb06/[email protected]
该 action 始终传入 --ci，因此它只报告和门禁，绝不重写
检出内容。有发现会使该步骤失败；设置 fail-on-findings: false 可只报告
而不门禁。无论哪种情况，出错都会使该步骤失败。
上传到 Code Scanning 而不是在有发现时失败：
- uses: rxb06/[email protected]
with:
format: sarif
upload-sarif: true
fail-on-findings: false
该 job 需要 permissions: security-events: write 才能上传。有关每个输入
（包括导入 Gitleaks、TruffleHog 和 Betterleaks 报告），请参阅
CI 集成指南。
Credactor 检测最常泄露的凭据类型，并为每种类型分配严重级别，以便你一眼就能分诊。
| 类别 | 示例 | 严重级别 |
|---|---|---|
| 云服务商密钥 | AWS (AKIA…)、GCP (AIza…)、Stripe (sk_live_…)、Slack (xoxb-…) | 严重 |
| 平台令牌 | GitHub (ghp_、github_pat_)、GitLab (glpat-)、npm (npm_)、PyPI (pypi-) | 严重 |
| 私钥 | PEM 块 (-----BEGIN … PRIVATE KEY-----) | 严重 |
| JWT | eyJ… 三段式令牌 | 高 |
| 连接字符串 | 含内联凭据的 URL (scheme://user:pass@host) | 高 |
| 凭据变量 | password = "…"、api_key = "…"、secret_key = "…" | 高/中/低 |
| XML 属性 | <add key="Password" value="…" /> | 高/中/低 |
| 高熵字符串 | 带引号的十六进制（32–64 字符）/ Base64（60+ 字符） | 中/低 |
确定性的服务商令牌（上述前缀）无论熵值如何都会被标记。启发式检测器（JWT、连接字符串、十六进制、Base64）必须达到熵值下限。独立的十六进制或 Base64 仅在带引号时才会被标记。不带引号的高熵值仅在凭据命名的变量上才会被捕获，从而避免误伤 git SHA 和校验和。完整的检测和严重级别规则，请参阅手册。
Credactor 的原生规则集比专用扫描器更窄，某些服务商格式（例如 SendGrid、Twilio 和 Slack webhook）不会被检测到。它的优势在于修复：将其与 Gitleaks、TruffleHog 或 Betterleaks 搭配可获得最广泛的检测，或者单独运行它。
Credactor 可以独立使用，而结伴时会更强大。已经在运行 Gitleaks、TruffleHog 或 Betterleaks？把它们的报告传给 Credactor，它就会脱敏合并后的集合，并与其自身发现去重（重叠时，以更高的严重级别为准）。一次修复即可覆盖你和它们的扫描：
gitleaks dir . -f json -r gitleaks.json
credactor --from-gitleaks gitleaks.json --fix-all --yes .
betterleaks dir . -f json -r betterleaks.json
credactor --from-betterleaks betterleaks.json --fix-all --yes .
--from-gitleaks / --from-trufflehog / --from-betterleaks（或 .credactor.toml 中的 [ingest] 表）需要一个目录目标——将 Credactor 指向扫描器所针对的同一根目录。报告路径相对于工作目录解析，而报告是一个快照：在脱敏或更改目录树后请重新生成它。请参阅 CI 集成指南。
--replacement 自定义替换字符串；--scan-history 扫描 git 提交历史--secure-delete（覆盖并删除 .bak；提高随意恢复的门槛，但并非取证级保证）或 --secure-backup-dir 将备份存储在仓库之外# credactor:ignore 和 .credactorignore 允许列表（glob、file:line、值字面量）.credactor.toml 进行按仓库配置.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 以包含它。在命令行中直接指定名称的文件即使其扩展名不在该列表中也会被扫描。
| 代码 | 含义 |
|---|---|
0 | 无发现，或全部已解决 |
1 | 未解决的发现 |
2 | 错误（例如：路径错误、危险的 --replacement、--ci --fix-all、缺失或无效的导入报告，或 --fail-on-error 遇到无法读取的文件） |
一个安全工具不仅运行起来要安全，安装起来也应当安全。Credactor 的构建和发布流水线端到端加固；完整细节见安全文档。
pip install credactor 不拉取任何第三方包（仅可选的 [encoding] 附加项），因此安装时无需审查任何东西。--require-hashes 锁文件安装，包括构建后端（针对固定版本的 setuptools 运行 python -m build --no-isolation），因此被篡改的依赖会导致构建失败。scripts/audit_wheel.py 会将 wheel 和 sdist 与已提交的源码逐字节比较（sha256 对比 git HEAD）；任何新增、缺失或改动的文件都会使门禁失败，因此构建步骤无法在无人察觉的情况下注入代码。contents: read，仅发布 job 使用 id-token: write。| 文档 | 描述 |
|---|---|
| 安装指南 | 安装、配置、CI/CD 集成 |
| 手册 | 完整参考：每个标志、模式和组合，替换和备份行为，检测和严重级别，退出码，以及限制（行为经测试验证） |
| 示例 | 常见工作流及输出 |
| CI 集成 | Pre-commit 钩子、CI 流水线 |
| 安全 | 威胁模型、加固措施、已知限制 |
| 变更日志 | 版本历史 |
| 贡献 | 开发环境搭建、代码风格、PR 流程 |
| 免责声明 | 限制、安全使用、保证 |
Apache 2.0。见 LICENSE。