ESP32 Marauder Firmware Volume 7 — Fork Landscape Deep Dive — ESP32 Marauder · Hacking

Mainline vs Ghost ESP vs Bruce vs Bad Pinguino — feature deltas, decision tree, migration mechanics

Section	Topic
1	About this volume
2	Decision tree — which fork right now?
3	Marauder mainline (Koko) — the canon
· 3.1	Feature catalogue at v1.12.x
· 3.2	What’s deliberately not in mainline
· 3.3	Build cadence and PR policy
4	Ghost ESP (Spooks4576) — the feature-rich superset
· 4.1	What Ghost ESP adds over mainline
· 4.2	What Ghost ESP drops or de-prioritizes
· 4.3	Build target list and stability posture
5	Bruce (pr3y) — the multi-modal meta-firmware
· 5.1	The multi-modal positioning
· 5.2	What Bruce adds (beyond Marauder)
· 5.3	When Bruce is the right answer
6	Bad Pinguino and narrower forks
7	Side-by-side feature comparison
8	Migrating between forks
· 8.1	What survives the migration
· 8.2	What doesn’t
· 8.3	Migration mechanics (web flasher path)
· 8.4	Migration mechanics (source-build path)
· 8.5	Recovery from mis-flash
9	Detection considerations across forks
10	Resources

1. About this volume

Vol 7 is the fork landscape. Vol 1 § 4 teased it; this volume goes feature-by-feature, build-flag-by-build-flag, with a clear migration path for when switching is the right call.

The four forks covered:

Marauder mainline (Koko) — the canon. The starting point.
Ghost ESP (Spooks4576) — the feature-rich superset. Adds BLE-spam, more attack variants, richer visualization.
Bruce (pr3y) — the multi-modal meta-firmware. Marauder + sub-GHz + IR + RFID + BadUSB unified.
Bad Pinguino and other narrower forks — minor entries.

The four are not strictly equivalent — Ghost ESP and Bruce ship features mainline doesn’t, but they also lag mainline on some board support and stability. The decision is not “which is best” but “which fits the current job.”

For tjscientist’s lineup, the operational implication is concrete: the AWOK Dual Touch V3 runs Marauder mainline today. Switching to Ghost ESP is a flash-the-binary operation that takes ~5 minutes including SD-card content migration; switching to Bruce is similar but with more re-learning on the UI side. The migration mechanics (§ 8) cover both.

2. Decision tree — which fork right now?

                    Need a Wi-Fi/BLE attack feature?
                              │
            ┌─────────────────┴─────────────────┐
            │                                   │
       Wi-Fi-only?                          Multi-modal hardware
       (deauth, beacon                      (Cardputer ADV, T-Embed
        spam, Evil Portal,                   with sub-GHz, etc.)?
        EAPOL/PMKID
        capture)                                  │
            │                                     ↓
            ↓                              **Bruce** — exposes all modes
       Mainline ✓ — start here              from one boot. Worth the
       (canon, most stable,                 multi-modal UX learning curve.
       widest hardware support)
            │
            ↓
       Need BLE-spam?
       (Sour Apple,
        Swiftpair, etc.)
            │
       ┌────┴────┐
       │         │
       No        Yes
        │         │
        ↓         ↓
   Stay on    **Ghost ESP** — Marauder superset
   mainline.  with BLE-spam, AirTag detect,
              richer visualizations. Trade-off:
              less hardware support, sometimes
              flakier.
            │
       Need an unusual feature
       mainline+Ghost+Bruce
       don't have?
            │
            ↓
       Niche fork or
       authored-locally fork.
       (Vol 10 § 6)

The first split is the most consequential: Wi-Fi+BLE only → mainline or Ghost ESP; multi-modal hardware → Bruce. The second split (BLE-spam needed?) is the most common reason to leave mainline.

3. Marauder mainline (Koko) — the canon

3.1 Feature catalogue at v1.12.x

The mainline feature catalog at the current tag:

Wi-Fi scanning:

Probe-request sniffer (Vol 4 § 3)
Beacon sniffer / AP-list (Vol 4 § 4)
PMKID capture (Vol 4 § 5)
EAPOL 4-way handshake capture (Vol 4 § 6)
AP + client mapping (Vol 4 § 7)
Channel hop / static (Vol 4 § 8)

Wi-Fi attack:

Deauth (Vol 5 § 2) — gated by MARAUDER_DEAUTH build flag
Beacon spam (Vol 5 § 3)
Probe spam (Vol 5 § 4.1)
Karma probe-response (Vol 5 § 4.2)
Evil Portal (Vol 5 § 5)

