Upload firmware images, unpack them, explore the filesystem, analyze binaries, and conduct security assessments — all powered by AI analysis via Model Context Protocol (MCP).

Connect any MCP-compatible AI agent to Wairz's 60+ analysis tools — Claude Code, Claude Desktop, OpenCode, Codex, Cursor, VS Code + Copilot, Gemini CLI, Windsurf, and more.

Watch the demo video

• Firmware Unpacking — Automatic extraction of SquashFS, JFFS2, UBIFS, CramFS, ext, and CPIO filesystems via binwalk, with multi-partition support
• RTOS Support — Auto-classifies firmware as linux | rtos | unknown on unpack (FreeRTOS / Zephyr / baremetal Cortex-M), with manual override. RTOS projects get a dedicated tool category for vector-table parsing, task enumeration, base-address recovery, and memory-map analysis on raw .axf / .elf blobs
• File Explorer — Browse extracted filesystems with a virtual tree, view text/binary/hex content, and search across files
• Binary Analysis — Disassemble and decompile binaries using radare2 and Ghidra headless, with cross-reference and taint analysis
• Component Map — Interactive dependency graph showing binaries, libraries, scripts, and their relationships
• Security Assessment — Detect hardcoded credentials, crypto material, setuid binaries, insecure configs, and weak permissions
• SBOM & CVE Scanning — Generate Software Bill of Materials (CycloneDX) and scan components against the NVD for known vulnerabilities
• Firmware Emulation — Boot firmware in QEMU (user-mode for single binaries, system-mode for full OS) in isolated containers, with GDB support
• Fuzzing — AFL++ with QEMU mode for cross-architecture binary fuzzing, with automatic dictionary/corpus generation and crash triage
• Firmware Comparison — Diff filesystem trees, binaries, and decompiled functions across firmware versions
• Live Device UART — Connect to physical devices via a host-side serial bridge for interactive console access
• AI Analysis via MCP — 60+ analysis tools exposed to Claude for autonomous security research
• Findings & Reports — Record security findings with severity ratings and evidence, export as Markdown or PDF

Claude Code / Claude Desktop / OpenCode
        │
        │ MCP (stdio)
        ▼
┌─────────────────┐     ┌──────────────────────────────────┐
│   wairz-mcp     │────▶│         FastAPI Backend           │
│  (MCP server)   │     │                                    │
│  60+ tools      │     │  Services: firmware, analysis,     │
│                 │     │  emulation, fuzzing, sbom, uart    │
└─────────────────┘     │                                    │
                        │  Ghidra headless · QEMU · AFL++    │
                        └──────────┬───────────────────────┘
                                   │
┌──────────────┐    ┌──────────────┼──────────────┐
│   React SPA  │───▶│  PostgreSQL  │  Redis       │
│  (Frontend)  │    │              │              │
└──────────────┘    └──────────────┴──────────────┘

Optional:
  wairz-uart-bridge.py (host) ←─ TCP:9999 ─→ Docker backend

• Docker and Docker Compose
• uv (for local development only)

WAIRZ is currently in public beta. You may encounter bugs or rough edges. If you run into any issues, please open an issue on GitHub or reach out at andrew@digitalandrew.io.

WAIRZ supports embedded Linux, FreeRTOS, Zephyr, and baremetal Cortex-M firmware. Auto-detection runs on unpack and can be overridden from the project page. Linux-specific tools (emulation, init-script analysis, SBOM, etc.) are hidden on RTOS projects, and a dedicated RTOS tool category is exposed in their place. See RTOS support for details.

git clone https://github.com/digitalandrew/wairz.git
cd wairz
cp .env.example .env
docker compose up --build

• Frontend: http://localhost:3000
• API docs: http://localhost:8000/docs

# Start PostgreSQL and Redis
docker compose up -d postgres redis

# Backend
cd backend
uv sync
uv run alembic upgrade head
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Frontend (separate terminal)
cd frontend
npm install
npm run dev

Or use the helper script:

./launch.sh

Wairz uses MCP to give AI agents access to firmware analysis tools. After starting the backend, register the MCP server with your preferred client:

--project-id is optional — omit it on shared/team instances where you want to switch between projects from inside the agent. The agent will call list_projects on first use and ask which project you mean.

