Gitleaks導入ガイド：Git HookからCI/CDパイプラインまでAPIキーやパスワードの流出を徹底ブロック - ITFROMZERO - Share tobe shared! Gitleaks実践導入ガイド：Git pre-commitフックとGitHub Actions CI/CDパイプラインを連携し、APIキー、パスワード、トークンの漏洩を二重で阻止する手法を解説。

Table of Contents

課題：うっかりEnterを押した瞬間、AWSトークンがGitHubへ直送される恐怖

OpenAIのAPIキーやAWSのシークレットアクセスキーを残したまま、思わずgit pushして背筋が凍りついた経験があるエンジニアは少なくないはずです。ネット上の自動巡回ボットは、わずか2〜5分で流出したトークンを検知します。翌朝起きてみたら、第三者に勝手に暗号資産のマイニングインスタンスを立ち上げられて5,000ドルのAWS請求が届いていた、あるいは顧客データベースが丸ごとダンプされていた……といった悲劇は現実に起きています。

原因は往々にして単純なものです。動作確認のために数分だけ認証情報をコードへハードコードして消し忘れたり、git add .で.envファイルごとステージングしてしまったりすることです。人間の注意力だけに頼る運用は、決して安全な戦略とは言えません。開発者の手元（Git hooks）と自動テストパイプライン（CI/CD）という2重の防壁で、シークレットスキャンを自動化する仕組みが必要です。これこそまさにGitleaksが真価を発揮する場面です。

1. クイックスタート：3分で完了するインストールと初回スキャン

Gitleaksは単一のGoバイナリとして配布されており、わずか数十ミリ秒で起動します。正規表現とシャノンエントロピー（Shannon Entropy）アルゴリズムを組み合わせ、160種類以上の主要サービスの認証情報を網羅的に検出します。

ステップ1：Gitleaksのインストール

macOSの場合、Homebrewを使うのがもっとも手軽です：

brew install gitleaks

Linux環境では、ビルド済みバイナリを直接ダウンロードします：

wget https://github.com/gitleaks/gitleaks/releases/download/v8.18.2/gitleaks_8.18.2_linux_x64.tar.gz
tar -zxvf gitleaks_8.18.2_linux_x64.tar.gz
sudo mv gitleaks /usr/local/bin/

正しくインストールされたかバージョンを確認します：

gitleaks version

ステップ2：リポジトリのテストスキャン

プロジェクトのルートディレクトリに移動し、これまでのコミット履歴全体をスキャンします：

gitleaks detect --verbose

直前にgit addしたステージングエリアの変更のみを検証したい場合：

gitleaks protect --staged --verbose

シークレットが含まれている場合、ターミナルに対象ファイル名、行番号、フィンガープリント、キーの種別（例：Stripe Secret Key、AWS Access Keyなど）が赤字で出力され、終了コード1（exit code 1）を返して処理を即座に中断します。なお、すでにコミット履歴全体に埋もれてしまった秘密情報を徹底的に洗い出したい場合は、Trufflehogでコミット履歴からAPIキーの漏洩を特定する方法も併せて確認しておくと安心です。

2. 仕組みの深掘りと2段階防御の構築

Gitleaksはどのようにソースコードを解析するのか？

GitleaksのTOML設定ファイルは、主に2つのアプローチで判定を行います：

Regex Pattern（正規表現パターン）：明確なフォーマットを持つ文字列を捕捉します。例えば、AWS Access Key IDは常にAKIA[0-9A-Z]{16}というプレフィックスで始まり、GitHubのパーソナルトークンはghp_[a-zA-Z0-9]{36}の形式をとります。
Shannon Entropy（シャノンエントロピー）：文字列のランダム性（乱雑さ）を計算します。xK9#mQ2$vL8!zP1@のような32文字のランダムなパスワードはエントロピーが非常に高く、user_display_nameのような一般的な変数名とは明確に区別されます。

