TruffleHogとGitleaksでGitの漏洩シークレットを検知・完全削除する方法

背景と必要性

Gitリポジトリへのシークレット漏洩は、多くのチームが認識しているよりも一瞬で発生します。開発者がローカル環境でStripeのWebhookやRDS PostgreSQLインスタンスをテストする際、デバッグ目的で設定ファイルにAPIトークンを一時的に貼り付け、git commit -am "quick test"を実行してアップストリームへプッシュしてしまうケースが後を絶ちません。自動化されたボットや公開GitHubスクレイパーは、露出したAWSキー、Slack Webhook、秘密証明書などを60秒足らずで日常的に収集しています。

Gitは過去を絶対に忘れません。git rm credentials.envを実行して新しくコミットしても、根本的な解決にはなりません。Gitはイミュータブル(不変)なコンテンツアドレス指定データベースとして動作するため、すべてのコミットスナップショットはその瞬間のリポジトリの状態を固定して保持します。リポジトリをクローンできる人なら誰でも、git log -pを実行したり過去のスナップショットを検査したりすることで、数か月前に削除したはずのキーを容易に掘り出すことができます。

強力な認証情報を生成することは対策の半分にすぎません。toolcraft.app/ja/tools/security/password-generatorのようなブラウザベースのパスワードジェネレーターを使用すれば、ネットワーク経由で生文字列を送信することなく、64文字の高エントロピートークンを手軽に生成できます。しかし、そのトークンがパブリックなコミットログに残ってしまえば、どれほど高いエントロピーであっても安全ではありません。

強固な防御体制を築くには、役割の異なる2つの専門レイヤーが必要です。

  • TruffleHog: 有効性のライブ検証を兼ね備えた、詳細な履歴発掘ツール。800以上の検出器(Detector)を備え、単なる正規表現マッチングにとどまらず、プロバイダーのAPI(AWS STS、Stripe、Slack、GitHubなど)へ実際にリクエストを送り、露出した認証情報が現在有効かどうかを報告します。
  • Gitleaks: Go言語で記述された極めて高速な静的解析ツール。正規表現とシャノンエントロピーのルールを用いて、ステージングされた数百行の差分を10ミリ秒未満で処理します。ローカルのpre-commitフックやPRパイプラインのゲートキーパーとして最適です。

インストール

開発マシンへの両ツールのセットアップは3分以内に完了します。

1. Gitleaksのインストール

Gitleaksは依存関係のないスタンドアロンバイナリとして配布されており、macOS、Linux、Windowsに対応しています。Linuxの場合はリリースアーカイブを直接取得します。

# Gitleaksのダウンロードと展開 (x86_64 Linux)
curl -sSL https://github.com/gitleaks/gitleaks/releases/download/v8.18.2/gitleaks_8.18.2_linux_x64.tar.gz | tar -xz gitleaks
sudo mv gitleaks /usr/local/bin/

# バージョンの確認
gitleaks version

macOSでは、Homebrewを使って簡単に導入できます。

brew install gitleaks

2. TruffleHogのインストール

TruffleHog v3には、適切なアーキテクチャのバイナリを取得する公式インストールスクリプトが用意されています。

# TruffleHogバイナリを /usr/local/bin に直接インストール
curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sudo sh -s -- -b /usr/local/bin

# バージョンの確認
trufflehog --version

3. Pre-Commitフレームワークのインストール

危険なコミットをローカル環境で未然に防ぐため、Gitleaksをpre-commitパッケージと連携させます。

# pipまたはシステムパッケージマネージャー経由でインストール
pip install pre-commit

# バージョンの確認
pre-commit --version

設定方法

1. ローカルフックでの防止に向けたGitleaksの設定

リポジトリのルートに.pre-commit-config.yamlファイルを配置し、ステージングされた差分をGitleaksが自動検証するようにします。

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.2
    hooks:
      - id: gitleaks

フックをローカルの.git/hooksディレクトリに登録します。

pre-commit install

これ以降、git commitを実行するたびに瞬時に差分検査がトリガーされます。秘密鍵やAPIトークンがインデックスに紛れ込んでいる場合、コミットは即座に中断されます。

2. Gitleaksルールのカスタマイズ (.gitleaks.toml)

テスト用のフィクスチャやダミーハッシュが検出器に誤検知されることがあります。スキャナー全体を無効化せずに誤検知(False Positive)を抑制するには、ルートフォルダに.gitleaks.tomlファイルを作成します。

