Accompanying blog post is located here.
Fox Trap is a wireless mesh based Command and Control infrastructure for locating mobile rogue access points. The original idea was to plant cheap wireless SOCs in a wireless theater which could detect multiple rogue aps as well as receive commands. Each Bot Node works by having tasks run synchronously, such as wireless packet sniffing, and then dropping into a communication mode where the mesh network exchanges information and passes it back to a Root Node. The framework was written for the ESP8266 and leverages the EspressIf ESP-SDK. Other chips utilizing the ESP-SDK should also be compatible. The current implementation scans for probes or beacons which originate from any of the target BSSIDs defined.
We recommend using Atom IDE and PlatfomIO as a development environment. Assuming you have those installed, simply clone the project and open it with PlatformIO. If you want to create the project from scratch, be sure to set NodeMCU as the chipset firmware. Optionally, you can use the Signal CLI to report target sightings via a Signal group.
- PlatformIO
- OPTIONAL Signal-CLI
The last known good upstream versions of Fox Trap's dependencies are the following:
- ArduinoJson@6.11.0
- painlessMesh@1.4.0
Around July 2019, one of the upstream dependencies completely broke the Task Scheduling functionality of the project, therefore it is recommended to run using the above listed dependency versions.
The design philosophy of the framework is to base all decisions off of the interval lengths of each task. To understand the tasks, please see the Software Implementation Section below. Otherwise you may run it with the default values and skip to the Usage section.
Tailor the following variables (directly below the #include directives) to your wireless environment:
- uint16_t channel : Wireless Channel
- uint32_t meshCommInterval : The amount of time for mesh communication (Default 20000 ms)
- uint32_t sniffInterval : The amount of time to sniff for targets (Default 9000 ms)
- uint32_t resyncInterval : How often to resyncronize communication to the (Default 900000)
- uint8_t channelHopInterval : How often to change channels while in sniff mode (Default 400 ms)
- unsigned long alertSeconds : How often to send a sighting alert across the mesh (Default 3 seconds)
- uint32_t alertTimes : How many times to attempt to send a sighting alert (Default 20 times)
Define the Wifi config the same in both root and bots
#define MESH_PREFIX "Your_Mesh_SSID"
#define MESH_PASSWORD "Your_Mesh_Password"
#define MESH_PORT 5566
Change _targets vector. For example if you were looking for 00:20:91:1A:22:33 and 00:20:91:1A:22:44 your vector would look like
std::vector<std::array<uint8_t, 6> > _targets =
{
{ 0x00, 0x20, 0x91, 0x1A, 0x22, 0x33 },
{ 0x00, 0x20, 0x91, 0x1A, 0x22, 0x44 }
};
Interactive Mode
c2Update.py -s /dev/ttyUSB1 -i
tar 0020911A2233
Single Command
c2Update.py -s /dev/ttyUSB1 -c tar 0020911A2233
Update over the air (serial is connected root node)
c2Update.py -s /dev/ttyUSB1 -i
rem 0020911A2233
c2Update.py -s /dev/ttyUSB1 -c rem 0020911A2233
Wifi Configuration : Define the Wifi config the same in both root and bots
#define MESH_PREFIX "Your_Mesh_SSID"
#define MESH_PASSWORD "Your_Mesh_Password"
#define MESH_PORT 5566
Tailor the following variables (directly below the #include directives) to your wireless environment:
- unsigned long ackSeconds : How often you want the root to send acknowledgement signals back to bots with sightings (Default 3 seconds)
- uint32_t ackTimes : How long you want the root to send acknowledgement signals back to bots (default 20 times)
The root operates over a serial port. There are two serial monitoring modes invoked with the Python 2 c2 script:
- Mode 1 uses pyserial and may require adjustment to the timeout parameter, however provides more granular monitoring.
- Mode 2 uses the PlatformIO serial monitoring tool
usage: c2.py [-h] -s SERIALPORT [-u SIGNALUSERID] [-g SIGNALGROUPID] -m MODE
Monitor in Mode 1, exit when target found
python2 c2.py -s /dev/ttyUSB1 -m 1
Monitor and send signal notifications (from user 123) to a group (345) when a target is found, then exit
python2 c2.py -s /dev/ttyUSB1 -u 123 -g 345 -m 2
Run the Signal Notification Scenario, exit when target found and immeadeatly drop into airodump-ng scan mode with the target MAC and channel selected
python2 c2.py -s /dev/ttyUSB1 -u 123 -g 345 -m 2 && launchAiro.sh
Bots are either in communication mode or sniffing the air for target BSSIDs. Each bot reports back to the root node as soon as it detects a target. The following tasks are used to accomplish this:
- botInitialization : Places the bot into mesh communication mode to talk to the network. All bots must be in communication at the same time.
- channelHop : Changes the wireless channels at specified time intervals while sniffing.
- resync : Sets flag to resynchronize node to the mesh at a guaranteed period.
- snifferInitialization : Places the node into 'sniffing' promiscuous mode and scans the air for a BSSID (MAC) contained in the targets list which is either probing or beaconing.
- sendAlert : Drops out of sniffing mode when a target is found and continuously reports to the mesh for specified periods.
The root node simply opens the mesh and handles communications across the mesh network with the following tasks:
- rootInitializationTask : a one time mesh initialization which opens the network
- acknowledgementTask : these tasks are only used after receiving a target sighting from a bot. It will attempt for a given amount of times / per interval to acknowledge to the bot it has received the sighting so that the bot can go back to doing its jobs (See alert mode diagram). The bot will subsequently send a finAck to get the server to stop this task.
Alert mode occcurs when a bot finds a target BSSID in promiscuous 'sniffer' mode. It immeadeatly drops out of sniffer mode and sends a pre-defined amount of alerts (default uint32_t alertTimes = 20;) at a pre-defined interval (default uint32_t alertTimes = 3;). As soon as the root discovers one of these alerts, it too fires of a pre-defined amount of acknowledgements (default unsigned long uint32_t ackTimes = 20;) at a pre-defined interval (default unsigned long ackSeconds = 3;). Finally, if the bot receives the acknowledgement, it will fire one finish acknowledgement message back to the root in an attempt to quiet the root down. It then resynchronizes itself, and returns to the normal duty cycle.
Fundamentally, bots should all be in communication at the same time so that nodes which are far away can reach the root. This guarantees nodes in the network won't be sinkholed. Over extended periods of time, the nodes will fall out of sync with one another, i.e. one will scan while another is communicating. Since the painlessMesh library includes built in NTP time with a precision of 10ms, it is guaranteed that nodes have a common concept of the network. This is used by Fox Track to find the next duty cycle time of all bots in the network, and waits to start its duty cycle accordingly followed by negation of the resync flag. This waiting occurs when the resync flag is set to true, and after negation it is reset every uint32_t resyncInterval ms (default 900000 ms).
- PlatformIO
- Painless Mesh
- Arduino Task Scheduler
- Ray Burnette's Wifi Sniffer
- rw950431's Probe collection logic
- ArduinoJson
- Signal-CLI
- Joe Minicucci - Software implementation and architecture
- Todd Cronin - Hardware and conceptual design
This project is licensed under The MIT License - see the LICENSE.mit file for details
- Defcon Wireless Village - Thanks for holding the Defcon wireless WTF and for the inspiration to create Fox Trap
- Lars Juhl Jensen - Thanks for the idea of sending commands over serial. A future implementation could use the same logic to create a more robust command infrastructure.
- Ideas for future c2 updates (sorted least-most effort)
- Remove all bssids command
- Sync the NTP interval with the python updater so the command propagation does not need to be timed by operator
- Change MAC addresses, SSID, and WIFI password to subvert adversarial traffic / attack (over the air)
- Weaponization (most likely better suited to other projects)
- Beacon / Probe spamming to disinform
- Distributed Deauthentication