AntiHunter

<div align="center">

</div> <p align="center"> <img src="https://github.com/TheRealSirHaXalot/AntiHunter-Command-Control-PRO/blob/main/TopREADMElogo.png?raw=true" alt="AntiHunter Command Center Logo" width="320" /> <h3 align="center">DIGI Detection Node 2.4GHz WiFi/BLE Firmware</h3> </p>

[!NOTE] Standalone or for use with the AntiHunter Command Center.

Early Release - Beta version. Potential stability issues and unexpected behavior may exist in the process.

Table of Contents

1. Overview
2. Primary Detection Modes
3. Sensor Integration
4. Secure Data Destruction
5. RF Configuration
6. System Architecture
7. Hardware Requirements
8. Getting Started
9. Mesh Command Reference
10. API Reference
11. Credits
12. Disclaimer

News

• Jan. 29 2026: Featured in Best 20 XIAO Projects in 2025.

Overview

AntiHunter is a low-cost, open-source distributed perimeter defense system for wireless network security and operational awareness. Built on ESP32-S3 with mesh networking, it creates a scalable sensor network for real-time threat detection, device mapping, and perimeter security.

The system combines WiFi/BLE scanning, GPS positioning, environmental sensors, and distributed coordination to provide a digital and physical "tripwire", transforming spectrum activity into actionable security intelligence.

<a href="https://www.tindie.com/stores/teamantihunter/"><img src="https://d2ss6ovg47m0r5.cloudfront.net/badges/tindie-mediums.png" alt="I sell on Tindie" width="150" height="78"></a>

Primary Detection Modes

1. List/Target Scan Mode

Maintain a watchlist of target MAC addresses (full 6-byte) or OUI prefixes (3-byte vendor IDs). AntiHunter sweeps WiFi channels and BLE frequencies, providing immediate alerts and detailed logging on detection.

• Target monitoring by MAC address or vendor OUI prefix
• WiFi-only, BLE-only, or combined scanning
• Global user-configurable allowlist
• Logs RSSI, channel, GPS coordinates, and device names to SD card
• Real-time alerts via web interface, command center, and mesh network

2. Triangulation/Trilateration (Distributed)

Experimental

<img width="859" height="899" alt="Triangulation diagram" src="https://github.com/user-attachments/assets/c76bb177-ce4e-42db-aafb-fd360b7f49e2" />

[!TIP] Target RSSI above -80 will produce more accurate results.

Coordinates multiple nodes across a mesh network for precise location tracking. Each node simultaneously scans for a target, recording RSSI and GPS coordinates. Data is aggregated and forwarded over mesh for RSSI-based trilateration processing.

• Multi-node coordination across mesh network
• GPS integration from each contributing node
• RSSI-based weighted trilateration with Kalman filtering
• Outputs: Average HDOP, GPS coordinates, confidence, estimated uncertainty (m), GPS quality
• Google Maps link sent over mesh with details

Experimental T114 Support: Small buffer and slow speed causes latency. Heltec v3 recommended.

<details> <summary>RF Environment Calibration and Distance Tuning</summary>

Passive Detection Range (ESP32 + 5 dBi Antenna)

Ranges assume passive scanning. Active transmission achieves greater distances.

Path loss model: distance = 10^((RSSI0 - RSSI) / (10 * n))

| Environment | WiFi n | BLE n | WiFi RSSI0 | BLE RSSI0 | Use Case | |-------------|--------|-------|------------|-----------|----------| | Open Sky | 2.0 | 2.0 | -23 dBm | -60 dBm | Clear LOS, minimal obstruction | | Suburban | 2.7 | 2.5 | -24 dBm | -62 dBm | Light foliage, scattered buildings | | Indoor | 3.2 | 2.9 | -25 dBm | -65 dBm | Typical indoor, some walls | | Indoor Dense | 4.0 | 3.5 | -27 dBm | -69 dBm | Office spaces, many partitions | | Industrial | 4.8 | 4.0 | -30 dBm | -73 dBm | Heavy obstruction, machinery |

Distance Tuning (Target-Specific)

Fine-tune calculated distances per target using multipliers (0.1x - 5.0x):

• < 1.0: Target appears closer (increase sensitivity) -- e.g., 0.5x = 2x closer
• > 1.0: Target appears farther (reduce false positives) -- e.g., 2.0x = 2x farther
• Default: 1.0x (no adjustment)