title = "プロジェクト用 Gitleaks 許可リスト設定"

[allowlist]
description = "モックのペイロードやドキュメントのサンプルを除外"
paths = [
  '''tests/mocks/''',
  '''fixtures/dummy_keys.json'''
]
regexes = [
  '''EXAMPLE_KEY_[a-zA-Z0-9]{16,32}''',
  '''AKIAIOSFODNN7EXAMPLE'''
]

3. Git履歴からの漏洩シークレットの完全削除

コミットログ内に有効なキーを発見した場合は、まず該当する認証情報を直ちにローテーション(再発行・無効化)してください。公開されたキーはすでにスクレイパーによって取得されていると見なすべきです。

次に、Gitから痕跡を完全に消去します。標準のGitコマンドでは、全ブランチにわたるツリーを確実に書き換えることは困難です。コミュニティの標準的な公式ツールであるgit-filter-repoを使用します。

対象となる機密文字列の置換マッピングをreplace-secrets.txtというファイルに定義します。

sk_live_51AbCdEfGhIjKlMnOpQrSt==>REMOVED_SECRET
AKIAIOSFODNN7EXAMPLE_SECRET_STRING==>REMOVED_SECRET

続いてリポジトリのバックアップを作成し、すべてのコミットツリーを一括で書き換えます。

# 最初にリポジトリのクローンをバックアップ
cp -r my-repo my-repo-backup
cd my-repo

# git-filter-repoのインストール
pip install git-filter-repo

# 過去の全コミット、タグ、ブランチから該当文字列を抹消
git filter-repo --replace-text replace-secrets.txt --force

履歴の書き換えが完了したら、書き換え後のコミット参照をoriginへ強制プッシュ(force-push)します。

git push origin --force --all
git push origin --force --tags

作業完了後、すぐにチームメンバーへ周知してください。メンバーのローカルクローンは書き換えられたツリーと競合するため、再クローンするか、新しくプッシュされたブランチに対してハードリセットを行う必要があります。

検証とモニタリング

1. ローカルPre-Commit保護の動作検証

実際のGitHubパーソナルアクセストークンの形式を模したダミートークンを使って、ローカルフックの動作を確認します。

# サンプルトークンパターンをステージング
echo 'GITHUB_TOKEN=ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ123456' > test_leak.py
git add test_leak.py
git commit -m "シークレット保護のテスト"

Gitleaksがコミットをミリ秒単位で検知し、実行をブロックします。

[INFO] https://github.com/gitleaks/gitleaks の環境を初期化中...
シークレットを検出しています...

    ○
    │╲
    │ ○
    ○ ░
    ░    gitleaks

Finding:     ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ123456
Secret:      ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ123456
RuleID:      github-pat
Entropy:     3.854
File:        test_leak.py
Line:        1

ERR ステージングされた変更内にシークレットが検出されました!コミットをブロックしました。

一時ファイルをアンステージして削除し、ブランチを元の状態に戻します。

git reset HEAD test_leak.py
rm test_leak.py

2. TruffleHogによるリポジトリ履歴全体の監査

TruffleHogを使用して、コミットグラフ全体の履歴をスキャンします。--only-verifiedオプションを追加することで、すでに無効化されたマッチを除外し、リモートAPIに対して認証が成功した「現在有効なキー」のみを抽出・表示できます。

# 現在のリポジトリのコミット履歴から有効なキーをスキャン
trufflehog git file://$(pwd) --only-verified

ディスク上にクローンすることなく、リモートリポジトリを直接監査することも可能です。

trufflehog git https://github.com/your-org/target-repo.git --only-verified

3. GitHub Actionsによる継続的モニタリング

ローカルフックは優れた第一防衛ラインですが、急いでいる開発者がgit commit --no-verifyを使ってバイパスしてしまう可能性があります。すべてのプッシュやプルリクエストに対してGitleaksを一元実行することで、スキャンを強制適用します。以下のパイプラインを.github/workflows/secret-scan.ymlとして保存します。

name: シークレットスキャン

on:
  pull_request:
  push:
    branches: [main, develop]

jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - name: コードのチェックアウト
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Gitleaksの実行
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

fetch-depth: 0を指定することで、単一コミットの浅いスナップショットではなく、完全なコミットグラフを取得します。これにより、スカッシュコミットやPRの中間コミットに隠れたシークレットが見逃され、本番ブランチへ混入することを防ぎます。

Share: