secrets-gitleaks

Gitleaks によるシークレット検出

概要

Gitleaks は、Git リポジトリ、ファイル、ディレクトリをスキャンし、パスワード、API キー、トークンなどのハードコードされた認証情報や、その他の機密情報を検出するツールです。正規表現ベースのパターンマッチングと Shannon エントロピー分析を組み合わせ、漏えいした場合に不正アクセスにつながる可能性のあるシークレットを特定します。

このスキルでは、コードが本番環境に到達する前にシークレットの漏えいを防ぐことに重点を置き、コミット前フックから CI/CD パイプラインまで、DevSecOps ワークフローに Gitleaks を組み込むための包括的なガイダンスを提供します。

クイックスタート

現在のリポジトリをスキャンしてシークレットを検出します。

# Install gitleaks
brew install gitleaks  # macOS
# or: docker pull zricethezav/gitleaks:latest

# Scan current git repository
gitleaks detect -v

# Scan specific directory
gitleaks detect --source /path/to/code -v

# Generate report
gitleaks detect --report-path gitleaks-report.json --report-format json

主なワークフロー

1. リポジトリのスキャン

既存のリポジトリをスキャンして、漏えいしたシークレットを特定します。

# Full repository scan with verbose output
gitleaks detect -v --source /path/to/repo

# Scan with custom configuration
gitleaks detect --config .gitleaks.toml -v

# Generate JSON report for further analysis
gitleaks detect --report-path findings.json --report-format json

# Generate SARIF report for GitHub/GitLab integration
gitleaks detect --report-path findings.sarif --report-format sarif

使用する場面：初回のセキュリティ監査、コンプライアンスチェック、インシデント対応。

2. コミット前フックによる保護

シークレットがコミットされることを未然に防ぎます。

# Install pre-commit hook (run in repository root)
cat << 'EOF' > .git/hooks/pre-commit
#!/bin/sh
gitleaks protect --verbose --redact --staged
EOF

chmod +x .git/hooks/pre-commit

自動でフックをインストールするには、同梱のスクリプトを使用します。

./scripts/install_precommit.sh

使用する場面：開発者のワークステーションのセットアップ、チームへの導入、必須のセキュリティ対策。

3. CI/CD パイプラインへの統合

GitHub Actions

name: gitleaks
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitLab CI

gitleaks:
  image: zricethezav/gitleaks:latest
  stage: test
  script:
    - gitleaks detect --report-path gitleaks.json --report-format json --verbose
  artifacts:
    paths:
      - gitleaks.json
    when: always
  allow_failure: false

使用する場面：自動化されたセキュリティゲート、プルリクエストのチェック、リリースの検証。

4. ベースラインと段階的なスキャン

セキュリティベースラインを設定し、新たに検出されたシークレットのみを追跡します。

# Create initial baseline
gitleaks detect --report-path baseline.json --report-format json

# Subsequent scans detect only new secrets
gitleaks detect --baseline-path baseline.json --report-path new-findings.json -v

使用する場面：レガシーコードベースの修正、段階的な導入、コンプライアンスの追跡。

5. 設定のカスタマイズ

カスタムの .gitleaks.toml 設定を作成します。

title = "Custom Gitleaks Configuration"

[extend]
# Extend default config with custom rules
useDefault = true

[[rules]]
id = "custom-api-key"
description = "Custom API Key Pattern"
regex = '''(?i)(custom_api_key|custom_secret)[\s]*[=:][\s]*['"][a-zA-Z0-9]{32,}['"]'''
tags = ["api-key", "custom"]

[allowlist]
description = "Global allowlist"
paths = [
  '''\.md$''',           # Ignore markdown files
  '''test/fixtures/''',  # Ignore test fixtures
]
stopwords = [
  '''EXAMPLE''',         # Ignore example keys
  '''PLACEHOLDER''',
]

assets/ にある同梱の設定テンプレートを使用します。

• assets/config-strict.toml - 厳格な検出（見逃しを最小限に抑える）
• assets/config-balanced.toml - バランスの取れた検出（推奨）
• assets/config-custom.toml - カスタムルール用テンプレート