Bluetooth:

BLE advertising scan (Vol 6 § 4)
BT-classic Inquiry (on classic-ESP32 hosts only — Vol 6 § 7)
(No BLE-spam — see § 3.2)
(No AirTag detection — see § 3.2)

Utility:

AP list save/load to SD
Settings menu with persistent config
GPS integration on HAS_GPS builds (filename-prefix geotagging)
Battery percent UI
Color-theme selection

Hardware support:

~15 documented PlatformIO environments (Vol 3 § 4.2)
ESP32-classic, ESP32-S3, ESP32-S2 targets
TFT (ST7789, ILI9341) and OLED (SSD1306) display paths

3.2 What’s deliberately not in mainline

Notable omissions, with the why:

BLE-spam variants (Sour Apple, Swiftpair, Easysetup, Fast Pair) — Koko’s stated rationale per Vol 6 § 5.6: iOS device-lockup edge case + RF/legal posture incompatible with “useful with discipline” envelope. Available in Ghost ESP and Bruce.
AirTag detection — added value lower than BLE-spam controversy; not on the mainline roadmap. Available in Ghost ESP and Bruce.
Sub-GHz attacks — Marauder is the ESP32 Wi-Fi/BLE firmware. Sub-GHz requires CC1101 daughter hardware which Marauder mainline doesn’t drive. Bruce handles this when paired with appropriate hardware.
WPA3 SAE attack work — research-ongoing in the broader community; mainline waits for stable, well-tested implementations before integration.
Wi-Fi 6 / 6E features — ESP32-S3 silicon is Wi-Fi 4 (802.11n) — the firmware doesn’t have features it can’t physically support. Wi-Fi 6 awaits ESP32-C5 silicon (see ../AWOK ESP32 C5/).

3.3 Build cadence and PR policy

Tagged release cadence: roughly monthly for minor versions; quarterly-ish for majors. Per github.com/justcallmekoko/ESP32Marauder/releases.
Master branch policy: master runs ahead of tags; merges are conservative — usually one to two days between PR merge and tag if the change is tag-worthy.
PR acceptance: Koko reviews community PRs but the merge bar is high. Feature PRs that overlap fork-only features (BLE-spam, AirTag detect) are typically declined with the deliberate-omission rationale (§ 3.2). Bug-fix PRs and per-board-env PRs are usually accepted on functional review.

For maintainers thinking of contributing upstream: discuss in advance via Discord or an issue before authoring a feature PR — saves rework when a feature is unwanted.

4. Ghost ESP (Spooks4576) — the feature-rich superset

4.1 What Ghost ESP adds over mainline

Ghost ESP is a Marauder fork that adds material features. Forked roughly 2023; maintained at github.com/Spooks4576/Ghost_ESP. Forked from mainline at a known commit; periodically rebased to pull in mainline improvements.

Additions:

BLE-spam variants: Sour Apple, Swiftpair, Easysetup, Google Fast Pair (all covered in Vol 6 § 5). The single most-cited reason to switch.
AirTag detection (Vol 6 § 6) with the 2-second advertising-interval consistency detector.
Signal-strength bar graphs — visual RSSI rendering for AP-list and BLE-list modes; mainline shows numeric RSSI only.
Multi-SSID karma — responds to each probe request with multiple synthetic probe-responses (vs mainline’s one-per-request basic karma) to increase association probability.
Richer beacon-spam SSID lists — Ghost ESP ships more built-in lists than mainline.
Runtime country code — beacon channel-plan switchable from menu (mainline requires re-flashing with a different COUNTRY_* build flag).
Runtime beacon-rate tuning — mainline rate is fixed at compile-time.
Some additional Wi-Fi attacks — variant probe-flood patterns, custom beacon-frame crafting beyond mainline’s offerings.
Extended manufacturer-data parses — more granular Apple Continuity subtype identification (Vol 6 § 4.2 covers the labels both fork to display).

4.2 What Ghost ESP drops or de-prioritizes

The trade-offs:

Smaller documented board target list — Spooks4576 ships build environments only for boards he actively tests on. Less coverage of obscure platforms than mainline. Boards present in mainline but not Ghost ESP: typically supported by community-maintained Ghost ESP forks-of-forks.
Less battle-tested stability — newer features land before edge-case stability work. The reverse pattern from mainline. Expect periodic regressions in BLE-spam variants when iOS / Android push updates.
Documentation lag — Ghost ESP’s wiki is less comprehensive than Marauder’s. Build-flag inventory is more sparsely documented; “read the source” is more often the answer.
AGPLv3 (vs Marauder’s GPLv3) for some components — relevant for downstream commercial use; less relevant for tjscientist’s use.

4.3 Build target list and stability posture

Ghost ESP’s documented PlatformIO environments as of 2026-05-13 (the list rotates; verify against the current repo):

ESP32 v6 / v6.1 / Mini (Koko hardware — mainline ports brought over)
ESP32 Dev Board Pro (classic ESP32)
LilyGO T-Embed CC1101 (Ghost ESP’s sub-GHz integration target — when CC1101 daughter is present)
Generic ESP32 / ESP32-S3 dev boards
M5Stack hardware (some variants)
AWOK Dual Touch V3 — has a documented build env (the AWOK ecosystem ships with Ghost ESP as an alternative to mainline)

Notably not in Ghost ESP’s list but in mainline: DSTIKE Watch (OLED-display path is mainline-only). Flipper WiFi Devboard build is community-maintained, not always in sync.

Stability rating: for the most-used attacks (BLE-spam Sour Apple, AirTag detect, Wi-Fi scan/attack), Ghost ESP is solid. For minor features and niche board ports, expect occasional rough edges.

Bruce is fundamentally different from Marauder and Ghost ESP. It’s not a Marauder alternative — it’s a meta-firmware that combines Marauder-class Wi-Fi/BLE attacks with sub-GHz (CC1101 daughter), IR, RFID, BadUSB, and a top-level menu that unifies all of them.

Repo: github.com/pr3y/Bruce. License: AGPLv3. Forked roughly 2024; active development.

The use case Bruce addresses: handheld hardware that has more than just Wi-Fi/BLE — Cardputer ADV with the unified-tool positioning, T-Embed with CC1101 daughter, LilyGO T-Display-S3 with shield expansions. For such hardware, Bruce exposes every capability from one boot rather than requiring the user to switch between Marauder-for-Wi-Fi and a different firmware-for-sub-GHz.

5.2 What Bruce adds (beyond Marauder)

Sub-GHz attack catalog (when CC1101 daughter is present): replay attacks against rolling-code remotes, fuzzer, configurable TX. Targets common ISM bands.
IR transmit catalog: pre-canned codes for common TV / AC / hardware remotes. The Bruce “IR Zapper” is well-known.
RFID work: 125 kHz LF and 13.56 MHz HF read/clone (via PN532 daughter when present).
BadUSB scripting: HID payload execution over USB-OTG.
GPS workflows: Bruce integrates GPS into multiple modules (Marauder mainline uses GPS only for filename-prefix tagging).
A unified top-level menu that presents everything from one boot.

5.3 When Bruce is the right answer

Bruce is the right answer when:

The hardware is genuinely multi-modal (CC1101 + IR + Wi-Fi all wanted from one device).
The Cardputer ADV or T-Embed CC1101 is the target. The Cardputer ADV deep dive § 9 covers Bruce-specific configuration.
The user wants to learn one UI instead of switching between Marauder and dedicated sub-GHz firmware.

Bruce is not the right answer when:

The hardware is single-purpose (Marauder Mini, v6.1) — Bruce works on these but you’re paying multi-modal overhead for no benefit. Mainline is the cleaner choice.
The user wants minimal binary footprint or absolute stability.
The hardware doesn’t have sub-GHz / IR / RFID daughters — Bruce’s value proposition shrinks.

For tjscientist’s lineup, Bruce is the natural answer on the Cardputer ADV (when that purchase happens) and is the alternative to consider on the Game Over (though the Game Over’s vendor fork covers similar territory with the closed-source integration tjscientist already has).

6. Bad Pinguino and narrower forks

Bad Pinguino (github.com/bmorcelli/Bad-Pinguino) — a deliberately minimal Marauder derivative. Single-screen “do one attack well” UI. Useful as a demo or training tool where the operator wants to be sure no off-target attack can accidentally fire. Strips the menu to one attack at a time, makes it impossible to navigate to anything else without rebooting.

Niche use case: when handing a Marauder host to a non-technical user for a controlled scenario.

Other forks worth knowing exist but not authoring against:

GhostESP-S3 / GhostESP-Mini — board-specific repackagings of Ghost ESP. Treat as Ghost ESP variants; check the README for which board they target.
Evil-M5Project / Evil-S3 — M5Stick-specific. Shares some attack code with Marauder via copy-paste lineage but is not a fork. Covered in ../M5Stick S3/ when that platform is in play.
Various community forks for very specific hardware (custom boards, language localizations, niche feature additions). Most are unmaintained after the initial author’s enthusiasm wanes; check git log activity before committing to one.

7. Side-by-side feature comparison

The big table. Sourced from each fork’s current README / wiki / commit log as of 2026-05-13.

Capability	Mainline	Ghost ESP	Bruce	Bad Pinguino
Probe-req sniffer	✓	✓	✓	✓ (single mode)
Beacon sniffer	✓	✓	✓	✓
PMKID capture	✓	✓	✓	partial
EAPOL handshake capture	✓	✓	✓	✓
AP+client mapping	✓	✓ (with bar graphs)	✓	✗
Deauth	✓ (build-flag gated)	✓ (default on)	✓	✓
Beacon spam	✓	✓ (more lists, runtime rate)	✓	✓
Probe spam	✓	✓	✓	✗
Karma probe-response (basic)	✓	✓	✓	✗
Karma multi-SSID-per-client	✗	✓	✗	✗
Evil Portal	✓	✓	✓	✗
BLE scan	✓	✓ (richer parses)	✓	✗
BLE-spam Sour Apple	✗	✓	✓	✗
BLE-spam Swiftpair	✗	✓	✓	✗
BLE-spam Easysetup	✗	✓	✓	✗
BLE-spam Fast Pair	✗	✓	✓	✗
AirTag detection	✗	✓	✓	✗
BT-classic scan (classic ESP32 only)	✓	✓	✓	✗
Sub-GHz attacks (CC1101)	✗	✓ (T-Embed only)	✓ (broad CC1101 support)	✗
IR attacks	✗	partial	✓	✗
RFID work (PN532)	✗	✗	✓	✗
BadUSB	✗	✗	✓	✗
GPS in attacks	filename-tag only	filename-tag + map UI	full integration	✗
Runtime country code	✗ (build-flag)	✓	✓	✗
Runtime beacon-rate	✗	✓	✓	✗
Web flasher	✓ (maurer-hosted)	✓ (Ghost-hosted)	✓ (pr3y-hosted)	✓ (limited)
Documented board envs (count)	~15	~10	~8	~5
License	GPLv3	AGPLv3 (per file)	AGPLv3	GPLv3
Activity (commits/month average 2026)	~30	~50	~80	~5
Documentation quality	★★★★	★★	★★★	★

The bolded BLE-spam + AirTag rows are the operationally consequential mainline omissions. The bolded Bruce rows are the operationally consequential multi-modal additions.

8. Migrating between forks

8.1 What survives the migration

SD-card content is the most-shared resource:

/marauder/pcaps/ — pcap captures: portable across all four forks (standard format).
/marauder/evil_portal/ — Evil Portal HTML: portable; same data/portal/-priority order across mainline + Ghost ESP. Bruce’s path differs slightly.
/marauder/wordlists/ — wordlists: portable.
/marauder/beacons.txt — beacon-spam SSID list: portable.
/marauder/creds.txt — captured creds: portable but format is plain text and the same.

8.2 What doesn’t

/marauder/settings.txt — settings file format. Mainline and Ghost ESP share most keys; Bruce uses a different format entirely. Migrating mainline → Ghost ESP usually works without re-configuration; mainline → Bruce requires re-doing settings.
Compile-time build flags — these are bound to the binary, not the SD. Switching firmware means re-evaluating which build matches your hardware. MARAUDER_DEAUTH was on/off in mainline → Ghost ESP defaults on → migrating preserves deauth-on.
Per-board pin assignments — these vary by build env, not by fork. Mainline marauder_v6_1 and Ghost ESP marauder_v6_1 should agree, but Bruce v6_1 may have UI-related pin reassignments.
Display behavior — fonts, colors, theme. Each fork has its own visual identity. Don’t expect the menu to look identical post-migration.

8.3 Migration mechanics (web flasher path)

The simplest migration is the web flasher:

Backup SD card to a host first. (cp -r /mnt/sd /tmp/marauder_backup_pre_ghost)
Open the destination fork’s web flasher:
- Marauder mainline: https://flasher.marauder.maurersystems.com/
- Ghost ESP: hosted at https://flipperzero.one/ or https://github.com/Spooks4576/Ghost_ESP (check README for current URL)
- Bruce: https://bruce.computer/
Connect target Marauder host via USB.
In the flasher: select the board variant matching your hardware (typically the same name across forks — marauder_v6_1, t_display_s3, etc.).
Click “Flash” / “Erase + Flash”.
The flasher erases existing firmware and writes the new fork’s binary.
Reinsert SD card; reboot.
First-boot of the new fork creates any missing directories (/marauder/airtags/ for Ghost ESP, etc.). Settings reset to defaults.

Time: ~5 minutes end-to-end.

