CrimsonGlory/wairz
GitHub: CrimsonGlory/wairz
一款基于 MCP 协议的 AI 辅助固件安全分析工具，支持嵌入式 Linux、RTOS、UEFI 和 Android 固件的自动化解包、逆向分析、漏洞检测与合规评估。
Stars: 0 | Forks: 1
上传固件镜像，进行解包，探索文件系统，分析二进制文件，并进行安全评估 —— 所有这些都通过 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 提供的 AI 分析功能来实现。
将任何兼容 MCP 的 AI Agent 连接到 Wairz 的 383 个分析工具 —— [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[Claude Desktop](https://claude.ai/download)、[OpenCode](https://opencode.ai/)、[Codex](https://github.com/openai/codex)、[Cursor](https://cursor.com/)、[VS Code + Copilot](https://code.visualstudio.com/docs/copilot/)、[Gemini CLI](https://github.com/google-gemini/gemini-cli)、[Windsurf](https://windsurf.com/) 等。
[观看演示视频](https://www.youtube.com/watch?v=gDLhtMFMmMM)
## 功能
- **固件解包** — 通过 binwalk3 和 unblob 自动提取 SquashFS、JFFS2、UBIFS、CramFS、ext、CPIO 和 Intel HEX 文件系统，支持多分区
- **RTOS 支持** — 解包时自动将固件分类为 `linux | rtos | unknown`（FreeRTOS / Zephyr / 裸机 Cortex-M），并支持手动覆盖。RTOS 项目拥有专用的工具类别，用于对原始 `.axf` / `.elf` blob 进行向量表解析、任务枚举、基地址恢复和内存映射分析
- **文件浏览器** — 使用虚拟树浏览提取的文件系统，查看文本/二进制/十六进制内容，并跨文件搜索
- **二进制分析** — 使用 radare2 和 Ghidra headless 对二进制文件进行反汇编和反编译，支持交叉引用、污点分析和能力检测
- **组件映射** — 交互式依赖图，显示二进制文件、库、脚本及其关系
- **安全评估** — 检测硬编码凭证、加密材料、硬编码 IP、setuid 二进制文件、不安全配置、弱权限和网络依赖项
- **攻击面评分** — 针对网络暴露、CGI、setuid、危险函数和已知 daemon 进行自动化的 0-100 风险评分
- **SAST** — 对 shell 脚本使用 ShellCheck，对 Python 脚本使用 Bandit，并附带 CWE 映射
- **cwe_checker** — 通过 Docker sidecar 进行二进制漏洞模式检测（17 种 CWE），支持 ARM/MIPS/x86
- **YARA 扫描** — 自定义规则 + 约 5000 条 YARA Forge 社区规则，支持按需更新
- **威胁情报** — ClamAV 恶意软件扫描、VirusTotal 哈希查询（隐私优先，不上传文件）、abuse.ch 套件（MalwareBazaar、ThreatFox、URLhaus、YARAify），以及用于通过 NSRL 识别已知良好二进制文件的 CIRCL Hashlookup
- **SBOM & CVE 扫描** — 生成物料清单（CycloneDX 1.7、SPDX 2.3、CycloneDX VEX），带有通用二进制版本检测回退、通过 NVD 字典进行 CPE 丰富，以及针对 NVD 的漏洞扫描
- **固件模拟** — 用于单个二进制文件的用户模式，用于在隔离的 container 中完整启动 OS 的系统模式，支持 GDB、pcap 捕获和 Web endpoint 交互
- **网络协议分析** — 从模拟固件中捕获并分析流量：协议分析、不安全协议检测、DNS 查询、TLS 元数据
- **Fuzzing** — 带有 QEMU 模式的 AFL++，用于跨架构二进制模糊测试，具有自动生成字典/语料库和崩溃分类功能
- **固件对比** — 跨固件版本对比文件系统树、二进制文件和反编译函数
- **RTOS 和裸机支持** — 检测 FreeRTOS、VxWorks、Zephyr、ThreadX 及配套组件（lwIP、FatFs 等）
- **UEFI 固件支持** — 使用 UEFIExtract 处理固件卷、模块列表、NVRAM 变量提取和 PE32+ 扫描
- **Android 固件** — 多阶段 APK 安全扫描：18 项清单安全检查（相当于 MobSF）、DEX 字节码模式检测（约 30 种不安全的 API 模式）、jadx 反编译 + mobsfscan SAST（43 条规则），并针对 system/priv-app APK 进行感知固件的严重性调整。包括所有 APK 的批量扫描、反编译源码查看器、权限分析、签名验证和 Android 设备状态审计
- **设备采集** — 通过主机端 bridge 直接从 ADB 连接的 Android 设备拉取固件
- **固件更新检测** — 识别 SWUpdate、RAUC、Mender、opkg、U-Boot 和自定义更新机制，并进行安全差距分析
- **CRA 合规性** — 欧盟网络弹性法案附件 I 评估（20 项要求），从现有发现中自动填充，Article 14 通知导出
- **实时设备 UART** — 通过主机端串行 bridge 连接到物理设备，以进行交互式控制台访问
- **Windows 取证工件** — 注册表配置单元、EVTX 事件日志、Prefetch、SRUM、MFT、USN Journal、LNK 文件、计划任务、WMI 持久化、DPAPI 主密钥、EFS 加密文件、BCD/ESP 启动链、MBR/VBR、ETL 跟踪、AppCompat/Shim DB、驱动程序签名和 BYOVD 检测、.NET 单文件捆绑包和 R2R stomping，以及存档/安装程序格式（MSI、MSIX、MSU、CAB、INF）
- **Linux 取证工件** — systemd unit、journald 日志、container 工件、持久化机制和内核加固配置，每个都支持跨固件查找
- **ICS/OT 协议检测** — 可扩展的 YAML 驱动目录，用于识别嵌入在固件中的 Modbus/TCP、DNP3、Siemens S7comm 和其他工业协议
- **裸机 / MCU 芯片分析** — Schema 驱动的芯片系列目录（例如 TI C28x DSP），用于对原始 MCU/DSP 固件 blob 进行安全状况审计，可通过操作员提供的 YAML 描述符进行扩展
- **固件 carving 沙箱** — 隔离的、无网络的 shell 环境，包含完整的逆向工程工具集（binwalk、unsquashfs、jefferson、ubireader、mkimage 等），用于手动提取非标准的供应商封装
- **跨固件查找** — 数十个 `lookup_*_across_firmwares` MCP 工具允许 agent 在一次调用中查询整个项目语料库中的工件（驱动程序、注册表项、systemd unit、ICS 协议、芯片系列等），而不仅仅是当前活动的固件
- **Ghidra 研究工作区** — 跨会话的持久研究脚本、日志和存档导入，外加用于临时 headless 分析的 `run_ghidra_headless` 工具
- **通过 MCP 进行 AI 分析** — 383 个分析工具（跨越 34 个类别）公开给任何兼容 MCP 的 AI agent，用于自主安全研究
- **发现与报告** — 记录具有严重性评级和证据的安全发现，导出为 Markdown 或结构化叙述报告，并具有完整的评估编排
## 架构
```
Claude Code / Claude Desktop / OpenCode
│
│ MCP (stdio)
▼
┌─────────────────┐ ┌──────────────────────────────────┐
│ wairz-mcp │────▶│ FastAPI Backend │
│ (MCP server) │ │ │
│ 383 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/)（仅用于本地开发）
## 关于该 Fork
该仓库是 [digitalandrew/wairz](https://github.com/digitalandrew/wairz) 的一个分支，在上游基础上进行了大量额外的提交，将 MCP 工具的覆盖面从上游基线扩展到了跨越 34 个类别的 384 个工具：
- **eastmadc** — 大幅扩展了分析“walker”pipeline 及相应的 MCP 工具：一套庞大的 Windows 取证工件解析器（注册表配置单元、EVTX 事件日志、Prefetch、SRUM、MFT、USN Journal、LNK、计划任务、WMI 持久化、DPAPI、EFS、BCD/ESP 启动链、MBR/VBR、ETL 跟踪、AppCompat/Shim DB、驱动程序签名和 BYOVD、.NET 捆绑包以及存档/安装程序格式），Linux 取证工件解析器（systemd、journald、container、持久化、内核加固），ICS/OT 协议检测，Schema 驱动的裸机/MCU 芯片系列目录，Android 状态审计，固件 carving 沙箱，以及硬件固件/SBOM 扩展 —— 每个都有自己对应的 MCP 工具、数据库迁移和（在适用的地方）跨固件查找支持。
- **CrimsonGlory** — 主要致力于使 Ghidra MCP 集成更加灵活：支持原始 MIPS16E 二进制文件，提供 `run_ghidra_headless` 工具，支持跨会话的持久化 Ghidra 研究文件/脚本/日志，以及各种 CI、lint 和开发服务器（CORS/主机检查）的修复。
有关相对于上游的完整更改列表，请查看 git 历史。
## 公测阶段
WAIRZ 目前处于**公测**阶段。您可能会遇到 bug 或功能不完善的地方。如果您遇到任何问题，请[在 GitHub 上提出 issue](https://github.com/digitalandrew/wairz/issues) 或通过 andrew@digitalandrew.io 联系我们。
WAIRZ 支持**嵌入式 Linux**、**RTOS/裸机**（FreeRTOS、VxWorks、Zephyr、ThreadX）、**UEFI** 和 **Android** 固件。自动检测在解包时运行，可以从项目页面进行覆盖。特定于 Linux 的工具（模拟、init-script 分析、SBOM 等）在 RTOS 项目中会被隐藏，取而代之的是专用的 RTOS 工具类别。有关详细信息，请参阅 [RTOS 支持](docs/features/rtos.md)。
## 快速开始
### Docker（推荐）
```
git clone https://github.com/digitalandrew/wairz.git
cd wairz
cp .env.example .env
# 编辑 .env 并将 POSTGRES_PASSWORD 和 FIRMAE_DB_PASSWORD 设置为强随机值：
# python3 -c 'import secrets; print(secrets.token_urlsafe(32))'
# （对于全新的本地安装，任何值都可以；占位符将无法启动 stack。）
docker compose up --build
```
- 前端：http://localhost:3000
- API 文档：http://localhost:8000/docs
### 带有热重载的 Docker（开发环境）
```
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d
```
后端 Python 代码的更改会通过 uvicorn `--reload` 自动生效。前端使用带有 HMR 的 Vite 开发服务器。代码更改无需重新构建 —— 仅在依赖项发生更改（`pyproject.toml` 或 `package.json`）时才需要重新构建。
### 本地开发
```
# 启动 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 让 AI Agent 访问固件分析工具。启动后端后，在您首选的客户端中注册 MCP 服务器：
`--project-id` 是可选的 —— 在希望从 agent 内部切换项目的共享/团队实例上可以省略它。agent 会在首次使用时调用 `list_projects` 并询问您指的是哪个项目。
### Claude Code
```
claude mcp add wairz -- docker exec -i wairz-backend-1 uv run wairz-mcp --project-id
```
对于通过 SSH 访问的共享 Wairz 服务器（启动时未固定项目）：
```
claude mcp add wairz -- ssh wairz-host docker exec -i wairz-backend-1 uv run wairz-mcp
```
### 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", ""
]
}
}
}
```
### OpenCode
添加到您的 `opencode.json` 中（项目根目录或 `~/.config/opencode/opencode.json`）：
```
{
"mcp": {
"wairz": {
"type": "local",
"command": ["docker", "exec", "-i", "wairz-backend-1", "uv", "run", "wairz-mcp", "--project-id", ""],
"timeout": 30000,
"enabled": true
}
}
}
```
连接成功后，您的 AI Agent 就可以自主探索固件、分析二进制文件、运行模拟、对目标进行 Fuzzing，并生成安全发现。MCP 服务器支持通过 `switch_project` 工具进行动态项目切换 —— 更改项目无需重启。
#### 包含多个固件版本的项目
当一个项目上传了多个固件时（对于通过 `diff_firmware` 在不同版本之间进行 diff 对比非常有用），MCP 服务器默认选择最早解包上传的固件。要针对特定版本，请在启动命令中添加 `--firmware-id `，或者将 `firmware_id` 传递给 `switch_project` MCP 工具。使用 `list_firmware_versions` 查找 ID。
### MCP 工具（共 34 个类别 383 个）
准确计数：`create_tool_registry()` (`backend/app/ai/__init__.py`) 在 `backend/app/ai/tools/` 下的 32 个类别文件中注册了 380 个工具；`backend/app/mcp_server.py` 直接注册了另外 4 个（`get_project_info`、`switch_project`、`list_projects`、`save_code_cleanup`），总计 384 个。
| 类别 | 数量 | 工具 |
|----------|-------|-------|
| **Windows 取证** | 126 |list_appcompat_entries`, `lookup_appcompat_entry`, `lookup_appcompat_entry_across_firmwares`, `appcompat_walk_status`, `trigger_appcompat_walk`, `list_cab_contents`, `read_msix_manifest`, `dump_msi_custom_actions`, `parse_inf_basic`, `identify_psf_baseline`, `classify_driver_package_subtype`, `search_bcd_entries`, `bcd_walk_status`, `trigger_bcd_walk`, `lookup_bcd_entry_across_firmwares`, `list_dotnet_bundles`, `get_bundle_metadata`, `list_extracted_assemblies`, `get_assembly_il`, `scan_r2r_stomping`, `trigger_dotnet_decompile`, `list_dpapi_master_keys`, `lookup_dpapi_master_key`, `lookup_dpapi_master_key_across_firmwares`, `dpapi_walk_status`, `trigger_dpapi_walk`, `list_drivers`, `get_driver_info`, `list_signed_drivers`, `get_signing_tier_histogram`, `scan_inf_imports`, `diff_driver_matrix`, `lookup_byovd_driver`, `list_efs_encrypted_files`, `lookup_efs_encrypted_file`, `search_efs_by_sid`, `efs_walk_status`, `trigger_efs_walk`, `lookup_efs_recovery_agent_across_firmwares`, `search_esp_entries`, `esp_walk_status`, `trigger_esp_walk`, `lookup_esp_chain`, `lookup_esp_entry_across_firmwares`, `list_etl_events`, `lookup_etl_event`, `search_etl_events`, `etl_walk_status`, `trigger_etl_walk`, `lookup_etl_provider_across_firmwares`, `list_evtx_files`, `parse_evtx_file`, `query_evtx_events`, `evtx_walk_status`, `trigger_evtx_walk`, `search_events`, `evtx_walk_summary`, `lookup_event_record_across_firmwares`, `list_windows_injection_detections`, `windows_injection_walk_status`, `trigger_windows_injection_walk`, `lookup_volatility_injection_across_firmwares`, `search_lnk_records`, `lnk_walk_status`, `trigger_lnk_walk`, `lookup_lnk_record_across_firmwares`, `list_mbr_vbr_sectors`, `lookup_mbr_vbr_sector`, `lookup_mbr_vbr_sector_across_firmwares`, `search_mft_records`, `mft_walk_status`, `lookup_mft_record_across_firmwares`, `trigger_mft_walk`, `verify_authenticode`, `decode_rich_header`, `scan_dbx_revocation`, `detect_pe_arch_view`, `list_signatures`, `get_signature_chain`, `search_prefetch_records`, `prefetch_walk_status`, `trigger_prefetch_walk`, `lookup_prefetch_record_across_firmwares`, `list_windows_processes`, `windows_processes_walk_status`, `trigger_windows_processes_walk`, `lookup_windows_process_across_firmwares`, `list_hives`, `walk_hive`, `get_run_keys`, `scan_persistence`, `dump_subkey`, `diff_hives`, `trigger_registry_hive_walk`, `lookup_registry_extract_across_firmwares`, `search_scheduled_tasks`, `scheduled_task_walk_status`, `trigger_scheduled_task_walk`, `lookup_scheduled_task_across_firmwares`, `list_sdb_entries`, `lookup_sdb_shim`, `summarize_sdb_anomalies`, `lookup_sdb_entry_across_firmwares`, `search_srum_records`, `srum_walk_status`, `trigger_srum_walk`, `lookup_srum_record_across_firmwares`, `list_vhdx_partitions`, `list_bcd_entries`, `list_esedb_tables`, `dump_esedb_table`, `get_storage_summary`, `list_update_packages`, `get_package_metadata`, `get_supersedence_chain`, `list_kb_files`, `diff_kb_packages`, `list_usnjrnl_entries`, `lookup_usnjrnl_entry`, `lookup_usnjrnl_entry_across_firmwares`, `usnjrnl_walk_status`, `trigger_usnjrnl_walk`, `search_wmi_events`, `wmi_walk_status`, `trigger_wmi_walk`, `lookup_wmi_persistence` |
| **Linux 取证** | 27 | `list_journald_entries`, `lookup_journald_entry`, `search_journald_messages`, `journald_walk_status`, `trigger_journald_walk`, `lookup_journald_entry_across_firmwares`, `list_systemd_units`, `lookup_systemd_unit`, `search_systemd_units`, `systemd_walk_status`, `trigger_systemd_walk`, `lookup_systemd_unit_across_firmwares`, `list_container_artifacts`, `lookup_container_artifact`, `search_container_images`, `container_walk_status`, `trigger_container_walk`, `lookup_container_image_across_firmwares`, `list_linux_persistence_entries`, `lookup_linux_persistence_entry`, `lookup_linux_persistence_across_firmwares`, `linux_persistence_walk_status`, `trigger_linux_persistence_walk`, `audit_kernel_config_firmware`, `lookup_kernel_config_across_firmwares`, `trigger_kernel_config_walk`, `get_kernel_config_extraction` |
| **安全** | 26 | `check_known_cves`, `analyze_config_security`, `check_setuid_binaries`, `analyze_init_scripts`, `check_filesystem_permissions`, `analyze_certificate`, `check_kernel_hardening`, `scan_with_yara`, `extract_kernel_config`, `check_kernel_config`, `analyze_selinux_policy`, `check_selinux_enforcement`, `check_compliance`, `scan_scripts`, `shellcheck_scan`, `bandit_scan`, `check_secure_boot`, `update_yara_rules`, `detect_network_dependencies`, `detect_update_mechanisms`, `analyze_update_config`, `create_cra_assessment`, `auto_populate_cra`, `update_cra_requirement`, `export_cra_checklist`, `generate_article14_notification` |
| **二进制分析** | 29 | `start_binary_analysis`, `check_binary_analysis_status`, `start_function_decompile`, `check_function_decompile_status`, `list_functions`, `disassemble_function`, `decompile_function`, `batch_decompile_functions`, `list_imports`, `list_exports`, `xrefs_to`, `xrefs_from`, `get_binary_info`, `analyze_binary_format`, `check_binary_protections`, `find_string_refs`, `resolve_import`, `check_all_binary_protections`, `trace_dataflow`, `find_callers`, `search_binary_content`, `get_stack_layout`, `get_global_layout`, `cross_binary_dataflow`, `detect_capabilities`, `list_binary_capabilities`, `analyze_raw_binary`, `detect_rtos`, `get_ghidra_analysis_logs` |
| **模拟** | 25 | `list_available_kernels`, `download_kernel`, `start_emulation`, `run_command_in_emulation`, `stop_emulation`, `check_emulation_status`, `get_emulation_logs`, `diagnose_emulation_environment`, `troubleshoot_emulation`, `enumerate_emulation_services`, `get_crash_dump`, `run_gdb_command`, `save_emulation_preset`, `list_emulation_presets`, `start_emulation_from_preset`, `emulate_with_qiling`, `check_qiling_rootfs`, `start_system_emulation`, `system_emulation_status`, `list_firmware_services`, `run_command_in_firmware`, `stop_system_emulation`, `capture_network_traffic`, `get_nvram_state`, `interact_web_endpoint` |
| **硬件固件** | 10 | `list_hardware_firmware`, `analyze_hardware_firmware`, `list_firmware_drivers`, `check_firmware_cves`, `find_unsigned_firmware`, `export_hardware_firmware_hbom`, `extract_dtb`, `verify_cve_attribution`, `describe_advisory`, `list_extension_points` |
| **威胁情报** | 10 | `scan_with_clamav`, `scan_firmware_clamav`, `check_virustotal`, `scan_firmware_virustotal`, `check_malwarebazaar_hash`, `check_threatfox_ioc`, `check_urlhaus_url`, `enrich_firmware_threat_intel`, `check_known_good_hash`, `scan_firmware_known_good` |
| **Android** | 9 | `analyze_apk`, `list_apk_permissions`, `check_apk_signatures`, `scan_apk_manifest`, `scan_apk_bytecode`, `scan_apk_sast`, `trigger_android_posture_walk`, `get_android_posture`, `lookup_android_posture_across_firmwares` |
| **Fuzzing** | 9 | `analyze_fuzzing_target`, `generate_fuzzing_dictionary`, `generate_seed_corpus`, `generate_fuzzing_harness`, `start_fuzzing_campaign`, `check_fuzzing_status`, `stop_fuzzing_campaign`, `triage_fuzzing_crash`, `diagnose_fuzzing_campaign` |
| **SBOM** | 9 | `generate_sbom`, `get_sbom_components`, `check_component_cves`, `run_vulnerability_scan`, `list_vulnerabilities_for_assessment`, `export_sbom`, `push_to_dependency_track`, `assess_vulnerabilities`, `set_vulnerability_status` |
| **Ghidra 研究** | 10 | `list_ghidra_research_files`, `read_ghidra_script`, `save_ghidra_script`, `import_ghidra_archive`, `get_ghidra_import_status`, `export_ghidra_archive`, `resolve_firmware_path`, `run_ghidra_headless`, `list_ghidra_logs`, `read_ghidra_log` |
| **文档** | 7 | `read_scratchpad`, `update_scratchpad`, `save_document`, `read_project_instructions`, `list_project_documents`, `read_project_document`, `save_code_cleanup` |
| **文件系统** | 8 | `list_directory`, `read_file`, `search_files`, `file_info`, `find_files_by_type`, `get_component_map`, `get_firmware_metadata`, `extract_bootloader_env` |
| **UART** | 8 | `uart_connect`, `uart_send_command`, `uart_read`, `uart_send_break`, `uart_send_raw`, `uart_disconnect`, `uart_status`, `uart_get_transcript` |
| **报告** | 6 | `add_finding`, `list_findings`, `update_finding`, `generate_assessment_report`, `generate_executive_summary`, `run_full_assessment` |
| **字符串** | 5 | `extract_strings`, `search_strings`, `find_crypto_material`, `find_hardcoded_credentials`, `find_hardcoded_ips` |
| **网络** | 5 | `analyze_network_traffic`, `get_protocol_breakdown`, `identify_insecure_protocols`, `get_dns_queries`, `get_network_conversations` |
| **UEFI** | 5 | `list_firmware_volumes`, `list_uefi_modules`, `extract_nvram_variables`, `identify_uefi_module`, `read_uefi_module` |
| **RTOS** *(applies_to `rtos`)* | 5 | `detect_rtos_kernel`, `enumerate_rtos_tasks`, `analyze_vector_table`, `recover_base_address`, `analyze_memory_map` |
| **对比** | 4 | `list_firmware_versions`, `diff_firmware`, `diff_binary`, `diff_decompilation` |
| **裸机 / MCU** | 4 | `list_chip_families`, `audit_bare_metal_firmware`, `submit_bare_metal_descriptor`, `lookup_bare_metal_findings_across_firmwares` |
| **ICS 协议** | 4 | `trigger_ics_protocol_walk`, `list_ics_protocols`, `lookup_ics_protocol_across_firmwares`, `describe_ics_protocol_anomalies` |
| **Python AST** | 4 | `python_ast_walk_status`, `trigger_python_ast_walk`, `get_python_ast_summary`, `lookup_python_ast_across_firmwares` |
| **项目** | 3 | `get_project_info`, `switch_project`, `list_projects` |
| **cwe_checker** | 3 | `cwe_check_status`, `cwe_check_binary`, `cwe_check_firmware` |
| **VulHunt** | 3 | `vulhunt_scan_binary`, `vulhunt_scan_firmware`, `vulhunt_check_available` |
| **报告编写器** | 3 | `report_start`, `report_write_section`, `report_render` |
| **文件格式检测** | 3 | `validate_file_format`, `list_file_formats`, `cross_firmware_format_collision_audit` |
| **模块可达性** | 3 | `trigger_module_reachability_walk`, `get_module_reachability`, `lookup_module_across_firmwares` |
| **网络暴露** | 3 | `trigger_network_exposure_walk`, `get_network_exposure`, `lookup_network_listener_across_firmwares` |
| **DS1QRSetup 调用图** | 3 | `ds1qrsetup_callgraph_walk_status`, `trigger_ds1qrsetup_callgraph_walk`, `lookup_ds1qrsetup_callgraph_across_firmwares` |
| **攻击面** | 2 | `detect_input_vectors`, `analyze_binary_attack_surface` |
| **污点 LLM** | 2 | `scan_taint_analysis`, `deep_dive_taint_analysis` |
| **Carving 沙箱** | 1 | `run_shell` |
上述许多类别附带一个 `lookup_*_across_firmwares` 工具 —— 这是一个项目聚合查询（例如“哪些固件共享此驱动程序哈希/注册表项/systemd unit/ICS 协议/芯片系列”），只需单次 MCP 调用即可得到解答，无需按固件逐一迭代。
## UART Bridge（可选）
要通过 UART 访问实时设备，请在主机上运行该 bridge（USB 串行适配器无法轻易直通到 Docker）：
```
pip install pyserial
python3 scripts/wairz-uart-bridge.py --bind 0.0.0.0 --port 9999
```
该 bridge 是一个 TCP 服务器 —— 串行设备路径和波特率是通过 `uart_connect` MCP 工具指定的，而不是在命令行中指定。
在 Linux 上，允许 Docker 流量访问该 bridge，并确保正确配置了 `.env`：
```
sudo iptables -I INPUT -p tcp --dport 9999 -j ACCEPT
```
`.env` 中的 `UART_BRIDGE_HOST` 必须是 `host.docker.internal`（而不是 `localhost`）。更改 `.env` 后重启后端：`docker compose restart backend`。
有关完整的设置详细信息，请参阅 [UART 控制台文档](docs/features/uart.md)。
## 设备采集 Bridge（可选）
要直接从 ADB 连接的 Android 设备拉取固件，请在主机上运行设备 bridge：
```
python3 scripts/wairz-device-bridge.py --bind 0.0.0.0 --port 9998
```
要在没有真实设备的情况下进行开发，请使用模拟模式：
```
python3 scripts/wairz-device-bridge.py --mock --port 9998
```
设置与 UART bridge 的模式相同：在 `.env` 中设置 `DEVICE_BRIDGE_HOST=host.docker.internal`，并允许 Docker 流量访问 9998 端口。
## 技术栈
| 层级 | 技术 |
|-------|------------|
| 前端 | 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 |
| 固件提取 | binwalk3, unblob, sasquatch, jefferson, ubi_reader, cramfs-tools, UEFIExtract |
| 二进制分析 | radare2 (r2pipe), pyelftools, LIEF, capa |
| 反编译 | Ghidra 11.3.1 (headless) 配有自定义分析脚本 |
| 漏洞检测 | cwe_checker (17 CWEs), VulHunt, YARA (~5000 Forge 规则), ShellCheck, Bandit |
| 威胁情报 | ClamAV, VirusTotal, abuse.ch (MalwareBazaar, ThreatFox, URLhaus, YARAify), CIRCL Hashlookup (NSRL) |
| 模拟 | QEMU 用户模式 + 系统模式, FirmAE, Qiling (ARM, MIPS, MIPSel, AArch64) |
| 网络分析 | Scapy（pcap 捕获 + 来自模拟固件的协议分析） |
| Fuzzing | 带有 QEMU 模式的 AFL++ |
| SBOM | CycloneDX 1.7, SPDX 2.3, CycloneDX VEX, NVD API (nvdlib), Grype, Syft |
| Android | Androguard (APK 分析), ADB (设备采集) |
| UART | pyserial (主机端 bridge) |
| 合规性 | 欧盟 CRA 附件 I（20 项要求），ETSI EN 303 645 |
| 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 + 383 tool implementations
│ │ │ └── tools/ # 32 category files (filesystem, binary, security, emulation, hardware_firmware, windows_*, linux_*, ics_protocol, bare_metal, cwe_checker, vulhunt, attack_surface, network, uefi, taint_llm, 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
│ └── wairz-device-bridge.py # Host-side ADB device acquisition bridge
├── docker-compose.yml
├── launch.sh # Local development launcher
├── .env.example
└── CLAUDE.md
```
## 配置
所有设置均通过环境变量或 `.env` 文件进行配置：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `DATABASE_URL` | *(通过 `.env` 中的 `POSTGRES_PASSWORD` 设置)* | PostgreSQL 连接 |
| `REDIS_URL` | `redis://redis:6379/0` | Redis 连接 |
| `STORAGE_ROOT` | `/data/firmware` | 固件存储目录 |
| `MAX_UPLOAD_SIZE_MB` | `2048` | 固件最大上传大小 |
| `MAX_TOOL_OUTPUT_KB` | `30` | MCP 工具输出截断限制 |
| `GHIDRA_PATH` | `/opt/ghidra` | Ghidra 安装路径 |
| `GHIDRA_TIMEOUT` | `300` | Ghidra 反编译超时时间（秒） |
| `FUZZING_IMAGE` | `wairz-fuzzing` | Fuzzing 容器镜像名称 |
| `FUZZING_TIMEOUT_MINUTES` | `120` | Fuzzing 活动最大持续时间 |
| `FUZZING_MAX_CAMPAIGNS` | `1` | 并发 Fuzzing 活动最大数量 |
| `UART_BRIDGE_HOST` | `host.docker.internal` | UART bridge 主机名 |
| `UART_BRIDGE_PORT` | `9999` | UART bridge TCP 端口 |
| `DEVICE_BRIDGE_HOST` | `host.docker.internal` | 设备采集 bridge 主机名 |
| `DEVICE_BRIDGE_PORT` | `9998` | 设备采集 bridge TCP 端口 |
| `NVD_API_KEY` | *(空)* | 可选的 NVD API key，用于获取更高速率限制 |
| `VIRUSTOTAL_API_KEY` | *(空)* | 可选的 VirusTotal API key（仅哈希查询，无文件上传） |
| `ABUSECH_AUTH_KEY` | *(空)* | 可选的 abuse.ch 身份验证 key，用于获取更高速率限制 |
| `CLAMAV_HOST` | `clamav` | ClamAV daemon 主机名（Docker 服务） |
| `CLAMAV_PORT` | `3310` | ClamAV daemon TCP 端口 |
| `API_KEY` | *(空)* | 可选的 API key，用于 REST endpoint 身份验证 |
| `LOG_LEVEL` | `INFO` | 日志级别 |
## 安全
Wairz 会摄取并分析不受信任的固件二进制文件；部署层面本身也需要小心。默认的 `docker-compose.yml` 强制执行以下规则：
**必需的密钥。** `POSTGRES_PASSWORD` 和 `FIRMAE_DB_PASSWORD` 是必需的 —— 如果未在 `.env` 中设置它们，执行 `docker compose up` 会报错：
```
$ docker compose config
error while interpolating services.postgres.environment.POSTGRES_PASSWORD:
required variable POSTGRES_PASSWORD is missing a value
```
使用以下命令生成强密码：
```
python3 -c 'import secrets; print(secrets.token_urlsafe(32))'
```
不要提交 `.env` 文件。仅将 `.env.example` 用作模板。
**绑定默认值。** 后端（`:8000`）和前端（`:3000`）默认绑定到 `127.0.0.1` —— 仅限本地访问。`/ws` WebSocket endpoint 尚未经过身份验证，因此在设置 `API_KEY` *并且* 对 WebSocket 进行身份验证门控之前，将后端暴露给局域网是不安全的。在您了解其中的权衡之后，如果需要允许局域网访问：
```
# .env
API_KEY=
BACKEND_HOST_BIND=0.0.0.0
FRONTEND_HOST_BIND=0.0.0.0
```
Postgres（`:5432`）和 Redis（`:6379`）始终绑定到环回接口 —— 无法覆盖。使用 `docker compose exec postgres psql ...` 进行主机端数据库访问，而不是通过网络套接字。
**轮换凭证。** 编辑 `.env`，然后重新创建受影响的容器：
```
docker compose up -d
```
特别针对 Postgres，针对现有的 `pgdata` 卷更改 `POSTGRES_PASSWORD` 需要在运行中的容器内执行 `ALTER USER wairz WITH PASSWORD ...`，或者使用一个全新的卷。`pg-backup` 服务（每晚将 `pg_dump` 导出到 `${BACKUP_DIR:-./backups}`）使通过转储和恢复进行轮换可以安全地进行试验。
**生产环境。** 对于生产部署，请考虑使用外部密钥管理器（HashiCorp Vault、AWS Secrets Manager、SOPS 加密的 `.env` 文件），而不是明文的 `.env`。`docker-compose.prod.yml` Docker-secrets 变体已在路线图中，但目前尚未包含在代码树中。
## 测试固件
适合测试的优秀固件镜像：
- **[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)标签：DNS 反向解析, 二进制分析, 云安全运维, 云资产清单, 人工智能, 固件分析, 域名收集, 嵌入式系统, 搜索引擎查询, 测试用例, 用户模式Hook绕过, 请求拦截, 身份验证强制, 逆向工具, 逆向工程