claude mcp add wairz -- docker exec -i wairz-backend-1 uv run wairz-mcp --project-id <PROJECT_ID>

For a shared Wairz server reached over SSH (no project pinned at boot):

claude mcp add wairz -- ssh wairz-host docker exec -i wairz-backend-1 uv run wairz-mcp

Add to your Claude Desktop config (~/.config/Claude/claude_desktop_config.json on Linux, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "wairz": {
      "command": "docker",
      "args": [
        "exec", "-i", "wairz-backend-1",
        "uv", "run", "wairz-mcp",
        "--project-id", "<PROJECT_ID>"
      ]
    }
  }
}

Add to your opencode.json (project root or ~/.config/opencode/opencode.json):

{
  "mcp": {
    "wairz": {
      "type": "local",
      "command": ["docker", "exec", "-i", "wairz-backend-1", "uv", "run", "wairz-mcp", "--project-id", "<PROJECT_ID>"],
      "timeout": 30000,
      "enabled": true
    }
  }
}

Note: The timeout must be increased from the default 5000ms because Wairz registers 90+ tools.

Once connected, your AI agent can autonomously explore firmware, analyze binaries, run emulation, fuzz targets, and generate security findings. The MCP server supports dynamic project switching via the switch_project tool — no restart needed to change projects.

When a project has more than one firmware uploaded (useful for diffing across versions via diff_firmware), the MCP server picks the earliest-uploaded unpacked firmware by default. To target a specific version, add --firmware-id <FIRMWARE_ID> to the launch command, or pass firmware_id to the switch_project MCP tool. Use list_firmware_versions to find IDs.

For live device access via UART, run the bridge on the host machine (USB serial adapters can't easily pass through to Docker):

pip install pyserial
python3 scripts/wairz-uart-bridge.py --bind 0.0.0.0 --port 9999

The bridge is a TCP server — the serial device path and baud rate are specified via the uart_connect MCP tool, not on the command line.

On Linux, allow Docker traffic to reach the bridge and ensure .env is configured correctly:

sudo iptables -I INPUT -p tcp --dport 9999 -j ACCEPT

UART_BRIDGE_HOST in .env must be host.docker.internal (not localhost). Restart the backend after changing .env: docker compose restart backend.

See UART Console docs for full setup details.

wairz/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI application
│   │   ├── config.py            # Settings (pydantic-settings)
│   │   ├── database.py          # Async SQLAlchemy engine/session
│   │   ├── mcp_server.py        # MCP server with dynamic project switching
│   │   ├── models/              # SQLAlchemy ORM models
│   │   ├── schemas/             # Pydantic request/response schemas
│   │   ├── routers/             # REST API endpoints
│   │   ├── services/            # Business logic
│   │   ├── ai/                  # MCP tool registry + 60+ tool implementations
│   │   │   └── tools/           # Organized by category (filesystem, binary, security, etc.)
│   │   └── utils/               # Path sandboxing, output truncation
│   ├── alembic/                 # Database migrations
│   └── pyproject.toml
├── frontend/
│   ├── src/
│   │   ├── pages/               # Route pages (explorer, emulation, fuzzing, SBOM, etc.)
│   │   ├── components/          # UI components (file tree, hex viewer, component map, etc.)
│   │   ├── api/                 # API client functions
│   │   ├── stores/              # Zustand state management
│   │   └── types/               # TypeScript type definitions
│   └── package.json
├── ghidra/
│   ├── Dockerfile               # Ghidra headless container
│   └── scripts/                 # Custom Java analysis scripts
├── emulation/
│   ├── Dockerfile               # QEMU container (ARM, MIPS, MIPSel, AArch64)
│   └── scripts/                 # Emulation helper scripts
├── fuzzing/
│   └── Dockerfile               # AFL++ container with QEMU mode
├── scripts/
│   └── wairz-uart-bridge.py     # Host-side UART serial bridge
├── docker-compose.yml
├── launch.sh                    # Local development launcher
├── .env.example
└── CLAUDE.md

All settings are configured via environment variables or .env file:

Good firmware images for testing:

• OpenWrt — Well-structured embedded Linux (MIPS, ARM)
• DD-WRT — Similar to OpenWrt
• DVRF (Damn Vulnerable Router Firmware) — Intentionally vulnerable, great for security testing

AGPL-3.0