防壁1：ローカル開発環境でのGit pre-commit hook

コミットハッシュが生成される前に、開発者の端末上でシークレットの混入を食い止めます。トークンが検知された場合、コミット自体が直ちにキャンセルされます。JavaScriptプロジェクトなどでフックを管理する場合は、Husky と lint-stagedを組み合わせるか、より高速な代替としてGit Hooksの管理をLefthookに移行して検証を自動化する構成も人気があります。

もっとも簡単な導入方法はpre-commitフレームワークを使うことです。リポジトリのルートに.pre-commit-config.yamlを作成します：

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

プロジェクトの.git/hooksディレクトリにフックをインストールします：

pip install pre-commit
pre-commit install

これで設定完了です。以降はgit commitを実行するたびに、ステージングされたファイルが自動検査され、シークレットが見つかるとコミット処理がストップします。

防壁2：ゲートキーパーとしてのCI/CDパイプライン

なぜCI/CDでの検査も必要なのでしょうか？それは、開発者がgit commit --no-verifyを使ってローカルフックをバイパスできてしまうからです。CI/CDサーバーが最終防衛ラインとなり、スキャンをパスしたコードのみマージを許可します。

GitHub Actions向けのワークフロー定義例（.github/workflows/gitleaks.yml）：

name: gitleaks-security-scan

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

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

注意点：fetch-depth: 0の指定は必須です。デフォルトではGitHub Actionsは最新の1コミットのみを浅くクローン（shallow clone）するため、Pull Requestに含まれる途中のコミットがすべて検査対象から漏れてしまいます。

3. 応用：ルールのカスタマイズと誤検知（False Positive）への対処

.gitleaks.tomlによるカスタム設定

プロジェクト内のモックデータや検証用トークンが原因で、Gitleaksが誤検知を起こすことがあります。リポジトリのルートに.gitleaks.tomlを作成し、検査対象から除外するルールを追加します：

title = "Custom Gitleaks Config"

[extend]
useDefault = true

[allowlist]
description = "フィクスチャとロックファイルをスキップ"
paths = [
  '''tests/fixtures/.*''',
  '''go\.sum''',
  '''package-lock\.json'''
]
regexes = [
  '''fake_dummy_secret_for_unit_tests'''
]

インラインコメントによる手軽なホワイトリスト指定

決済機能の単体テストなどで、どうしてもテスト用キーを直接記述しなければならないケースがあります。全体ルールを修正する代わりに、対象行の末尾にインラインコメントを追記するだけで除外できます：

stripe_test_key = "pk_test_51NzABC1234567890dummy"  # gitleaks:allow

スキャナーはこの行を安全なものとしてスキップします。

4. チーム展開における実践的ノウハウ

ツールの導入自体は15分で終わりますが、実運用に乗せる段階ではチームの開発プラクティスや文化に起因する課題が浮き彫りになります。実際にチームへ展開した際に得られた3つの知見を紹介します：

シークレットを削除して上書きコミットしても意味がない：コミット履歴（git log）にはシークレットが残り続けます。ステップ1：直ちに管理コンソールから該当キーを失効（revoke/rotate）させること。ステップ2：git-filter-repoやBFG Repo-Cleanerを使用し、履歴から該当コミットを完全に抹消（purge）すること。
歴史の長いリポジトリにはベースラインを活用する：数年間運用されているリポジトリで突然Gitleaksを有効化すると、過去の蓄積により数百件のアラートが一度に爆発することがあります。まずはgitleaks detect --report-path baseline.jsonで既存の警告を記録してください。その上で--baseline-pathオプションを指定すれば、CI/CDで「新規に追加されたコミットのみ」をブロックできるようになります。
.env.exampleファイルの命名規則を徹底する：サンプル用の設定ファイルに長いランダム文字列を含めないようにします。エントロピー検知に引っかからないよう、STRIPE_KEY=your_stripe_key_hereのような明確なプレースホルダーを使用しましょう。