😄 BruceMod (Independent Fork)

BruceMod is a versatile, independent ESP32 firmware fork based on the original Bruce project. It focuses on stability, enhanced UI, and advanced offensive features for Red Team operations using M5Stack and Lilygo hardware.

This project is an independent community fork and is not affiliated with the original pre-built tools or commercial offerings.

Check bruce's fully open-source hardware too: https://bruce.computer/boards

🚀 Optimized Features

BruceMod includes several optimizations and UI improvements:

• Independent Menu Styling: Set different styles for the Main Menu and Submenus (e.g., PS4 style for main, C64 style for submenus).
• Enhanced File Explorer: A modern interface with icons, breadcrumbs, and live item metadata.
  • Context Menu: Use the [Opt] button (next to Ctrl) to open context menus for both files and folders.
  • Recursive Copy/Paste: Easily move entire folders and files between SD Card and LittleFS.
• USB Mass Storage with Speedometer: Real-time average speed monitoring (kB/s) updated every 20 seconds.
• Improved Performance: Pre-parsed BLE patterns and constexpr precomputations for IR/RF engines reduce CPU load.
• Dirty-Region Renderer: System-wide UI redraws only changed regions instead of full-screen blits — eliminates flicker on menus and live views.
• Categorized WiFi Menu: Organized into Connectivity, Attacks, Sniffers, Network Tools, and Config for faster access.
• Smart Battery Estimator: Builds a per-device discharge curve from observed usage and persists it to the SD card (/bruce/bat_curve.bin). Falls back to a piecewise Li-ion curve until ~30 min of history is collected, then switches to the learned curve and adapts as the cell ages. ADC samples are 8x averaged to remove jitter.
• Cross-module Clipboard: One-tap paste from any feature into MAC change, frequency change, etc.

✨ New in this fork

• BLE Scan → Attack actions: pick a device from BLE → BLE Scan, press OK and choose:
  • Connect Flood — rapid GATT connect/disconnect against the target MAC, with live OK / Fail / rate counters.
  • Directed Adv Spam — ADV_DIRECT_IND advertising aimed at the target, low-duty interval (100 ms) so any spec-compliant peer keeps parsing it.
  • L2CAP Echo Flood (PSM 0x25 / 0x80) — opens an LE L2CAP Connection-Oriented Channel and fires 80-byte SDUs, handling BLE_HS_ESTALLED credit pauses. Requires NimBLE built with MYNEWT_VAL_BLE_L2CAP_COC_MAX_NUM ≥ 1; the cardputer build sets this for you.
• BLE Anomaly Monitor (BLE → Anomaly Monitor): passive defensive scanner. Counts adv reports per MAC, flags bursts above 8/s, and tags known spam payloads (Apple 0x004C, Microsoft SwiftPair 0x0006, Samsung 0x0075, Google FastPair 0xFE2C, Samsung EasySetup 0xFD5A).
• Starter Guide (Quick → Starter Guide): on-device walkthrough of the new features, force-close gesture, menu styles, SD layout, BLE attacks, battery estimator, and Authenticator.
• Wii main menu by default: cleaner first-run feel; pair with C64 submenus (the existing default) for the classic look. Switch via Config → Interface → Main Mode / Sub Mode.
• First-run SD layout: brand-new card auto-creates /bruce/ with subfolders for ir, rf, badusb, wifi, ble, lora, nfc, captures, scripts, themes, configs, plus a README.txt explaining what goes where. Idempotent (gated by /bruce/.bruce_initialized). Firmware also boots cleanly without an SD card and falls back to LittleFS, surfacing a brief "no SD" hint instead of hanging.
• Force Close gesture: hold the side / G0 button for 4 seconds from anywhere to bail out of a stuck module and return to the main menu (look for the FORCE CLOSE banner).
• Authenticator (Others → Authenticator): RFC 6238 TOTP and FIDO U2F (ECDSA P-256) credentials in a single AES-256-CBC vault, password-protected and stored on the SD card. Add TOTP entries via Base32 secret; register / sign / list U2F credentials.
• System Status (Others → System Status): live RAM, flash, SD, battery, uptime, and radio state.
• Partition Viewer & Advance Music Player v2.
• PCAP Inspector (under WiFi sniffers): browse captured .pcap files frame-by-frame on-device.
• NRF24 Promiscuous Scan: pseudo-promiscuous channel-hopping scan with CRC disabled and a short address.
• MQTT Client (under Network Tools): publish/subscribe via PubSubClient.
• LoRa improvements ported from d4rkmen/plai: better channel UI, packet inspection, signal strength view.
• Honeypot atomicity fix, Responder NTLM bounds-check, and a wider audit pass for unsigned underflow / dead-store / NimBLE-v2 deprecation issues.

🏗️ How to install

The easiest way to install BruceMod is using bruce's official Web Flasher!

Check out: https://bruce.computer/flasher

Alternatively, flash locally using esptool.py:

esptool.py --port /dev/ttyACM0 write_flash 0x00000 Bruce-<device>.bin

📑 Wiki

For detailed information on each module, check our internal wiki:

• WiFi Guide | BLE Guide | Files & Storage | IR Engine | UI & Customization

❤️ Sources & Credits

BruceMod is built upon the incredible work of the ESP32 and security communities. We would like to credit and thank:

• bmorcelli/Bruce: The foundation of this firmware.
• AdvanceOS: Inspiration for the enhanced file explorer and UI elements.
• ESP32-Marauder: For the core WiFi and BLE attack logic.
• Evil-M5Project: For specialized BLE spam and security tools.
• Cardputer-Battery: For the battery monitoring and status logic.
• Ultimate Remote: Inspiration for the Advanced IR and protocol support.

💻 List of Features

WiFi (Categorized)

• Connectivity (Connect, AP, Wireguard)
• Attacks (Evil Portal, Bad Msg, Sleep, Responder)
• Sniffers (RAW, Probe/Karma, Packet Count)
• Network Tools (ARP Scan, Port Scan, TelNet/SSH, TCP)
• Pass Recovery & BruceModgotchi

BLE

• BLE Scan with per-device attack menu: Connect Flood, Directed Adv Spam, L2CAP Echo Flood
• BLE Anomaly Monitor (defensive — adv-rate spikes + spam-payload signatures)
• Bad BLE
• Wall of Flippers / Airtags / Skimmers (Optimized)
• iOS / Windows / Android / Samsung Spam
• Airtag Spoofing

RF & IR

• RF: Scan, Replay, Custom SubGhz, Jammer, Spectrum
• IR: TV-B-Gone, Capture, Custom .ir Files, MakeHex Engine

Others

• Enhanced File Manager (Recursive Copy/Paste, Icons)
• USB Mass Storage + Speedometer
• Audio Player (Themed) + Advance Music Player v2
• WebUI, QRCodes, iButton, LED Control
• Authenticator (TOTP + U2F, encrypted SD vault)
• System Status, Partition Viewer, Games
• PCAP Inspector, MQTT Client, NRF24 Promiscuous Scan

🚧 Disclaimer

BruceMod is a tool for cyber offensive and red team operations, distributed under the terms of the Affero General Public License (AGPL). It is intended for legal and authorized security testing purposes only. Use at your own risk.