autarch/docs/esp32_capture_probe.md

ESP32 WiFi Capture Probe — Design Document

Project: AUTARCH Hardware Probe Status: Planned Author: darkHal Security Group

---

Problem

The Orange Pi 5 Plus built-in WiFi adapter (managed mode only) cannot:

• Enter monitor mode for raw 802.11 frame capture
• Detect deauthentication attacks (requires reading management frames)
• Do passive channel hopping while staying connected to a network
• Capture probe requests, beacon frames, or association traffic

USB WiFi adapters that support monitor mode (Alfa AWUS036ACH, etc.) work but are bulky, expensive, and require specific driver support.

Solution

A small ESP32-based WiFi capture probe that runs custom firmware. The ESP32's WiFi chipset natively supports promiscuous mode and can capture raw 802.11 frames on both 2.4GHz and 5GHz (ESP32-S3/C6). The probe connects to AUTARCH over USB serial or TCP and streams captured frames in real time.

AUTARCH already has ESP32 flashing built into the Hardware page — users can flash the probe firmware directly from the web UI.

Hardware

Minimum:

• ESP32 dev board (any variant) — ~$5
• USB cable

Recommended:

• ESP32-S3 or ESP32-C6 (dual-band 2.4/5GHz support)
• External antenna connector (IPEX/U.FL) for better range
• Small 3D-printed case
• Optional: LiPo battery + charging circuit for portable deployment

Cost: Under $10 for a complete probe

Capabilities

Capture Modes

1. Promiscuous Mode — capture all 802.11 frames on a channel (data, management, control)
2. Channel Hopping — cycle through channels 1-13 (2.4GHz) and 36-165 (5GHz on S3/C6)
3. Targeted Capture — lock to a specific channel and BSSID
4. Beacon Monitor — capture only beacon and probe frames (low bandwidth, good for SSID mapping)

Detection

• Deauthentication frame detection (count, source MAC, target MAC, reason code)
• Evil twin detection (same SSID, different BSSID appearing)
• Probe request tracking (which devices are looking for which networks)
• Rogue AP detection (new BSSIDs appearing)
• Karma attack detection (AP responding to all probe requests)
• Association flood detection

Output Formats

