BadKB Payload Generator

Modular Python tool for generating Flipper Zero BadUSB / BadKB DuckyScript files from structured JSON payload definitions and text templates. Built for research, homelab experimentation, and payload development workflows.

Installation

Prerequisites

• Python 3.11+
• pip

From source

pip install -e .

With TUI support:

pip install -e ".[tui]"

With dev/test dependencies:

pip install -e ".[dev]"

Without install (run directly)

pip install -r payload_gen/requirements.txt
pip install textual   # optional, for TUI
python -m payload_gen --help

Usage

python -m payload_gen <command> [options]

List payloads

python -m payload_gen list                 # all payloads
python -m payload_gen list --os windows    # filter by OS
python -m payload_gen list --tactic Execution

Inspect a payload

python -m payload_gen info win_ps_reverse_shell

Generate a payload

# dry-run preview (no file written)
python -m payload_gen generate win_ps_reverse_shell --profile homelab --dry-run

# write to output/
python -m payload_gen generate win_ps_reverse_shell --profile homelab

# override parameters
python -m payload_gen generate win_ps_reverse_shell \
    --profile homelab \
    --param ATTACKER_IP=10.0.0.50 \
    --param ATTACKER_PORT=9001

# generate all payloads for an OS
python -m payload_gen generate --os windows --profile homelab

Validate all definitions

python -m payload_gen validate

Batch generation

Create a recipe JSON file, then:

python -m payload_gen batch my_recipe.json

Export catalog

python -m payload_gen catalog --format markdown
python -m payload_gen catalog --format csv
python -m payload_gen catalog --format json

Scaffold a new payload

python -m payload_gen scaffold --os windows --tactic Persistence --name my_new_payload

Interactive TUI

python -m payload_gen --tui
# or
python -m payload_gen tui

TUI controls:

Key	Action
Arrow keys	Navigate payload tree
Enter	Select payload
Ctrl+G	Generate
Ctrl+D	Dry run
Ctrl+B	Batch select
Ctrl+S	Search
Ctrl+P	Cycle profile
F5	Refresh preview
Q	Quit

Profiles

Profiles store reusable parameter values (IPs, ports, timing, device identity). Two included:

• default.json - minimal defaults
• homelab.json - example homelab config

Profiles live in profiles/ and support inheritance and environment variable interpolation ($ENV_VAR).

Project Layout

payload_gen/
├── payload_gen.py          # entry point
├── cli.py                  # Click CLI (7 commands)
├── tui.py                  # Textual TUI
├── tui.tcss                # TUI theme
├── core/
│   ├── models.py           # Pydantic data models
│   ├── validator.py        # 15-type parameter validator
│   ├── registry.py         # auto-discovery payload registry
│   ├── generator.py        # 13-step rendering pipeline
│   ├── profile.py          # profile manager with inheritance
│   ├── catalog.py          # catalog exporter
│   └── scaffold.py         # new payload scaffolding
├── payloads/               # JSON payload definitions (80)
│   ├── windows/            # 75 payloads across 10 MITRE tactics
│   ├── linux/
│   ├── macos/
│   └── cross_platform/
├── templates/              # DuckyScript templates
├── profiles/               # reusable parameter profiles
├── tests/                  # pytest suite
├── pyproject.toml
├── requirements.txt
├── README.md
├── SECURITY.md
└── LICENSE

Dependencies

Package	Purpose
pydantic ≥ 2.0	data models & validation
click ≥ 8.0	CLI framework
rich ≥ 13.0	terminal formatting
rich-click ≥ 1.7	rich-formatted CLI help
jsonschema ≥ 4.0	JSON schema validation
textual ≥ 0.50	TUI (optional)
pytest ≥ 8.0	tests (dev)
pytest-cov	coverage (dev)

Running Tests

python -m pytest payload_gen/tests/ -v
python -m pytest payload_gen/tests/ --cov=payload_gen --cov-report=term-missing

License

Apache License 2.0. See LICENSE.

Safety Notice

This is a demo/showcase project for authorized testing and education only. Review all generated output before use. Use only in environments where you have explicit authorization.