detecting-aws-credential-exposure-with-trufflehog

使用 TruffleHog 检测 AWS 凭证泄露

何时使用

• 将密钥检测集成到 CI/CD 流水线中，防止凭证提交进入生产环境时
• 对现有代码仓库进行安全审计，查找历史上曾提交过的 AWS 凭证时
• 响应 AWS GuardDuty 关于凭证从异常 IP 或区域被使用的告警时
• 接入来自被收购公司或第三方供应商的代码仓库时
• 验证凭证轮换流程是否已清除所有旧访问密钥的引用时

请勿使用于实时凭证监控（请使用 AWS GuardDuty 或 Amazon Macie）、密钥管理（请使用 AWS Secrets Manager 或 HashiCorp Vault），或检测 PII 等非凭证类敏感数据（请使用 Amazon Macie 或 DLP 工具）。

前置条件

• 已安装 TruffleHog v3（brew install trufflehog 或 pip install trufflehog）
• 已安装 git-secrets 以集成 pre-commit 钩子（brew install git-secrets）
• 拥有源代码仓库的访问权限（GitHub、GitLab、Bitbucket 或本地 git 仓库）
• AWS CLI 已配置，并具有检查密钥状态的权限（iam:ListAccessKeys、iam:GetAccessKeyLastUsed）
• 用于扫描组织范围内仓库的 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 设置 pre-commit 钩子

使用 git-secrets 作为 pre-commit 钩子，从一开始就防止凭证被提交。

# 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 流水线

将 TruffleHog 扫描添加为 CI/CD 门禁，阻止包含泄露凭证的部署。

# 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 的 pre-commit 钩子工具，防止将匹配 AWS 凭证模式的字符串提交到 git 仓库
访问密钥轮换	定期更换 AWS 访问密钥对的实践，以在密钥泄露时限制暴露窗口
BFG Repo Cleaner	从 git 历史中移除敏感数据的工具，无需重写整个仓库，比 git filter-branch 更快
GitHub Secret Scanning	GitHub 原生功能，扫描公共仓库中的已知凭证模式并通知凭证提供方

工具与系统

• TruffleHog v3：主要扫描引擎，支持 git、文件系统、S3 和 CI/CD 集成，并具备已验证凭证检测能力
• git-secrets：AWS Labs 的 pre-commit 钩子，在开发者工作站层面防止凭证提交
• 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. 运行 aws cloudtrail lookup-events，按泄露的 AccessKeyId 过滤，检查是否存在未授权使用
3. 使用 trufflehog git 扫描完整的仓库历史，查找任何其他泄露的凭证
4. 为该开发者生成新的访问密钥，并通过 Secrets Manager 交付
5. 使用 BFG Repo Cleaner 从 git 历史中移除该凭证
6. 在开发者的工作站上安装 git-secrets pre-commit 钩子
7. 将 TruffleHog 添加到仓库的 CI/CD 流水线中，防止再次发生

陷阱：仅仅删除提交或强制推送，并不能从 GitHub 的缓存或 fork 中移除凭证。必须立即在 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