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，用于预提交钩子集成（`brew install git-secrets`）
- 访问源代码仓库（GitHub、GitLab、Bitbucket 或本地 git 仓库）
- 配置了用于检查密钥状态的 AWS CLI（`iam:ListAccessKeys`、`iam:GetAccessKeyLastUsed`）
- GitHub 或 GitLab API 令牌，用于扫描整个组织的仓库

## 工作流程

### 步骤 1：安装和配置 TruffleHog

安装 TruffleHog v3 并验证其能够检测 AWS 凭据模式。

```bash
# 安装 TruffleHog v3
pip install trufflehog

# 或从二进制发行版安装
curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin

# 验证安装
trufflehog --version

# 使用已知测试仓库测试
trufflehog git https://github.com/trufflesecurity/test_keys --only-verified
```

### 步骤 2：扫描 Git 仓库中的暴露凭据

扫描完整 git 历史（包括所有分支和提交），查找 AWS 访问密钥、私密密钥和会话令牌。

```bash
# 扫描本地 git 仓库（完整历史）
trufflehog git file:///path/to/repo --only-verified --json > trufflehog-results.json

# 扫描 GitHub 组织的仓库
trufflehog github --org=your-organization --token=$GITHUB_TOKEN --only-verified

# 扫描特定 GitHub 仓库的所有分支
trufflehog git https://github.com/org/repo.git --only-verified --branch=main

# 扫描 GitLab 组
trufflehog gitlab --group=your-group --token=$GITLAB_TOKEN --only-verified

# 扫描文件系统路径，查找配置文件中的凭据
trufflehog filesystem /path/to/project --only-verified
```

### 步骤 3：分析和验证检测到的凭据

解析 TruffleHog 结果，识别已验证（仍处于活跃状态）的凭据与已轮换或测试密钥。

```bash
# 解析 TruffleHog JSON 输出中的 AWS 发现
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\"检测器: {finding['DetectorName']}\")
        print(f\"已验证: {finding.get('Verified', False)}\")
        print(f\"来源: {finding.get('SourceMetadata', {})}\")
        print(f\"提交: {finding.get('SourceMetadata', {}).get('Data', {}).get('Git', {}).get('commit', 'N/A')}\")
        print(f\"文件: {finding.get('SourceMetadata', {}).get('Data', {}).get('Git', {}).get('file', 'N/A')}\")
        print('---')
"

# 检查检测到的访问密钥是否仍处于活跃状态
aws iam get-access-key-last-used --access-key-id AKIAIOSFODNN7EXAMPLE

# 列出用户的所有访问密钥以查找活跃密钥
aws iam list-access-keys --user-name target-user \
  --query 'AccessKeyMetadata[*].[AccessKeyId,Status,CreateDate]' --output table
```

### 步骤 4：使用 git-secrets 设置预提交钩子

使用 git-secrets 作为预提交钩子，从源头防止凭据被提交。

```bash
# 安装 git-secrets
git secrets --install  # 在每个仓库中

# 注册 AWS 凭据模式
git secrets --register-aws

# 为内部凭据格式添加自定义模式
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*.+'

# 扫描整个仓库历史
git secrets --scan-history

# 添加到全局 git 模板，用于所有新仓库
git secrets --install ~/.git-templates/git-secrets
git config --global init.templateDir ~/.git-templates/git-secrets
```

### 步骤 5：将 TruffleHog 集成到 CI/CD 流水线

添加 TruffleHog 扫描作为 CI/CD 门禁，阻止包含暴露凭据的部署。

```yaml
# GitHub Actions 工作流 (.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
```

```yaml
# 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：响应检测到的凭据暴露

发现已验证的暴露凭据时，执行事件响应程序。

```bash
# 立即: 停用暴露的访问密钥
aws iam update-access-key \
  --user-name compromised-user \
  --access-key-id AKIAEXPOSEDKEY123456 \
  --status Inactive

# 生成新凭据
aws iam create-access-key --user-name compromised-user

# 查看 CloudTrail，了解暴露密钥的未授权使用情况
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

# 确认轮换后删除暴露的密钥
aws iam delete-access-key \
  --user-name compromised-user \
  --access-key-id AKIAEXPOSEDKEY123456

# 使用 BFG Repo Cleaner 从 git 历史中删除凭据
java -jar bfg.jar --replace-text credentials.txt repo.git
```

## 核心概念

| 术语 | 定义 |
|------|------|
| TruffleHog | 开源密钥检测工具，使用正则表达式模式和验证 API 扫描 git 历史、文件系统和云服务中的暴露凭据 |
| 已验证密钥（Verified Secret） | TruffleHog 通过向目标服务（如 AWS STS GetCallerIdentity）进行 API 调用而确认仍处于活跃状态的凭据 |
| git-secrets | AWS Labs 预提交钩子工具，防止将匹配 AWS 凭据模式的字符串提交到 git 仓库 |
| 访问密钥轮换（Access Key Rotation） | 定期更换 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. 运行 `aws cloudtrail lookup-events` 并按暴露的 AccessKeyId 过滤，检查是否存在未授权使用
3. 使用 `trufflehog git` 扫描完整仓库历史，查找其他暴露的凭据
4. 为开发者生成新访问密钥，并通过 Secrets Manager 交付
5. 使用 BFG Repo Cleaner 从 git 历史中删除凭据
6. 在开发者工作站上安装 git-secrets 预提交钩子
7. 将 TruffleHog 添加到仓库的 CI/CD 流水线中以防止再次发生

**常见陷阱**：简单地删除提交或强制推送无法从 GitHub 缓存或 fork 中删除凭据。必须立即在 AWS 层面停用密钥。GitHub 密钥扫描可能已通知 AWS，触发了自动密钥停用。

## 输出格式

```
AWS 凭据暴露扫描报告
======================================
扫描目标: github.com/acme-corp（42 个仓库）
扫描日期: 2026-02-23
工具: TruffleHog v3.63.0
模式: 带验证的完整 git 历史扫描

已验证发现（活跃凭据）:
[CRED-001] AWS 访问密钥 - 已验证活跃
  密钥 ID: AKIA...WXYZ
  仓库: acme-corp/backend-api
  文件: deploy/config.env
  提交: a1b2c3d（2025-08-15）
  作者: developer@acme.com
  IAM 用户: svc-backend-deploy
  权限: S3、DynamoDB、SQS（生产环境）
  状态: 严重 - 密钥活跃且从 3 个 IP 地址使用过
  所需操作: 立即停用并轮换

[CRED-002] AWS 私密密钥 - 已验证活跃
  仓库: acme-corp/data-pipeline
  文件: scripts/etl_config.py
  提交: d4e5f6g（2025-11-22）
  作者: data-engineer@acme.com
  状态: 高 - 密钥活跃，2 天前最后使用

未验证发现（潜在凭据）:
  模式匹配总数: 15
  可能为测试/示例密钥: 12
  需要人工审查: 3

摘要:
  扫描的仓库数: 42
  分析的提交数: 125,847
  已验证的活跃凭据: 2
  未验证的凭据模式: 15
  已配置预提交钩子的仓库: 8 / 42
```