Antihunter

What is Antihunter?

A low-cost, open-source tool for wireless threat detection, tracking, and counter-surveillance.

What Does Antihunter Do?

• Detect rogue Wi-Fi & BLE devices
• Hunt with directional antennas/ proximity
• Deploy perimeters via Meshtastic

Antihunter provides powerful, real-time wireless intelligence through an intuitive web-based interface. It operates in two primary modes:

1. List Scan Mode (Area Surveillance): Upload a list of target MAC addresses (full 6-byte) or OUI prefixes (first 3-byte Vendor ID). Antihunter will meticulously sweep the designated WiFi channels and BLE frequencies. Upon detection, you receive immediate audible alerts (customizable beep patterns) and detailed logs, including signal strength (RSSI), channel, and device name. This mode is perfect for:

   • Passive monitoring of specific devices in an environment.
   • Initial reconnaissance in a wireless survey.
   • Identifying rogue access points or suspicious BLE beacons.

2. Tracker Mode (The Digital Foxhunt): This is Antihunter's specialty for close-quarters signal pursuit. Provide a single target MAC address, and Antihunter transforms into a responsive "Geiger counter" for that specific device. As you move (or point a directional antenna), the device's integrated buzzer will dynamically adjust its pitch and tempo – faster and higher-pitched tones indicate you're closing in on the target, while a slow, deep click means the signal is weak or lost. Tracker mode is indispensable for:

   • Locating lost or stolen wireless devices.
   • Pinpointing the exact physical location of a transmitting device.
   • Real-time "foxhunting" games and exercises.

3. Dedicated Blue/Red Tools Coming Soon

Mesh Network Integration (Meshtastic-compatible):

Antihunter seamlessly integrates with Meshtastic-compatible mesh networks. When enabled, it can broadcast alerts for detected targets (from either List Scan or Tracker mode) directly over your meshtastic radio.

This feature extends Antihunter's reach, allowing remote teams or distant nodes to receive immediate notifications about target activity, making it a critical asset for coordinated detection efforts over long ranges. Alerts are sent at a configurable interval (default: 10 seconds).

How to Get Started

Getting Antihunter up and running is straightforward. Use the quick flasher or build from source: Simply clone the repository, open it in VS Code with PlatformIO, and flash your desired configuration.

Quick Flasher Option

• If you choose not to build from source, precompiled bins are available in the Dist folder
• Plug in your esp32s3 device and then download & flash with the following command. Choose Mesh/Standard from given options:

curl -fsSL -o flashAntihunter.sh https://raw.githubusercontent.com/lukeswitz/AntiHunter/refs/heads/main/Dist/flashAntihunter.sh && chmod +x flashAntihunter.sh && ./flashAntihunter.sh

1. Prerequisites

• VS Code: Visual Studio Code IDE.
• PlatformIO Extension: Install the PlatformIO IDE extension in VS Code.
• Hardware:
  • ESP32 development board (Seeed XIAO ESP32S3 and other s3 varients) • 8MB flash memory boards required for reliably
  • Passive piezo buzzer connected to the designated pin
  • Meshtastic board (Heltec, etc.)

2. Clone the Repository

Open your terminal or command prompt and execute:

git clone https://github.com/lukeswitz/AntiHunter.git Antihunter_Project
cd Antihunter_Project

This creates a new folder Antihunter_Project containing the Antihunter source code.

3. Open in VS Code

Open the Antihunter_Project folder as your workspace in VS Code. PlatformIO will automatically detect the platformio.ini file at the root.

4. Flashing the Firmware

Antihunter supports multiple boards and two project variants (core Antihunter and Antihunter_Mesh). Your platformio.ini is set up to let you choose.

• Select Your Target:

  • In the VS Code Status Bar (the blue bar at the bottom), locate the PlatformIO environment selector. It typically shows something like Default (esp32s3).
  • Click on it. A list of available environments will appear, clearly prefixed:
  • Select the environment corresponding to your board and the project variant you wish to upload.

• Upload: Click the "Upload" button (the right arrow icon) in the PlatformIO status bar. PlatformIO will compile the selected project and flash it to your connected ESP32 board.

How to Use Antihunter (Web Interface)

Once flashed, Antihunter hosts a web interface for all operations.

1. Connect to Antihunter's Access Point (AP):

   • On your computer, phone, or tablet, scan for WiFi networks.
   • Connect to the network: Antihunter
   • Default Password: ouispy123

2. Access the Web UI:

   • Open a web browser and navigate to http://192.168.4.1/.

