{"id":49164418,"url":"https://github.com/xunholy/promptzero","last_synced_at":"2026-06-09T13:01:17.871Z","repository":{"id":351933413,"uuid":"1213121380","full_name":"xunholy/promptzero","owner":"xunholy","description":"AI operated Flipper Zero","archived":false,"fork":false,"pushed_at":"2026-06-06T20:49:22.000Z","size":28762,"stargazers_count":177,"open_issues_count":1,"forks_count":25,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-06-06T21:20:19.632Z","etag":null,"topics":["badusb","cybersecurity","flipper","flipper-zero","golang","hardware-hacking","marauder","momentum","pentesting","red-team","subghz","unleashed","unlocked","wifi-hacking"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xunholy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-17T04:11:21.000Z","updated_at":"2026-06-06T20:49:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xunholy/promptzero","commit_stats":null,"previous_names":["xunholy/promptzero"],"tags_count":641,"template":false,"template_full_name":null,"purl":"pkg:github/xunholy/promptzero","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xunholy%2Fpromptzero","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xunholy%2Fpromptzero/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xunholy%2Fpromptzero/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xunholy%2Fpromptzero/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xunholy","download_url":"https://codeload.github.com/xunholy/promptzero/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xunholy%2Fpromptzero/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34107866,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["badusb","cybersecurity","flipper","flipper-zero","golang","hardware-hacking","marauder","momentum","pentesting","red-team","subghz","unleashed","unlocked","wifi-hacking"],"created_at":"2026-04-22T14:04:48.849Z","updated_at":"2026-06-09T13:01:17.851Z","avatar_url":"https://github.com/xunholy.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/banner.png\" alt=\"PromptZero — natural-language operator for the Flipper Zero\" width=\"560\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/xunholy/promptzero/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/xunholy/promptzero?label=release\" alt=\"Latest release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/xunholy/promptzero/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-AGPL--3.0-blue\" alt=\"AGPL-3.0\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/xunholy/promptzero/actions/workflows/ci.yaml\"\u003e\u003cimg src=\"https://github.com/xunholy/promptzero/actions/workflows/ci.yaml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e **Describe it. Generate it. Deploy it. Run it.**\n\nPromptZero is a natural-language operator for the [Flipper Zero](https://flipperzero.one). Talk to it like you'd talk to a person — it generates payloads, deploys them, and runs them, all from a single sentence.\n\n\u003e [!CAUTION]\n\u003e **Authorised use only.** PromptZero generates and runs RF, NFC, RFID, and HID payloads — illegal outside contexts you own or have written authorisation to test. Read [`SECURITY.md`](SECURITY.md) for the safety model and threat boundary. The project is under active development; APIs and tools change between minor versions.\n\u003e\n\u003e *Built end-to-end with [Claude](https://claude.ai). Review generated payloads before deployment.*\n\n```\npromptzero\u003e make me a Starbucks WiFi captive portal\n  Generated and deployed evil_portal to /ext/apps_data/evil_portal/index.html\n  Evil portal started on Marauder devboard\n\npromptzero\u003e scan for nearby WiFi networks and deauth the strongest one\n  Found 12 access points. Strongest: \"NETGEAR-5G\" (-31 dBm, channel 6)\n  Selected AP 0. Deauth attack running...\n\npromptzero\u003e create a BadUSB payload that opens a reverse shell on Windows\n  Generated and deployed badusb to /ext/badusb/generated_payload.txt\n  Ready to execute - plug into target and run\n\npromptzero\u003e identify this device: /tmp/remote.jpg\n  That's a Samsung BN59 series TV remote using the Samsung32 IR protocol.\n  I can generate a complete remote file. Want me to create it?\n```\n\n---\n\n## Quick start\n\n**Prerequisites** — Flipper Zero with modded firmware (Momentum / Unleashed / RogueMaster), an Anthropic API key, and a USB cable.\n\n```bash\n# 1. Install (Linux/macOS, amd64/arm64) — pinned to release artifacts (immutable per tag)\ncurl -fsSL https://github.com/xunholy/promptzero/releases/latest/download/install.sh | sh\n\n# 2. Configure\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n\n# 3. Run\npromptzero\n```\n\n```\npromptzero\u003e what's connected?\n  Flipper Zero — firmware 0.99.1, hardware v7.4\n  Battery 84 % | SD card 4.1 GB free / 7.4 GB total\n```\n\nThat's the whole onboarding. From here, type natural-language instructions or `/help` to see slash commands.\n\n\u003e **Defensive posture (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](docs/reference/configuration.md#read-only-safety-rail) for the full rule.\n\u003e\n\u003e ```bash\n\u003e promptzero --read-only          # blue-team / forensics / training\n\u003e ```\n\n**Other paths:** Windows users grab the `.zip` from the [releases page](https://github.com/xunholy/promptzero/releases). WSL2 needs USB passthrough — see [Transports → WSL2](docs/reference/transports.md#wsl2-usb-passthrough). For wireless BLE, config files, personas, environment variables, and self-upgrade: [Configuration reference](docs/reference/configuration.md).\n\n---\n\n## What it does\n\nPromptZero connects to your Flipper Zero (and optional ESP32 Marauder WiFi devboard) over USB serial or BLE, then lets you control everything through natural language.\n\n| Subsystem | Capabilities |\n|---|---|\n| **Flipper Zero** | Sub-GHz TX/RX, IR TX/RX, NFC detect/emulate, RFID read/write/emulate, iButton, GPIO, BadUSB, storage, app launcher |\n| **ESP32 Marauder** | WiFi scan, deauth, beacon spam, probe flood, PMKID capture, evil portal, BLE spam, BT scanning, skimmer detection, wardriving, MAC spoofing |\n| **AI Generation** | Evil portal HTML, BadUSB DuckyScript, Sub-GHz `.sub`, IR `.ir`, NFC `.nfc` from natural language — plus parametric builders for typed parameters |\n| **Intelligence** | Image analysis via Claude vision (file path → device ID + attack vector), SD card discovery |\n| **Audit** | SQLite audit log with MITRE ATT\u0026CK technique tags, session export, statistics |\n\nRun `promptzero` and type `/tools` for the live registry. Tool count grows release-over-release.\n\nThe **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 `\u003cdevice-state\u003e` oracle injected each turn, and OpenTelemetry GenAI spans. See [`docs/`](docs/) for architecture details.\n\n---\n\n## Modes\n\n### CLI — `promptzero`\n\nDefault. Interactive REPL.\n\n```\npromptzero\u003e scan the SD card and show me what signals I have saved\npromptzero\u003e transmit the garage door signal\npromptzero\u003e read the NFC tag on my desk\n```\n\nSlash commands (run `/help` for the full list with descriptions):\n\n- **Conversation**: `/help`, `/reset`, `/quit`\n- **Session**: `/sessions`, `/save \u003cname\u003e`, `/resume \u003cid\u003e`, `/forget \u003cid\u003e`\n- **Info**: `/status`, `/tools [filter|page \u003cn\u003e]`, `/history [N]`, `/audit {stats|find|tail|top|session|query|export}`, `/stats [section]`, `/cost`, `/budget [set \u003cUSD\u003e|off]`, `/debug`\n- **Operator**: `/persona [name]`, `/mode [name]`, `/watch [pause|resume]`, `/webhooks [test \u003cname\u003e]`, `/validate \u003cpath\u003e`, `/attack {set|clear} \u003ctechniques\u003e`, `/campaign {validate|run} \u003cfile\u003e`, `/rewind [snapshot]`, `/report [session] [json] [save]`, `/rules [list|pause|resume|test]`\n- **Device**: `/reconnect`\n\nKeystrokes during a turn:\n\n- **Ctrl+C** — cancel the current turn entirely.\n- **Ctrl+G** — abort the current streaming tool (e.g. `subghz_receive`, `wifi_scan_ap`) but let the agent continue with the partial result. Use this when you've seen what you needed and don't want to wait out the full duration.\n- **Ctrl+R** — reverse-incremental history search.\n- **Ctrl+L** — clear screen.\n\n### Web UI — `promptzero --web`\n\nDark-themed browser interface at `http://localhost:8080`. Includes the chat surface, a live Flipper viewport, file browser, audit log, report builder, and (when a Marauder is connected) a TFT display panel.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/assets/web.png\" alt=\"PromptZero web UI — chat, live Flipper viewport, file browser, audit log\" width=\"900\"\u003e\n\u003c/p\u003e\n\n\u003e [!IMPORTANT]\n\u003e **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 → server prints a red warning. PromptZero speaks plain HTTP — terminate TLS at a reverse proxy (Caddy / Traefik / nginx) or a Tailscale / Cloudflare tunnel.\n\n### Voice — `promptzero --voice`\n\nPush-to-talk in CLI mode. Press Enter with no text to record (requires `sox`); audio is transcribed via OpenAI Whisper, then processed as a normal command.\n\n```\nUbuntu/Debian:  apt install sox\nmacOS (brew):   brew install sox\nArch:           pacman -S sox\n```\n\n### MCP — `promptzero --mcp`\n\nRuns as a [Model Context Protocol](https://modelcontextprotocol.io/) server over stdio. Add to Claude Desktop / Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"promptzero\": {\n      \"command\": \"/path/to/promptzero\",\n      \"args\": [\"--mcp\"]\n    }\n  }\n}\n```\n\n\u003e [!IMPORTANT]\n\u003e **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](#safety-model) below.\n\n---\n\n## Safety model\n\nPromptZero is dual-use offensive tooling. The safety story is the project's social licence to exist.\n\n- **Risk classification per tool.** Every spec carries a tier — Low / Medium / High / Critical. Read-only ops are Low; destructive RF transmit, RFID write, BadUSB run, factory-reset are Critical.\n- **Consent gate.** High and Critical tools require operator confirmation. The CLI shows a boxed preview (frequency / modulation / hex) with a 2-second delay; positive consent (`y`, `all`, `confirm`) is rejected before the delay opens. Negative decisions (`n`, `r` for revise, Esc) bypass the delay.\n- **MCP refuses by default.** No MCP client can run High+ tools without explicit env-var opt-in (see above).\n- **Audit-log fail-closed.** If no audit log is initialised, the agent refuses High+ actions rather than running them silently.\n- **Prompt-injection quarantine.** Tool outputs (scanned SSIDs, captured packets, image content, SD filenames) are wrapped before being fed back into the model so they can't override the system prompt.\n- **No auto-deploy of generated payloads.** BadUSB scripts deploy without execution by default.\n\nRead [`SECURITY.md`](SECURITY.md) for the full threat model, scope / out-of-scope, and how to report a vulnerability.\n\n---\n\n## Compatibility\n\n| Firmware | Status |\n|---|---|\n| **Momentum** (formerly Xtreme) | Primary target |\n| **Unleashed** | Supported |\n| **RogueMaster** | Supported |\n| **Official (OFW) 1.x** | Supported with reduced feature set — region-locked Sub-GHz, no rolling code |\n\n\u003e [!NOTE]\n\u003e 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.\n\nESP32 Marauder devboard requires firmware **v1.11.1+** over USB CDC ACM (`/dev/ttyACM1` for the official Flipper WiFi devboard, baud 115200).\n\nFor BLE wireless (no cable, all tools work, ~10× slower than USB) and per-platform pairing: see [Transports reference](docs/reference/transports.md).\n\n---\n\n## Documentation\n\n- [`docs/`](docs/) — handbook with task-oriented scenarios, prompt patterns, and reproducible transcripts.\n- [`docs/reference/tools.md`](docs/reference/tools.md) — every tool's schema, risk level, and the prompts that fire it reliably.\n- [`docs/reference/transports.md`](docs/reference/transports.md) — serial, BLE, WSL2 setup.\n- [`docs/reference/configuration.md`](docs/reference/configuration.md) — config file, env vars, personas, rules, self-upgrade.\n- [`SECURITY.md`](SECURITY.md) — threat model and disclosure policy.\n- [`examples/`](examples/) — copy-paste templates: config, rules, four operator personas (red team / blue team / CTF / hardware lab).\n- [`CHANGELOG.md`](CHANGELOG.md) — what's in each release.\n\n---\n\n## Build \u0026 contribute\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md). Short version:\n\n```bash\ngit clone https://github.com/xunholy/promptzero.git\ncd promptzero\ntask dev:setup\ntask build\ntask test\n```\n\n---\n\n## License\n\n[AGPL-3.0-or-later](LICENSE). Hosting a modified PromptZero as a network service requires publishing source changes under the same license.\n\n---\n\n\u003csub\u003eBuilt with [Claude](https://claude.ai) by [xunholy](https://github.com/xunholy).\u003c/sub\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxunholy%2Fpromptzero","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxunholy%2Fpromptzero","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxunholy%2Fpromptzero/lists"}