hotwash

WIP

Interactive incident-response runbooks.

GitHub repo → self-hosted · run from source

node types

visual themes

MIT

open source

WHAT IT DOES

Hotwash turns incident-response playbooks written in Markdown or Mermaid into interactive flowchart visualizations with a full execution engine. A SOC analyst can build a runbook, execute it step-by-step, and track every run with timestamps and history. AI generation drafts a complete playbook from a plain-English incident description, and a built-in SOAR action library maps steps onto real response actions like isolating a host or blocking an IOC. A Wazuh ingestion path can turn an incoming alert into an auto-started run or a human-review suggestion.

The frontend is React 18 + TypeScript on Vite; an optional FastAPI backend on Python 3.9+ adds playbook storage, the execution engine, and integrations. Visualization works offline-first with no backend required.

Status: work in progress. Hotwash is a self-hosted application, not an MCP server, so there is no AI-client config block on this page. The web app itself is not published to a registry, you run it from source. A companion hotwash-mcp package is published separately (see below) for agents that want to drive runs.

WHAT IT DOES, IN DETAIL

Markdown to flowchart

Parse structured Markdown playbooks into node-edge graphs, no diagram tool required.

Mermaid syntax

Native support for Mermaid flowchart syntax alongside the Markdown format.

Interactive canvas

Drag, pan, and zoom over the playbook graph with React Flow, plus minimap and viewport controls.

Custom node types

Phase, Step, Decision, Execute, and Merge nodes model real IR procedures.

Execution engine

Run playbooks step-by-step with live status tracking, timestamps, and run history.

AI playbook generation

Generate a complete playbook from a natural-language incident description.

SOAR action library

Built-in templates: isolate_host, disable_account, block_ioc, snapshot_vm, quarantine_email, and recon actions.

Wazuh ingestion

Accept Wazuh alerts over an HMAC-authenticated webhook and auto-start, queue, or log a run via mapping rules.

Playbook library

Browse, categorize, and filter playbooks by type: vulnerability, incident response, threat hunting.

5 visual themes

SOC, Analyst, Terminal, Command, and Cyber variants share one parsing engine and canvas.

RUNNING IT

Prerequisites: Node.js 20+ for the frontend, and Python 3.9+ if you want the optional backend. Clone the repo, install, and start the dev server. The backend is only needed for playbook storage, the execution engine, and integrations.

$ git clone https://github.com/solomonneas/hotwash.git

$ cd hotwash

# frontend (dev server on http://localhost:5177)

$ cd web && npm install && npm run dev

# backend (optional, from the repo root)

$ python3 -m venv .venv && .venv/bin/pip install -r requirements.txt

$ .venv/bin/uvicorn api.main:app --port 8000

Frontend at http://localhost:5177, optional backend at http://localhost:8000. The Wazuh ingest webhook posts to /api/ingest/wazuh with HMAC auth; see docs/WAZUH-INGEST.md in the repo for the integration script and mapping rules.

COMPANION MCP SERVER

A separate hotwash-mcp package lets AI agents drive playbook runs over the Model Context Protocol: list and read playbooks, start and query runs, manage the human-review suggestion queue, and attach artifacts. It is published to npm and points at a running Hotwash backend.

$ npm i -g hotwash-mcp # or: npx hotwash-mcp

Tool groups: playbooks, runs, suggestions, and artifacts. See the mcp/ directory in the repo for the full reference and client config.