⚒️ Hotwash

交互式应急响应 runbook：将 IR playbook 构建为可视化流程图，逐步执行，并通过 MCP 由 LLM 驱动整个运行过程。

官方网站  ·  npm 上的 hotwash-mcp  ·  Wazuh 接入  ·  路线图

Hotwash 将使用 Markdown 或 Mermaid 编写的应急响应（IR）playbook 转化为具有真实执行引擎的交互式流程图 runbook，这样 SOC 分析师就可以构建 runbook，针对真实发生的应急事件启动运行，并跟踪每一个步骤、决策和证据。其核心在于，相同的运行过程同样可以由 AI agent 驱动：捆绑的 `hotwash-mcp` Model Context Protocol server 将运行引擎作为工具公开，因此 LLM 可以列出 playbook、启动运行、推进步骤、附加产物（artifact），并对 Wazuh 接入队列进行分类处理。与静态的 playbook 文档或流程图绘制工具不同，每一次 Hotwash 运行都是实时、可审计的状态，可以由人类和 agent 共享。 ## 它的功能 Hotwash 是一款用于 SOC 和蓝队工作的应急响应（IR）runbook 工具。它整合了通常存在于三个不同工具中的三项功能： - **编写。** 将结构化的 Markdown 或 Mermaid playbook 解析为节点-边图，并在交互式的 React Flow 画布上渲染它们（阶段、步骤、决策、执行节点、合并）。按类型（应急响应、漏洞、威胁狩猎）浏览、分类和过滤 playbook 库。 - **执行。** 从 playbook 启动运行，然后通过实时状态、时间戳、指派人、备注、决策和附加的证据逐步进行操作。每次运行都是可查询的状态，而不是有人重新输入到工单中的核对清单。 - **自动化。** `hotwash-mcp` MCP server 允许 AI agent 端到端地驱动运行，而 Wazuh 接入路径通过 HMAC 认证的映射，将警报转换为自动启动的运行或人工审查建议。 关键词：应急响应、IR runbook、SOC、SOAR、playbook 自动化、Model Context Protocol (MCP)、Wazuh 警报接入、蓝队。 ## 快速开始 ``` # 克隆和安装 git clone https://github.com/lidless-labs/hotwash.git cd hotwash # Frontend（web app） cd web && npm install && npm run dev # Backend（run engine + REST API + MCP backend，从 repo root 开始） python3 -m venv .venv && .venv/bin/pip install -r requirements.txt .venv/bin/uvicorn api.main:app --port 8000 ``` 前端：**http://localhost:5177** 后端：**http://localhost:8000** Web 应用在没有后端的情况下可以离线进行可视化。执行引擎、REST API、MCP server 和 Wazuh 接入需要后端支持。 ## MCP server：由 LLM 驱动运行 `hotwash-mcp`（[在 npm 上](https://www.npmjs.com/package/hotwash-mcp)）是一个封装了 Hotwash REST API 的 stdio MCP server。将其指向正在运行的 Hotwash 后端，任何支持 MCP 的客户端（Claude Desktop、Claude Code、Cursor 等）都可以将应急响应 playbook 作为工具来运行。 将其添加到您的 MCP 客户端配置中： ``` { "mcpServers": { "hotwash": { "command": "npx", "args": ["-y", "hotwash-mcp"], "env": { "HOTWASH_URL": "http://localhost:8000", "HOTWASH_API_KEY": "your-hotwash-api-key" } } } } ``` 服务器读取的环境变量：`HOTWASH_URL`（默认为 `http://localhost:8000`），`HOTWASH_API_KEY`（可选，在后端需要身份验证时作为 API key 发送），以及 `HOTWASH_TIMEOUT`（请求超时时间，以秒为单位，默认为 `30`）。 ### 工具 服务器注册了 10 个工具，均以 `hotwash_` 为前缀： | 工具 | 功能 | |------|--------------| | `hotwash_list_playbooks` | 列出库中的 playbook，支持可选的类别/标签/搜索过滤；返回 id、标题、类别、标签和节点数。 | | `hotwash_get_playbook` | 根据 id 获取单个 playbook 的完整图（节点 + 边）和元数据。 | | `hotwash_start_run` | 针对某个应急事件启动 playbook 的新执行过程；将节点克隆为逐步状态，并返回执行 id。 | | `hotwash_query_run` | 获取当前执行状态：状态、包含状态/证据/备注的完整步骤列表，以及可选的时间线。 | | `hotwash_advance_step` | 更新单个步骤：更改状态、指派分析师、附加备注或记录决策。 | | `hotwash_cancel_run` | 放弃正在进行的运行（为审计日志保持可查询状态）。破坏性操作；需要 `confirm: true`。 | | `hotwash_attach_artifact` | 将文本或 base64 二进制产物（日志片段、截图、哈希列表）附加到某个步骤。 | | `hotwash_list_suggestions` | 列出由 `mode=suggest` Wazuh 映射排队的接入建议（分析师审查队列）。 | | `hotwash_accept_suggestion` | 将待处理的建议提升为实际执行，并将其 Wazuh 警报作为上下文带入。破坏性操作；需要 `confirm: true`。 | | `hotwash_dismiss_suggestion` | 将待处理的建议作为噪声忽略，并锚定映射冷却时间。破坏性操作；需要 `confirm: true`。 | 破坏性工具（`hotwash_cancel_run`、`hotwash_accept_suggestion`、`hotwash_dismiss_suggestion`）除非调用者传入 `confirm: true`，否则将拒绝执行操作，这样 agent 就不会意外放弃运行或耗尽建议队列。 ## 功能特性 - **Markdown 转流程图** - 将结构化的 Markdown playbook 解析为节点-边图 - **Mermaid 语法** - 原生支持 Mermaid 流程图语法 - **交互式画布** - 使用 React Flow 进行拖拽、平移、缩放 - **自定义节点类型** - 阶段、步骤、决策、执行、合并，拥有 5 种变体样式 - **Playbook 库** - 按类型（漏洞、应急响应、威胁狩猎）浏览、分类和过滤 - **执行引擎** - 逐步运行 playbook，提供实时状态跟踪、时间戳和执行历史 - **AI Playbook 生成** - 根据自然语言的事件描述生成完整的 playbook - **SOAR 集成** - 内置动作库，可连接到真实的响应平台 - **MCP 集成** - Model Context Protocol server，允许 AI agent 驱动运行 - **Wazuh 接入** - 经过 HMAC 认证的警报接入，具备映射规则和建议队列 - **小地图与控制** - 提供鸟瞰视图和视口导航 - **客户端解析** - 在浏览器中进行零延迟 Markdown 渲染 - **5 种视觉主题** - SOC、Analyst、Terminal、Command、Cyber 变体 - **引导教程** - 为首次使用的用户提供交互式演练 - **离线优先** - 可视化无需后端支持 ## 技术栈 | 层级 | 技术 | 用途 | |-------|-----------|---------| | **前端** | React 18.2 | 交互式仪表盘 | | **语言** | TypeScript 5.3 | 类型安全 | | **样式** | Tailwind CSS 3.4 | 实用优先的 CSS | | **画布** | React Flow Renderer 10.3 | 节点-边图可视化 | | **状态** | Zustand | 全局状态管理 | | **打包工具** | Vite 5 | 开发服务器和构建 | | **后端** | FastAPI 0.136 | Playbook 存储、执行引擎、集成 | | **MCP** | @modelcontextprotocol/sdk 1.29 | `hotwash-mcp` server (Node >= 20) | | **解析器** | 自定义 Markdown 解析器 | 内联 playbook 解析 | ## Playbook 语法 ### Markdown 格式 ``` # 应急响应：Ransomware 攻击 ## 阶段：Detection - Step: Identify affected systems - Check EDR alerts - Correlate with SIEM events - Document initial indicators ## 阶段：Analysis - Decision: Is it a critical system? - YES -> Execute: Isolate from network - NO -> Execute: Begin forensic collection ## 阶段：Containment - Step: Isolate affected hosts - Segment network access - Disable user accounts - Preserve evidence ## 阶段：Eradication - Step: Remove malware - Scan with multiple AV engines - Remove registry keys - Patch vulnerabilities ## 阶段：Recovery - Step: Restore systems - Restore from clean backups - Apply security patches - Re-enable user access ``` ### Mermaid 格式 ``` flowchart TD A[Detection] --> B{Critical System?} B -->|Yes| C[Isolate Network] B -->|No| D[Preserve Evidence] C --> E[Begin Analysis] D --> E E --> F[Eradicate Threat] F --> G[Recover Systems] ``` ## 节点类型 | 类型 | 用途 | 示例 | |------|---------|---------| | **阶段** | 主要的应急响应阶段 | 检测、分析、遏制 | | **步骤** | 流程化操作 | 执行 EDR 扫描、记录发现 | | **决策** | 条件分支（是/否） | 是否严重？是否存在恶意软件？ | | **执行** | SOAR 动作或工具集成 | 隔离主机、禁用账户、封锁 IP | | **合并** | 汇合点 | 重新合并分析路径 | ## 5 种变体 | 变体 | 主题 | 用例 | |---------|-------|----------| | **SOC** | 深板岩色，红色强调 | 安全运营中心 | | **Analyst** | 纯白，蓝色 | 专业分析 | | **Terminal** | 黑色，矩阵绿 | 技术应急响应 | | **Command** | OD 绿，琥珀色 | 军事风格行动 | | **Cyber** | 霓虹青色/品红 | 赛博朋克美学 | 所有变体均使用相同的解析引擎和 React Flow 画布。可即时切换主题。 ## 项目结构 ``` hotwash/ ├── web/ # React 18 + TypeScript + Vite frontend │ ├── src/ │ │ ├── components/ # FlowCanvas (React Flow), panels, viewers │ │ ├── pages/ # Editor, Library, Executions, Suggestions, ... │ │ ├── parsers/ # Client-side Markdown/Mermaid parsing │ │ ├── api/ # Backend API client │ │ ├── hooks/ # useExecutionSocket and friends │ │ └── variants/ # Theme layouts │ ├── package.json │ └── vite.config.ts ├── api/ # FastAPI backend (run engine + REST API) │ ├── main.py # Entry point │ ├── routers/ # playbooks, executions, export, ingest, integrations, parse │ ├── services/ # Execution engine, ingest matching, tags │ ├── parsers/ # Markdown + Mermaid parsers │ ├── integrations/ # SOAR integration clients (TheHive) │ └── tests/ # pytest suite ├── mcp/ # hotwash-mcp npm package (MCP server, Node >= 20) │ ├── src/index.ts # Entry point │ └── src/tools/ # playbooks, runs, suggestions, artifacts tools ├── docs/ # ARCHITECTURE, CONFIGURATION, THEHIVE-INTEGRATION, WAZUH-INGEST └── requirements.txt ``` ## SOAR 动作 针对常见 SOAR 平台的内置动作库： **应急响应动作：** - `isolate_host` - 将主机从网络中移除 - `disable_account` - 禁用用户账户 - `block_ioc` - 封锁 IP/域名/哈希 - `snapshot_vm` - 创建 VM 快照 - `quarantine_email` - 隔离电子邮件 **侦察：** - `whois_lookup` - IP/域名注册信息 - `virustotal_check` - 文件哈希信誉 - `shodan_search` - 互联网扫描结果 所有动作均为模板，团队可进行自定义。 ## Wazuh 集成 Hotwash 通过 `POST /api/ingest/wazuh` 接收 Wazuh 警报（经 HMAC 认证）， 并将其与映射表进行匹配，从而可以 `auto`（自动）启动运行、排队人工审查建议，或仅作记录。映射通过 `/api/ingest/mappings` CRUD 进行管理。有关集成脚本模板、HMAC 方案和冷却语义，请参阅 [docs/WAZUH-INGEST.md](docs/WAZUH-INGEST.md)。 ## 路线图 已交付：允许 AI agent 驱动 playbook 运行的 `hotwash-mcp` Model Context Protocol server（在 npm 上），以及包含 HMAC 认证、映射规则和人工审查建议队列的 Wazuh 警报接入路径。下一步：更丰富的执行报告、超越 TheHive 的更多 SOAR 目标，以及更深度的建议队列工作流。 完整计划请参阅 [docs/ROADMAP.md](docs/ROADMAP.md)。 ## 为什么不直接使用 Markdown 文档或流程图工具？ - **对比 wiki 或 Markdown 文件中的 playbook：** 文档是只读文本。Hotwash 运行 playbook：实时步骤状态、时间戳、指派人、决策和附加的证据成为可查询的状态和审计跟踪，而不是有人重新输入到工单中的核对清单。 - **对比绘图工具（Mermaid Live、draw.io、Lucidchart）：** 这些工具只是画出流程图就停止了。Hotwash 将相同的 Markdown/Mermaid 解析为图，*并*使用引擎、运行历史和可由 agent 驱动的 MCP 接口来执行它。 - **对比完整的商业 SOAR 平台：** Hotwash 是一个本地优先、基于 MIT 许可证、可自托管的 runbook 引擎，您可以阅读并扩展它。SOAR 动作以可自定义的模板形式提供；其设计是让人和 agent 共同参与循环，而不是一个自主触发 playbook 的黑盒。 ## Hotwash 不是什么 - 不是 SIEM，也不是检测引擎。它接入 Wazuh 警报；它不生成警报。 - 不是为每个工具提供供应商集成的交钥匙 SOAR。SOAR 动作（`isolate_host`、`block_ioc` 等）是团队可自定义的模板；TheHive 是目前唯一上线的实时集成。 - 不是托管或多租户服务。它是一个由您自己运行的自托管应用。 - 不是全自动的响应器。破坏性 MCP 工具需要明确的确认，并且 `mode=suggest` 的 Wazuh 映射被设计为路由到人工审查队列。 - 尚未完成。它是 WIP（开发中）；预期会发生变化。 ## 贡献与安全 - [CONTRIBUTING.md](CONTRIBUTING.md) - 如何进行设置，哪些内容可以轻松提交，以及哪些内容需要先提 issue。 - [SECURITY.md](SECURITY.md) - 如何报告漏洞（请不要公开提 issue）。 - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - Contributor Covenant 2.1。 [CHANGELOG.md](CHANGELOG.md) - 重要变更。 ## 许可证 MIT - 详情请参阅 [LICENSE](LICENSE)。

标签：AV绕过, FastAPI, LLM, MCP, MITM代理, React, Syscalls, Unmanaged PE, 工作流引擎, 库, 应急响应, 网络调试, 自动化, 自动化攻击, 逆向工具