pwnagotchibeacon

A Pwnagotchi plugin to run beacon attacks automatically!

pwnagotchi-beacon

Safe-by-default Pwnagotchi plugin + companion wordlist generator Simulate — or (with explicit opt-in) run — SSID beacon broadcasts from your Pwnagotchi. Designed for UI testing, demonstrations, and controlled lab experiments. Real broadcasting is disabled by default.

⚠️ Strong safety & legal note: Transmitting Wi-Fi beacon frames (especially beacon floods or impersonation) can interfere with networks and violate local laws. This project defaults to simulation (simulate: true) and requires explicit configuration to enable real transmissions. Only use real broadcasting on hardware you own and in locations where you have permission.

---

Table of contents

• What it does

• Use cases

• Safety & legal

• Repository layout

• Requirements

• Quick install

• Configuration (example)

• Usage

  • Generate wordlists (SSH)
  • Simulation mode
  • Enabling real broadcasting (lab-only)

• Examples & optional lab scripts

• Implementation notes

• Troubleshooting

• Contributing

• Changelog / versioning

• Authors / credits

---

What it does

• Provides a Pwnagotchi plugin (beacon.py) that:

  • Reads a plaintext SSID list (default: /root/.pwnagotchi/beacons.txt).

  • Displays on the Pwnagotchi UI:

    • Beacons: N — number loaded.
    • Beacons: <ssidname> — rotates through SSIDs at configurable rate.

  • Runs a background worker:

    • Simulation mode (default) — no radio activity; safe for demos and development.
    • Real broadcast mode (opt-in) — spawns external broadcaster processes using a configurable command template (you supply and enable the external tool).

  • Auto-reloads the wordlist when it changes.

• Companion beacon_wordlist_gen.py script:

  • Generate SSID lists by pattern, prefix, or random strings.
  • Designed to be run over SSH on the Pi to update the wordlist quickly.

---

Use cases

• UI development and demonstration without touching the radio.
• Generating large SSID lists for controlled lab testing.
• Rapidly testing how Pwnagotchi screens display rotating SSIDs and counts.
• Research & education on beacon behavior in authorised testbeds (always with explicit permission).

---

Safety & legal

• Default: simulation (simulate: true) — plugin will never transmit.
• If you enable simulate: false and add a broadcast_command_template, you accept responsibility for legal compliance.
• Do not use real broadcasting in public spaces or on hardware/networks you do not own or have permission to test.
• Consider using a Faraday cage / shielded environment or an RF test range for experiments.

---

Repository layout

pwnagotchi-beacon/
├─ beacon.py                     # Pwnagotchi plugin (drop into plugins/ folder)
├─ beacon_wordlist_gen.py        # SSH-friendly wordlist generator
├─ README.md                     # this file
├─ examples/
│  ├─ airbase_wrapper.sh         # example wrapper for airbase-ng (safe-by-default, no continuous flood)
│  └─ scapy_lab_beacon.py        # OPTIONAL: lab-only scapy example (not included by default)
└─ docs/
   └─ notes.md                   # implementation notes & tips

---

Requirements

• Pwnagotchi already installed and working.
• Python 3 on the Pi (python3).
• (Optional for real broadcasting) External tools such as airbase-ng, mdk3/mdk4, or a packet-injection-capable driver + scapy. These are not installed by this plugin.
• Appropriate privileges (root) to run external broadcasting tools (only when you enable them).

---

Quick install

1. Copy the plugin and generator to your Pi:

   # on your dev machine:
   scp beacon.py root@pwnagotchi:/usr/local/lib/python3.x/dist-packages/pwnagotchi/plugins/beacon.py
   scp beacon_wordlist_gen.py root@pwnagotchi:~/beacon_wordlist_gen.py

2. Ensure the generator is executable:

   ssh root@pwnagotchi 'chmod +x ~/beacon_wordlist_gen.py'

3. Enable plugin in your Pwnagotchi config.yml (see below).

4. Restart Pwnagotchi service (or reboot the device).

---

Configuration (example)

Add the plugin configuration under main.plugins in your config.yml:

main:
  plugins:
    beacon:
      enabled: true
      wordlist_path: /root/.pwnagotchi/beacons.txt
      simulate: true               # default true -> no radio activity
      update_interval: 1.0         # seconds between rotating SSIDs on the display
      reload_interval: 30.0        # seconds to check for changes in wordlist
      broadcast_command_template: ""   # set only if enabling real broadcasting
      iface_for_broadcast: wlan0mon
      batch_size: 50               # if using batch spawning for external tools

• wordlist_path — path to the SSID file (one SSID per line).

• simulate — set false only if you understand and enable real broadcasting.

