https://github.com/solomonneas/hotwash
SOC playbook parser with mermaid diagram generation
https://github.com/solomonneas/hotwash
automation blue-team cybersecurity incident-response playbooks security-operations soar
Last synced: 5 days ago
JSON representation
SOC playbook parser with mermaid diagram generation
- Host: GitHub
- URL: https://github.com/solomonneas/hotwash
- Owner: solomonneas
- License: mit
- Created: 2026-05-23T19:50:34.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-10T16:13:20.000Z (19 days ago)
- Last Synced: 2026-06-10T18:07:57.059Z (19 days ago)
- Topics: automation, blue-team, cybersecurity, incident-response, playbooks, security-operations, soar
- Language: TypeScript
- Size: 1.18 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Roadmap: docs/ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
⚒️ Hotwash
IR runbook builder with visual flowcharts, SOAR execution, and AI playbook generation.
Hotwash transforms incident response playbooks from Markdown and Mermaid syntax into interactive flowchart visualizations with a full execution engine. SOC teams can build, execute, and track playbook runs step-by-step. AI generation creates playbooks from natural language prompts. SOAR integrations connect to real response platforms.
---
## Features
- **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 hooks for AI-assisted execution
- **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
---
## Quick Start
```bash
# Clone and install
git clone https://github.com/solomonneas/hotwash.git
cd hotwash
# Frontend
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: **http://localhost:5177**
Backend: **http://localhost:8000** (optional)
---
## Tech Stack
| 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** (Optional) | FastAPI 0.136 | Playbook storage, execution engine, integrations |
| **Parser** | Custom Markdown Parser | Inline playbook parsing |
---
## Playbook Syntax
### Markdown Format
```markdown
# 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 access
```
### Mermaid Format
```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]
```
---
## Node Types
| 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 |
---
## 5 Variants
| 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.
---
## Project Structure
```text
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 (optional)
│ ├── 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 Actions
Built-in action library for common SOAR platforms:
**Incident Response Actions:**
- `isolate_host` - Remove host from network
- `disable_account` - Disable user account
- `block_ioc` - Block IP/domain/hash
- `snapshot_vm` - Create VM snapshot
- `quarantine_email` - Isolate email message
**Reconnaissance:**
- `whois_lookup` - IP/domain registration info
- `virustotal_check` - File hash reputation
- `shodan_search` - Internet scan results
All actions are templates that teams can customize.
---
## Wazuh integration
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](docs/WAZUH-INGEST.md)
for the integration script template, HMAC scheme, and cooldown semantics.
---
## Roadmap
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](docs/ROADMAP.md) for the full plan.
---
## License
MIT - see [LICENSE](LICENSE) for details.