pfrederiksen/guardduty-playbook-commons

[](https://github.com/pfrederiksen/guardduty-playbook-commons/actions/workflows/ci.yml) [](https://pypi.org/project/guardduty-playbook-commons/) [](LICENSE) [](https://www.python.org/downloads/) # guardduty-playbook-commons 安全团队总是重复构建相同的 GuardDuty 响应逻辑 —— 一个团队编写 Tines workflows，另一个构建 Step Functions，第三个维护 Python scripts —— 所有人都以专有格式编码相同的补救知识。**guardduty-playbook-commons** 在供应商中立的 YAML schema 中定义 playbook 逻辑，并将其编译为多种自动化目标。可以把它看作是“用于事件响应的 Sigma Rules”。 ## 安装 ``` # 从 PyPI 安装 pip install guardduty-playbook-commons # 或从源码安装（用于开发或获取 playbook YAML 文件） git clone https://github.com/pfrederiksen/guardduty-playbook-commons.git cd guardduty-playbook-commons pip install -e ".[dev]" ``` 要运行生成的 Python runbooks，还需安装 boto3： ``` pip install guardduty-playbook-commons[runbook] ``` ## 快速开始 ``` # 将单个 playbook 转换为 Python runbook gdpc convert playbooks/iam/IAMUser-AnomalousBehavior.yaml --target python --output out/ # 将所有 playbook 转换为 Tines Stories gdpc convert playbooks/ --target tines --output out/ # 将所有 playbook 转换为 Step Functions ASL gdpc convert playbooks/ --target stepfunctions --output out/ # 根据 schema 验证所有 playbook gdpc validate playbooks/ ``` ## 使用场景 ### SOC / 事件响应团队 以共享的、版本控制的格式定义您的 GuardDuty 响应 runbooks。新分析师可以遵循一致的 分类 → 调查 → 遏制 步骤，而不是依赖口口相传的知识。使用带有 `--dry-run` 参数的 Python runbooks 进行临时事件处理和培训。 ### SOAR 平台工程师 将社区 playbooks 直接转换为您的自动化平台。Tines 团队获得可导入的 Story JSON；Step Functions 团队获得带有 Lambda 占位符的 ASL 定义，他们可以将其部署在现有基础设施旁。 ### 安全咨询公司 以客户使用的任何自动化格式向他们交付标准化的事件响应 playbooks。维护一个单一事实来源并按项目编译。 ### 红队 / 紫队演练 使用 playbooks 作为检测-响应覆盖范围的测试基线。运行 `gdpc convert --target python` 获取可执行的 runbooks，以验证在模拟攻击期间遏制操作是否实际触发。 ### 社区知识共享 贡献包含现实世界调查查询和遏制步骤的 playbooks。与博客文章不同，这些 playbooks 是机器可读的，可立即投入使用。 ## Schema 概述 每个 playbook 都是一个 YAML 文件，针对特定的 GuardDuty finding 类型定义分类、调查、遏制和升级步骤： ``` id: IAMUser-AnomalousBehavior version: "1.0.0" finding_type: "IAMUser/AnomalousBehavior" severity: [MEDIUM, HIGH, CRITICAL] description: "Respond to anomalous IAM user behavior" triage: - step: "Check if the IAM user is human or service account" how: "aws iam get-user --user-name {principal_id}" investigation: queries: - name: "Recent API calls by this principal" type: athena template: | SELECT eventTime, eventName, sourceIPAddress, errorCode FROM cloudtrail_logs WHERE userIdentity.userName = '{principal_id}' AND eventTime > DATE_ADD('hour', -24, NOW()) containment: automated: false actions: - id: deny_all_access description: "Attach DenyAll inline policy" aws_cli: "aws iam put-user-policy --user-name {principal_id} ..." requires_confirmation: true escalation: notify: - channel: slack condition: "severity == CRITICAL" message: "GuardDuty CRITICAL: {finding_type} on {principal_id}" variables: - name: principal_id source: finding.resource.accessKeyDetails.userName - name: account_id source: finding.accountId ``` 有关完整的 schema 参考，请参阅 [docs/schema.md](docs/schema.md)。 ## 支持的输出目标 | Target | Flag | Output | Description | |--------|------|--------|-------------| | Tines | `--target tines` | JSON | Tines Story，每步包含 actions | | Python Runbook | `--target python` | .py | 独立的 boto3 脚本，支持 `--dry-run` | | Step Functions | `--target stepfunctions` | JSON | AWS Step Functions ASL，包含 Lambda 占位符 | ## 输出示例 ### Python Runbook ``` gdpc convert playbooks/iam/IAMUser-AnomalousBehavior.yaml --target python --output out/ ``` 生成一个包含 argparse、从真实 GuardDuty finding JSON 中提取变量以及交互式遏制步骤的自包含脚本： ``` def extract_variables(finding: dict) -> dict: """Extract playbook variables from a GuardDuty finding.""" principal_id = finding.get("resource", {}).get("accessKeyDetails", {}).get("userName", "UNKNOWN") account_id = finding.get("accountId", "UNKNOWN") region = finding.get("region", "UNKNOWN") return {"principal_id": principal_id, "account_id": account_id, "region": region} def attach_deny_all_policy(variables: dict, dry_run: bool = False) -> None: """Attach an inline DenyAll policy to the IAM user to block all API access""" print(f"\n[CONTAINMENT] Attach DenyAll policy") cmd = f"""aws iam put-user-policy --user-name {variables['principal_id']} ...""" if dry_run: print(f" [DRY RUN] Skipping execution.") return confirm = input(" Execute this action? (yes/no): ") ... ``` 针对真实 finding 运行： ``` python out/iam-user-anomalous-behavior.py --finding-json finding.json --dry-run ``` ### Tines Story JSON ``` gdpc convert playbooks/iam/IAMUser-AnomalousBehavior.yaml --target tines --output out/ ``` 生成带有链接 actions 的可导入 Tines Story： ``` { "name": "GuardDuty: iam-user-anomalous-behavior", "actions": [ { "id": 1, "name": "Triage: Determine if the principal is a human user or a service account", "type": "Send to Story", "description": "Check the userName and userType in the finding's accessKeyDetails..." }, { "id": 4, "name": "Investigate: Recent API calls by the principal (last 24h)", "type": "Event Transformation", "options": { "query_template": "SELECT eventTime, eventSource, eventName ..." } }, { "id": 6, "name": "Contain: Attach an inline DenyAll policy", "type": "Send to Story" } ], "links": [ { "source": 1, "receiver": 2 }, { "source": 2, "receiver": 3 } ] } ``` ### Step Functions ASL ``` gdpc convert playbooks/iam/IAMUser-AnomalousBehavior.yaml --target stepfunctions --output out/ ``` 生成带有 Lambda ARN 占位符和列出所需 Lambda 部署的 `_comment` 的 ASL： ``` { "_comment": "Required Lambda functions: gdpc-query-executor; gdpc-attach-deny-all-policy; gdpc-notify-slack", "StartAt": "Triage_1", "States": { "Triage_1": { "Type": "Pass", "Comment": "Determine if the principal is a human user or a service account", "Result": { "step": "...", "instructions": "..." }, "Next": "Triage_2" }, "Contain_attach-deny-all-policy": { "Type": "Task", "Comment": "[MANUAL] Attach DenyAll policy", "Resource": "arn:aws:states:::lambda:invoke.waitForTaskToken", "Parameters": { "task_token.$": "$$.Task.Token", "variables.$": "$.variables" } } } } ``` ## Playbook 覆盖范围 | Finding Type | Severity | Automated | |-------------|----------|-----------| | IAMUser/AnomalousBehavior | MEDIUM, HIGH, CRITICAL | No | | IAMUser/InstanceCredentialExfiltration.OutsideAWS | HIGH, CRITICAL | No | | Policy/S3BucketPublicAccessGranted | HIGH, CRITICAL | No | | UnauthorizedAccess/S3MaliciousIPCaller.Custom | MEDIUM, HIGH, CRITICAL | No | | CryptoCurrency/EC2BitcoinTool.B!DNS | HIGH | No | | UnauthorizedAccess/EC2TorClient | HIGH | No | | Backdoor/Lambda.NetworkPortProbing | MEDIUM, HIGH | No | | Execution/Malware.EC2MaliciousFile | HIGH, CRITICAL | No | ## 贡献 我们欢迎贡献！最有帮助的方式包括： ### 添加新 Playbooks GuardDuty 有 [100+ finding types](https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_finding-types-active.html) —— 我们仅覆盖了 8 个。高价值的补充包括： - **RDS findings**: `CredentialAccess/RDS.AnomalousBehavior.SuccessfulLogin` - **EKS findings**: `PrivilegeEscalation/Kubernetes.PrivilegedContainer` - **Runtime Monitoring**: `Execution/Runtime.ReverseShell` - **DNS findings**: `Trojan/EC2.DNSDataExfiltration` ### 添加新输出目标 转换器是模块化的 —— 每个目标都是一个带有 `convert(playbook: dict)` 函数的单个 Python 模块。合适的候选目标： - **XSOAR (Cortex)** playbook YAML - **Splunk SOAR** (Phantom) app JSON - **Terraform** 用于部署 Step Functions + Lambda stubs - **Markdown runbook** 用于 wiki/Confluence 发布 ### 改进现有 Playbooks - 添加更具体的调查查询（VPC Flow Logs, DNS logs, S3 access logs） - 包含常见日志源的 Athena table 创建 DDL - 为多账户/组织环境添加条件逻辑 有关分步指南、schema 参考和 PR 检查清单，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 Apache 2.0 — 请参阅 [LICENSE](LICENSE)。

标签：AMSI绕过, ASL, AWS, boto3, DevSecOps, DPI, GuardDuty, Python, SOAR, Step Functions, Tines, YAML, 上游代理, 供应商中立, 剧本, 威胁检测, 安全库, 开源, 无后门, 自动修复, 补救措施, 逆向工具