使用する場面：誤検知の削減、独自のシークレットパターンの追加、組織標準への対応。

セキュリティに関する考慮事項

機密データの取り扱い

• シークレットの秘匿：シークレットが誤って漏えいするのを防ぐため、ログやレポートでは必ず --redact フラグを使用してください
• レポートのセキュリティ：Gitleaks のレポートには検出されたシークレットが含まれます。機密情報として扱い、保存時は暗号化してください
• Git の履歴：Git の履歴内で検出されたシークレットは、git filter-repo や BFG Repo-Cleaner などのツールを使用して完全に削除する必要があります
• 認証情報のローテーション：コードから削除した場合でも、漏えいしたシークレットはすべて直ちにローテーションする必要があります

アクセス制御

• CI/CD の権限：Gitleaks のスキャンには、リポジトリのコンテンツと Git の履歴への読み取りアクセスが必要です
• レポートへのアクセス：機密性の高い検出結果を含むスキャンレポートへのアクセスを制限してください
• ベースラインファイル：ベースライン JSON ファイルにはシークレットのメタデータが含まれます。検出結果と同じ管理策で保護してください

監査ログ

コンプライアンス対応とインシデント対応のため、以下を記録してください。

• スキャンの実行日時と対象範囲（リポジトリ、ブランチ、コミット範囲）
• 検出されたシークレットの数と種類
• 実施した修正措置（認証情報のローテーション、コミット履歴のクリーンアップ）
• 誤検知の分類と許可リストの更新

コンプライアンス要件

• PCI-DSS 3.2.1：要件 6.5.3 - 決済アプリケーションでの認証情報のハードコードを防止
• SOC2：CC6.1 - 論理的アクセス制御により、認証情報の不正な漏えいを防止
• GDPR：第 32 条 - 個人データの認証情報を処理するための適切なセキュリティ対策
• CWE-798：ハードコードされた認証情報の使用
• CWE-259：ハードコードされたパスワードの使用
• OWASP A07:2021：識別と認証の失敗

同梱リソース

スクリプト（scripts/）

• install_precommit.sh - 設定に関するプロンプトを備えた、コミット前フックの自動インストール
• scan_and_report.py - 複数の出力形式と重大度分類に対応した包括的なスキャン
• baseline_manager.py - ベースラインの作成、比較、段階的なスキャンの管理

References (references/)

• detection_rules.md - CWE マッピングを含む、Gitleaks の組み込み検出ルールの包括的な一覧
• remediation_guide.md - git 履歴のクリーンアップを含む、シークレット修復の手順
• false_positives.md - よくある誤検知パターンと許可リストの設定方法
• compliance_mapping.md - PCI-DSS、SOC2、GDPR、OWASP の要件との詳細なマッピング

Assets (assets/)

• config-strict.toml - 高感度設定（最大限の検出）
• config-balanced.toml - 本番環境向けのバランスの取れた設定
• config-custom.toml - カスタムルール用のインラインドキュメントを含むテンプレート
• precommit-config.yaml - Pre-commit フレームワークの設定
• github-action.yml - GitHub Actions ワークフローの完全なテンプレート
• gitlab-ci.yml - GitLab CI パイプラインの完全なテンプレート

よくあるパターン

パターン 1：リポジトリの初回監査

セキュリティ評価のための初回シークレットスキャン：

# 1. Clone repository with full history
git clone --mirror https://github.com/org/repo.git audit-repo
cd audit-repo

# 2. Run comprehensive scan
gitleaks detect --report-path audit-report.json --report-format json -v

# 3. Generate human-readable report
./scripts/scan_and_report.py --input audit-report.json --format markdown --output audit-report.md

# 4. Review findings and classify false positives
# Edit .gitleaks.toml to add allowlist entries

# 5. Create baseline for future scans
cp audit-report.json baseline.json

パターン 2：開発者ワークステーションのセットアップ

開発者が誤ってシークレットをコミットするのを防ぎます：

# 1. Install gitleaks locally
brew install gitleaks  # macOS
# or use package manager for your OS

# 2. Install pre-commit hook
./scripts/install_precommit.sh

