TruffleHogで漏えい資格情報を検出し有効性まで分ける

DiscoveryからAnalysisへ進む四段階

TruffleHog は、漏えいした認証情報を探すためのコマンドラインツールです。README はその動作を4つの段階で説明しています。発見、分類、検証、分析です。ここでいうシークレットとは、あるマシンが別のマシンに対して認証するために使う認証情報のことで、API キー、データベースのパスワード、秘密暗号鍵などを含みます。発見は Git リポジトリ、チャット、wiki、ログ、API テストプラットフォーム、オブジェクトストア、ファイルシステムなどのソースを検索します。分類は見つかった文字列を800以上のシークレットタイプにマッピングし、それがどのアイデンティティに属するかを特定します。AWS シークレットなのか、Stripe シークレットなのか、Cloudflare シークレットなのか、Postgres パスワードなのか、SSL 秘密鍵なのかがわかります。検証は、分類された各シークレットでログインを試み、実際に有効かどうかを確認します。分析は、最もよく漏えいする約20種類の認証情報タイプについて、複数のリクエストを送り、誰がそのシークレットを作成したか、どのリソースにアクセスできるか、それらのリソースでどのような権限を持つかを調べます。

TruffleHogは漏えいしたcredentialを見つけるCLIで、secretをAPI key、DB password、private encryption keyなど機械間認証の情報として扱う。検出後に分類、利用可能性の確認、権限分析へ分ける設計が判断の軸だ。 trufflesecurity/trufflehogのREADMEとメタデータに基づく判断であり、実行結果や性能測定を意味しない。導入範囲はここで挙げた形式、コマンド、設定ファイルに限って確認する。

Git、ログ、クラウドを横断する入力

コマンド面はデータソースごとのサブコマンドとして構成されています。README には git、github、gitlab、huggingface、docker、s3、filesystem、syslog、circleci、travisci、gcs、postman、jenkins、elasticsearch、stdin、multi-scan が列挙されています。各サブコマンドは独自のフラグを持ち、--help で確認できます。クイックスタートの節では代表的な呼び出しが示されています。trufflehog git https://github.com/trufflesecurity/test_keys --results=verified はリポジトリをスキャンし、trufflehog github --org=trufflesecurity は組織をスキャンし、trufflehog s3 --bucket=<bucket name> は S3 バケットを、trufflehog gcs --project-id=<project-ID> --cloud-environment は Google Cloud Storage を、trufflehog docker --image trufflesecurity/secrets はコンテナイメージを、trufflehog filesystem path/to/file1.txt はローカルのファイルとディレクトリをスキャンします。実験的な github-experimental コマンドは GitHub リポジトリ上の削除済み・非表示コミットを列挙します。README はこれをアルファ機能と警告し、有効なコミットの列挙はリポジトリの規模にもよりますが20分から数時間かかるとしています。

入力はGit、chat、wiki、log、API testing platform、object store、filesystemなどとREADMEに列挙される。800を超えるsecret typeを分類すると説明されるが、対象システムへの接続権限を持たせる範囲はスキャン設計で限定すべきだ。 trufflesecurity/trufflehogのREADMEとメタデータに基づく判断であり、実行結果や性能測定を意味しない。導入範囲はここで挙げた形式、コマンド、設定ファイルに限って確認する。

verifiedが示す資格情報の状態

README は3つの結果ステータスを定義しています。verified は、そのシークレットが属すると見られる API に対してテストを行い、有効かつアクティブであると確認できた状態です。unverified は検出されたが有効性が確認できていない状態で、無効、期限切れ、または検証が無効化されている可能性があります。unknown は検証を試みたものの、ネットワークや API のエラーなどで失敗した状態です。README は AWS 検出器を例に挙げ、GetCallerIdentity API 呼び出しを行って AWS 認証情報がアクティブかどうかを確認すると説明しています。秘密鍵については、SSH または SSL 認証で実際に使用できることを確認します。README はこれを Driftwood と呼ぶ技術で実現し、数百万の GitHub ユーザーと数十億の TLS 証明書を対象にするとしています。検出率、誤検出率、検証のカバレッジについての具体的な数値は README には記載されていません。

分類できたsecretについてログインし、liveかどうかを確認する処理をverifiedとして説明する。そのうえ一部のcredential typeでは複数リクエストで作成者、resource、permissionを調べるため、単なる文字列検索より外部アクセスの影響が大きい。 trufflesecurity/trufflehogのREADMEとメタデータに基づく判断であり、実行結果や性能測定を意味しない。導入範囲はここで挙げた形式、コマンド、設定ファイルに限って確認する。

Docker、Homebrew、Goでの導入

README には複数のインストール方法が記載されています。macOS では brew install trufflehog を実行します。Docker では現在のディレクトリを /pwd にマウントします。Unix、Windows コマンドプロンプト、Windows PowerShell、M1/M2 Mac 向けの変種が示されており、M1/M2 では --platform linux/arm64 を使います。バイナリリリースは GitHub の releases ページからダウンロードして展開します。ソースからのビルドは git clone の後に cd trufflehog; go install を実行します。インストールスクリプトは scripts/install.sh にあり、-v フラグでチェックサム署名を検証し、リリースタグを渡すと特定バージョンをインストールできます。すべてのアーティファクトにチェックサムが付与され、チェックサムファイルは cosign で署名されます。検証には releases ページからチェックサム、pem、sig の各ファイルをダウンロードし、cosign verify-blob を GitHub ワークフローに一致する証明書 ID の正規表現付きで実行し、その後 sha256sum --ignore-missing -c でアーティファクトのハッシュを確認します。