• Raw pcap over serial (AUTARCH reads with scapy)
• JSON event stream over serial (parsed on ESP32, lighter bandwidth)
• TCP stream over WiFi (ESP32 connects to AUTARCH's network in station mode on one radio, captures on the other — dual-radio ESP32 only)

Firmware Architecture

esp32-capture-probe/
  main/
    main.c              Entry point, WiFi init, mode selection
    capture.c           Promiscuous mode callback, frame parsing
    channel_hop.c       Channel hopping logic with configurable dwell time
    serial_output.c     Frame/event output over USB serial (SLIP framing)
    tcp_output.c        Frame/event output over TCP socket
    detector.c          Deauth/evil twin/karma detection logic
    config.c            Runtime configuration via serial commands
    led.c               Status LED control (capturing, alert, idle)
  CMakeLists.txt
  sdkconfig             ESP-IDF configuration

Frame Processing Pipeline

802.11 Frame (promiscuous callback)
  |
  +-- Parse header (type, subtype, addresses, sequence)
  |
  +-- Filter (by type, BSSID, channel)
  |
  +-- Detection engine
  |     +-- Deauth counter (threshold alert)
  |     +-- SSID/BSSID tracker (evil twin check)
  |     +-- Probe request log
  |
  +-- Output
        +-- JSON event (for alerts/detections)
        +-- Raw frame bytes (for pcap capture)

Serial Protocol

Commands from AUTARCH to probe (newline-delimited JSON):

{"cmd": "start", "mode": "promiscuous", "channel": 0}
{"cmd": "start", "mode": "beacon_only"}
{"cmd": "set_channel", "channel": 6}
{"cmd": "hop", "channels": [1,6,11], "dwell_ms": 200}
{"cmd": "stop"}
{"cmd": "status"}
{"cmd": "set_filter", "bssid": "aa:bb:cc:dd:ee:ff"}
{"cmd": "set_output", "format": "json"}
{"cmd": "set_output", "format": "pcap"}

Events from probe to AUTARCH:

{"event": "deauth", "src": "aa:bb:cc:dd:ee:ff", "dst": "11:22:33:44:55:66", "reason": 7, "channel": 6, "rssi": -45, "count": 15}
{"event": "beacon", "ssid": "FreeWiFi", "bssid": "aa:bb:cc:dd:ee:ff", "channel": 1, "rssi": -60, "security": "open"}
{"event": "evil_twin", "ssid": "HomeNetwork", "bssid_original": "aa:bb:cc:dd:ee:ff", "bssid_rogue": "11:22:33:44:55:66"}
{"event": "probe_req", "src": "aa:bb:cc:dd:ee:ff", "ssid": "MyPhone_Hotspot", "rssi": -70}
{"event": "karma", "ap_bssid": "aa:bb:cc:dd:ee:ff", "responded_to": ["Network1", "Network2", "Network3"]}
{"event": "frame", "hex": "80000000...", "channel": 6, "rssi": -55}
{"event": "status", "mode": "hopping", "channel": 6, "frames_captured": 1547, "alerts": 3, "uptime": 120}

AUTARCH Integration

Hardware Page

The probe appears as an ESP32 device on the Hardware page. Users can:

• Flash the capture firmware (one click from the ESP32 tab)
• Monitor probe status (connected, capturing, channel, frame count)
• Configure capture settings (mode, channels, filters)

Network Security Page

New sub-features when a probe is connected:

• Live 802.11 Monitor — real-time frame stream with protocol breakdown
• Deauth Alert — instant notification when deauth frames detected (with source tracking)
• Channel Survey — signal strength and AP count per channel (helps pick the cleanest channel)
• Hidden Network Discovery — find SSIDs that don't broadcast beacons by watching probe responses
• Client Tracker — which devices (MACs) are associated to which APs

Capture Agent Integration

The capture agent (core/capture_agent.py) gains a new action:

{"action": "probe_start", "serial_port": "/dev/ttyUSB0", "mode": "promiscuous", "channels": [1,6,11]}
{"action": "probe_stop"}
{"action": "probe_status"}

The capture agent reads the serial stream, converts to pcap or forwards JSON events to Flask via its existing socket.

WiFi Audit Integration

With the probe providing monitor mode:

• Deauth attacks actually work (raw frame injection)
• Handshake capture works (WPA 4-way handshake monitoring)
• Channel hopping during audit scans
• Passive reconnaissance without disconnecting from the network

Implementation Phases

Phase 1: Basic Capture (1-2 days)

• ESP-IDF project setup
• Promiscuous mode callback
• Serial output (JSON events)
• Channel hopping
• Flash from AUTARCH Hardware page

Phase 2: Detection Engine (1-2 days)

• Deauth frame counter with threshold alerting
• Evil twin detection (SSID/BSSID tracking)
• Probe request logging
• AUTARCH integration (Network Security page reads probe events)

Phase 3: Advanced Features (2-3 days)

• pcap output mode (raw frame bytes over serial)
• TCP streaming mode (dual-radio only)
• Karma attack detection
• Client association tracking
• Channel survey with signal heatmap data
• Hidden network discovery

Phase 4: WiFi Audit Integration (1-2 days)

• Frame injection for deauth (if supported by ESP32 variant)
• Handshake capture and forwarding to aircrack-ng
• Automated WPA audit workflow

Bill of Materials

Component	Purpose	Price
ESP32-S3 DevKitC	Dual-band WiFi, USB-C	~$8
IPEX antenna	Better range	~$2
USB-C cable	Connection to AUTARCH host	~$3
3D printed case	Protection (optional)	~$1
Total		~$14

For budget builds, any ESP32 board works ($3-5) but is limited to 2.4GHz only.

Comparison to Alternatives

Feature	ESP32 Probe	Alfa Adapter	HackRF	Built-in WiFi
Cost	~$14	~$40-70	~$300	$0
Monitor mode	Yes	Yes	N/A	Usually no
5GHz	ESP32-S3/C6	Model dependent	Yes	Model dependent
Portable	Very (tiny)	Medium	Large	N/A
Driver issues	None (serial)	Frequent	Complex	N/A
Frame injection	Limited	Yes	Yes	No
Power	USB powered	USB powered	USB powered	N/A
AUTARCH integration	Native	Requires airmon-ng	Complex	Limited

The ESP32 probe fills the gap between "no monitor mode" and "expensive USB adapter with driver hell." It's cheap, reliable, driver-free (serial protocol), and integrates natively with AUTARCH.

---

darkHal Security Group & Setec Security Labs Planned for AUTARCH v2.5