# 3. Test hook with dummy commit
echo "api_key = 'EXAMPLE_KEY_12345'" > test.txt
git add test.txt
git commit -m "test"  # Should be blocked by gitleaks

# 4. Clean up test
git reset HEAD~1
rm test.txt

パターン 3：ベースラインを使用した CI/CD パイプライン

継続的インテグレーションにおける段階的なシークレット検出：

# In CI pipeline script:

# 1. Check if baseline exists
if [ -f ".gitleaks-baseline.json" ]; then
  # Incremental scan - only new secrets
  gitleaks detect \
    --baseline-path .gitleaks-baseline.json \
    --report-path new-findings.json \
    --report-format json \
    --exit-code 1  # Fail on new secrets
else
  # Initial scan - create baseline
  gitleaks detect \
    --report-path .gitleaks-baseline.json \
    --report-format json \
    --exit-code 0  # Don't fail on first scan
fi

# 2. Generate SARIF for GitHub Security tab
if [ -f "new-findings.json" ] && [ -s "new-findings.json" ]; then
  gitleaks detect \
    --baseline-path .gitleaks-baseline.json \
    --report-path results.sarif \
    --report-format sarif
fi

パターン 4：カスタムルールの開発

組織固有のシークレットパターンを追加します：

# Add to .gitleaks.toml

[[rules]]
id = "acme-corp-api-key"
description = "ACME Corp Internal API Key"
regex = '''(?i)acme[_-]?api[_-]?key[\s]*[=:][\s]*['"]?([a-f0-9]{40})['"]?'''
secretGroup = 1
tags = ["api-key", "acme-internal"]

[[rules]]
id = "acme-corp-database-password"
description = "ACME Corp Database Password Format"
regex = '''(?i)(db_pass|database_password)[\s]*[=:][\s]*['"]([A-Z][a-z0-9@#$%]{15,})['"]'''
secretGroup = 2
tags = ["password", "database", "acme-internal"]

# Test custom rules
# gitleaks detect --config .gitleaks.toml -v

統合ポイント

CI/CD 統合

• GitHub Actions：gitleaks/gitleaks-action@v2 を使用して、Security タブとネイティブに統合します
• GitLab CI：監査証跡のためにアーティファクトを保持する、Docker ベースのスキャン
• Jenkins：パイプラインの各ステージで Docker またはインストール済みのバイナリを実行します
• CircleCI：Orb をサポートする Docker Executor
• Azure Pipelines：タスクベースの統合と結果の公開

セキュリティツールのエコシステム

• SIEM 統合：JSON 形式の検出結果を Splunk、ELK、または Datadog にエクスポートして、一元的に監視します
• 脆弱性管理：SARIF レポートを Snyk、SonarQube、または Checkmarx にインポートします
• シークレット管理：検出結果を HashiCorp Vault または AWS Secrets Manager のローテーションワークフローと統合します
• チケット管理システム：修復状況を追跡するため、Jira／ServiceNow のチケットを自動作成します

SDLC 統合

• 設計フェーズ：セキュリティアーキテクチャレビューにシークレット検出要件を含めます
• 開発：Pre-commit フックにより、開発者に即時フィードバックを提供します
• コードレビュー：PR／MR のチェックにより、シークレットがメインブランチに到達するのを防ぎます
• テスト：テスト環境と Infrastructure as Code をスキャンします
• デプロイ：本番リリース前の最終検証ゲート
• 運用：デプロイ済みの設定とログを定期的にスキャンします

トラブルシューティング

問題：誤検知が多すぎる

症状：正当なコードパターンがシークレットとして検出される（テスト用フィクスチャ、サンプル、プレースホルダー）

解決策：

1. 検出結果を確認し、パターンを特定します：grep -i "example\|test\|placeholder" gitleaks-report.json
2. .gitleaks.toml の許可リストに追加します：

   [allowlist]
   paths = ['''test/''', '''examples/''', '''\.md$''']
   stopwords = ["EXAMPLE", "PLACEHOLDER", "YOUR_API_KEY_HERE"]
   

3. 特定の誤検知には、コミット許可リストを使用します：

   [allowlist]
   commits = ["commit-sha-here"]
   

4. よくあるパターンについては references/false_positives.md を参照してください

問題：大規模なリポジトリでパフォーマンスに問題がある

症状：スキャンに時間がかかりすぎる（10 分超）、メモリ使用量が多い

解決策：

1. --log-opts を使用して git 履歴を絞り込みます：gitleaks detect --log-opts="--since=2024-01-01"
2. 特定のブランチをスキャンします：gitleaks detect --log-opts="origin/main"
3. ベースライン方式を使用して、最近の変更のみをスキャンします
4. 初回スキャンでは、浅いクローンを検討します：git clone --depth=1000
5. 複数のブランチまたはサブディレクトリにまたがってスキャンを並列化します

問題：Pre-commit フックが正当なコミットをブロックする

症状：開発者が正当なパターンを含むコードをコミットできない

解決策：

1. フックを回避するには、インラインコメントを追加します：# gitleaks:allow
2. 特定のパターンを .gitleaks.toml の許可リストに追加します
3. 検出結果を安全に確認するには、--redact を使用します：gitleaks protect --staged --redact
4. 一時的に回避します（注意して使用してください）：git commit --no-verify
5. パターンが本当に必要な場合は、セキュリティチームに確認します

問題：Git の履歴でシークレットが見つかった

症状：古いコミットでシークレットが検出されましたが、現在のコードからはすでに削除されています

解決策：

1. 侵害された認証情報を直ちにローテーションします（最優先）
2. パブリックリポジトリの場合は、次の方法で履歴全体を書き換えることを検討します：
   • git filter-repo（推奨）：git filter-repo --path-glob '*.env' --invert-paths
   • BFG Repo-Cleaner：bfg --delete-files credentials.json
3. クリーンアップした履歴を強制プッシュします：git push --force
4. すべてのコントリビューターにリベースまたは再クローンするよう通知します
5. 詳しい手順については、references/remediation_guide.md を参照してください
6. インシデントをセキュリティ監査ログに記録します

問題：カスタムのシークレットパターンが検出されない

症状：組織固有のシークレットがデフォルトのルールで検出されません

解決策：

1. 正規表現パターンを作成します：サンプルのシークレットを使って regex101.com でテストします
2. .gitleaks.toml にカスタムルールを追加します：

   [[rules]]
   id = "custom-secret-id"
   description = "Description"
   regex = '''your-pattern-here'''
   secretGroup = 1  # Capture group containing actual secret
   

3. パターンをテストします：gitleaks detect --config .gitleaks.toml -v --no-git
4. パターンが曖昧な場合は、エントロピーのしきい値を検討します：

   [[rules.Entropies]]
   Min = "3.5"
   Max = "7.0"
   Group = "1"
   

5. 既知の真陽性と偽陽性を使って検証します

高度な設定

エントロピーベースの検出

明確なパターンがないシークレットには、シャノンエントロピー分析を使用します：

[[rules]]
id = "high-entropy-strings"
description = "High entropy strings that may be secrets"
regex = '''[a-zA-Z0-9]{32,}'''
entropy = 4.5  # Shannon entropy threshold
secretGroup = 0

複合ルール（v8.28.0+）

複数行にまたがるシークレットや、コンテキストを必要とするシークレットを検出します：

[[rules]]
id = "multi-line-secret"
description = "API key with usage context"
regex = '''api_key[\s]*='''

[[rules.composite]]
pattern = '''initialize_client'''
location = "line"  # Must be within same line proximity
distance = 5       # Within 5 lines

グローバルとルール固有の許可リスト

# Global allowlist (highest precedence)
[allowlist]
description = "Organization-wide exceptions"
paths = ['''vendor/''', '''node_modules/''']

# Rule-specific allowlist
[[rules]]
id = "generic-api-key"
[rules.allowlist]
description = "Exceptions only for this rule"
regexes = ['''key\s*=\s*EXAMPLE''']

参考資料

• Gitleaks 公式ドキュメント
• OWASP A07:2021 - 識別および認証の失敗
• CWE-798：ハードコードされた認証情報の使用
• CWE-259：ハードコードされたパスワードの使用
• CWE-321：ハードコードされた暗号鍵の使用
• PCI-DSS 要件
• SOC2 セキュリティ基準