</details>

3. Detection and Analysis Sniffers

A. Device Scanner

Captures all WiFi and Bluetooth devices in range. Records MAC addresses, SSIDs, signal strength, names, and channels for complete 2.4GHz spectrum visibility.

<img width="869" height="454" alt="Device Scanner" src="https://github.com/user-attachments/assets/c8a5d38b-9020-48c9-8bc4-f22d7c64a8df" />

B. Baseline Anomaly Detection

[!TIP] A longer initial scan will produce more reliable detection behavior

Two-phase scanning: establishes baseline, then monitors for anomalies (new devices, disappearances, reappearances, significant RSSI changes). Configurable RAM cache (200-500 devices) and SD storage (1K-100K devices, defaults to 1500 without SD). Persistent storage with automatic tiering survives reboots.

Use cases: distributed "trail cam" for intruders, perimeter security, surveillance detection, threat identification.

<img width="870" height="346" alt="Baseline Detection" src="https://github.com/user-attachments/assets/6204a8e5-418d-49fd-b99c-c1d9c31ee3f2" />

C. Deauthentication Attack Scan

WiFi deauth/disassoc attack sniffer with frame filtering, real-time detection, and integration with randomization tracking for source identification.

<img width="858" height="382" alt="Deauth Detection" src="https://github.com/user-attachments/assets/1b1e77db-a479-4cfd-beae-e13a7187cae4" />

D. Drone RID Detection

Identifies drones broadcasting Remote ID (FAA/EASA compliant). Supports ODID/ASTM F3411 protocols (NAN action frames and beacon frames), French drone ID format (OUI 0x6a5c35). Extracts UAV ID, pilot location, and flight telemetry. Sends immediate mesh alerts and logs to SD card and two API endpoints.

E. MAC Randomization Correlation

Experimental

[!TIP] Use the Privacy button at the top of the results pane if sharing screenshots

Traces device identities across randomized MAC addresses using behavioral signatures: IE fingerprinting, channel sequencing, timing analysis, RSSI patterns, and sequence number correlation. Assigns unique identity IDs (T-XXXX) with persistent SD storage.

• Up to 30 simultaneous identities with up to 50 linked MACs each
• Dual signature support (full and minimal IE patterns)
• Confidence-based linking with threshold adaptation
• Detects global MAC leaks and WiFi-BLE device correlation

<img width="861" height="721" alt="Randomization Analyzer" src="https://github.com/user-attachments/assets/1939e7b1-dcac-46e6-aae9-c08032bbb340" />

Use Cases

• Perimeter security and intrusion detection
• WiFi penetration testing, security auditing, and MAC randomization analysis
• Device fingerprinting and persistent identification across randomization
• Counter-UAV operations and airspace awareness
• Event security and monitoring
• Red team detection and defensive operations
• Wireless threat hunting, forensics, and privacy assessments

---

Sensor Integration

| Sensor | Interface | Description | |--------|-----------|-------------| | GPS | UART2 (RX=GPIO44, TX=GPIO43) 9600 baud | TinyGPS++ NMEA parsing. Location, altitude, satellite data. API at /gps. | | SD Card | SPI | Logs to /antihunter.log with timestamps, MACs, RSSI, GPS. Web interface shows storage stats. | | Vibration/Tamper | SW-420 (interrupt) | Interrupt-driven with 3s rate limiting. Mesh alerts with GPS and timestamps. | | RTC | DS3231 via I2C | NTP sync on flash, fallback to system time and GPS. Drift correction. All timestamps UTC. |

---

Secure Data Destruction

Tamper detection and emergency data wiping to protect data from unauthorized access.

• Auto-erase on tampering: Configurable vibration-triggered destruction (disabled by default)
• Setup delay: Grace period after enabling to complete deployment
• Manual secure wipe: Via web interface
• Remote force erase: Mesh-commanded with token authentication (5-min expiry, device-specific)
• Obfuscation: Creates a dummy IoT weather device config after wipe

Warning: Data destruction is permanent and irreversible. Configure thresholds carefully.

<details> <summary>Auto-Erase Configuration Parameters</summary>

| Parameter | Range | Description | |-----------|-------|-------------| | Setu