• broadcast_command_template — a shell command template; use {ssid}, {iface}, and {bssid} placeholders. Example (only if you know what you're doing):

  broadcast_command_template: 'airbase-ng --essid "{ssid}" {iface}'

---

Usage

Generate wordlists (SSH)

Run the companion generator on the Pi to produce/update an SSID list:

# basic: produce 300 SSIDs "Cafe-0" .. "Cafe-299"
python3 ~/beacon_wordlist_gen.py --out /root/.pwnagotchi/beacons.txt --prefix "Cafe-" --count 300

# pattern example: Store-0 .. Store-199
python3 ~/beacon_wordlist_gen.py --out /root/.pwnagotchi/beacons.txt --pattern "Store-{n}" --count 200

# random SSIDs (150 items, 10 chars)
python3 ~/beacon_wordlist_gen.py --out /root/.pwnagotchi/beacons.txt --random 150 --length 10

# from file (one word per line)
python3 ~/beacon_wordlist_gen.py --out /root/.pwnagotchi/beacons.txt --from-file ./customlist.txt

The plugin watches the file and will auto-reload the SSID list within reload_interval seconds.

Simulation mode (default)

• No radio activity.

• Use this for development, demos, and UI verification.

• On the Pwnagotchi screen you should see:

  • Beacons: N (count)
  • Beacons: <ssidname> rotating

Enabling real broadcasting (lab-only)

If you explicitly want to broadcast, you must:

1. Set simulate: false.
2. Provide a safe broadcast_command_template.
3. Ensure the external tool (e.g., airbase-ng) works from the shell and that your interface is correctly configured (monitor/managed mode as required).
4. Test with a single SSID first, on a controlled test range.

Example config.yml snippet to enable airbase-ng (example only; tailor to your environment):

main:
  plugins:
    beacon:
      enabled: true
      simulate: false
      wordlist_path: /root/.pwnagotchi/beacons.txt
      broadcast_command_template: 'airbase-ng --essid "{ssid}" {iface}'
      iface_for_broadcast: wlan0mon
      batch_size: 20

Important: The plugin spawns processes based on your template. If your template launches one process per SSID you might overwhelm the device. Prefer wrapper scripts that accept many SSIDs in a single process when possible.

---

Examples & optional lab scripts

• examples/airbase_wrapper.sh — an example wrapper that accepts a list of SSIDs and runs airbase-ng more efficiently. Use carefully and test on one SSID first.

• examples/scapy_lab_beacon.py — a lab-only scapy example would:

  • include explicit consent checks (--i-know-what-im-doing),
  • require --duration and --max-ssids flags, and
  • abort unless run in a controlled environment.

---

Implementation notes

• Wordlist reload: plugin checks file mtime to reload only when changed.

• Deduplication: duplicates are removed; order preserved where possible.

• UI: plugin sets beacon_count and beacon_line for Pwnagotchi UI to display.

• Broadcasting architecture: plugin has two modes:

  • simulate — no processes spawned.
  • real — spawns broadcaster processes using your broadcast_command_template. The default implementation is intentionally simple; you can replace _broadcaster_worker with a custom batching wrapper to reduce process count and resource usage.

---

Troubleshooting

• Wordlist not loading

  • Verify path and permissions.
  • Force reload by touching the file: touch /root/.pwnagotchi/beacons.txt.

• UI not updating

  • Confirm plugin is enabled in config.yml and no syntax errors.
  • Check Pwnagotchi logs (/var/log/pwnagotchi.log or your system's logs).

• External broadcasting not working

  • Test your broadcast_command_template manually on the Pi shell.
  • Verify the wireless interface is in the required mode (monitor vs managed).
  • Confirm required external tool is installed and runnable as the same user that runs Pwnagotchi.

• High CPU / too many processes

  • Lower batch_size.
  • Use a single-process wrapper script that accepts a list of SSIDs from a temporary file or stdin.

---

Contributing

• Fork the repo, make changes in a branch, open a PR.

• Prefer small focused changes:

  • UI improvements
  • safer broadcaster wrappers
  • more efficient batching / wrappers
  • unit tests for generator logic

• Keep the plugin safe-by-default. Add explicit safety checks for any code that touches the radio.

---

Changelog & versioning

Keep a CHANGELOG.md in the repo with semantic versioning (e.g., v0.1.0 initial release). Example entries:

• v0.1.0 — initial release: plugin + wordlist generator, simulation mode, UI rotation.
• v0.2.0 — added broadcast_command_template, batching, and basic process management.

---

Authors / credits

• Project: pwnagotchi-beacon
• Original design & scaffolding: Jibril Richardson (idea)
• Suggested tools & examples: aircrack-ng (airbase-ng), mdk3/mdk4, scapy (lab-only).

---