RIT-MESH/aws-guardduty-tines-jira-incident-response

# AWS GuardDuty → Tines → Jira 事件响应 ``` ╔════════════════════════════════════════════════════════════════╗ ║ Event-driven AWS security monitoring • SOAR automation • IaC ║ ╚════════════════════════════════════════════════════════════════╝ ```         一个自动化的安全事件响应工作流，它通过 **Amazon EventBridge** 接收 **Amazon GuardDuty** 的发现结果，将其转发到 **Tines** 进行扩充和去重，并创建或更新 **Jira Cloud** 事件工单 —— 然后在整个响应生命周期中跟踪该事件。 ## 业务问题 SOC 团队被大量重复的 GuardDuty 发现结果所淹没。如果没有自动化，相同的发现结果会被重复分类，导致工单重复，并且会忽略严重程度的增加。该项目展示了一个完整的事件驱动 SOAR pipeline，它能够： - 检测并路由达到或超过可配置严重程度的 GuardDuty 发现结果。 - 规范化、扩充并**去重**发现结果。 - 为每个发现结果创建一个单一的、结构良好的 Jira 事件。 - 当发现结果重复出现时，添加复发评论并更新严重程度。 - 提供可观测性（日志、警报、死信队列）和弹性（重试、DLQ）。 ## 核心功能 - **AWS 安全监控** — 包含 S3、Kubernetes 和恶意软件保护源的 GuardDuty 检测器。 - **事件驱动架构** — 具有可配置最低严重程度过滤的 EventBridge 规则。 - **SOAR 自动化** — 包含凭据占位符的 Tines Story（19 个 action）。 - **事件响应工作流** — 带有去重功能的 Jira 创建/搜索/评论/状态流转。 - **REST API 集成** — 使用有效的 Atlassian Document Format (ADF) 的 Jira Cloud REST API v3。 - **基础设施即代码** — Terraform（fmt/init/validate 绿灯），最小权限 IAM。 - **Python 自动化** — 类型化、模块化、仅使用标准库、经过全面测试。 - **安全的密钥管理** — Secrets Manager / SSM 引用；代码或状态中无密钥。 - **可观测性** — CloudWatch 日志 + 警报 + SQS DLQ。 - **弹性** — 重试/退避/Retry-After、死信队列、畸形事件处理。 - **测试** — 106 个测试，87.9% 覆盖率；ruff/black/mypy 无报错。 - **DevSecOps 就绪** — CI/CD 工作流和质量文件（在后续阶段添加）。 ## 架构 ``` flowchart LR GD["Amazon GuardDuty"] --> EB["Amazon EventBridge
(rule + severity filter)"] EB -->|API Destination| TINES["Tines Webhook"] EB -->|optional Lambda| LAMBDA["Lambda Forwarder"] LAMBDA --> TINES TINES --> VALID["Validate • Normalize
Severity map • Dedup key"] VALID --> JIRASEARCH["Jira REST API v3
Search (JQL)"] JIRASEARCH -->|new| CREATE["Create incident ticket
(ADF description)"] JIRASEARCH -->|duplicate| COMMENT["Add recurrence comment
Update severity/last-seen"] CREATE --> TRACK["Track lifecycle
New→…→Closed"] COMMENT --> TRACK EB -.->|failures| DLQ["SQS DLQ"] LAMBDA -.->|failures| DLQ DLQ --> CW["CloudWatch alarms"] ``` 完整的图表集合（事件处理序列、去重流程、错误处理、事件生命周期）位于 [docs/architecture.md](docs/architecture.md) 中。 ## 事件流 ``` sequenceDiagram participant GD as GuardDuty participant EB as EventBridge participant T as Tines participant J as Jira GD->>EB: GuardDuty Finding event EB->>EB: severity >= min filter alt API Destination (default) EB->>T: POST normalized finding else Lambda forwarder EB->>T: POST via Lambda (retries) end T->>T: validate + normalize + dedup key T->>J: GET /search (JQL by dedup label) alt no existing issue T->>J: POST /issue (create, ADF) else existing issue T->>J: POST /comment (recurrence) end T->>J: POST /transitions (lifecycle) ``` ## 技术栈 | 层级 | 技术 | |---|---| | 检测 | Amazon GuardDuty | | 事件路由 | Amazon EventBridge (rule, API Destination, Connection) | | SOAR | Tines (Webhook + HTTP Request actions) | | 工单系统 | Jira Cloud REST API v3 (ADF) | | 计算 (可选) | AWS Lambda (Python 3.12, 仅标准库) | | IaC | Terraform (AWS provider ~> 5.0) | | 密钥 | AWS Secrets Manager + SSM Parameter Store | | 可观测性 | Amazon CloudWatch Logs + Alarms + SQS DLQ | | 自动化代码 | Python 3.11+ (类型化，仅标准库) | | 测试 | pytest, pytest-cov, ruff, black, mypy | ## 仓库结构 ``` . ├── src/ │ ├── incident_response/ # core library (validation, normalizer, jira ADF, http, masking, logging) │ └── lambda_forwarder/ # optional Lambda target ├── tools/simulate_finding.py # CLI simulator (dry-run by default) ├── local_emulator/ # Tines-independent fallback (stdlib HTTP + mock Jira) ├── examples/ # 12 sanitized GuardDuty event files ├── tests/ # pytest suite (106 tests) ├── terraform/ # IaC (GuardDuty, EventBridge, IAM, SQS, monitoring, lambda, secrets) ├── tines/ # importable Tines Story template (JSON) ├── docs/ # architecture, setup, schema, playbooks, threat model, etc. ├── pyproject.toml ├── Makefile # (added in CI/quality phase) └── README.md ``` ## 前置条件 - Python 3.11+ - Terraform >= 1.5 - AWS 账户（仅用于部署；演示不需要） - Tines 租户和 Jira Cloud 站点（仅用于实时集成；演示使用本地模拟器） ## AWS 费用（警告） - GuardDuty 按受监控的资源（EC2/EBS、S3、Kubernetes 等）计费。 - EventBridge、SQS、CloudWatch Logs 和 Secrets Manager 会产生少量的按调用/GB 计算的费用。 - 对于非同寻常的账户，**每天几美元**是现实的；成本会随着工作负载而增加。 - 使用 `guardduty_min_severity` 来减少数量，并在完成后运行 `terraform destroy`。 - 当前定价请参见 https://aws.amazon.com/guardduty/pricing/ （可能会有变动）。 ## 快速开始（演示，不需要 AWS/Tines/Jira） ``` python -m pip install -e ".[dev]" python -m tools.simulate_finding --input examples/guardduty-high-severity.json --dry-run ``` 启动本地模拟器并发送一个脱敏的发现结果： ``` python -m local_emulator.server # serves on 127.0.0.1:8080 # 在另一个 shell 中： curl -X POST http://127.0.0.1:8080/webhook ` -H "Content-Type: application/json" ` --data @examples/guardduty-high-severity.json ``` 完整的的安全演示请参见 [docs/demo-guide.md](docs/demo-guide.md)。 ## AWS 部署 1. 配置 AWS 凭证。 2. `cd terraform` 3. `cp terraform.tfvars.example terraform.tfvars` 并进行编辑（设置 Tines webhook URL 等）。 4. 在带外设置 Secrets Manager 的值（绝不要在 tfvars 中设置）。 5. `terraform init && terraform plan && terraform apply` 请参见 [docs/setup-aws.md](docs/setup-aws.md)。 ## Tines 设置 导入 Story 并创建这四个凭据。请参见 [docs/setup-tines.md](docs/setup-tines.md)。 ## Jira 设置 创建 Jira API token 并配置优先级映射。请参见 [docs/setup-jira.md](docs/setup-jira.md)。 ## 测试 ``` python -m pytest python -m pytest --cov=src/incident_response --cov=src/lambda_forwarder --cov=tools --cov=local_emulator --cov-report=term-missing --cov-fail-under=85 ruff check . black --check . mypy src tools local_emulator ``` 结果：**106 个通过，87.9% 覆盖率，ruff/black/mypy 无报错。** ## GuardDuty 事件示例 参见 `examples/guardduty-high-severity.json`（已脱敏：仅包含账户 `111122223333`、文档 IP 范围）。请参见 [docs/event-schema.md](docs/event-schema.md)。 ## Jira 工单示例 摘要：`[GuardDuty][High][111122223333][us-east-1] Trojan Dropper detected on EC2 instance.` 请参见 [docs/jira-ticket-schema.md](docs/jira-ticket-schema.md)。 ## 去重行为 重复的发现结果共享一个稳定的 `gd-<16hex>` 标签；将添加复发评论，而不是创建重复的工单。请参见 [docs/deduplication.md](docs/deduplication.md)。 ## 故障处理 - 遇到超时/408/429（遵守 `Retry-After`）/5xx 时进行 HTTP 重试；其他 4xx 错误不重试。 - 无法投递的事件进入 SQS DLQ；CloudWatch 警报会针对 DLQ 深度和失败的调用发出告警。 - 畸形/未经身份验证的事件将被拒绝，且日志中不包含密钥。 - 请参见 [docs/architecture.md](docs/architecture.md)（错误处理流程）和 [docs/troubleshooting.md](docs/troubleshooting.md)。 ## 监控 CloudWatch 日志组、DLQ 深度警报、EventBridge FailedInvocations 警报、Lambda 错误警报。请参见 [docs/monitoring.md](docs/monitoring.md)。 ## 安全控制 - 最小权限 IAM (EventBridge, Lambda)。 - 创建不带版本的 Secrets Manager 密钥（值绝不会出现在 Terraform 状态中）。 - 日志中的递归密钥掩码；webhook URL 已脱敏。 - Webhook 共享密钥身份验证。 - 输入验证和 payload 大小限制。 - 请参见 [docs/threat-model.md](docs/threat-model.md) (STRIDE) 和 [SECURITY.md](SECURITY.md)（在 CI/质量阶段添加）。 ## 事件响应生命周期 ``` flowchart LR A[New] --> B[Triage] --> C[Investigating] --> D[Contained] D --> E[Remediated] --> F[Closed] ``` 剧本（IAM key、EC2、crypto、S3、malware、Kubernetes）位于 [docs/incident-response-playbooks.md](docs/incident-response-playbooks.md) 中。 出于设计考虑，已禁用自动的破坏性遏制。 ## 清理 ``` cd terraform terraform destroy ``` 移除 Tines Story/凭据，并轮换/删除 Jira API token。 ## 故障排除 请参见 [docs/troubleshooting.md](docs/troubleshooting.md)。 ## 已知限制 - API Destination 路径将 Tines webhook URL 存储在 EventBridge 配置中；使用 Lambda 路径 + Secrets Manager 可避免此问题。 - Jira 流转 ID 和优先级名称是特定于站点的。 - Tines Story 是一个模板；必须在真实的 Tines 租户中验证 Liquid 表达式。 - 出于设计考虑，不包含自动的破坏性修复。 ## 未来改进 - 在 Lambda 中进行运行时密钥解析（从 Secrets Manager 获取 webhook URL/secret）。 - 将 Jira 状态双向同步回跟踪仪表板。 - 在 N 次复发后自动抑制低严重程度的噪音。 - 支持多账户 GuardDuty 聚合器。 ## 本项目展示的内容 AWS 安全监控、事件驱动架构、SOAR 自动化、事件响应工作流、REST API 集成、基础设施即代码、Python 自动化、安全的密钥管理、可观测性、弹性、测试和 DevSecOps 就绪情况。 ## 设计决策 - EventBridge 位于 GuardDuty 和 Tines 之间（GuardDuty 不会 POST 到任意 URL）。 - API Destination 是首选目标；Lambda 对于自定义签名/重试/密钥是可选的。 - 去重使用存储为 Jira 标签的发现 ID 的稳定哈希。 - ADF 用于 Jira 富文本（REST API v3 要求）。 - 引用密钥，绝不嵌入；创建的 Secrets Manager 密钥是空的。 ## 权衡 - 简单胜于过度设计：仅使用标准库的 Python，没有繁重的运行时依赖。 - Tines Story 是一个模板，不会在此处执行；仅作为 JSON 进行验证。 - `terraform plan`/`apply` 需要实时的 AWS 凭证（未在此仓库的验证中运行）。 ## 面试讨论点 请参见 [docs/interview-talking-points.md](docs/interview-talking-points.md)。 ## 截图 请参见 [docs/screenshots.md](docs/screenshots.md)（占位符）。 ## 免责声明 本项目仅用于教育目的，展示了架构和工程实践。GuardDuty 发现结果是通过 AWS 服务生成和传递的。Tines 和 Jira 可能需要单独的账户或许可证；免费层的可用性和定价可能会发生变化。请使用脱敏的样本发现结果进行演示。在生产环境使用之前，请进行审查和强化。出于设计考虑，已禁用自动的破坏性遏制。

标签：AWS GuardDuty, ECS, Jira, Python, SOAR自动化, Terraform, 安全规则引擎, 安全运营, 扫描框架, 无后门, 逆向工具