brookbdt/guardpost

# Guardpost 一个云原生 AI 辅助安全分诊流水线，使用 Terraform 配置 AWS 检测基础设施，摄取 GuardDuty 发现结果，使用 MITRE ATT&CK 上下文对其进行规范化和丰富化，将相关活动聚类为事件，并生成分析师就绪的风险评估和响应建议。 ## 架构 ``` AWS Infrastructure (Terraform) Python Detection Pipeline Outputs ┌─────────────────────────┐ ┌─────────────────────────────────┐ ┌──────────────┐ │ CloudTrail │ │ ingest │ │ Markdown │ │ GuardDuty ──────────────► │ normalize │ │ incident │ │ S3 (encrypted logs) │ │ enrich (MITRE ATT&CK) │───►│ reports │ │ IAM (least privilege) │ │ cluster │ │ │ │ SNS (alert routing) │ │ score (deterministic) │ │ JSON │ └─────────────────────────┘ │ triage (AI-assisted) ─────┐ │ │ artifacts │ │ report │ │ │ │ └────────────────────────────│────┘ │ Summary │ │ │ dashboard │ Claude API └──────────────┘ (structured clusters only) ``` **关键设计原则：** 确定性优于生成性。LLM 仅接收结构化的事件聚类 —— 绝不接收原始 JSON。所有解析、规范化、丰富化、聚类和评分均为确定性代码。 ## 快速开始 ``` # 1. 克隆项目并进入该目录 git clone cd guardpost # 2. 创建并激活 virtual environment python3 -m venv .venv source .venv/bin/activate # 3. 安装 package 和 dev dependencies pip install -e ".[dev]" ``` ## 运行流水线 以下所有命令均假设您位于项目根目录 (`guardpost/`) 且已激活虚拟环境。 ### 演示模式 (无需 AWS 凭证或 API 密钥) ``` # 在示例 GuardDuty 数据上运行完整 pipeline (AI triage 已禁用) python -m src.main --mode demo ``` ### 带 AI 分诊的演示模式 ``` # 请先设置您的 Anthropic API key export ANTHROPIC_API_KEY=your-key-here # 通过所有 7 个阶段运行 demo 数据，包括 AI triage python -m src.main --mode demo --triage ``` ### 实时模式 (需要 AWS 凭证) ``` # 确保已配置 AWS credentials (通过 aws configure, env vars, 或 IAM role) # 并设置用于 AI triage 的 Anthropic key export ANTHROPIC_API_KEY=your-key-here # 从您的 AWS account 运行实时 GuardDuty findings python -m src.main --mode live --triage ``` ### 自定义输出目录 ``` # 将报告写入自定义目录，而非默认的 output/ python -m src.main --mode demo --output-dir ./my-reports ``` ### CLI 帮助 ``` # 查看所有可用 flags 和用法示例 python -m src.main --help ``` ## 运行测试 ``` # 运行所有 tests pytest # 运行 tests 并显示详细输出 pytest -v # 运行 tests 并生成 coverage report pytest --cov=src # 运行指定的 test 文件 pytest tests/test_normalize.py pytest tests/test_enrich.py pytest tests/test_cluster.py pytest tests/test_score.py ``` ## Terraform 基础设施 `terraform/` 目录用于配置 AWS 安全遥测环境。所有 Terraform 命令必须在该目录内运行。 ``` # 进入 Terraform 目录 cd terraform # 初始化 Terraform providers 和 modules terraform init # 预览将要创建的内容 terraform plan # 部署 infrastructure terraform apply # 销毁所有已 provisioned 的资源 terraform destroy # 返回项目根目录 cd .. ``` ## 示例输出 运行 `python -m src.main --mode demo` 将通过完整流水线处理 10 个样本 GuardDuty 发现结果： - **10 个发现结果** 被规范化为标准 schema - **8 个事件聚类** 通过分组相关警报形成 - **确定性风险评分** 已分配 (0-100 分制) - **17 个报告文件** 已生成 (每个事件的 markdown + JSON，以及摘要仪表板)  ## 项目结构 ``` ├── src/ Python pipeline modules │ ├── main.py CLI entry point │ ├── schemas.py Pydantic data models (NormalizedAlert, IncidentCluster) │ ├── ingest.py Load findings from JSON or AWS API │ ├── normalize.py Flatten GuardDuty → canonical schema │ ├── enrich.py MITRE ATT&CK mapping + IP/resource context │ ├── cluster.py Group related alerts into incidents │ ├── score.py Deterministic risk scoring │ ├── triage.py AI-assisted triage via Claude API │ └── report.py Markdown + JSON report generation ├── terraform/ AWS infrastructure as code │ ├── main.tf Root module │ └── modules/ Child modules (cloudtrail, guardduty, s3, iam, sns) ├── data/ Sample findings and MITRE mappings ├── output/ Generated incident reports ├── tests/ pytest test suite └── docs/ Architecture and planning documents ``` ## 流水线阶段 | 阶段 | 模块 | 用途 | |-------|--------|---------| | 1. 摄取 | `ingest.py` | 从本地 JSON 或 AWS API 加载 GuardDuty 发现结果 | | 2. 规范化 | `normalize.py` | 将嵌套结构扁平化为标准 `NormalizedAlert` schema | | 3. 丰富化 | `enrich.py` | 添加 MITRE ATT&CK 映射，分类 IP，评估资源敏感度 | | 4. 聚类 | `cluster.py` | 按源 IP、发现类型、目标、时间窗口分组相关警报 | | 5. 评分 | `score.py` | 确定性风险评分 (严重性、数量、重现度、敏感度、技术风险) | | 6. 分诊 | `triage.py` | 通过 Claude 进行 AI 辅助分析 (仅限结构化聚类输入) | | 7. 报告 | `report.py` | 生成 markdown 事件报告、JSON 产物、摘要仪表板 | ## MITRE ATT&CK 覆盖范围 流水线将 GuardDuty 发现类型映射到 ATT&CK 技术： | 发现类型 | 技术 | 战术 | |-------------|-----------|--------| | SSH/RDP 暴力破解 | T1110 - Brute Force | Credential Access | | 端口探测 | T1046 - Network Service Discovery | Discovery | | 加密挖矿 | T1496 - Resource Hijacking | Impact | | 异常控制台登录 | T1078 - Valid Accounts | Initial Access | | 黑洞流量 | T1071/T1041 - C2/Exfiltration | Command and Control | | IAM 异常行为 | T1098/T1136 - Account Manipulation | Persistence | ## 风险评分 评分是确定性的且可解释的。每个聚类基于以下因素评分： - **严重性** (GuardDuty 原始严重性) - **发现数量** (更多发现 = 更高置信度) - **重现度** (时间窗口内的重复活动) - **目标敏感度** (生产环境/IAM 资源权重更高) - **技术风险** (凭证和持久化技术评分更高) AI 分诊层在此基础之上添加顾问式推理 —— 它不替代确定性评分。 ## AI 分诊契约 LLM **仅接收结构化的事件聚类摘要**，而非原始发现结果。它返回： - 执行摘要 - 风险推理 - 可能的攻击模式 - 调查步骤 (3-5 个具体行动) - 建议的响应行动 - 明确的不确定性 该模型是**分析师助手**，而非自主响应者。 ## 技术 - **Python 3.10+** 与 Pydantic, Rich - **Terraform** 用于 AWS 基础设施即代码 - **AWS** --- CloudTrail, GuardDuty, S3, IAM, SNS - **Anthropic Claude API** 用于 AI 辅助分诊 - **pytest** 用于测试 ## 许可证 MIT

标签：AMSI绕过, AWS, Claude, Cloudflare, CloudTrail, CVE检测, DevSecOps, DPI, ECS, GuardDuty, IAM, LLM, MITRE ATT&CK, Python, S3, SNS, SOAR, Terraform, Unmanaged PE, 上游代理, 事件关联, 合规监控, 威胁检测, 安全分诊, 安全管道, 安全规则引擎, 攻击聚类, 无后门, 漏洞分诊, 生成式AI, 索引, 自动化报告, 逆向工具