digitalandrew/wairz
GitHub: digitalandrew/wairz
基于 MCP 协议的 AI 驱动固件安全分析平台，集成解包、逆向、模拟、Fuzzing 和漏洞扫描于一体。
Stars: 1 | Forks: 0
上传固件镜像、解包、浏览文件系统、分析二进制文件并进行安全评估——全部通过 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 由 AI 分析驱动。
通过 MCP 将 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 或 [Claude Desktop](https://claude.ai/download) 连接到 Wairz 的 60 多个分析工具，并使用你自己的 Claude 订阅进行 AI 驱动的固件安全研究。
## 功能特性
- **固件解包** — 通过 binwalk 自动提取 SquashFS、JFFS2、UBIFS、CramFS、ext 和 CPIO 文件系统，支持多分区
- **文件浏览器** — 浏览提取的文件系统，支持虚拟树视图，查看文本/二进制/十六进制内容，以及跨文件搜索
- **二进制分析** — 使用 radare2 和 Ghidra headless 对二进制文件进行反汇编和反编译，支持交叉引用和污点分析
- **组件图谱** — 交互式依赖关系图，展示二进制文件、库、脚本及其相互关系
- **安全评估** — 检测硬编码凭据、加密材料、setuid 二进制文件、不安全配置和弱权限
- **SBOM 与 CVE 扫描** — 生成软件物料清单 (CycloneDX)，并根据 NVD 扫描组件的已知漏洞
- **固件模拟** — 在隔离容器中通过 QEMU 启动固件（用户模式用于单个二进制文件，系统模式用于完整操作系统），支持 GDB
- **Fuzzing** — 支持 QEMU 模式的 AFL++，用于跨架构二进制 Fuzzing，具备自动字典/语料库生成和崩溃分类
- **固件对比** — 对比不同固件版本之间的文件系统树、二进制文件和反编译函数
- **实时设备 UART** — 通过主机端串行网桥连接到物理设备，进行交互式控制台访问
- **通过 MCP 进行 AI 分析** — 向 Claude 暴露 60 多个分析工具，用于自主安全研究
- **发现与报告** — 记录安全发现及其严重等级和证据，导出为 Markdown 或 PDF
## 架构
```
Claude Code / Claude Desktop
│
│ 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](https://docs.docker.com/get-docker/) 和 Docker Compose
- [uv](https://docs.astral.sh/uv/getting-started/installation/)（仅用于本地开发）
## 公开测试版
WAIRZ 目前处于 **公开测试版** 阶段。你可能会遇到 Bug 或体验不完善之处。如果遇到任何问题，请在 [GitHub 上提交 issue](https://github.com/digitalandrew/wairz/issues) 或通过 andrew@digitalandrew.io 联系我们。
WAIRZ 目前专为 **嵌入式 Linux** 固件样本设计。对 RTOS 和裸机固件的支持计划在未来版本中推出。
## 快速开始
### Docker（推荐）
```
git clone https://github.com/digitalandrew/wairz.git
cd wairz
cp .env.example .env
docker compose up --build
```
- 前端：http://localhost:3000
- API 文档：http://localhost:8000/docs
### 本地开发
```
# 启动 PostgreSQL 和 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 (单独终端)
cd frontend
npm install
npm run dev
```
或者使用辅助脚本：
```
./launch.sh
```
## 通过 MCP 连接 AI
Wairz 使用 MCP 让 Claude 能够访问固件分析工具。启动后端后，在你的 Claude 客户端注册 MCP 服务器：
### Claude Code
```
claude mcp add wairz -- docker exec -i wairz-backend-1 uv run wairz-mcp --project-id
```
### Claude Desktop
添加到你的 Claude Desktop 配置中（Linux 上为 `~/.config/Claude/claude_desktop_config.json`，macOS 上为 `~/Library/Application Support/Claude/claude_desktop_config.json`）：
```
{
"mcpServers": {
"wairz": {
"command": "docker",
"args": [
"exec", "-i", "wairz-backend-1",
"uv", "run", "wairz-mcp",
"--project-id", ""
]
}
}
}
```
连接后，Claude 可以自主探索固件、分析二进制文件、运行模拟、Fuzzing 目标并生成安全发现。MCP 服务器支持通过 `switch_project` 工具动态切换项目——切换项目无需重启。
### MCP 工具（60+）
| 类别 | 工具 |
|----------|-------|
| **Project** | `get_project_info`, `switch_project`, `list_projects` |
| **Filesystem** | `list_directory`, `read_file`, `search_files`, `file_info`, `find_files_by_type`, `get_component_map`, `get_firmware_metadata`, `extract_bootloader_env` |
| **Strings** | `extract_strings`, `search_strings`, `find_crypto_material`, `find_hardcoded_credentials` |
| **Binary Analysis** | `list_functions`, `disassemble_function`, `decompile_function`, `list_imports`, `list_exports`, `xrefs_to`, `xrefs_from`, `get_binary_info`, `check_binary_protections`, `check_all_binary_protections`, `find_string_refs`, `resolve_import`, `find_callers`, `search_binary_content`, `get_stack_layout`, `get_global_layout`, `trace_dataflow`, `cross_binary_dataflow` |
| **Security** | `check_known_cves`, `analyze_config_security`, `check_setuid_binaries`, `analyze_init_scripts`, `check_filesystem_permissions`, `analyze_certificate` |
| **SBOM** | `generate_sbom`, `get_sbom_components`, `check_component_cves`, `run_vulnerability_scan` |
| **Emulation** | `start_emulation`, `run_command_in_emulation`, `stop_emulation`, `check_emulation_status`, `get_emulation_logs`, `enumerate_emulation_services`, `diagnose_emulation_environment`, `troubleshoot_emulation`, `get_crash_dump`, `run_gdb_command`, `save_emulation_preset`, `list_emulation_presets`, `start_emulation_from_preset` |
| **Fuzzing** | `analyze_fuzzing_target`, `generate_fuzzing_dictionary`, `generate_seed_corpus`, `generate_fuzzing_harness`, `start_fuzzing_campaign`, `check_fuzzing_status`, `stop_fuzzing_campaign`, `triage_fuzzing_crash` |
| **Comparison** | `list_firmware_versions`, `diff_firmware`, `diff_binary`, `diff_decompilation` |
| **UART** | `uart_connect`, `uart_send_command`, `uart_read`, `uart_send_break`, `uart_send_raw`, `uart_disconnect`, `uart_status`, `uart_get_transcript` |
| **Reporting** | `add_finding`, `list_findings`, `update_finding`, `read_project_instructions`, `list_project_documents`, `read_project_document` |
| **Code** | `save_code_cleanup` |
## UART 网桥（可选）
要通过 UART 访问实时设备，请在主机上运行网桥（USB 串行适配器无法轻松透传到 Docker）：
```
pip install pyserial
python scripts/wairz-uart-bridge.py --port /dev/ttyUSB0 --baud 115200
```
网桥监听 TCP 端口 9999。Docker 后端通过 `host.docker.internal` 连接到它。你可能需要允许 Docker 网桥流量：
```
sudo iptables -A INPUT -i docker0 -p tcp --dport 9999 -j ACCEPT
```
## 技术栈
| 层级 | 技术 |
|-------|------------|
| 前端 | React 19, Vite, TypeScript, Tailwind CSS, shadcn/ui |
| 代码查看器 | Monaco Editor |
| 组件图谱 | ReactFlow + Dagre |
| 终端 | xterm.js |
| 状态管理 | Zustand |
| 后端 | Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Alembic |
| 数据库 | PostgreSQL 16 |
| 缓存 | Redis 7 |
| 固件提取 | binwalk, sasquatch, jefferson, ubi_reader, cramfs-tools |
| 二进制分析 | radare2 (r2pipe), pyelftools |
| 反编译 | Ghidra 11.3.1 (headless) 配合自定义分析脚本 |
| 模拟 | QEMU user-mode + system-mode (ARM, MIPS, MIPSel, AArch64) |
| Fuzzing | 支持 QEMU 模式的 AFL++ |
| SBOM | CycloneDX, NVD API (nvdlib) |
| UART | pyserial（主机端网桥）|
| AI 集成 | MCP (Model Context Protocol) |
| 容器 | Docker + Docker Compose |
## 项目结构
```
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
```
## 配置
所有设置均通过环境变量或 `.env` 文件配置：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `DATABASE_URL` | `postgresql+asyncpg://wairz:wairz@postgres:5432/wairz` | PostgreSQL 连接 |
| `REDIS_URL` | `redis://redis:6379/0` | Redis 连接 |
| `STORAGE_ROOT` | `/data/firmware` | 固件存储目录 |
| `MAX_UPLOAD_SIZE_MB` | `500` | 固件上传大小上限 |
| `MAX_TOOL_OUTPUT_KB` | `30` | MCP 工具输出截断限制 |
| `GHIDRA_PATH` | `/opt/ghidra` | Ghidra 安装路径 |
| `GHIDRA_TIMEOUT` | `120` | Ghidra 反编译超时（秒）|
| `FUZZING_IMAGE` | `wairz-fuzzing` | Fuzzing 容器镜像名称 |
| `FUZZING_TIMEOUT_MINUTES` | `120` | 最大 Fuzzing 活动持续时间 |
| `FUZZING_MAX_CAMPAIGNS` | `1` | 最大并发 Fuzzing 活动数 |
| `UART_BRIDGE_HOST` | `host.docker.internal` | UART 网桥主机名 |
| `UART_BRIDGE_PORT` | `9999` | UART 网桥 TCP 端口 |
| `NVD_API_KEY` | *(空)* | 可选的 NVD API 密钥，用于提高速率限制 |
| `LOG_LEVEL` | `INFO` | 日志级别 |
## 测试固件
适合测试的固件镜像：
- **[OpenWrt](https://downloads.openwrt.org/)** — 结构良好的嵌入式 Linux（MIPS, ARM）
- **[DD-WRT](https://dd-wrt.com/)** — 与 OpenWrt 类似
- **[DVRF](https://github.com/praetorian-inc/DVRF)** (Damn Vulnerable Router Firmware) — 故意设计的易受攻击固件，非常适合安全测试
## 许可证
[AGPL-3.0](LICENSE)标签：AFL++, AI安全, Amass, binwalk, Chat Copilot, Claude, CVE检测, CycloneDX, DevSecOps, Ghidra, IoT, LLM, MCP, Model Context Protocol, QEMU, radare2, SBOM, SquashFS, UART, Unmanaged PE, URL提取, Wayback Machine, 上游代理, 二进制分析, 二进制发布, 云安全运维, 云资产清单, 人工智能, 代码比对, 内联执行, 加密材料检测, 反汇编, 反编译, 固件仿真, 固件分析, 固件解包, 域名收集, 嵌入式系统, 开源工具, 弱点检测, 提示词注入, 搜索引擎查询, 文件系统, 文档安全, 测试用例, 物联网安全, 用户模式Hook绕过, 硬件无关, 硬编码凭据, 系统运维工具, 组件依赖分析, 网络安全, 请求拦截, 身份验证强制, 逆向工具, 逆向工程, 配置审计, 隐私保护