Interactive incident-response runbooks: build IR playbooks as visual flowcharts, execute them step-by-step, and drive whole runs from an LLM over MCP.
Website · hotwash-mcp on npm · Wazuh ingest · Roadmap
Hotwash turns incident-response (IR) playbooks written in Markdown or Mermaid into interactive flowchart runbooks with a real execution engine, so a SOC analyst can build a runbook, kick off a run against a live incident, and track every step, decision, and piece of evidence. The point is that the same run is also drivable by an AI agent: the bundled hotwash-mcp Model Context Protocol server exposes the run engine as tools, so an LLM can list playbooks, start a run, advance steps, attach artifacts, and triage the Wazuh ingest queue. Unlike a static playbook doc or a flowchart drawing tool, every Hotwash run is live, audited state that a human and an agent can share.
Status: WIP. The web app, the FastAPI run engine, the
hotwash-mcpserver (published to npm), and the Wazuh ingest path are working and tested. Some SOAR actions are templates, and the surface is still moving. See Roadmap.
Hotwash is an incident-response (IR) runbook tool for SOC and blue-team work. It does three things that usually live in three different tools:
- Authoring. Parse structured Markdown or Mermaid playbooks into a node-edge graph and render them on an interactive React Flow canvas (phases, steps, decisions, execute nodes, merges). Browse, categorize, and filter a playbook library by type (Incident Response, Vulnerability, Threat Hunting).
- Execution. Start a run from a playbook, then walk it step-by-step with live status, timestamps, assignees, notes, decisions, and attached evidence. Every run is queryable state, not a checklist someone re-types into a ticket.
- Automation. The
hotwash-mcpMCP server lets an AI agent drive runs end to end, and the Wazuh ingest path turns alerts into either an auto-started run or a human-review suggestion via HMAC-authenticated mappings.
Keywords: incident response, IR runbooks, SOC, SOAR, playbook automation, Model Context Protocol (MCP), Wazuh alert ingestion, blue team.
# Clone and install
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, from the repo root)
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/uvicorn api.main:app --port 8000Frontend: http://localhost:5177 Backend: http://localhost:8000
The web app works offline for visualization without the backend. The backend is required for the execution engine, the REST API, the MCP server, and Wazuh ingest.
hotwash-mcp (on npm) is a stdio MCP server that wraps the Hotwash REST API. Point it at a running Hotwash backend and any MCP-capable client (Claude Desktop, Claude Code, Cursor, and others) can run incident-response playbooks as tools.
Add it to your MCP client config:
{
"mcpServers": {
"hotwash": {
"command": "npx",
"args": ["-y", "hotwash-mcp"],
"env": {
"HOTWASH_URL": "http://localhost:8000",
"HOTWASH_API_KEY": "your-hotwash-api-key"
}
}
}
}Environment variables read by the server: HOTWASH_URL (default http://localhost:8000), HOTWASH_API_KEY (optional, sent as the API key when the backend requires auth), and HOTWASH_TIMEOUT (request timeout in seconds, default 30).
The server registers 10 tools, all prefixed hotwash_:
| Tool | What it does |
|---|---|
hotwash_list_playbooks |
List playbooks in the library with optional category/tag/search filters; returns id, title, category, tags, and node count. |
hotwash_get_playbook |
Fetch the full graph (nodes + edges) and metadata for one playbook by id. |
hotwash_start_run |
Start a new execution of a playbook against an incident; clones nodes into per-step state and returns the execution id. |
hotwash_query_run |
Get current execution state: status, the full step list with statuses/evidence/notes, and optionally the timeline. |
hotwash_advance_step |
Update a single step: change status, assign an analyst, append a note, or record a decision. |
hotwash_cancel_run |
Abandon an in-progress run (stays queryable for the audit log). Destructive; requires confirm: true. |
hotwash_attach_artifact |
Attach a text or base64 binary artifact (log snippet, screenshot, hash list) to a step. |
hotwash_list_suggestions |
List ingest suggestions queued from mode=suggest Wazuh mappings (the analyst review queue). |
hotwash_accept_suggestion |
Promote a pending suggestion into a real execution, carrying its Wazuh alert as context. Destructive; requires confirm: true. |
hotwash_dismiss_suggestion |
Dismiss a pending suggestion as noise and anchor the mapping cooldown. Destructive; requires confirm: true. |
Destructive tools (hotwash_cancel_run, hotwash_accept_suggestion, hotwash_dismiss_suggestion) refuse to act unless the caller passes confirm: true, so an agent cannot abandon a run or burn through the suggestion queue by accident.
- Markdown to Flowchart - Parse structured Markdown playbooks into node-edge graphs
- Mermaid Syntax - Native support for Mermaid flowchart syntax
- Interactive Canvas - Drag, pan, zoom with React Flow
- Custom Node Types - Phase, Step, Decision, Execute, Merge with 5 variant styles
- Playbook Library - Browse, categorize, and filter by type (Vulnerability, Incident Response, Threat Hunting)
- Execution Engine - Run playbooks step-by-step with live status tracking, timestamps, and execution history
- AI Playbook Generation - Generate complete playbooks from natural language incident descriptions
- SOAR Integration - Built-in action library with connections to real response platforms
- MCP Integration - Model Context Protocol server so AI agents can drive runs
- Wazuh Ingest - HMAC-authenticated alert ingestion with mapping rules and a suggestion queue
- MiniMap & Controls - Bird's-eye view and viewport navigation
- Client-Side Parsing - Zero-latency Markdown rendering in browser
- 5 Visual Themes - SOC, Analyst, Terminal, Command, Cyber variants
- Guided Tour - Interactive walkthrough for first-time users
- Offline-First - No backend required for visualization
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | React 18.2 | Interactive dashboards |
| Language | TypeScript 5.3 | Type safety |
| Styling | Tailwind CSS 3.4 | Utility-first CSS |
| Canvas | React Flow Renderer 10.3 | Node-edge graph visualization |
| State | Zustand | Global state management |
| Bundler | Vite 5 | Dev server and build |
| Backend | FastAPI 0.136 | Playbook storage, execution engine, integrations |
| MCP | @modelcontextprotocol/sdk 1.29 | hotwash-mcp server (Node >= 20) |
| Parser | Custom Markdown Parser | Inline playbook parsing |
# Incident Response: Ransomware Attack
## Phase: Detection
- Step: Identify affected systems
- Check EDR alerts
- Correlate with SIEM events
- Document initial indicators
## Phase: Analysis
- Decision: Is it a critical system?
- YES -> Execute: Isolate from network
- NO -> Execute: Begin forensic collection
## Phase: Containment
- Step: Isolate affected hosts
- Segment network access
- Disable user accounts
- Preserve evidence
## Phase: Eradication
- Step: Remove malware
- Scan with multiple AV engines
- Remove registry keys
- Patch vulnerabilities
## Phase: Recovery
- Step: Restore systems
- Restore from clean backups
- Apply security patches
- Re-enable user accessflowchart 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]
| Type | Purpose | Example |
|---|---|---|
| Phase | Major incident response phase | Detection, Analysis, Containment |
| Step | Procedural action | Execute EDR scan, Document findings |
| Decision | Conditional branch (Yes/No) | Is it critical? Is malware present? |
| Execute | SOAR action or tool integration | Isolate host, Disable account, Block IP |
| Merge | Convergence point | Rejoining analysis paths |
| Variant | Theme | Use Case |
|---|---|---|
| SOC | Dark slate, red accents | Security operations center |
| Analyst | Clean white, blue | Professional analysis |
| Terminal | Black, matrix green | Technical incident response |
| Command | OD green, amber | Military-style operations |
| Cyber | Neon cyan/magenta | Cyberpunk aesthetic |
All variants use the same parsing engine and React Flow canvas. Switch themes instantly.
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
Built-in action library for common SOAR platforms:
Incident Response Actions:
isolate_host- Remove host from networkdisable_account- Disable user accountblock_ioc- Block IP/domain/hashsnapshot_vm- Create VM snapshotquarantine_email- Isolate email message
Reconnaissance:
whois_lookup- IP/domain registration infovirustotal_check- File hash reputationshodan_search- Internet scan results
All actions are templates that teams can customize.
Hotwash accepts Wazuh alerts via POST /api/ingest/wazuh (HMAC-authenticated)
and matches them against a mapping table that can auto-start a run, queue a
human-review suggestion, or log only. Mappings are managed via
/api/ingest/mappings CRUD. See docs/WAZUH-INGEST.md
for the integration script template, HMAC scheme, and cooldown semantics.
Shipped: the hotwash-mcp Model Context Protocol server (on npm) that lets AI agents drive playbook runs, and the Wazuh alert ingestion path with HMAC auth, mapping rules, and a human-review suggestion queue. Next up: richer execution reporting, more SOAR targets beyond TheHive, and deeper suggestion-queue workflows.
See docs/ROADMAP.md for the full plan.
- vs. a playbook in a wiki or Markdown file: a doc is read-only prose. Hotwash runs the playbook: live step status, timestamps, assignees, decisions, and attached evidence become queryable state and an audit trail, not a checklist someone re-types into a ticket.
- vs. a diagram tool (Mermaid Live, draw.io, Lucidchart): those draw the flowchart and stop there. Hotwash parses the same Markdown/Mermaid into a graph and executes it, with an engine, a run history, and an MCP surface an agent can drive.
- vs. a full commercial SOAR platform: Hotwash is a local-first, MIT-licensed, self-hosted runbook engine you can read and extend. SOAR actions ship as customizable templates; the design is human-and-agent in the loop, not a black box that fires playbooks autonomously.
- Not a SIEM and not a detection engine. It ingests Wazuh alerts; it does not generate them.
- Not a turnkey SOAR with vendor integrations for every tool. SOAR actions (
isolate_host,block_ioc, and friends) are templates teams customize; TheHive is the one live integration today. - Not a hosted or multi-tenant service. It is a self-hosted app you run yourself.
- Not a fully autonomous responder. Destructive MCP tools require explicit confirmation, and
mode=suggestWazuh mappings route to a human-review queue by design. - Not finished. It is WIP; expect the surface to change.
- CONTRIBUTING.md - how to set up, what lands easily, and what needs an issue first.
- SECURITY.md - how to report a vulnerability (please do not open a public issue).
- CODE_OF_CONDUCT.md - Contributor Covenant 2.1.
- CHANGELOG.md - notable changes.
MIT - see LICENSE for details.
Part of Lidless Labs · the eye does not close
Security / SOC: soc-stack · wazuh-mcp · misp-mcp · suricata-mcp · thehive-mcp · cortex-mcp · mitre-mcp · zeek-mcp