Repository navigation
Architecture
Brucia splits a security-research multitool across two devices: a cheap ESP32 does the radio/sensor work, and a phone does the computation, storage and UI. The phone is the brain; the ESP32 is the antenna.
ESP32-S3 (Brucia firmware) Android (Brucia app)
-------------------------- --------------------
Radio / sensor FRONT-END <=USB=> Compute + storage + GUI
- capture / transmit - decode / crypto / analysis
- realtime timing - Room DB, big datasets
- raw-data framing + stream - GPS, offline maps, viz
| |
+-------- Transport (abstract) -------------+
USB-CDC | Wi-Fi | BLE (USB today)
+-- one Protocol --+
Guiding principle: whatever needs the peripherals (CC1101, Wi-Fi/BLE radio, PN532, IR) stays on the ESP; whatever is compute, memory, UI or geolocation moves to the phone. Radio transmit is never delegated.
Compatibility principle (non-negotiable): Brucia is a superset of Bruce. Every Bruce feature keeps working, and with no phone connected the device is still a full Bruce (standalone mode). Companion mode is strictly additive.
feature logic (wardrive, crack, ir, ... - never touches the wire)
+- protocol (message kinds + JSON payloads; see [[Protocol]])
+- framing (length-prefixed frames on a byte stream)
+- transport (USB-CDC today; Wi-Fi / BLE behind the same interface)
Feature logic never touches the wire; it talks to the protocol layer. The protocol layer defines message kinds and payloads; framing turns messages into length-prefixed frames on a byte stream; the transport is just a byte pipe.
-
companionModeUSB()takes exclusive ownership of the USB-CDC serial, shows a themed status screen, and runs the message loop. -
HELLO -> CAPS: reports board, chip, firmware, transports and a real
per-peripheral
caps{}capability object (see below). -
CMD: a set of companion-specific commands is intercepted first (streaming or
direct-control commands); everything else is routed into Bruce's existing serial CLI
with the output captured into the
ACK, exposing the whole device feature set.fs_readstreams a file as base64DATAframes. -
SUB: starts/stops streams -
wifi.ap,wifi.sta,wifi.probe,wifi.monitor(promiscuous 802.11),ble.scan(NimBLE),subghz.rawandsubghz.spectrum(CC1101), andmic.spectrum- each device result is emitted as anEVENT. - Reuses Bruce's CLI and scan code rather than reinventing it. The companion layer wraps the CLI with framing and streaming; it does not duplicate it.
The device no longer advertises a static feature list. CAPS carries a caps{} object
computed by a hybrid of compile-time board macros (fixed onboard peripherals: cc1101,
ir, mic, speaker, and the always-present wifi/ble) and quick runtime probes
for the optional/uncertain ones (nfc via a PN532 I2C probe, nrf24 via an SPI
presence probe, fm via a Si4713 I2C probe). The app uses this map to show or hide
each page, so the same APK adapts to whatever board and add-ons are actually attached
(for example FM is implemented in firmware but reports fm:false on the T-Embed CC1101,
and that page stays hidden). A legacy coarse modules array is still sent for
backward compatibility.
The split follows a clear line: the ESP does everything that needs the radio in real
time, and the phone does everything built on captured bytes. Wi-Fi monitor mode is
the clearest example - the ESP runs the promiscuous 802.11 capture and streams raw
frames (wifi.monitor, base64), while the phone assembles the pcap, runs Wireshark-style
analysis and does PSK-based decryption. The same pattern applies to sub-GHz (ESP
captures RMT edge timings; phone decodes OOK and rolling codes) and to WPA (ESP captures
the handshake/PMKID; phone cracks it).
The companion code lives in src/companion/companion.cpp and companion.h.
-
transport/ - a
Transportinterface;UsbTransportbuilt on usb-serial-for-android. - protocol/framing - mirrors the protocol document exactly.
-
feature packages -
wardrive,wifi(WPA/PMKID crypto, monitor/pcap),mitm(on-phone HTTPS proxy),nfc,subghz,ir,ble,nrf24,badusb,wordlist,report(OSINT + insights),update(app OTA + device USB flash) andremote- the heavy work the ESP cannot do. - ui/ - Jetpack Compose, flame theme; screens are verified with Paparazzi screenshot tests on the JVM.
- Storage - Room DB, bundled assets (OUI table, IR catalog, dictionaries), and phone storage for rockyou-scale wordlists.
Length-prefixed (uint32 little-endian) JSON envelopes {v, t, id, d}. Kinds: HELLO,
CAPS, CMD, ACK, ERR, EVENT, DATA, SUB, PING, PONG. The protocol is the single
source of truth for both sides. Never add a message to one side only; bump
PROTOCOL_VERSION on schema changes. Full detail in Protocol.
Several features exist only because the phone, not the ESP, does the compute:
- WPA crack - captured handshakes/PMKIDs are cracked on the phone (PBKDF2/PTK/MIC) against rockyou-scale wordlists with hashcat-style rules.
-
MITM HTTPS proxy - once the ESP sets up the ARP redirect (
arp_spoof), an HTTPS proxy runs on the phone to inspect the redirected traffic. The radio work is on the ESP; the interception and TLS handling are on the phone. - Session report - a report generator on the phone combines the session's findings with OSINT enrichment and insights.
- Decoders and catalogs - OOK/rolling-code decode, OUI/IR catalogs, offline maps and visualization all run on the phone from the ESP's raw captures.
- USB-CDC is implemented: native on the ESP32-S3, high bandwidth, leaves the radios free.
-
Wi-Fi (TCP/WebSocket) and BLE (commands / light data only) are planned
behind the same
Transportinterface. See the roadmap.
Separate from companion offload mode, Remote control drives the device's real UI from the phone using two firmware primitives:
-
nav <next|prev|up|down|select|esc|nextpage|prevpage>injects input into the real UI (the same mechanism Bruce's WebUI uses). -
display start(src/core/tftLogger) streams the TFT draw operations over serial so the app can mirror the screen live.
The app's Remote tab sends nav from a D-pad and renders the device screen from that
draw-op stream, while the device runs its normal UI (the serial CLI task runs in the
background). This yields every standalone feature - Evil Portal, Karma, Beacon spam,
Sniffer, Reverse Shell, Scripts - without wrapping each one.
Brucia hooks into the existing Bruce code rather than reinventing it. Key integration points:
| Area | Location | Role |
|---|---|---|
| Serial command task | src/core/serialcmds.{h,cpp} |
entry point parseSerialCommand(...)
|
| CLI dispatcher | src/core/serial_commands/cli.{h,cpp} |
routes every CMD
|
| Per-domain commands | src/core/serial_commands/*_commands.cpp |
wifi_, rf_, ir_, rfid_, badusb_, crypto_, gpio_, power_, screen_, settings_, sound_, storage_, util_, interpreter_
|
| Connect / transfer plumbing |
src/core/connect/serial_commands.*, esp_connection.*
|
framing reference (file_sharing) |
| USB CDC access | src/core/USBSerial/USBSerial.h |
primary transport |
| Companion menu entry |
src/core/menu_items/ConnectMenu.cpp, src/core/main_menu.{h,cpp}
|
the Brucia / Companion entry |
| Wi-Fi modules |
src/modules/wifi/ (sniffer.cpp, ap_info.*, channel_analyzer.*, scan_hosts.h) |
AP/packet capture; sniffer emits the wifi.ap stream |
| GPS module | src/modules/gps/ |
kept for standalone; phone GPS replaces it in companion mode |
| Board / build |
platformio.ini env lilygo-t-embed-cc1101, custom_*.csv partitions |
ESP32-S3, native USB CDC |
| New companion code | src/companion/ |
transport, framing, dispatcher, HELLO/CAPS handshake, stream hooks |
CMD messages route through the existing CLI dispatcher, so most device control is
available for free; companion-only commands (streaming hooks) are added there as new
entries.
A LilyGo T-Embed CC1101 is ~$30-50. Paired with a phone most people already own, it reaches capabilities (rockyou-scale cracking, GPS wardriving with maps, large catalogs, rich visualization) that a standalone device in this price class cannot - an affordable, open alternative for research and education.