hotwash

<p align="center"> <img src="docs/assets/hotwash-banner.jpg" alt="hotwash banner" width="900"> </p> <p align="center"> <a href="https://lidless.dev"><img src="docs/assets/marks/hotwash-circle.png" width="48" alt="Lidless Labs"></a> </p> <h1 align="center">⚒️ 热点清洗</h1> <p align="center"> <strong>交互式事件响应运行手册：以可视化流程图形式构建 IR 运行手册，逐步执行，并通过 MCP 在 LLM 上驱动整个运行。</strong> </p> <p align="center"> <a href="https://lidless.dev/hotwash"><strong>官网</strong></a> &nbsp;·&nbsp; <a href="https://www.npmjs.com/package/hotwash-mcp">hotwash-mcp on npm</a> &nbsp;·&nbsp; <a href="docs/WAZUH-INGEST.md">Wazuh 数据导入</a> &nbsp;·&nbsp; <a href="docs/ROADMAP.md">路线图</a> </p> <p align="center"> <img src="https://shieldcn.dev/github/ci/lidless-labs/hotwash.svg?branch=main&workflow=ci.yml" alt="CI 状态"> <img src="https://shieldcn.dev/npm/hotwash-mcp.svg" alt="hotwash-mcp on npm"> <img src="https://shieldcn.dev/badge/React-18.2-61DAFB.svg?logo=react&logoColor=0f172a" alt="React 18.2"> <img src="https://shieldcn.dev/badge/FastAPI-0.136-009688.svg?logo=fastapi&logoColor=white" alt="FastAPI 0.136"> <img src="https://shieldcn.dev/badge/license-MIT-green.svg" alt="MIT 许可证"> </p> 热点清洗（Hotwash）将以 Markdown 或 Mermaid 编写的事件响应（IR）运行手册转换为交互式流程图运行手册，并带有真正的执行引擎。安全运营中心（SOC）分析师可以构建运行手册，启动针对实时事件的运行，并跟踪每一步、每个决策和每条证据。关键在于，同一运行也可以由 AI 代理驱动：捆绑的 `hotwash-mcp` 模型上下文协议（MCP）服务器将运行引擎暴露为工具，因此 LLM 可以列出运行手册、启动运行、推进步骤、附加工件，并对 Wazuh 数据导入队列进行分类。 > 状态：工作中。Web 应用程序、FastAPI 运行引擎、`hotwash-mcp` 服务器（发布到 npm）和 Wazuh 数据导入路径正在运行并经过测试。一些 SOAR 操作是模板，界面仍在变化中。参见 [路线图](docs/ROADMAP.md)。 --- ## 功能 Hotwash 是一个用于 SOC 和蓝队工作的事件响应（IR）运行手册工具。它执行通常分布在三个不同工具中的三个功能： - **创作。** 将结构化的 Markdown 或 Mermaid 运行手册解析为节点-边图，并在交互式 React Flow 画布上渲染它们（阶段、步骤、决策、执行节点、合并）。通过类型（事件响应、漏洞、威胁狩猎）浏览、分类和筛选运行手册库。 - **执行。** 从运行手册启动运行，然后逐步执行，并具有实时状态、时间戳、分配者、注释、决策和附加证据。每个运行都是可查询的状态，而不是某人重新输入到票据中的检查清单。 - **自动化。** `hotwash-mcp` MCP 服务器允许 AI 代理驱动运行到结束，而 Wazuh 数据导入路径将警报转换为自动启动的运行或人工审查建议，通过 HMAC 身份验证的映射。 关键词：事件响应、IR 运行手册、SOC、SOAR、运行手册自动化、模型上下文协议（MCP）、Wazuh 警报导入、蓝队。 --- ## 快速入门 ```bash # 克隆并安装 git clone https://github.com/lidless-labs/hotwash.git cd hotwash # 前端（Web 应用程序） cd web && npm install && npm run dev # 后端（运行引擎 + REST API + MCP 后端，从存储库根目录） 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 服务器和 Wazuh 数据导入是必需的。 --- ## MCP 服务器：从 LLM 驱动运行 `hotwash-mcp`（[在 npm 上](https://www.npmjs.com/package/hotwash-mcp)）是一个包装 Hotwash REST API 的 stdio MCP 服务器。将它指向正在运行的 Hotwash 后端，任何具有 MCP 能力的客户端（Claude Desktop、Claude Code、Cursor 等）都可以将事件响应运行手册作为工具运行。 在您的 MCP 客户端配置中添加它： ```json { "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`（可选，当后端需要身份验证时发送）和 `HOTWASH_TIMEOUT`（以秒为单位的请求超时时间，默认为 `30`）。 ### 工具 服务器注册了 10 个工具，所有工具都以 `hotwash_` 为前缀： | 工具 | 功能 | |------|--------------| | `hotwash_list_playbooks` | 列出库中的运行手册，可选类别/标签/搜索筛选器；返回 ID、标题、类别、标签和节点数。 | | `hotwash_get_playbook` | 获取一个运行手册的完整图（节点 + 边）和元数据。 | | `hotwash_start_run` | 启动一个运行手册针对事件的新执行；克隆节点到每步状态并返回执行 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`，否则拒绝执行，以免代理意外放弃运行或耗尽建议队列。 --- ## 特性 - **Markdown 到流程图** - 将结构化的 Markdown 运行手册解析为节点-边图 - **Mermaid 语法** - 原生支持 Mermaid 流程图语法 - **交互式画布** - 使用 React Flow 拖动、平移、缩放 - **自定义节点类型** - 阶段、步骤、决策、执行、合并，具有 5 种变体样式 - **运行手册库** - 按类型（漏洞、事件响应、威胁狩猎）浏览、分类和筛选 - **执行引擎** - 逐步运行运行手册，具有实时状态跟踪、时间戳和执行历史 - **AI 运行手册生成** - 从自然语言事件描述中生成完整的运行手册 - **SOAR 集成** - 带有连接到真实响应平台的内置操作库 - **MCP 集成** - 模型上下文协议服务器，以便 AI 代理驱动运行 - **Wazuh 数据导入** - HMAC 身份验证的警报导入，具有映射规则和建议队列 - **小地图和控件** - 鸟瞰图和视口导航 - **客户端解析** - 浏览器中零延迟 Markdown 渲染 - **5 种视觉主题** - SOC、分析师、终端、命令、网络变体 - **引导式游览** - 首次使用者的交互式演练 - **离线优先** - 无需后端即可进行可视化 --- ## 技术栈 | 层 | 技术 | 目的 | |-------|-----------|---------| | **前端** | React 18.2 | 交互式仪表盘 | | **语言** | TypeScript 5.3 | 类型安全 | | **样式** | Tailwind CSS 3.4 | 实用优先的 CSS | | **画布** | React Flow Renderer 10.3 | 节点-边图可视化 | | **状态** | Zustand | 全局状态管理 | | **打包器** | Vite 5 | 开发服务器和构建 | | **后端** | FastAPI 0.136 | 运行手册存储、执行引擎、集成 | | **MCP** | @modelcontextprotocol/sdk 1.29 | `hotwash-mcp` 服务器（Node >= 20） | | **解析器** | 自定义 Markdown 解析器 | 内联运行手册解析 | --- ## 运行手册语法 ### Markdown 格式 ```markdown # 事件响应：勒索软件攻击 ## 阶段：检测 - 步骤：识别受影响的系统 - 检查 EDR 警报 - 与 SIEM 事件关联 - 记录初始指标 ## 阶段：分析 - 决策：是否为关键系统？ - 是 -> 执行：隔离网络 - 否 -> 执行：开始取证收集 ## 阶段：遏制 - 步骤：隔离受影响的主机 - 分段网络访问 - 禁用用户账户 - 保存证据 ## 阶段：根除 - 步骤：删除恶意软件 - 使用多个 AV 引擎扫描 - 删除注册表键 - 修复漏洞 ## 阶段：恢复 - 步骤：恢复系统 - 从干净的备份中恢复 - 应用安全补丁 - 重新启用用户访问 ``` ### Mermaid 格式 ```mermaid flowchart TD A[检测] --> B{是否为关键系统？} B -->|是| C[隔离网络] B -->|否| D[保存证据] C --> E[开始分析] D --> E E --> F[根除威胁] F --> G[恢复系统] ``` --- ## 节点类型 | 类型 | 目的 | 示例 | |------|---------|---------| | **阶段** | 主要事件响应阶段 | 检测、分析、遏制 | | **步骤** | 程序化操作 | 执行 EDR 扫描、记录发现结果 | | **决策** | 条件分支（是/否） | 是否为关键？是否存在恶意软件？ | | **执行** | SOAR 操作或工具集成 | 隔离主机、禁用账户、阻止 IP | | **合并** | 收敛点 | 重新连接分析路径 | --- ## 5 种变体 | 变体 | 主题 | 用例 | |---------|-------|----------| | **SOC** | 深灰色，红色装饰 | 安全运营中心 | | **分析师** | 干净的白色，蓝色 | 专业分析 | | **终端** | 黑色，矩阵绿色 | 技术事件响应 | | **命令** | 橄榄绿，琥珀色 | 军事风格操作 | | **网络** | 霓虹青/洋红 | 网络美学 | 所有变体都使用相同的解析引擎和 React Flow 画布。瞬间切换主题。 --- ## 项目结构 ```text hotwash/ ├── web/ # React 18 + TypeScript + Vite 前端 │ ├── src/ │ │ ├── components/ # FlowCanvas（React Flow）、面板、查看器 │ │ ├── pages/ # 编辑器、库、执行、建议、... │ │ ├── parsers/ # 客户端 Markdown/Mermaid 解析 │ │ ├── api/ # 后端 API 客户端 │ │ ├── hooks/ # useExecutionSocket 等 │ │ └── variants/ # 主题布局 │ ├── package.json │ └── vite.config.ts ├── api/ # FastAPI 后端（运行引擎 + REST API） │ ├── main.py # 入口点 │ ├── routers/ # 运行手册、执行、导出、导入、集成、解析 │ ├── services/ # 执行引擎、导入匹配、标签 │ ├── parsers/ # Markdown + Mermaid 解析器 │ ├── integrations/ # SOAR 集成客户端（TheHive） │ └── tests/ # pytest 套件 ├── mcp/ # hotwash-mcp npm 包（MCP 服务器，Node >= 20） │ ├── src/index.ts # 入口点 │ └── src/tools/ # 运行手册、运行、建议、工件工具 ├── docs/ # 架构、配置、TheHive-集成、WAZUH-导入 └── 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` （HMAC 身份验证）接受 Wazuh 警报，并将其与映射表匹配，可以 `auto` 启动运行、排队人工审查建议或仅记录。映射通过 `/api/ingest/mappings` CRUD 管理。参见 [docs/WAZUH-INGEST.md](docs/WAZUH-INGEST.md) 获取集成脚本模板、HMAC 方案和冷却期语义。 --- ## 路线图 已交付：`hotwash-mcp` 模型上下文协议服务器（在 npm 上），允许 AI 代理驱动运行手册执行，以及具有 HMAC 身份验证、映射规则和人工审查建议队列的 Wazuh 警报导入路径。接下来：更丰富的执行报告、超出 TheHive 的更多 SOAR 目标、更深入的建议队列工作流。 参见 [docs/ROADMAP.md](docs/ROADMAP.md) 获取完整计划。 --- ## 为什么不只是 Markdown 文档或流程图工具？ - **对比 Markdown 文档或 wiki 页面：** 文档是只读文本。Hotwash 运行运行手册：实时步骤状态、时间戳、分配者、决策和附加证据成为可查询状态和审计跟踪，而不是某人重新输入到票证中的检查清单。 - **对比图表工具（Mermaid Live、draw.io、Lucidchart）：** 它们绘制流程图就停止了。Hotwash 将相同的 Markdown/Mermaid 解析为图表 *和* 执行它，具有引擎、运行历史和 MCP 表面，代理可以驱动。 - **对比完整的商业 SOAR 平台：** Hotwash 是一个本地优先、MIT 许可、自托管的运行手册引擎，您可以阅读和扩展。SOAR 操作作为可自定义的模板提供；设计是人类和代理在环中，而不是一个自主运行的黑盒。 ## Hotwash 不是什么 - 不是 SIEM 和检测引擎。它导入 Wazuh 警报；它不生成它们。 - 不是具有每个工具的供应商集成的交钥匙 SOAR。SOAR 操作（`isolate_host`、`block_ioc` 等）是团队自定义的模板；今天只有一个实时集成（TheHive）。 - 不是托管或多租户服务。它是一个自托管应用程序，您可以自己运行。 - 不是完全自主的响应者。破坏性 MCP 工具需要显式确认，并且 `mode=suggest` Wazuh 映射通过设计路由到人工审查队列。 - 不是完成。正在进行中；期待表面发生变化。 --- ## 贡献和安全 - [CONTRIBUTING.md](CONTRIBUTING.md) - 如何设置、轻松落地的内容以及需要先创建问题的内容。 - [SECURITY.md](SECURITY.md) - 如何报告漏洞（请不要公开创建问题）。 - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - 贡献者契约 2.1。 - [CHANGELOG.md](CHANGELOG.md) - 值得注意的更改。 --- ## 许可证 MIT - 参见 [LICENSE](LICENSE) 获取详细信息。 --- <p align="center"><a href="https://lidless.dev">Lidless Labs</a> 部分 &middot; 眼睛不会闭上</p> <p align="center">_{<strong>安全/SOC:</strong> <a href="https://github.com/lidless-labs/soc-stack">soc-stack</a> &middot; <a href="https://github.com/lidless-labs/wazuh-mcp">wazuh-mcp</a> &middot; <a href="https://github.com/lidless-labs/misp-mcp">misp-mcp</a> &middot; <a href="https://github.com/lidless-labs/suricata-mcp">suricata-mcp</a> &middot; <a href="https://github.com/lidless-labs/thehive-mcp">thehive-mcp</a> &middot; <a href="https://github.com/lidless-labs/cortex-mcp">cortex-mcp</a> &middot; <a href="https://github.com/lidless-labs/mitre-mcp">mitre-mcp</a> &middot; <a href="https://github.com/lidless-labs/zeek-mcp">zeek-mcp</a>}</p> <p align="center">_{<a href="https://lidless.dev">所有工具</a> &middot; <a href="https://github.com/lidless-labs">Lidless Labs on GitHub</a>}</p>