Bad_Usb_Forge (Flipper Zero HID Auto Tool)

The Flipper Zero BadUSB payload pipeline: classify, fill in every script's placeholders in one pass, and build a ready-to-flash folder you can copy straight onto your Flipper Zero's SD card — one command, any source folder, local-first with optional AI

Overview

Bad_Usb_Forge is a Flipper Zero BadUSB payload pipeline for security professionals, researchers, and enthusiasts. Its core job: take a messy folder of BadUSB/Ducky Script payloads — your own, or pulled from any of the ~90 community source repos it already knows about — classify every script by theme, then fill in all of them in a single pass (Discord webhook, attacker IP, Telegram token, and other placeholders each payload needs before it'll actually run), and build a clean, ready-to-flash output folder you copy-paste directly onto the Flipper Zero's SD card. No manual per-script editing, no juggling a dozen half-configured BadUSB payloads by hand.

Key Use Cases

• 🔍 BadUSB Payload Classification — automatically categorize and organize BadUSB scripts into 24 topic-based folders
• 🤖 AI-Powered Analysis — optional Ollama integration for classification and placeholder detection; the tool works fully offline without it
• 🧩 Semi-Interactive Enrichment — detects scripts that need a webhook/IP/token and walks you through filling them in (including a from-scratch Discord webhook setup guide)
• 📊 Batch Processing — classify and enrich hundreds of payloads in one pass
• 🔄 Cross-Platform — one-line automated install for macOS, Linux, and Windows, plus standalone executables that need no Python at all

Quick Start

Automated Install (macOS / Linux / Unix)

curl -fsSL https://raw.githubusercontent.com/TFD-42/Bad_Usb_Forge/main/scripts/install.sh | bash

Automated Install (Windows, PowerShell)

irm https://raw.githubusercontent.com/TFD-42/Bad_Usb_Forge/main/scripts/install.ps1 | iex

Both scripts detect your OS, verify Python 3.8+, create an isolated venv under ~/.auto-flipper-tools (%USERPROFILE%\.auto-flipper-tools on Windows), install the package, and add badusb-pipeline (+ the other CLIs) to your PATH. Nothing is installed with sudo/admin rights.

Standalone Executables (no Python required)

Download the executable for your OS from the latest release: badusb-pipeline-linux, badusb-pipeline-macos, or badusb-pipeline-windows.exe.

Manual Install (from source)

git clone https://github.com/TFD-42/Bad_Usb_Forge.git
cd Bad_Usb_Forge
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Dependencies

• Python 3.8+
• Ollama (optional — only used as a fallback for classification/placeholder-detection when keyword matching doesn't find an answer; --no-ollama runs the whole pipeline with zero network calls)

Basic Usage

# One-shot: classify + enrich any folder of BadUSB scripts
python3 badusb_pipeline.py ./payloads

# Or step by step:
python Bad_USB_Classifier/classify_badusb.py ./payloads --no-ollama
python Bad_USB_Classifier/payload_setup_agent.py ./payloads_organized

# Refresh the bundled source corpus (git clone/pull from url.txt)
python Bad_USB_Classifier/classify_badusb.py --urls Bad_USB_Classifier/url.txt

# Find new sources not yet in url.txt (dry-run by default)
python Bad_USB_Classifier/discover_repos.py

Core Components

badusb_pipeline.py — Unified Entry Point

Point any folder of BadUSB scripts (.txt/.duck/.ds, loose or nested, any structure) at this script and it will classify them by theme and enrich the ones that need a value before you copy the result onto your Flipper Zero's SD card. Chains the two tools below into one clean output folder — no manual two-step process required.

Bad_USB_Classifier/

• classify_badusb.py — recursive, dedup-aware, two-pass classifier. Pattern-based Ducky Script validation, keyword topic matching, optional Ollama fallback (24 categories), automatic collision handling, comprehensive logging.
• payload_setup_agent.py — semi-interactive enrichment agent: regex-detects placeholders (Discord webhook, Telegram bot/chat id, attacker IP/port, email, [bracket] placeholders), guides you through creating a Discord webhook from scratch if you don't have one, validates the URL format, and writes the configured scripts back.
• discover_repos.py — searches GitHub's search API and Reddit's public JSON search for new BadUSB payload source repos not yet in url.txt; never clones anything itself, only proposes candidates for you to review.
• ollama_agent.py — shared tool-calling wrapper for the two agents above; every AI suggestion is verified against the actual file content before being trusted, never blindly applied.

📖 Full Documentation

gui/ — 3-Column Desktop GUI

A local web-based interface for the whole pipeline — no terminal needed once installed. Three columns: Source (drag & drop a folder, browse for one, or clone a repo by URL) → Classified (one click to classify) → Ready to flash (detects placeholders, shows a form per field — with the Discord webhook guide inline — and writes the enriched, ready-to-copy scripts).

pip install -e ".[gui]"
badusb-gui

Opens automatically at http://127.0.0.1:5115. Runs entirely on localhost — nothing leaves your machine except what you explicitly trigger (a git clone, the discover step, or Ollama).

Architecture & Roadmap

Current Tools

• ✅ BadUSB Classifier — Ducky Script analysis and categorization
• ✅ Payload Setup Agent — semi-interactive enrichment before flashing
• ✅ Repo Discovery — GitHub/Reddit search for new payload sources
• ✅ Unified pipeline (badusb_pipeline.py) + automated cross-platform installers + standalone executables
• ✅ 3-column desktop GUI (gui/) — drag & drop / clone → classify → enrich, no terminal required

Planned Tools

• 🔜 Auto-Build System — pre-build and validation for scripts before classification
• 🔜 App Fuzzer Automation — automated app fuzzing payload generation
• 🔜 Script Validator — enhanced validation across multiple script types
• 🔜 API Integrations — Flipper Zero device API automation

Directory Structure

Bad_Usb_Forge/
├── badusb_pipeline.py          # unified entry point: classify + enrich
├── pyproject.toml              # pip-installable package (console_scripts)
├── Bad_USB_Classifier/
│   ├── classify_badusb.py      # classification (keyword + optional Ollama)
│   ├── payload_setup_agent.py  # enrichment (webhooks, IPs, tokens...)
│   ├── discover_repos.py       # find new source repos (GitHub/Reddit)
│   ├── ollama_agent.py         # shared Ollama tool-calling wrapper
│   ├── requirements.txt
│   ├── url.txt                 # ~90 known community source repos
│   └── README.md
├── scripts/
│   ├── install.sh               # automated installer: macOS/Linux/Unix
│   └── install.ps1              # automated installer: Windows
├── gui/
│   ├── app.py                   # Flask backend (badusb-gui entry point)
│   ├── templates/index.html     # 3-column UI
│   └── static/                  # app.js + style.css
├── tests/                       # pytest unit tests
├── docs/
│   ├── INSTALLATION.md
│   ├── USAGE.md
│   └── ARCHITECTURE.md
├── .github/
│   └── workflows/
│       ├── tests.yml            # pytest + lint + type-check, 3-OS matrix
│       ├── security-scan.yml    # secret scan, bandit, CodeQL, dependency check
│       └── release.yml          # sdist/wheel + per-OS executables → GitHub Release
├── .gitignore
├── README.md
├── LICENSE
└── requirements.txt

Security & Privacy

Security Features

• ✅ Secret Scanning — GitHub advanced security scanning + TruffleHog in CI
• ✅ Static Analysis — bandit + CodeQL run on every push
• ✅ Input Validation — placeholder detection never blindly trusts AI suggestions; every value is re-verified against the actual file content before use
• ✅ No Telemetry — nothing phones home; the only outbound calls are the ones you explicitly trigger (--urls, discover_repos.py, or Ollama)
• ✅ Error Handling — errors are caught per-file so one malformed script doesn't abort a batch run

Security Scanning

This repository uses GitHub's built-in security features plus a dedicated CI workflow:

• Secret scanning (GitHub + TruffleHog) to prevent credential leaks
• CodeQL analysis for code quality
• Bandit static analysis and safety/dependency vulnerability checks
• Dependabot for dependency vulnerability scanning

Responsible Disclosure

If you discover a security vulnerability, please email security concerns privately rather than opening a public issue — see SECURITY.md.

Contributing

Contributions are welcome and encouraged! Whether you're fixing bugs, adding features, improving documentation, or enhancing security — all help is appreciated. See CONTRIBUTING.md for the full guide, including the ethical obligations specific to BadUSB payload contributions.

Development Setup

git clone https://github.com/TFD-42/Bad_Usb_Forge.git
cd Bad_Usb_Forge
python -m venv venv
source venv/bin/activate

# Installs the package + all dev tools (pytest, black, isort, flake8, mypy, bandit)
pip install -e ".[dev]"

pytest                                  # run tests
black . && isort .                      # format
flake8 Bad_USB_Classifier/ --select=E9,F63,F7,F82   # critical lint
mypy Bad_USB_Classifier/ --ignore-missing-imports    # type-check

Performance

Measured on this repo's own test run (Apple Silicon Mac, --no-ollama keyword-only mode, a real 959-file corpus cloned from 4 community source repos in url.txt):

Metric	Result
Files processed (classify + enrich)	959 files in 1.83s (~524 files/sec)
Ducky scripts identified	369 (340 ready-to-use, 29 needing a value filled in)

With Ollama enabled as a fallback for files keyword-matching can't classify, throughput drops to roughly one Ollama call's latency per unmatched file (model- and hardware-dependent) — --no-ollama is the fast path when you just need bulk keyword-based sorting.

References & Attribution

Origins & Inspiration

This toolkit builds upon and references:

• Flipper Zero — multi-tool platform for security professionals
• BadUSB Research — original BadUSB concept and research
• Ducky Script — official USB Rubber Ducky documentation
• Hak5 USB Rubber Ducky — original Ducky Script implementation
• Flipper Zero Community — BadUSB payload research and development

No evidence of this codebase being forked from or reusing another project's source code was found (checked git remotes, commit history, and license headers) — the classifier/enrichment/discovery tools here are original implementations.

Related Projects

• Flipper Zero Firmware
• USB Rubber Ducky Payload Repository
• Flipper Zero Bad USB Database

FAQ

Q: Do I need Ollama for this tool? A: No. --no-ollama runs the full classify + enrich pipeline with pattern/keyword matching alone and zero network calls. Ollama is an optional fallback for files keyword matching can't confidently classify.

Q: Is this tool legal to use? A: Yes, but only for authorized security testing and research. Always obtain proper authorization before using any payload against a system you don't own or don't have explicit permission to test.

Q: What script formats are supported? A: Ducky Script (.txt, .duck, .ds).

Q: Can I use this commercially? A: Yes, under the MIT license. Please include license attribution.

Troubleshooting

Ollama Not Found

Error: Ollama not found - ensure it's installed and in PATH

Solution: Install Ollama from https://ollama.ai, or just add --no-ollama to skip AI entirely.

Timeout During Classification

Error: Ollama request timed out

Solution: This only affects the optional Ollama fallback path — re-run with --no-ollama for the deterministic keyword-only path, or increase OLLAMA_TIMEOUT_FAST/OLLAMA_TIMEOUT_DEEP in classify_badusb.py.

Permission Denied

Error: Cannot read file or Cannot move file

Solution: Check file permissions; ensure write access to the output directory.

Roadmap

• Additional classification models
• Support for additional script formats
• Community payload database
• Custom rule engine

License

This project is licensed under the MIT License — see the LICENSE file for details.

Source Repositories & Credits

This project classifies and organizes BadUSB payloads sourced from the community repositories below (79 repos, kept in sync with Bad_USB_Classifier/url.txt — the authoritative list, regenerate this section with python3 scripts/generate_credits_badges.py). This project does not claim authorship of any third-party payload it classifies; full credit and copyright remain with each original author. Star counts are live (shields.io dynamic badges), not hardcoded.

BadUSB Payload Collections

• I-Am-Jakoby/Flipper-Zero-BadUSB
• aleff-github/my-flipper-shits
• FalsePhilosopher/badusb
• Kavitate/FlipperZeroBadUSB
• SeenKid/flipper-zero-bad-usb
• RamtinHaf/Flipper-Zero-Bad-USB
• grugnoymeme/flipperzero-badUSB
• DoobTheGoober/BADUSB
• anste5/BADUSBrepo
• anste5/BadUSB-badkb
• hooker01/FlipperZero-Payloads
• dagnazty/Flipper_Zero_Bad_USB
• r3dsh3rl0ck/Flipper-Zero-Bad-USB-Payloads
• ClumsyLulz/Flipper_Zero_Badusb_hack5_payloads
• narstybits/MacOS-DuckyScripts
• zer0dayf/Ghost-Audit
• Offensive-Wireless/Flipper-Zero

Flipper Zero Tools & Utilities

• Zarcolio/flipperzero
• descambiado/flipper-purple-team
• D4rkDr4gon/flipper-zero-Utils
• Angrido/Flipper-WiFi-Grabber
• gam3r999/Flipper-Zero-Android
• gam3r999/Flipper-Zero-iOS
• heeeyflo/flipperzero-pin-bypass

Awesome Lists & Curated Collections

• djsime1/awesome-flipperzero
• anasancho/awesome-flipperzero
• RogueMaster/awesome-flipperzero-withModules

Asset Databases (IR, Sub-GHz, NFC)

• UberGuidoZ/Flipper
• UberGuidoZ/Flipper-IRDB
• Zero-Sploit/FlipperZero-Subghz-DB

Plugin Collections

• xMasterX/all-the-plugins
• xMasterX/flipperzero-good-faps

Individual Apps

• honeer/flipper-base
• SYOP200/Flipper-Zero-Downloads
• i12bp8/TagTinker
• Clawzman/Flipper_ListEM
• jblanked/FlipLibrary
• x0452950/flipper-nfc-toolkit
• TFD-42/Mhz_Localiser

Flipper Zero BadUSB / BadKB (new)

• SHUR1K-N/Flipper-Zero-BadKB-Files
• Mr-Proxy-source/BadUSB-Payloads
• bst04/payloads_flipperZero
• desktopsetup/BadOS
• desktopsetup/BadDroid
• evilvodun/wifi_passwords
• TBJr/Flipper-payloads
• AgeOfMarcus/flipper_badkb_payloads
• MrzpUnkn/FlipperUsbExfil
• cgarey2014/BadUSB-Scripts
• graydav1/badkb-scripts
• avltree9798/macos_badkb_scripts
• emrahustundag/ghost-audit-mac

Hak5 Official Payload Repos

• hak5/usbrubberducky-payloads
• hak5/bashbunny-payloads
• hak5/keycroc-payloads

DuckyScript Payload Collections

• UndedInside/DuckyScriptPayloads
• h1dd3n3y3/BadUSB
• OMG-Tech/DuckyScript-Payloads
• cvbenur/ducky-scripts-and-payloads
• 547y4m/Payloads-for-USB-Rubber-Ducky
• dsymbol/ducky-payloads
• kawaiipantsu/duckyscript-payloads
• xloudo/custom-rubberducky-payloads
• crashwire1/Rubber-Ducky-Payloads

BadUSB Hardware Platforms & Tools

• SpacehuhnTech/WiFiDuck
• dbisu/pico-ducky
• CedArctic/DigiSpark-Scripts
• MTK911/Attiny85
• mayankmetha/Rucky

BadUSB Attack-Specific Repos

• AleksaMCode/WiFi-password-stealer
• alexfrancow/badusb_botnet
• 0cool-design/BadUSB
• p0lymatic/InfestUSB
• tenable/router_badusb

Generators, Converters & Defence

• InfoSecREDD/REPG
• InfoSecREDD/REPG-Community-Payloads
• Dukweeno/Duckuino
• htr-tech/ducky
• cecio/USBvalve

Want to add your repo? Fork this project, add your URL to Bad_USB_Classifier/url.txt, and open a Pull Request!

Disclaimer

This toolkit is intended for authorized security testing, research, and educational purposes only. Users are responsible for legal compliance and obtaining proper authorization before testing security systems.

---

Made with tools for security professionals by the community

If you find this useful, please star the repository!