[](https://pypi.org/project/credactor/)
[](https://github.com/rxb06/credactor/actions/workflows/ci.yml)
[](https://github.com/rxb06/credactor/blob/main/LICENSE)
# Credactor
**秘密を発見し、修正し、クリーンにコミットする。**
シークレットスキャナは警告を発するのは得意だが、その問題を解決するのはあまり得意ではない。漏洩した認証情報のリストを渡して、後始末はあなたに任せる。Credactor はこのループを閉じる。ハードコードされた秘密を発見し、その場で書き換えるので、漏洩は検出から修正まで1つのコマンドで完了する。
<img alt="Credactor: scan, redact, commit clean" src="https://assets.kitploit.com/production/public/readmes/9024/3abc948c69d942141474c93431f182cf98a738ebbd43f94eef8f92fda2498f18.png" width="1280" height="320" />
認証情報をソースコードに含めないことは、オプションではなく基本的なセキュリティプラクティスである。Credactor はその基本を低コストで維持できるようにする。コミット前のあなたのマシン上でも、マージ前の CI でも。単独で実行することも、すでに信頼しているスキャナと並行して実行することもできる。
```python
# Credactor finds this:
db_password = "h8Tq2vKp9mRz4Wd"
# By default it rewrites the secret as a sentinel that fails loudly at runtime:
db_password = "REDACTED_BY_CREDACTOR"
# With --replace-with env, it writes a reference that reads from the environment:
db_password = os.environ["DB_PASSWORD"]
```
> リダクションは**作業ツリー**内のファイルを書き換える。秘密がすでにコミットされている場合は、キーをローテーションし、履歴もクリーンアップすること（例えば `git filter-repo` を使用）。ファイルの書き換えは、漏洩した認証情報の失効の代わりにはならない。
---
## Credactor を選ぶ理由
- **検出だけでなくリダクション。** ほとんどのスキャナは検出して終わり。Credactor はその場で秘密を置き換える。デフォルトでは実行時に失敗する大きな `REDACTED_BY_CREDACTOR` センチネル、または言語を認識した環境変数参照（Python、JavaScript/TypeScript、Go、Java/Kotlin、Ruby、PHP、シェル）例えば `os.environ["KEY"]`。置き換えは有効なコードである。ファイルに一致するインポート（例えば `import os`）がまだ含まれていない場合は、追加すること。
- **デフォルトで安全。** アトミック書き込み、自動 `.bak` バックアップ、シンボリックリンク境界とファイルパーミッションのガード、すべての出力での完全な秘密のマスキング。安全なバックアップを書き込めない場合、Credactor は盲目的に書き換えるのではなくファイルをスキップし、書き込み中のクラッシュでも元のファイルは無傷のまま残る。
- **ランタイム依存ゼロ。** 純粋な Python 3.11+ 標準ライブラリ、加えて非 UTF-8 エンコーディング用のオプションの追加機能。
- **パイプライン向けに構築。** GitHub Code Scanning 用の SARIF 出力、正確な終了コードを備えた読み取り専用の `--ci` ゲート、pre-commit フック、Gitleaks、TruffleHog、Betterleaks レポートの取り込み。すでに実行しているスキャナで検出し、Credactor で修復する。
## インストール
```bash
pip install credactor
```
Python 3.11+ が必要。他の依存関係はない。Linux、macOS、Windows で動作する（CI は Linux と Windows でテスト済み）。
macOS と Linux では、代わりに Homebrew でインストールできる：
```bash
brew install rxb06/tap/credactor
```
この formula は独自の virtualenv にインストールし、オプションの `[encoding]` extra を含むため、Homebrew インストールでは非 UTF-8 ファイル内の秘密も検出できる。通常の `pip install credactor` ではこの extra は含まれない。同じカバレッジが必要な場合は `pip install 'credactor[encoding]'` で追加する。
ソースから：
```bash
git clone https://github.com/rxb06/credactor.git
cd credactor
pip install -e .
```
これで `credactor` はどのディレクトリからでも動作する。
## クイックスタート
> まず `--dry-run` を実行し、リダクションの前に検出結果を確認すること。誤検出の可能性があり、`--fix-all` では誤検出も書き換えられる。既知の安全な値は `# credactor:ignore` または `.credactorignore` エントリで抑制する。
```bash
credactor --dry-run . # scan, change nothing
credactor . # scan, then redact interactively (y/n per finding)
credactor --fix-all . # redact everything after one confirmation
credactor --fix-all --yes . # redact non-interactively (CI / scripts)
credactor --ci . # read-only gate: exit 1 on findings
credactor --replace-with env . # redact to env-var references instead of the sentinel
```
### Pre-commit フック
> フックはステージングされた内容のみをゲートするため、すでにコミットされた秘密は再検出されない。リポジトリにすでに含まれているものを確認するには `credactor --scan-history .` を使用する。
```yaml
# .pre-commit-config.yaml
repos:
- repo: https://github.com/rxb06/credactor
rev: v2.7.4 # pin to the latest release tag
hooks:
- id: credactor
```
### GitHub Action
```yaml
- uses: rxb06/[email protected]
```
このアクションは常に `--ci` を渡すため、報告とゲートは行うがチェックアウトを書き換えることはない。検出結果はステップを失敗させる。ゲートせずに報告するには `fail-on-findings: false` を設定する。エラーはどちらの場合もステップを失敗させる。
検出結果で失敗させる代わりに Code Scanning にアップロードする：
```yaml
- uses: rxb06/[email protected]
with:
format: sarif
upload-sarif: true
fail-on-findings: false
```
アップロードにはジョブに `permissions: security-events: write` が必要。Gitleaks、TruffleHog、Betterleaks レポートの取り込みを含むすべての入力については、[CI 統合ガイド](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md#github-action)を参照。
## 検出
Credactor は最も頻繁に漏洩する認証情報の種類を検出し、それぞれに重大度を割り当てるので、一目でトリアージできる。
| カテゴリ | 例 | 重大度 |
|---|---|---|
| クラウドプロバイダーキー | AWS (`AKIA…`)、GCP (`AIza…`)、Stripe (`sk_live_…`)、Slack (`xoxb-…`) | Critical |
| プラットフォームトークン | GitHub (`ghp_`、`github_pat_`)、GitLab (`glpat-`)、npm (`npm_`)、PyPI (`pypi-`) | Critical |
| 秘密鍵 | PEM ブロック (`-----BEGIN … PRIVATE KEY-----`) | Critical |
| JWT | `eyJ…` の3セグメントトークン | High |
| 接続文字列 | インライン認証情報を含む URL (`scheme://user:pass@host`) | High |
| 認証情報変数 | `password = "…"`、`api_key = "…"`、`secret_key = "…"` | High/Medium/Low |
| XML 属性 | `<add key="Password" value="…" />` | High/Medium/Low |
| 高エントロピー文字列 | 引用符付き hex (32–64 文字) / Base64 (60+ 文字) | Medium/Low |
決定論的なプロバイダートークン（上記のプレフィックス）はエントロピーに関係なく検出される。ヒューリスティック検出器（JWT、接続文字列、hex、Base64）はエントロピーの下限をクリアする必要がある。単独の hex または Base64 は引用符で囲まれている場合にのみ検出される。引用符で囲まれていない高エントロピー値は、認証情報名の変数でのみ検出されるため、git SHA やチェックサムは除外される。完全な検出と重大度のルールについては、[マニュアル](https://github.com/rxb06/credactor/blob/main/docs/manual.md#detection--severity)を参照。
> Credactor のネイティブルールセットは専用スキャナよりも狭く、一部のプロバイダー形式（例えば SendGrid、Twilio、Slack webhook）は検出されない。その強みは修復にある。最も広い検出には Gitleaks、TruffleHog、Betterleaks と組み合わせるか、単独で実行する。
## 別のスキャナと組み合わせて、まとめてリダクション
Credactor は単独でも機能するが、組み合わせるとさらに強力になる。すでに Gitleaks、TruffleHog、Betterleaks を実行している？そのレポートを Credactor に渡すと、統合されたセットをリダクションし、自身の検出結果と重複排除する（重複する場合は重大度が高い方が優先される）。1回の修復パスで、あなたのスキャンと彼らのスキャンの両方をカバーする：
```bash
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 統合ガイド](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md)を参照。
## その他の機能
- 対話的またはバッチリダクション、`--replacement` によるカスタム置換文字列、git コミット履歴をスキャンする `--scan-history`
- 安全なバックアップ：`--secure-delete`（`.bak` を上書きして削除する。カジュアルな復元に対するハードルを上げるが、フォレンジック保証ではない）または `--secure-backup-dir` でリポジトリ外にバックアップを保存
- インライン `# credactor:ignore` と `.credactorignore` 許可リスト（glob、`file:line`、値リテラル）
- `.credactor.toml` によるリポジトリごとの設定
- 29 種類のソース/設定/ノートファイルタイプを標準でサポート（`.txt` を含む）。JSON を含めるには `--scan-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 のビルドとリリースパイプラインはエンドツーエンドで強化されている。詳細は[セキュリティドキュメント](https://github.com/rxb06/credactor/blob/main/docs/security.md#supply-chain-hardening)を参照。
- **ランタイム依存ゼロ。** デフォルトの `pip install credactor` はサードパーティパッケージを一切取り込まない（オプションの `[encoding]` extra のみ）ため、インストール時に検証すべきものがない。
- **ハッシュ固定のツールチェーン。** 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`。
## ドキュメント
| ドキュメント | 説明 |
|----------|-------------|
| [セットアップガイド](https://github.com/rxb06/credactor/blob/main/docs/setup.md) | インストール、設定、CI/CD 統合 |
| [マニュアル](https://github.com/rxb06/credactor/blob/main/docs/manual.md) | 完全なリファレンス：すべてのフラグ、モード、組み合わせ、置換とバックアップの動作、検出と重大度、終了コード、制限事項（動作はテストで検証済み） |
| [例](https://github.com/rxb06/credactor/blob/main/docs/examples.md) | 出力付きの一般的なワークフロー |
| [CI 統合](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md) | Pre-commit フック、CI パイプライン |
| [セキュリティ](https://github.com/rxb06/credactor/blob/main/docs/security.md) | 脅威モデル、強化策、既知の制限事項 |
| [変更履歴](https://github.com/rxb06/credactor/blob/main/CHANGELOG.md) | バージョン履歴 |
| [コントリビューション](https://github.com/rxb06/credactor/blob/main/CONTRIBUTING.md) | 開発セットアップ、コードスタイル、PR プロセス |
| [免責事項](https://github.com/rxb06/credactor/blob/main/docs/DISCLAIMER.md) | 制限事項、安全な使用、保証 |
## ライセンス
Apache 2.0。[LICENSE](https://github.com/rxb06/credactor/blob/main/LICENSE) を参照。
