duynhat326/SOAR-Playbook-Project

# SOAR Playbook - 端点恶意软件告警自动化响应 ## 目录 - [背景与目标](#background-and-goals) - [已实现功能](#what-is-implemented) - [端到端工作流](#end-to-end-workflow) - [当前架构](#current-architecture) - [React 仪表盘](#react-dashboard) - [安全与敏感数据处理](#security-and-sensitive-data-handling) - [持久化模型](#persistence-model) - [安装与运行](#setup-and-run) - [主要 API 路由](#main-api-routes) - [项目结构](#project-structure) - [验证快照](#verification-snapshot) ## 背景与目标 本项目模拟了蓝队或 SOC 自动化流程如何以结构化、可解释的方式处理端点恶意软件告警。 本仓库已不再局限于单一的检测规则或独立的富化脚本，而是构建了更完整的 incident-response 路径： 1. 通过 CLI、API 或仪表盘接收告警 2. 利用威胁情报和资产上下文对告警进行富化 3. 将行为映射到 MITRE ATT&CK 4. 计算标准化风险评分 5. 执行策略驱动的响应动作 6. 生成分析师可读的报告 7. 持久化存储 incident 以供重放、追溯历史和调查 本项目的主要目标是展示系统设计、安全意识以及分析师工作流思维，而不仅仅是孤立的自动化代码片段。 ## 已实现功能 当前仓库已不再仅仅是一个本地演示。以下功能模块目前已在本项目中正常运行： - 通过 `services/workflow_service.py` 实现共享编排 - FastAPI incident 处理及历史 API - 以 React 仪表盘作为主要 UI - 默认以 Supabase Postgres 作为运行时持久化目标 - 基于 SQLite 的显式本地/测试流程 - 基于 VirusTotal 的实时哈希富化路径 - 通过 YAML 规则加载实现策略即数据 - 适配队列的执行追踪与关联元数据 - 支持针对重复 `alert_id` 处理的幂等重放 - 报告产物存储，支持 Markdown、HTML 及可选的 PDF - 用于多代理工作流的 A2A 协作总线 - 受 RBAC 保护的 incident 和 A2A API - 针对身份验证、数据脱敏、身份伪造及 HTML 报告转义的安全回归测试覆盖 本仓库近期完成的仪表盘改进包括： - 基于真实 FastAPI 后端的告警接收 - 在执行 `Process Alert` 后，实时刷新 incident 流和优先级队列 - 在 incident 详情中预览 Markdown 报告 - 在详情面板中提供 `Open HTML report` 操作 - 在 UI 中展示执行追踪 - 显示哈希和 IP 情报的富化来源 - 仅限操作员读取敏感详情 - 拒绝处理经过脱敏/屏蔽的 payload ## 端到端工作流 当前 pipeline 的运行方式如下： ### 1. 告警接收 系统接收包含以下字段等内容的恶意软件告警 payload： - `alert_id` - `hostname` - `username` - `process_name` - `file_path` - `file_hash` - `parent_process` - `command_line` - `destination_ip` - `severity` - `detection_name` ### 2. 威胁富化 工作流会对以下信息进行富化： - 文件哈希情报 - 目标 IP 情报 - 资产关键性 - MITRE ATT&CK 映射 当满足以下条件时，哈希富化将基于 VirusTotal 运行： ``` SOAR_INTEL_PROVIDER=virustotal VIRUSTOTAL_API_KEY=... ``` ### 3. 风险评分 富化后的告警将被评分，并标准化为以下风险级别： - `low` - `medium` - `high` - `critical` ### 4. 策略评估 策略引擎会评估响应规则，并生成： - 触发的动作 - 动作执行结果 - 策略判定依据 - 执行追踪 ### 5. 响应动作 根据具体场景，工作流可执行： - 隔离主机 - 结束进程 - 封禁 IP - 升级上报 - 创建工单 - 通知 SOC ### 6. 报告生成 系统可生成： - Markdown 报告 - HTML 报告 - PDF 报告（在受支持的情况下） ### 7. 持久化与重放 Incident、动作执行结果及报告元数据将被保存，以便分析师稍后可以从仪表盘或 API 重新打开它们。 ## 当前架构 ``` +--------------------------------------------------------------------------------------+ | SOAR Playbook Architecture | +--------------------------------------------------------------------------------------+ | Entry points | | | | main.py api/app.py dashboard/src | | CLI FastAPI React analyst console | | \ | / | | \ | / | | +-------------------------+------------------------------+ | | | | | services/workflow_service.py | | Shared orchestration layer | | | | +----------------------------------+---------------------------------------------------+ | Enrichment and analysis | Policy and response | Output and storage | | | | | | enrichment/hash_intel.py | engine/policy_loader.py | reporting/report_ | | enrichment/ip_intel.py | engine/policy_engine.py | generator.py | | enrichment/asset_db.py | engine/action_dispatcher | storage/incident_ | | enrichment/mitre_mapping.py | actions/* | repository.py | | engine/risk_scoring.py | | storage/postgres.py | | | | storage/sqlite_ | | | | repository.py | +----------------------------------+---------------------------+------------------------+ | Security and collaboration | | | | security/auth.py RBAC, bearer auth, redaction defaults | | a2a/* workspace, task, message, artifact coordination | +--------------------------------------------------------------------------------------+ | Primary UI: React dashboard | | Legacy UI kept only for reference: dashboard/app.py | | Default runtime persistence: Supabase/Postgres | | Explicit local/test persistence: SQLite | +--------------------------------------------------------------------------------------+ ``` ### 入口点 - `main.py` - `api/app.py` - `dashboard/src/` - `a2a/cli.py` ### 共享编排 - `services/workflow_service.py` 此服务是 CLI、API 和仪表盘流程共用的核心协调层。 ### 主要后端域 - `enrichment/`：负责威胁情报、MITRE 映射及资产上下文 - `engine/`：负责评分、策略加载与策略评估 - `actions/`：负责执行响应动作 - `reporting/`：负责生成报告 - `storage/`：负责数据仓储与持久化适配器 - `security/`：负责身份验证与 RBAC - `a2a/`：负责协作总线工作流 ### 持久化路径 - 默认运行时：Supabase/Postgres - 显式本地/测试路径：在特意指定本地数据库目标时使用 SQLite ### UI 模型 - 主要 UI：`dashboard/src/` - 旧版 UI：`dashboard/app.py` `dashboard/app.py` 仅作为旧版参考保留，不再是核心的仪表盘交互体验。 ## React 仪表盘 React 仪表盘目前是本项目的主要分析师控制台。 ### 主要面板 - 告警接收 - 优先级队列 - Incident 流 - Incident 详情 ### Incident 详情视图 详情面板目前会显示： - 风险摘要 - 主机与进程上下文 - 威胁遥测数据 - 自动化响应结果 - 策略判定依据 - MITRE ATT&CK 覆盖范围 - 执行追踪 - 报告产物路径 - Markdown 报告预览 - HTML 报告链接 - 原始告警 payload ### 开发代理模型 仪表盘通过 `dashboard/vite.config.ts` 中的 Vite proxy 使用 FastAPI 后端。 该本地代理会执行以下操作： - 读取仓库根目录下的 `.env.local` - 将 `/soar-api/*` 请求转发至 FastAPI - 原封不动地转发浏览器的 `Authorization` header 现在，仪表盘要求每个浏览器标签页必须在 `sessionStorage` 中携带各自的 bearer token，因此代理不再注入共享的操作员凭据。 ## 安全与敏感数据处理 受保护的 API 路由需要通过 Bearer token 进行身份验证。 ### Incident 角色 - `incident_process` - `incident_read` ### A2A 角色 - `a2a_admin` - `a2a_read` - `a2a_agent` ### 脱敏行为 在面向 API 的 incident 详情响应中，敏感字段默认仍会被脱敏： - `username` - `command_line` - `file_hash` - `file_path` ### 仅限操作员访问 React 仪表盘现在会在读取 incident 详情时带上 `include_sensitive=true`，但只有具备 `incident_process` 权限的主体才被允许访问该路径。只读主体仍将收到脱敏后的值。 ### 接收防护机制 如果有人试图将经过净化处理的仪表盘/API 输出作为新告警再次处理，系统现在将予以拒绝。 这可以防止对已经包含以下值的 payload 进行错误的重复处理： - `[redacted]` - `[redacted-path]` - 类似 `0000...` 的全零哈希 为了获得准确的富化和策略结果，接收表单必须接收原始的告警 JSON 数据。 ## 持久化模型 默认运行时持久化需要使用 Supabase/Postgres。 存储的实体包括： - 告警 - Incident - 动作执行结果 - 报告 - A2A 工作区 - 代理 - 任务 - 消息 - 产物 - 时间线数据 已实现的重要行为： - 针对相同 `alert_id` 的重复处理具备幂等性 - 缺失的报告产物可在重放时生成 - 读取 incident 详情时可以从已存储的报告路径中提取并填充 Markdown 内容 ## 安装与运行 ### 1. 安装 Python 依赖 ``` pip install -r requirements.txt ``` ### 2. 安装仪表盘依赖 ``` npm --prefix dashboard install ``` ### 3. 配置环境 根据 `.env.example` 创建本地 `.env.local` 文件，并至少设置以下内容： ``` SUPABASE_DB_URL=postgresql://postgres.:@aws-0-.pooler.supabase.com:5432/postgres?sslmode=require SOAR_INTEL_PROVIDER=virustotal VIRUSTOTAL_API_KEY= SOAR_AUTH_TOKENS_JSON={"tokens":[{"token":"","principal_id":"incident-operator","principal_type":"user","roles":["incident_process","incident_read"],"workspaces":["*"]}]} SOAR_API_PROXY_TARGET=http://127.0.0.1:8000 ``` ### 4. 运行 FastAPI ``` python -m uvicorn api.app:app --reload ``` ### 5. 运行 React 仪表盘 ``` npm --prefix dashboard run dev ``` 当仪表盘打开时，请将操作员 bearer token 粘贴到 UI 中显示的会话提示框中。该 token 仅存储在该浏览器标签页的 `sessionStorage` 中。 ### 6. 可选的 CLI 冒烟测试 ``` python main.py --scenario mixed --no-report ``` ### 7. 运行测试 ``` pytest tests -q ``` ## 主要 API 路由 核心 Incident 路由： - `GET /health` - `GET /api/v1/dashboard/bootstrap` - `POST /api/v1/incidents/process` - `POST /api/v1/incidents/process-scenario` - `GET /api/v1/incidents` - `GET /api/v1/incidents/by-alert/{alert_id}` - `GET /api/v1/incidents/by-alert/{alert_id}/report/html` - `GET /api/v1/incidents/by-ticket/{ticket_id}` 重要的路由行为： - `GET /api/v1/incidents/by-alert/{alert_id}?include_sensitive=true` - 允许 `incident_process` 权限访问 - 拒绝只读主体访问 - `POST /api/v1/incidents/process` - 拒绝处理经过净化/脱敏的 payload，返回 HTTP `422` A2A 协作路由也可在 `/api/v1/a2a/*` 下使用。 ## 项目结构 ``` SOAR Playbook/ |-- actions/ |-- a2a/ |-- alert_generator/ |-- api/ |-- dashboard/ | |-- app.py | |-- src/ | `-- vite.config.ts |-- data/ | `-- sample_alerts/ |-- docs/ |-- engine/ |-- enrichment/ |-- output/ |-- policies/ |-- reporting/ |-- schemas/ |-- security/ |-- services/ |-- storage/ |-- tests/ |-- .env.example |-- main.py `-- README.md ``` ## 验证快照 本仓库最新验证日期为 2026-07-02： - `pytest tests -q` -> `63 passed` - 在 `dashboard/` 目录下执行 `cmd /c npm run build` -> 通过 - 通过 incident 处理验证了实时的 Supabase 持久化路径 - 在工作流中执行了基于 VirusTotal 的实时富化路径 推荐的配套文档： - `docs/supabase-setup.md` - `docs/upgrade-roadmap.md` - `docs/three-codex-team.md` - `docs/a2a-collaboration.md` - `docs/pentest-report-2026-07-02.md` ## 添加新工作前的注意事项 如果您准备通过仪表盘处理自定义告警： - 请使用原始的告警 JSON 数据 - 请勿粘贴已经显示 `[redacted]` 字段或全零哈希的 incident 详情输出 - 如果您需要重新测试现有的 incident，请克隆原始的源 payload，而不是复制脱敏后的详情视图

标签：Kubernetes, SOAR, 威胁情报, 安全报告, 安全规则引擎, 安全运营中心, 开发者工具, 网络映射, 自动化响应, 逆向工具