macOSはbrew install trufflehog、Dockerはtrufflesecurity/trufflehog:latestを使ったgithub --repo例、ソースはgit clone後のgo install、releaseからのbinary取得を示す。install scriptにはchecksum検証の案内もある。 trufflesecurity/trufflehogのREADMEとメタデータに基づく判断であり、実行結果や性能測定を意味しない。導入範囲はここで挙げた形式、コマンド、設定ファイルに限って確認する。

検出器とCI終了コードの接続

CLI は共通のグローバルフラグと、コマンドごとのオプションを公開しています。README に掲載された git --help の出力には、--results（デフォルトは verified,unverified,unknown）、--json、--concurrency、--no-verification、--fail（結果が見つかった場合に終了コード183を返す）などがあります。検出器の選択は --include-detectors と --exclude-detectors で制御し、アーカイブスキャンにはサイズ・深さ・タイムアウトの制限があります。--config で渡す設定ファイルには、カスタム正規表現検出器と複数のソースを定義できます。設定内のソースは multi-scan サブコマンドでのみ使われ、カスタム正規表現検出器はどのサブコマンドでも使えます。カスタム検出器には少なくとも1つの正規表現とキーワードが必要で、検証は webhook に委譲され、正規表現のマッチを含む JSON POST を受信します。200 OK 応答なら verified、ネットワークや API のエラーなら unknown になります。README はこの機能をアルファ版で変更される可能性があるとしています。公開鍵暗号を使い、公開鍵が取得できる JWT に対する汎用 JWT 検出も文書化されています。

READMEにはGitHub組織を対象にしたdocker run例があり、CI/CD用途では検出結果と終了コードをパイプラインの扱いへ結び付ける必要がある。検出器の追加、custom detector、flagsの詳細は同梱ドキュメントへ戻る。 trufflesecurity/trufflehogのREADMEとメタデータに基づく判断であり、実行結果や性能測定を意味しない。導入範囲はここで挙げた形式、コマンド、設定ファイルに限って確認する。

対象データと権限の取り扱い

README は GitHub Action（trufflesecurity/trufflehog@main）を文書化しており、path、base、head、extra_args、version、image の入力があります。サンプルワークフローは、すべてのプルリクエストと main へのプッシュでライブなシークレットをスキャンし、fetch-depth を0にして完全な履歴を取得します。単独のワークフローでは浅いクローンを推奨し、プッシュまたはプルリクエストイベントのコミット数から fetch-depth を計算します。GitLab CI の例ではインストールスクリプトでツールを入れ、マージリクエストパイプラインで trufflehog filesystem "$SCAN_PATH" --results=verified,unknown --fail --json を実行します。pre-commit フックは PreCommit.md に記載されています。終了コードは、0 がエラーなし・結果なし、1 がスキャン中にエラー、183 がエラーなし・結果ありで、--fail を使った場合のみ返されます。

スキャン対象に秘密を含むリポジトリやログを指定し、検証では対象サービスへ認証リクエストが送られる可能性がある。Dockerの-vで$PWDを/pwdへマウントする例もあるため、マウント範囲と出力ログの公開先を先に決めたい。 trufflesecurity/trufflehogのREADMEとメタデータに基づく判断であり、実行結果や性能測定を意味しない。導入範囲はここで挙げた形式、コマンド、設定ファイルに限って確認する。

AGPL-3.0とv3.97系列の更新

このリポジトリは Go で書かれており、メタデータのスナップショット時点で27,308スター、2,519フォーク、505の未解決イシューがあります。README によると v3 は Go による完全な書き直しで、700以上の認証情報検出器を追加し、GitHub、GitLab、Docker、ファイルシステム、S3、GCS、Circle CI、Travis CI のスキャンをネイティブにサポートし、GitHub Action と pre-commit フックとしても利用できます。v3.0 以降、プロジェクトは AGPL-3.0 で公開され、以前のコードベースは GPL 2.0 でリポジトリの履歴と以前のパッケージリリースに残されています。ライセンス文書はソフトウェアの複製・配布・変更の自由を認め、ネットワークサーバーでの使用については、公開サーバー上で稼働する改変版のソースコードを運営者が提供することを求めます。ライセンスはまた、提供される保証を除き、この作品には保証がないと述べており、サポート、セキュリティ保証、保守の約束については何も触れていません。README は公開 API が不安定であることを明示しており、活発な開発が続く間は安定性を保証できないとしています。今後のコントリビューションには CLA の完了が必要です。

ライセンスはAGPL-3.0、直近版はv3.97.1。漏えい対応の初動やCI検査には適するが、verifiedを無条件に無害化判断へ使うものではない。まずtest_keysのREADME例を隔離し、検出、verified、終了コードを個別に記録する。 trufflesecurity/trufflehogのREADMEとメタデータに基づく判断であり、実行結果や性能測定を意味しない。導入範囲はここで挙げた形式、コマンド、設定ファイルに限って確認する。

編集部の結論

TruffleHogは漏えいしたcredentialを見つけるCLIで、secretをAPI key、DB password、private encryption keyなど機械間認証の情報として扱う。検出後に分類、利用可能性の確認、権限分析へ分ける設計が判断の軸だ。 スキャン対象に秘密を含むリポジトリやログを指定し、検証では対象サービスへ認証リクエストが送られる可能性がある。Dockerの-vで$PWDを/pwdへマウントする例もあるため、マウント範囲と出力ログの公開先を先に決めたい。 ライセンスはAGPL-3.0、直近版はv3.97.1。漏えい対応の初動やCI検査には適するが、verifiedを無条件に無害化判断へ使うものではない。まずtest_keysのREADME例を隔離し、検出、verified、終了コードを個別に記録する。 採用するのはこの条件を受け入れられる利用者で、資料にない保証や別用途を求める利用者には向かない。最初に確認する対象はtrufflesecurity/trufflehogのREADMEに記載された具体的な入力、コマンド、設定、リリース番号である。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes