detecting-aws-credential-exposure-with-trufflehog

TruffleHog による AWS 認証情報の漏えい検出

使用するタイミング

• 本番環境に認証情報が含まれたコミットが到達するのを防ぐため、CI/CD パイプラインにシークレット検出を統合するとき
• 過去にコミットされた AWS 認証情報がないか、既存のリポジトリをセキュリティ監査するとき
• 想定外の IP アドレスやリージョンからの認証情報の使用に関する AWS GuardDuty のアラートに対応するとき
• 買収した企業やサードパーティベンダーのリポジトリを受け入れるとき
• 認証情報のローテーション処理によって古いアクセスキーへの参照がすべて削除されたことを検証するとき

リアルタイムの認証情報モニタリング（AWS GuardDuty または Amazon Macie を使用）、シークレットの管理（AWS Secrets Manager または HashiCorp Vault を使用）、PII のような認証情報以外の機密データの検出（Amazon Macie または DLP ツールを使用）には使用しないでください。

前提条件

• TruffleHog v3 がインストールされていること（brew install trufflehog または pip install trufflehog）
• プリコミットフックとの統合用に git-secrets がインストールされていること（brew install git-secrets）
• ソースコードリポジトリ（GitHub、GitLab、Bitbucket、またはローカルの git リポジトリ）へのアクセス権
• キーの状態を確認する権限（iam:ListAccessKeys、iam:GetAccessKeyLastUsed）を持つ AWS CLI の設定
• 組織全体のリポジトリをスキャンするための GitHub または GitLab API トークン

ワークフロー

ステップ 1：TruffleHog をインストールして設定する

TruffleHog v3 をインストールし、AWS 認証情報のパターンを検出できることを確認します。

# Install TruffleHog v3
pip install trufflehog

# Or install from binary release
curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin

# Verify installation
trufflehog --version

# Test with a known test repository
trufflehog git https://github.com/trufflesecurity/test_keys --only-verified

ステップ 2：Git リポジトリをスキャンして漏えいした認証情報を検出する

すべてのブランチとコミットを含む Git の全履歴をスキャンし、AWS アクセスキー、シークレットキー、セッショントークンを検出します。

# Scan a local git repository (full history)
trufflehog git file:///path/to/repo --only-verified --json > trufflehog-results.json

# Scan a GitHub organization's repositories
trufflehog github --org=your-organization --token=$GITHUB_TOKEN --only-verified

# Scan a specific GitHub repository with all branches
trufflehog git https://github.com/org/repo.git --only-verified --branch=main

# Scan a GitLab group
trufflehog gitlab --group=your-group --token=$GITLAB_TOKEN --only-verified

# Scan filesystem paths for credentials in config files
trufflehog filesystem /path/to/project --only-verified

ステップ 3：検出された認証情報を分析して検証する

TruffleHog の結果を解析し、有効な認証情報と、ローテーション済みまたはテスト用のキーを特定します。

# Parse TruffleHog JSON output for AWS findings
cat trufflehog-results.json | python3 -c "
import json, sys
for line in sys.stdin:
    finding = json.loads(line)
    if 'AWS' in finding.get('DetectorName', ''):
        print(f\"Detector: {finding['DetectorName']}\")
        print(f\"Verified: {finding.get('Verified', False)}\")
        print(f\"Source: {finding.get('SourceMetadata', {})}\")
        print(f\"Commit: {finding.get('SourceMetadata', {}).get('Data', {}).get('Git', {}).get('commit', 'N/A')}\")
        print(f\"File: {finding.get('SourceMetadata', {}).get('Data', {}).get('Git', {}).get('file', 'N/A')}\")
        print('---')
"

# Check if a detected access key is still active
aws iam get-access-key-last-used --access-key-id AKIAIOSFODNN7EXAMPLE

# List all access keys for a user to find active keys
aws iam list-access-keys --user-name target-user \
  --query 'AccessKeyMetadata[*].[AccessKeyId,Status,CreateDate]' --output table

ステップ 4：git-secrets でプリコミットフックを設定する

プリコミットフックとして git-secrets を使用し、認証情報がコミットされないようにします。

# Install git-secrets
git secrets --install  # In each repository

# Register AWS credential patterns
git secrets --register-aws

# Add custom patterns for internal credential formats
git secrets --add 'AKIA[0-9A-Z]{16}'
git secrets --add 'aws_secret_access_key\s*=\s*.{40}'
git secrets --add 'aws_session_token\s*=\s*.+'

# Scan entire repository history
git secrets --scan-history

# Add to global git template for all new repos
git secrets --install ~/.git-templates/git-secrets
git config --global init.templateDir ~/.git-templates/git-secrets

ステップ 5：TruffleHog を CI/CD パイプラインに統合する

CI/CD ゲートとして TruffleHog のスキャンを追加し、漏えいした認証情報を含むデプロイをブロックします。

# GitHub Actions workflow (.github/workflows/secrets-scan.yml)
name: Secrets Scan
on: [push, pull_request]

jobs:
  trufflehog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: TruffleHog Scan
        uses: trufflesecurity/trufflehog@main
        with:
          extra_args: --only-verified --results=verified

# GitLab CI (.gitlab-ci.yml)
secrets_scan:
  stage: test
  image: trufflesecurity/trufflehog:latest
  script:
    - trufflehog git file://$CI_PROJECT_DIR --since-commit $CI_COMMIT_BEFORE_SHA --only-verified --fail
  allow_failure: false

ステップ 6：検出された認証情報の漏えいに対応する

有効な認証情報の漏えいが見つかった場合は、インシデント対応手順を実行します。

# IMMEDIATE: Deactivate the exposed access key
aws iam update-access-key \
  --user-name compromised-user \
  --access-key-id AKIAEXPOSEDKEY123456 \
  --status Inactive

# Generate new credentials
aws iam create-access-key --user-name compromised-user

# Review CloudTrail for unauthorized usage of the exposed key
aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=AccessKeyId,AttributeValue=AKIAEXPOSEDKEY123456 \
  --start-time 2026-01-01T00:00:00Z \
  --query 'Events[*].[EventTime,EventName,EventSource,SourceIPAddress]' \
  --output table

# Delete the exposed key after rotation is confirmed
aws iam delete-access-key \
  --user-name compromised-user \
  --access-key-id AKIAEXPOSEDKEY123456

# Remove the credential from git history using BFG Repo Cleaner
java -jar bfg.jar --replace-text credentials.txt repo.git

主な概念

用語	定義
TruffleHog	正規表現パターンと検証 API を使用して、Git の履歴、ファイルシステム、クラウドサービスをスキャンし、漏えいした認証情報を検出するオープンソースのシークレット検出ツール
検証済みシークレット	TruffleHog が対象サービスへの API 呼び出し（AWS STS の GetCallerIdentity など）によって、現在も有効であることを確認した認証情報
git-secrets	AWS Labs のプリコミットフックツール。AWS 認証情報のパターンに一致する文字列が Git リポジトリにコミットされるのを防ぎます
アクセスキーのローテーション	キーが侵害された場合の露出期間を短縮するため、AWS のアクセスキーペアを定期的に交換する手法
BFG Repo Cleaner	リポジトリ全体を書き換えることなく Git の履歴から機密データを削除するツール。git filter-branch より高速です
GitHub Secret Scanning	既知の認証情報パターンを公開リポジトリからスキャンし、認証情報のプロバイダーに通知する GitHub ネイティブ機能

ツールとシステム

• TruffleHog v3：Git、ファイルシステム、S3 をサポートし、CI/CD と統合できる主要なスキャンエンジン。有効な認証情報の検出にも対応します
• git-secrets：開発者のワークステーションで認証情報のコミットを防ぐ、AWS Labs のプリコミットフック
• BFG Repo Cleaner：漏えいの検出後に、Git の履歴から認証情報を迅速に削除するツール
• AWS GuardDuty：想定外の場所からの AWS 認証情報の異常な使用をアラートする脅威検出サービス
• GitHub Advanced Security：プッシュ保護を備えた、GitHub リポジトリ向けのプラットフォームネイティブなシークレットスキャン

よくあるシナリオ

シナリオ：開発者が AWS 認証情報を公開 GitHub リポジトリにコミットする

コンテキスト：GitHub のシークレットスキャンにより、AWS アクセスキーが公開リポジトリにプッシュされたとの通知が届きました。このキーは、本番環境の S3 と DynamoDB へのアクセス権を持つ開発者のものです。

対応方法：

1. aws iam update-access-key --status Inactive を使用して、直ちにアクセスキーを無効化します
2. 公開された AccessKeyId で絞り込み、aws cloudtrail lookup-events を実行して不正使用がないか確認します
3. trufflehog git でリポジトリの全履歴をスキャンし、ほかに公開された認証情報がないか確認します
4. 開発者用の新しいアクセスキーを生成し、Secrets Manager を通じて渡します
5. BFG Repo Cleaner を使用して、Git の履歴から認証情報を削除します
6. 開発者のワークステーションに git-secrets のプリコミットフックをインストールします
7. 再発を防ぐため、リポジトリの CI/CD パイプラインに TruffleHog を追加します

注意点：コミットを削除したり、強制プッシュしたりするだけでは、GitHub のキャッシュやフォークから認証情報は削除されません。AWS 側で直ちにキーを無効化する必要があります。GitHub のシークレットスキャンからすでに AWS に通知が送信され、自動的にキーが無効化されている場合があります。

出力形式

AWS Credential Exposure Scan Report
======================================
Scan Target: github.com/acme-corp (42 repositories)
Scan Date: 2026-02-23
Tool: TruffleHog v3.63.0
Mode: Full git history scan with verification

VERIFIED FINDINGS (Active Credentials):
[CRED-001] AWS Access Key - VERIFIED ACTIVE
  Key ID: AKIA...WXYZ
  Repository: acme-corp/backend-api
  File: deploy/config.env
  Commit: a1b2c3d (2025-08-15)
  Author: [email protected]
  IAM User: svc-backend-deploy
  Permissions: S3, DynamoDB, SQS (production)
  Status: CRITICAL - Key active and used from 3 IP addresses
  Action Required: Immediate deactivation and rotation

[CRED-002] AWS Secret Key - VERIFIED ACTIVE
  Repository: acme-corp/data-pipeline
  File: scripts/etl_config.py
  Commit: d4e5f6g (2025-11-22)
  Author: [email protected]
  Status: HIGH - Key active, last used 2 days ago

UNVERIFIED FINDINGS (Potential Credentials):
  Total pattern matches: 15
  Likely test/example keys: 12
  Requires manual review: 3

SUMMARY:
  Repositories scanned: 42
  Commits analyzed: 125,847
  Verified active credentials: 2
  Unverified credential patterns: 15
  Repositories with pre-commit hooks: 8 / 42