promptzero - AI operated Flipper Zero

项目说明

<p align="center">
<img src=".github/assets/banner.png" alt="PromptZero — natural-language operator for the Flipper Zero" width="560">
</p>

<p align="center">
<a href=" src=" alt="Latest release"></a>
<a href=" src=" alt="AGPL-3.0"></a>
<a href=" src=" alt="CI"></a>
<a href="scripts/claude-usage.py"><img src=" alt="Claude usage"></a>
</p>

<sub align="center">_Claude usage/cost is an estimate aggregated from the maintainer's local Claude Code transcripts (task claude-usage); it reflects this machine's sessions only._</sub>

> Describe it. Generate it. Deploy it. Run it.

PromptZero is a natural-language operator for the Flipper Zero. Talk to it like you'd talk to a person — it generates payloads, deploys them, and runs them, all from a single sentence.

> [!CAUTION]
> Authorised use only. PromptZero generates and runs RF, NFC, RFID, and HID payloads — illegal outside contexts you own or ha authorisation to test. Read SECURITY.md for the safety model and threat boundary. The project is under acti; APIs and tools change between minor .
>
> *Built end-to-end with Claude. Review generated payloads before deployment.*

---

Quick start

Prerequisites — Flipper Zero with modded firmware (Momentum / Unleashed / RogueMaster), an Anthropic API key, and a USB cable.

That's the whole onboarding. From here, type natural-language instructions or /help to see slash commands.

> Defensi (one-flag safety rail): add --read-only to refuse any tool that writes, transmits, or executes. Pure reads / scans / queries still dispatch; anything risk-Medium or above is refused at the boundary. See Read-only safety rail for the full rule.
>
>

Other paths: Windows users grab the .zip from the releases page. WSL2 needs USB passthrough — see Transports → WSL2. For wireless BLE, config files, personas, en , and self-upgrade: Configuration reference.

---

What it does

PromptZero connects to your Flipper Zero (and optional ESP32 Marauder WiFi de) over USB serial or BLE, then lets you control e through natural language.

| Subsystem | Capabilities |
|---|---|
| Flipper Zero | Sub-GHz TX/RX, IR TX/RX, NFC detect/emulate, RFID read/write/emulate, iButton, GPIO, BadUSB, storage, app launcher |
| ESP32 Marauder | WiFi scan, deauth, beacon spam, probe flood, PMKID capture, e, BLE spam, BT scanning, skimmer detection, wardriving, MAC spoofing |
| AI Generation | E HTML, BadUSB DuckyScript, Sub-GHz .sub, IR .ir, NFC .nfc from natural language — plus parametric builders for typed parameters |
| Intelligence | Image analysis (file path → device ID + attack ), SD card discovery |
| Audit | SQLite audit log with MITRE ATT&CK technique tags, session export, statistics |

Run promptzero and type /tools for the li. Tool count grows release-o.

The agent layer ships prompt caching, cost-tier model routing (recon on Haiku / exploit on Opus), prompt-injection quarantine, reflexion-on-error with structured ToolError, a <de> oracle injected each turn, and OpenTelemetry GenAI spans. See docs/ for architecture details.

---

Modes

CLI — promptzero

Default. Interactive REPL.

Slash commands (run /help for the full list with descriptions):

Keystrokes during a turn:

Web UI — promptzero --web

Dark-themed browser interface at . Includes the chat surface, a li , file browser, audit log, report builder, and (when a Marauder is connected) a TFT display panel.

<p align="center">
<img src=".github/assets/web.png" alt="PromptZero web UI — chat, li , file browser, audit log" width="900">
</p>

> [!IMPORTANT]
> Auth. Set web.token in your config or PROMPTZERO_WEB_TOKEN in env. The browser picks up #token=… from the URL fragment on first load and caches it in sessionStorage. Empty token + non-loopback bind → ser a red warning. PromptZero speaks plain HTTP — terminate TLS at a reverse proxy (Caddy / Traefik / nginx) or a Tailscale / Cloudflare tunnel.

Host it with Docker. Multi-arch images (distroless, signed, with SBOM + pro) are published to ghcr.io/xunholy/promptzero on every release — see docs/deploy/docker.md.

Health probes. GET /healthz (li, 200 ok) and GET /readyz (readiness, JSON subsystem snapshot) are unauthenticated for headless / systemd / k8s deployment; device connectivity is reported but does not gate readiness (a Flipper/Marauder may attach after startup).

Voice — promptzero --voice

Push-to-talk in CLI mode. Press Enter with no text to record (requires sox); audio is transcribed Whisper, then processed as a normal command.

MCP — promptzero --mcp

Runs as a Model Context Protocol server o. Add to Claude Desktop / Claude Code:

> [!IMPORTANT]
> MCP risk gate. Risk-High and Risk-Critical tools are refused by default — set PROMPTZERO_MCP_ALLOW_HIGH=1 and / or PROMPTZERO_MCP_ALLOW_CRITICAL=1 to allow them. All MCP calls (allowed or denied) are recorded in the audit log. See Safety model below.

---

Safety model

PromptZero is dual-use offensi. The safety story is the project's social licence to exist.

Read SECURITY.md for the full threat model, scope / out-of-scope, and how to report a .

---

Compatibility

| Firmware | Status |
|---|---|
| Momentum (formerly Xtreme) | Primary target |
| Unleashed | Supported |
| RogueMaster | Supported |
| Official (OFW) 1.x | Supported with reduced feature set — region-locked Sub-GHz, no rolling code |

> [!NOTE]
> Official firmware locks Sub-GHz TX to region-specific ISM bands and blocks rolling-code protocols. Modded firmware unlocks the full CC1101 range (300–348 / 387–464 / 779–928 MHz) and enables TX for all 52 supported protocols.

ESP32 Marauder de requires firmware v1.11.1+ over USB CDC ACM (/de for the official Flipper WiFi de, baud 115200).

For BLE wireless (no cable, all tools work, ~10× slower than USB) and per-platform pairing: see Transports reference.

---

Documentation

---

Build & contribute

See CONTRIBUTING.md. Short :

---

License

AGPL-3.0-or-later. Hosting a modified PromptZero as a network service requires publishing source changes under the same license.

---

_{Built with Claude by xunholy.}

项目信息

开发语言：Go

Star 数：243

技术要点

该项目属于红蓝攻防方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕AI operated Flipper Zero展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。