[](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つのコマンドで「発見」から「修正」へと変わります。ローカルマシン上でも、pre-commit フックとしても、CI ゲートとしても動作し、Gitleaks、TruffleHog、Betterleaks が見つけたものも修正できます。
<img alt="Credactor: スキャン、秘匿化、クリーンにコミット" src="https://assets.kitploit.com/production/public/readmes/9024/3abc948c69d942141474c93431f182cf98a738ebbd43f94eef8f92fda2498f18.png" width="100%" />
```python
# Before
db_password = "h8Tq2vKp9mRz4Wd"
# credactor --fix-all . (default: a sentinel that fails loudly at runtime)
db_password = "REDACTED_BY_CREDACTOR"
# credactor --replace-with env --fix-all . (read it from the environment)
db_password = os.environ["DB_PASSWORD"]
```
> **リダクションは作業ツリーをクリーンにします。** 資格情報を失効させるわけではなく、
> git 履歴には触れません。シークレットが一度でもコミットされたり共有されたりした場合は、
> ローテーションし、そこからも消す必要があるなら履歴を書き換えてください(例えば
> `git filter-repo` を使って)。
## Credactor を選ぶ理由
- **指摘するだけでなく修正します。** 各検出結果は、センチネル、独自のマーカー、またはファイル自体の言語での環境変数参照にその場で置き換えられます。
- **慎重な書き込み。** 各編集はメモリ上で計画され、まずバックアップされ(モード `0600`)、一時ファイルに書き込まれてから所定の場所にリネームされます。実行中に変更されたファイル、スキャンルートの外に出るパス、秘密鍵ブロックは警告付きでスキップされ、その検出結果は報告されたままになります。
- **既に実行しているスキャナーと連携します。** Gitleaks、TruffleHog、Betterleaks のレポートを渡すと、それらの検出結果と自身の検出結果を重複排除した1回のパスで修正します。
- **パイプライン向けに設計。** 明確な終了コードを備えた読み取り専用の `--ci` ゲート、GitHub Code Scanning 向けの行・列位置付き SARIF 2.1.0、GitHub Action、pre-commit フック。シークレットはすべてのレポート形式でマスクされ、テキスト出力はクリーンアップされるため、スキャン対象ファイルがエスケープシーケンスや CI ワークフローコマンドをターミナルやログに注入することはできません。
- **リリースはソースと照合して検証。** ランタイム依存のない純粋な Python 3.11+ 標準ライブラリ。リリースが PyPI に届く前に、wheel と sdist 内のすべての Credactor ファイルがタグ付けされたソースとバイト単位で比較され、パッケージメタデータが `pyproject.toml` と一致している必要があります([サプライチェーンの強化](#supply-chain-hardening)を参照)。
単独では適さない場合:組み込みルールは数百のプロバイダーではなく、最も頻繁に漏れる資格情報形式をカバーしており、シークレットが有効かどうかはチェックしません。クリーンな実行結果はルールに何も一致しなかったという意味であり、コードにシークレットがないという意味ではありません。網羅性のために専用スキャナーと組み合わせてください([独自のスキャナーを持ち込む](#bring-your-own-scanner)を参照)。
## インストール
```bash
pip install credactor
```
[uv](https://docs.astral.sh/uv/) を使用して、ツールとしてインストールするか、インストールせずに一度だけ実行できます:
```bash
uv tool install credactor
uvx credactor --dry-run .
```
または、macOS と Linux では Homebrew を使用します:
```bash
brew install rxb06/tap/credactor
```
Python 3.11 以降が必要です。CI では Linux と Windows、Python 3.11 から 3.13 でテストされています。UTF-8、Latin-1、単純な UTF-16 以外のエンコーディングのファイルについては、オプションの追加パッケージをインストールしてください: `pip install 'credactor[encoding]'` または `uv tool install 'credactor[encoding]'`(Homebrew の formula には含まれています)。
## クイックスタート
**1. 検出結果を確認する。** 何も変更されません。
```bash
credactor --dry-run .
```
```text
======================================================================
CREDENTIAL SCAN REPORT -- 2 finding(s) in 1 file(s)
======================================================================
FILE: config.py
────────────────────────────────────────────────────────────
Line 3 [HIGH] [variable:db_password]
db_password = "h8Tq[REDACTED]"
Line 4 [CRITICAL] [pattern:AWS access key]
aws_key = "AKIA[REDACTED]"
```
レポートには各シークレットの最初の4文字のみが表示されます。
**2. 修正する。** まず検出結果を確認してください。`--fix-all` は誤検出を含むすべてを書き換えます。1つを残すには、その行に `# credactor:ignore` を追加するか([誤検出の抑制](#suppress-false-positives)を参照)、対話的に修正して `n` と回答してください。各ファイルが変更される前に、元に戻せるよう `.bak` コピーがその隣に書き込まれます。
```bash
credactor . # ask y/N for each finding (needs a terminal)
credactor --fix-all . # fix all after one confirmation
credactor --fix-all --yes . # fix all, no prompt (scripts)
credactor --replace-with env --fix-all . # environment lookups instead of the sentinel
```
Env モードは import ではなく参照を書き込むため、ファイルに `import os` やお使いの言語の同等のものがなければ追加してください。Windows の Git Bash では、インタラクティブモードを `winpty credactor .` として実行してください。
**3. 確認してからバックアップをクリーンアップします。** 各 `.bak` には依然として元のシークレットが含まれており、Credactor は `.gitignore` を編集しないため、単純な `git add .` ではそれがステージングされてしまいます。
```bash
diff config.py.bak config.py # check what changed
cp config.py.bak config.py # undo
```
`*.bak` と `*.credactor.tmp` を `.gitignore` に追加し、問題がなければバックアップを削除してください。最初からバックアップをツリーの外に置くには、修正実行時に `--secure-backup-dir DIR`(リポジトリ外のディレクトリ)を渡します。`--secure-delete` は代わりに各バックアップを完全に消去するため、取り消し手段は git だけになります。
## コマンド一覧
| コマンド | 動作 | ファイルを変更するか |
|---|---|---|
| `credactor --dry-run .` | 検出結果を報告 | いいえ |
| `credactor .` | 1件ずつ確認して修正 | `y` の場合のみ |
| `credactor --fix-all .` | 一度の確認後にすべての検出結果を修正 | はい |
| `credactor --ci .` | ゲート:検出結果があれば終了コード 1 | 決して変更しない |
| `credactor --staged --ci .` | コミット用にステージされたものだけをゲート | 決して変更しない |
| `credactor --scan-history .` | ファイルを変更した直近 100 件のコミットをスキャン | 決して変更しない |
| `credactor --ci -f sarif . > results.sarif` | Code Scanning 向けの SARIF 2.1.0 | 決して変更しない |
| `credactor --ci -f json . > findings.json` | 機械可読なレポート | 決して変更しない |
すべてのフラグと組み合わせは
[マニュアル](https://github.com/rxb06/credactor/blob/main/docs/manual.md)に記載されています。
## pre-commit と CI で使う
### pre-commit フック
```yaml
# .pre-commit-config.yaml
repos:
- repo: https://github.com/rxb06/credactor
rev: v2.7.5
hooks:
- id: credactor
```
```bash
pre-commit install
```
`git commit` のたびにステージされた内容をスキャンし、認証情報が含まれている場合はブロックします。このフックはファイルを書き換えることはありません。pre-commit 3.2.0 以降が必要です。フレームワークを使用しない場合は、[スタンドアロンフック](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md#standalone-git-hook)を参照してください。
### GitHub Action
```yaml
steps:
- uses: actions/checkout@v7
- uses: rxb06/[email protected]
```
この Action は常に `--ci` 付きで実行されるため、チェックアウトを書き換えることはありません。検出結果はステップを失敗させ、エラーも同様に失敗させます。失敗させる代わりに Code Scanning へ報告するには:
```yaml
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v7
- uses: rxb06/[email protected]
with:
format: sarif
upload-sarif: true
fail-on-findings: false
```
[CI 統合ガイド](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md)
には、すべての Action の入力と出力が記載されており、GitLab CI とプレーンなシェル手順についても説明されています。
## 独自のスキャナを持ち込む
すでに Gitleaks、TruffleHog、Betterleaks を実行していますか?そのレポートを Credactor に渡せば、それらの検出結果を自身の検出結果とともに修正し、重複を排除します(重複した場合は、より高い重大度が保持されます)。ネイティブスキャンと同様に、まず `--dry-run` でプレビューしてください。
```bash
gitleaks dir . -f json -r gl.json
credactor --from-gitleaks gl.json --fix-all --yes .
trufflehog filesystem . --no-verification --json > th.json
credactor --from-trufflehog th.json --fix-all --yes .
betterleaks dir . -f json -r bl.json
credactor --from-betterleaks bl.json --fix-all --yes .
```
Credactor をスキャナが実行されたのと同じディレクトリに向け、ツリーが変更された後にレポートを再生成してください。レポートには検出されたすべてのシークレットが平文で保持され、レポート自体はスキャンされません(`.json` には `--scan-json` が必要です)。そのため、リポジトリの外に書き出すか、実行後に削除してください。Credactor が安全に配置できない検出結果(有効な行番号がない、`.git` 配下のパス、単独で照合するには短すぎる値など)は報告されたままとなり、決して書き込まれません。詳細と対応バージョンについては [Manual](https://github.com/rxb06/credactor/blob/main/docs/manual.md#external-scanner-ingestion) を参照してください。
## 検出対象
| カテゴリ | 例 | 重大度 |
|---|---|---|
| クラウドおよび SaaS キー | AWS (`AKIA…`, `ASIA…`)、GCP (`AIza…`)、Stripe ライブ (`sk_live_…`, `rk_live_…`)、Slack (`xoxb-…`, `xoxp-…`) | Critical |
| プラットフォームトークン | GitHub (`ghp_`, `gho_`, `ghs_`, `github_pat_`)、GitLab (`glpat-`)、npm (`npm_`)、PyPI (`pypi-`) | Critical |
| 秘密鍵 | PEM ブロック (`-----BEGIN … PRIVATE KEY-----`、暗号化されたものを含む)、PGP 秘密鍵ブロック | 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 |
| Stripe テストキー | `sk_test_…` | Medium |
| 高エントロピー文字列 | 引用符で囲まれた hex(32〜64文字)または Base64(60文字以上) | Medium または Low |
プロバイダトークンはその形式で照合されるため、コメント内であっても、またランダム性に関係なく検出されます。ヒューリスティックな照合では、十分にランダムに見えることも必要であり、裸の hex や Base64 の値は、引用符で囲まれているか、認証情報名の変数に代入されている場合にのみ報告されるため、git SHA やチェックサムは除外されます。`changeme` のようなプレースホルダ、環境変数の参照、テンプレート参照はフラグ付けされません。
**知っておくとよいこと:**
- **秘密鍵は報告されるだけで、決して書き換えられません。** キーをローテーションし、ブロックを手動で削除してください。`--fix-all` はこれを失敗としてカウントします。
- **履歴は読み取り専用で、上限があります。** `--scan-history` は直近100件のファイル変更コミットを対象とし、リポジトリに100件を超えるコミットがある場合は警告を出します。
- **固定されたファイル種別のセット**がスキャンされます:29個のコード、設定、テキスト拡張子に加え、`.env.*` と SSH キーファイル(`id_rsa` など)です。JSON には `--scan-json` が必要で、それ以外には `.credactor.toml` の `extra_extensions` が必要です。直接指定したファイルは常にスキャンされます。
- **ディレクトリを走査する際、gitignore されたファイルはスキップされます**。これには通常、ローカルの `.env` も含まれます。テキストレポートにはそれらが一覧表示されますが、`-f json` と `-f sarif` では何も出力されません。確認するには直接指定してください:`credactor --dry-run .env`。
- **一部の形式はネイティブでは対象外です**。例えば SendGrid や Twilio のキー、Slack webhook、また実行時に構築されるシークレットや8文字未満の値も対象外です。
完全なルールは [Manual](https://github.com/rxb06/credactor/blob/main/docs/manual.md#detection--severity) に、脅威モデルは [Security doc](https://github.com/rxb06/credactor/blob/main/docs/security.md) に記載されています。
## 書き換え方法
| `--replace-with` | 結果 | 使用する場面 |
|---|---|---|
| `sentinel`(デフォルト) | `"REDACTED_BY_CREDACTOR"` | シークレットをまだ使用しているものを大声で失敗させたい場合 |
| `env` | `os.environ["DB_PASSWORD"]` | 値を環境変数から取得すべき場合 |
| `custom` | `--replacement` による `"<your marker>"` | 独自の規約がある場合 |
Envモードでは、ファイルの言語に応じたルックアップを書き込みます。Pythonでは`os.environ[…]`、JavaScriptとTypeScriptでは`process.env[…]`、Rubyでは`ENV[…]`、Go、Java、Kotlin、PHPではネイティブな形式です。それ以外のファイルタイプには`${VAR}`プレースホルダーが入りますが、これはそれを展開するもの(シェルスクリプト、`.env`ローダー、多くの設定ツール)がある場合にのみ実際のルックアップとなります。C#では単なる文字列のままとなり、Terraformでは存在しない参照として解釈されるため設定の検証に失敗します。そのため両方にはセンチネルを使用してください。名前は検出結果から取得されます。`db_password`は`DB_PASSWORD`になり、既知のトークンタイプには独自の名前が付くため、AWSキーは変数の名前が何であっても`AWS_ACCESS_KEY`になります。ルックアップがコードを壊してしまう場合(たとえばより大きな文字列の内部など)には、代わりにセンチネルが使用されます。
## 誤検知を抑制する
その行自体で、`#`、`//`、`/* */`、または`<!-- -->`コメント内に:
```python
example_key = "AKIAIOSFODNN7EXAMPLE" # credactor:ignore
```
またはスキャンルートの `.credactorignore` に記述します:
```text
tests/fixtures/*
app/settings.py:42
```
エントリは glob、`file:line`、または完全一致の値のいずれかです。`.`、`/`、`?`、`*` を含む値(URL、JWT、Base64)は `value:<literal>` として記述する必要があり、そうでなければ glob として解釈され効果を持ちません。取り込まれたレポートからの検出結果は `.credactorignore` によってのみフィルタリングされます。インラインの `credactor:ignore` はそれらを止めません。しきい値、スキップするディレクトリ、追加のファイル種別は [`credactor.toml`](https://github.com/rxb06/credactor/blob/main/docs/setup.md) に記述します。
## 終了コード
| コード | 意味 |
|---|---|
| `0` | 検出結果なし、またはすべて修正済み |
| `1` | 未解決の検出結果が残っている |
| `2` | エラー。不正なパス、無効なフラグの組み合わせ、読み取り不能なレポート、明示的な `--config`、または git リポジトリ外での `--staged` / `--scan-history` など |
未解決の検出結果がある場合、終了コードが 0 になることはありません。Credactor が読み取れなかったファイルはデフォルトでは警告にすぎないため、すべてのファイルを読み取る必要があるゲートには `--fail-on-error` を追加してください。その場合、終了コードは 2 になります。完全な一覧は [マニュアル](https://github.com/rxb06/credactor/blob/main/docs/manual.md#exit-codes) にあります。
## サプライチェーンの強化
リポジトリ内のすべてのシークレットを読み取るツールは、実行時だけでなくインストール時にも安全であるべきです。攻撃者がビルドや公開のパイプラインに侵入した後、いくつかの人気パッケージが悪意のあるリリースを出荷してきました。改ざんされたビルド依存関係、盗まれたアップロードトークン、リリースアーカイブに紛れ込んだファイルなどです。Credactor のリリースパイプラインには、それぞれに対する専用のチェックがあります。
- **ランタイム依存関係なし。** `pip install credactor` は Credactor のみをインストールし、他には何もインストールしません(オプションの `[encoding]` エクストラは `charset-normalizer` を追加します)。そのため、インストール時に検証すべきサードパーティのコードはありません。
- **すべてのリリースがソースと照合されます。** CI および公開前にも、`scripts/audit_wheel.py` がリポジトリ由来の wheel と sdist 内のすべてのファイルを、コミットされたソースとバイト単位(sha256)で比較し、`pyproject.toml` と一致しなければならないパッケージメタデータ以外のものはすべて拒否します。追加または改変されたモジュール、注入された依存関係、向き先を変えられたコマンド、tarball にはあるが git にはないファイルは、リリースを失敗させます。
- **ハッシュで固定されたビルド。** CI およびリリースビルドは、ビルドバックエンドを含めて `pip install --require-hashes` でツールをインストールするため、改ざんされた依存関係はパッケージに到達するのではなくビルドを失敗させます。
- **パイプラインにアップロードトークンなし。** リリースは専用の `pypi` 環境からの OIDC トラステッドパブリッシングを通じて PyPI に送信され、Sigstore のアテステーションが付与され、パッケージのバージョンがリリースタグと一致する場合にのみ行われます。パイプラインは長期間有効な PyPI トークンを保存しません。
- **厳格化された CI。** すべての GitHub Action はコミット SHA に固定され、ワークフロートークンはデフォルトで読み取り専用となり、チェックアウトは認証情報を保持せず、Dependabot が毎月更新を提案します。
- **Action はチェックアウトの外にインストールします。** GitHub Action はランナーの一時ディレクトリから pip を分離モード(`python -I`)で使用して Credactor をインストールし、その後インストールされたコマンドを実行します。
これらのチェックは、公開されたものがリリースタグでコミットされたソースと一致することを示します。しかし、そのソースが信頼できるものであることを保証したり、すでに侵害されたビルドマシンを保護したりすることはできません。詳細と限界については [セキュリティドキュメント](https://github.com/rxb06/credactor/blob/main/docs/security.md#supply-chain-hardening) を参照してください。
## セキュリティ
脆弱性は公開 issue ではなく、[GitHub Security Advisories](https://github.com/rxb06/credactor/security/advisories/new) を通じて非公開で報告してください。[SECURITY.md](https://github.com/rxb06/credactor/blob/main/SECURITY.md) にはサポート対象バージョンが記載されており、[セキュリティドキュメント](https://github.com/rxb06/credactor/blob/main/docs/security.md) では脅威モデル、各強化策、既知の限界について説明しています。
## ドキュメント
| ドキュメント | 内容 |
|---|---|
| [マニュアル](https://github.com/rxb06/credactor/blob/main/docs/manual.md) | すべてのフラグ、モード、組み合わせと、検証済みの動作 |
| [セットアップ](https://github.com/rxb06/credactor/blob/main/docs/setup.md) | インストールと `.credactor.toml` |
| [CI 統合](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md) | pre-commit、GitHub Action、その他の CI システム、取り込み |
| [例](https://github.com/rxb06/credactor/blob/main/docs/examples.md) | 出力付きの一般的なワークフロー |
| [セキュリティ](https://github.com/rxb06/credactor/blob/main/docs/security.md) | 脅威モデル、ハードニング、既知の制限 |
| [免責事項](https://github.com/rxb06/credactor/blob/main/docs/DISCLAIMER.md) | 安全な使用方法と保証 |
| [変更履歴](https://github.com/rxb06/credactor/blob/main/CHANGELOG.md) | バージョン履歴 |
| [コントリビューション](https://github.com/rxb06/credactor/blob/main/CONTRIBUTING.md) | 開発環境のセットアップとプルリクエスト |
## ライセンス
Apache 2.0。[LICENSE](https://github.com/rxb06/credactor/blob/main/LICENSE) を参照してください。