8.4 Migration mechanics (source-build path)

For non-flasher-supported boards (the AWOK Dual Touch V3 doesn’t have an official web flasher per fork — most users source-build):

Clone the destination fork repo.
Find the appropriate PlatformIO env in platformio.ini.
pio run -e <env> -t upload (covers details in Vol 10 § 3).
Same SD backup discipline as the web flasher path.

For the AWOK V3 specifically: the AWOK community ships pre-built binaries on their Discord; ask there before source-building unless you’re customizing.

8.5 Recovery from mis-flash

If the wrong firmware was flashed and the device is in an unhappy state:

Connect USB, put the ESP32 into bootloader mode (hold BOOT button during USB plug-in, or use the flasher’s “reset to bootloader” feature).
Re-flash the correct firmware via web flasher or PlatformIO.
Erase flash first if the device is genuinely confused: esptool.py erase_flash.

The ESP32-S3’s native USB-DFU is forgiving — there’s essentially no way to brick the device via firmware mis-flash. Bootloader is in mask-ROM and always available.

For classic-ESP32 hosts (DSTIKE Watch, AWOK V3), the same bootloader is also in mask-ROM but the USB path is via the UART-bridge chip (CP210x or CH340) — driver issues on the host can mask the bootloader’s availability. Most “my Marauder is bricked” stories trace to host-side driver issues, not actual device bricks.

9. Detection considerations across forks

From the perspective of a Wi-Fi IDS or BLE monitoring system, do the four forks look the same on the wire? Mostly yes, with notable deltas:

Signal	Mainline	Ghost ESP	Bruce	Detection delta
Deauth frame anatomy	Standard	Standard	Standard	Frame anatomy identical across forks; reason code = 1 default; source MAC = spoofed AP MAC
Deauth frame rate	~50/sec	~50/sec (default), runtime tunable	~50/sec	Ghost ESP’s runtime tunability means rate is the only fingerprintable difference, and it’s per-operator-choice
Beacon spam frame rate	~10-50/sec (build-flag fixed)	runtime tunable	runtime tunable	Same delta as above
Beacon spam SSID distribution	List-driven (cyclical)	List-driven (richer lists)	List-driven	All three exhibit the cyclical pattern of “new unique SSID every beacon” — distinctive vs a real AP
Evil Portal SoftAP SSID	Defaults to “ESP32 Marauder” or user-set	Same	Same	All three reveal themselves in the SSID; rename in settings
Evil Portal HTTP `Server:` header	”esp32” or “Marauder"	"Ghost ESP"	"Bruce”	Fingerprintable in HTTP logs
BLE-spam advertising rate	n/a (mainline lacks)	~10-30/sec	~10-30/sec	Ghost vs Bruce: similar rate; Sour Apple subtype rotation is similar
BLE-spam Sour Apple subtype distribution	n/a	Cycles through ~5 Apple subtypes	Cycles through ~8 Apple subtypes	Mild fingerprintable delta

Operationally, an attacker switching forks for operational stealth gets very little advantage — the on-the-wire signatures are dominated by the attack semantics, not the fork choice. Stealth in Marauder-class attacks is mostly an oxymoron (Vol 11 § 2).

10. Resources

Upstream repos

Marauder mainline: https://github.com/justcallmekoko/ESP32Marauder
Ghost ESP: https://github.com/Spooks4576/Ghost_ESP
Bruce: https://github.com/pr3y/Bruce
Bad Pinguino: https://github.com/bmorcelli/Bad-Pinguino

Web flashers

Marauder: https://flasher.marauder.maurersystems.com/
Ghost ESP: linked from https://github.com/Spooks4576/Ghost_ESP
Bruce: https://bruce.computer/

License references

GPLv3 full text: https://www.gnu.org/licenses/gpl-3.0.en.html
AGPLv3 full text: https://www.gnu.org/licenses/agpl-3.0.en.html

Community discussion

Marauder Discord (linked from Marauder README)
Ghost ESP Discord (linked from Ghost ESP README)
Bruce Discord (linked from Bruce README and bruce.computer)

Forward references in this series

SD card content compatibility (what survives migration in detail): Vol 8
Build toolchain + custom development (if you want to author your own fork): Vol 10
Operational posture / detection (the on-the-wire IDS perspective in more depth): Vol 11

This is Volume 7 of a twelve-volume series. Next: Vol 8 covers the SD card layout, Evil Portal HTML authoring conventions, the beacon-spam SSID list format, the settings.txt schema, and the migration mechanics for SD content between forks.

ESP32 Marauder Firmware Volume 7 — Fork Landscape Deep Dive

Contents