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 编码的可选扩展。
• 专为流水线打造。 SARIF 输出用于 GitHub 代码扫描，只读的 --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.5.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] 表）需要一个目录目标。参见 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 锁文件安装，包括构建后端（python -m build --no-isolation 使用锁定的 setuptools），因此被篡改的依赖会导致构建失败。
• 构件与源码逐字节校验。 每次推送和每次发布前，scripts/audit_wheel.py 将 wheel 和 sdist 与已提交的源码逐字节比较（sha256 对比 git HEAD）；任何添加、缺失或修改的文件都会导致关卡失败，因此构建步骤无法暗中注入代码。
• SHA 锁定、最小权限的 CI。 GitHub Actions 锁定到提交 SHA，工作流令牌保持狭窄——默认 contents: read，只有发布作业才使用 id-token: write。

文档

许可证

Apache 2.0。请参阅 LICENSE。