TruffleHog v3の使い方｜GitHubとローカルGitのシークレットを検出する

TruffleHog v3をmacOSへインストールし、GitHubの公開リポジトリとローカルGit履歴からシークレットを検出する手順を解説します。verifiedやunknownなど結果の違い、検出後に認証情報を失効・再発行する流れまで、実際に確認したコマンドでまとめます。

この記事の旧版では、TruffleHogをPythonパッケージとしてインストールする手順を紹介していました。しかし、現行のTruffleHog v3はGoで全面的に書き直されており、この手順は使いません。

今回は2026年8月1日に、macOSへTruffleHog 3.96.0をインストールして試しました。GitHub上の公開リポジトリとローカルのGit履歴を実際にスキャンし、どちらもシークレットを検出できるところまで確認しています。

注意

TruffleHogは、自分が管理しているリポジトリ、明示的に許可されたリポジトリ、公式のテスト用リポジトリだけで使ってください。検出結果には認証情報のRaw値が含まれることがあります。出力をそのまま記事、Issue、チャット、Git履歴へ貼らないようにしましょう。

TruffleHog v3とは

TruffleHogは、Git履歴やファイルなどからAPIキー、アクセストークン、秘密鍵といった認証情報を検出するオープンソースツールです。

v3では、候補を見つけるだけでなく、対応サービスのAPIを使って認証情報が現在も有効か確認できるDetectorがあります。検出結果をverified、unverified、unknownに分けられるため、対応の優先順位を付けやすくなっています。

公式READMEによると、v3はGoによる全面的な書き直しです。Python環境やpipでのインストールは必要ありません。

TruffleHog公式README

macOSへTruffleHog v3をインストールする

macOSでは、Homebrewを使うのが簡単です。

brew install trufflehog

インストール後にバージョンを確認します。

trufflehog --version

今回の環境では、次のように表示されました。

trufflehog 3.96.0

バージョンはインストール時期によって変わります。Dockerやバイナリで導入したい場合は、公式READMEのInstallationを確認してください。

公開GitHubリポジトリをスキャンする

最初は、Truffle Securityが公開しているテスト用リポジトリを使います。自分でダミーのAPIキーを作ったり、本物の認証情報をコミットしたりする必要はありません。

trufflehog --no-update git https://github.com/trufflesecurity/test_keys --results=verified

このコマンドでは、指定したGitリポジトリの履歴を調べ、verifiedと判定された結果だけを表示します。

--no-updateは、実行時の自己更新チェックを止めるオプションです。今回はHomebrewでインストールしたバイナリをHomebrew側で管理するために付けました。公式READMEの例と同じく、省略してもスキャンできます。

2026年8月1日に実行したときは、986チャンク、約11.8MBを走査し、verifiedが2件見つかりました。Raw値を除いた結果は次のとおりです。

状態	Detector Type	File	Line
verified	AWS	`new_key`	2
verified	URI	`keys`	3

実際の出力にはコミットやRaw値なども含まれます。シークレットの場所を確認するときは、主に次の項目を見ます。

Detector Type: AWSなど、検出した認証情報の種類
File: 認証情報が見つかったファイル
Line: ファイル内の行番号
Commit: 認証情報を含むコミット
Verified: 認証情報の有効性を確認できたか

公式テスト用リポジトリの内容は更新される可能性があるため、検出件数やファイル名がこの記事と違っても問題ありません。

ローカルGit履歴をスキャンする

次は、同じテスト用リポジトリをローカルへcloneして試します。

mkdir trufflehog-test
cd trufflehog-test
git clone https://github.com/trufflesecurity/test_keys.git
trufflehog --no-update git file://test_keys --results=verified,unknown

file://test_keysは、現在のディレクトリから見たローカルリポジトリのパスです。別の場所を調べる場合は、対象に合わせて変更してください。

今回の実行では、12チャンク、4,140バイトを走査し、verifiedが2件、unknownは0件でした。GitHubのURLを直接指定した場合よりチャンク数が少ないのは、ローカルcloneに含まれる参照と、リモートスキャンで取得する参照の範囲が同じではないためです。