3. Core Functionality:

• Targets (List Scan Watchlist):

  • Enter full MAC addresses (e.g., 00:11:22:33:44:55) or OUI prefixes (e.g., 00:11:22), one per line.
  • Click Save to update your watchlist.
  • Download exports your current target list.

• List Scan:

  • Scan Mode: Choose WiFi Only, BLE Only, or WiFi + BLE.
  • Duration: Set the scan duration in seconds (0 for "Forever").
  • WiFi Channels CSV: Specify channels to hop through (e.g., 1,6,11 or 1..13).
  • Click Start List Scan. (Note: The AP will go offline during the scan and return when stopped).
  • Click Stop to end any active scan.
  

• Tracker (Single MAC "Geiger"):

  • Scan Mode: Choose WiFi Only, BLE Only, or WiFi + BLE.
  • Target MAC: Enter the precise MAC address of the device you're tracking (e.g., 34:21:09:83:D9:51).
  • Duration: Set the tracking duration in seconds (0 for "Forever").
  • Click Start Tracker. AP will disappear for the duration of the scan. The buzzer will emit tones that change in frequency and period based on the target's signal strength (RSSI) – higher pitch/faster for closer, lower pitch/slower for further.
  • Click Stop to end tracking.
  

• Buzzer:

  • Beeps per hit (List Scan): Configure how many times the buzzer beeps when a target is detected in List Scan mode (default: 2).
  • Gap between beeps (ms): Adjust the pause between beeps (default: 80 ms).
  • Save Config applies changes. Test Beep triggers a single test pattern.

• Mesh Network:

  • Enable Mesh Notifications: Toggle this checkbox to send detected target alerts over your connected Meshtastic device (default: enabled).
  • Test Mesh: Sends a test message via UART to confirm mesh communication is active.
  • Mesh alerts are sent approximately every 10 seconds if a target is detected.
  • *(Hardware: The ESP32 communicates with your Meshtastic radio via Serial1 on pins RX=4, TX=5 at 115200 baud).
  • Meshtastic Configuration: Enable serial, Set RX/TX (19/20 for Heltec v3), text message mode, 115200 baud.*
  

• Diagnostics:

  • Provides real-time system status: scan mode, scanning status, frames seen (WiFi/BLE), total hits, unique devices, active targets, ESP32 temperature, and more.

• Last Results:

  • Displays a summary of the most recent scan or tracking session, including identified MACs, RSSI values, frame count, and other pertinent data.

Antihunter empowers you to assert control over your wireless environment, turning the invisible into actionable intelligence. Happy hunting.

Credits

Built by @TheRealSirHaXalot with additions from @lukeswitz

Thanks to

• @colonelpanichacks devices for pushing this development
• All the hackers and builders making it all go round

Disclaimer

Important

DISCLAIMER AND LIMITATION OF LIABILITY

THE SOFTWARE IN THIS REPOSITORY (“SOFTWARE”) IS PROVIDED “AS IS” AND “AS AVAILABLE,” WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT, ACCURACY, OR RELIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL THE DEVELOPERS, MAINTAINERS, OR CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF OR OTHER DEALINGS IN THE SOFTWARE, INCLUDING WITHOUT LIMITATION ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR LOSS OF DATA, PROFITS, GOODWILL, OR BUSINESS INTERRUPTION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

YOU ALONE ARE RESPONSIBLE FOR COMPLYING WITH ALL APPLICABLE LAWS, REGULATIONS, AND THIRD-PARTY RIGHTS. NO ADVICE OR INFORMATION, WHETHER ORAL OR WRITTEN, OBTAINED FROM THE PROJECT OR THROUGH THE SOFTWARE, CREATES ANY WARRANTY OR OBLIGATION NOT EXPRESSLY STATED HEREIN. IF APPLICABLE LAW DOES NOT ALLOW THE EXCLUSION OF CERTAIN WARRANTIES OR LIMITATION OF LIABILITY, THE DEVELOPERS’, MAINTAINERS’, AND CONTRIBUTORS’ AGGREGATE LIABILITY SHALL NOT EXCEED THE GREATER OF: (A) THE AMOUNT YOU PAID (IF ANY) FOR THE COPY OF THE SOFTWARE THAT GAVE RISE TO THE CLAIM, OR (B) USD $0.

BY ACCESSING, DOWNLOADING, INSTALLING, COMPILING, EXECUTING, OR OTHERWISE USING THE SOFTWARE, YOU ACCEPT THIS DISCLAIMER AND THESE LIMITATIONS OF LIABILITY.