現行版は、信頼できないローカルGit設定の影響を避けるため、対象リポジトリを一時ディレクトリへcloneしてから走査します。--trust-local-git-configというオプションもありますが、信頼できるリポジトリ以外では使わない方が安全です。

`verified`・`unverified`・`unknown`の違い

TruffleHog v3の結果は、次の3つに分かれます。

状態	意味	最初の判断
`verified`	対応サービスのAPIなどで、有効な認証情報だと確認できた	最優先で失効・ローテーションする
`unverified`	候補は検出したが、有効とは確認できなかった	誤検知と決めず、所有者と利用状況を確認する
`unknown`	検証を試みたが、ネットワークやAPIエラーなどで判定できなかった	安全とは判断せず、手動で確認する

最初は--results=verifiedで有効な認証情報に絞り、範囲を広げたいときはverified,unknownやverified,unverified,unknownを指定すると分かりやすいです。

なお、verifiedの判定では対応サービスのAPIへリクエストを送る場合があります。外部通信を行いたくない環境では、--no-verificationの挙動を公式ドキュメントと手元のバージョンで確認してから使ってください。

JSONで結果を受け取る場合

--jsonを付けると、1件ずつJSON形式で出力できます。

trufflehog --no-update git https://github.com/trufflesecurity/test_keys --results=verified --json

JSONにはRawなどのフィールドが含まれます。出力をファイルへ保存する場合は、共有場所やGit管理下へ置かず、不要になったら安全に削除してください。

GitHubアクセストークンは必要か

この記事で使った公開Gitリポジトリのスキャンには、GitHub Personal Access Tokenを用意していません。trufflehog git https://github.com/...で公開リポジトリを調べるだけなら、トークンなしで実行できます。

GitHub Organization、プライベートリポジトリ、IssueやPull Requestのコメントまで調べる場合は、githubサブコマンドを使います。現行版ではGITHUB_TOKEN環境変数または--tokenオプションを利用できますが、必要な権限と対象範囲が変わるため、今回は扱いません。

旧記事で案内していたアクセストークン指定は、現行v3のgitサブコマンドにはないため削除しました。

トークンをコマンドへ直接書くと、シェル履歴などへ残る可能性があります。認証が必要な場合は、権限を最小限にしたトークンとGITHUB_TOKEN環境変数を使い、作業後に不要なトークンを失効してください。

シークレットが見つかったら最初にすること

実在するシークレットが見つかった場合、ファイルを削除するだけでは不十分です。GitHubも、漏えいしたシークレットは侵害済みとして扱い、失効させるよう案内しています。

次の順番で対応します。

認証情報の種類、所有者、ファイル、コミットを確認する。
提供元のサービスで、認証情報を失効またはローテーションする。
影響を受けるサービスを更新し、不正利用がなかったか確認する。
現在のコードから認証情報を削除する。
必要に応じてGit履歴から削除し、TruffleHogでもう一度確認する。

シークレットを消す新しいコミットを追加しても、過去のコミットには残ります。一方、Git履歴の書き換えは、既存cloneやPull Request、共同作業者への影響が大きい操作です。詳しい対応は、GitHubの公式手順を確認してください。

まとめ

TruffleHog v3を初めて試すなら、次の流れで確認できます。

HomebrewでTruffleHogをインストールする。
公式テスト用リポジトリを--results=verifiedでスキャンする。
自分が管理するリポジトリを、GitHubのURLまたはfile://で指定する。
verifiedを最優先にし、unverifiedとunknownも安全だと決めつけない。
実在する認証情報が見つかったら、ファイル削除より先に失効・ローテーションする。

今回は、公開GitHubリポジトリとローカルGit履歴の基本操作まで確認しました。CIやGitHub Organizationへ広げる前に、まず手元のリポジトリで出力の見方と、見つかった後の対応順を確認しておきましょう。