Repository files navigation

An experimental Wi-Fi tracking system aiming at improving user awereness toward physical tracking technologies and at experimenting new privacy-preserving mechanisms.

Developed by Célestin Matte and Mathieu Cunche during Célestin Matte's PhD thesis (see link above), at INSA Lyon, in Inria's Privatics team, under a Région Rhône-Alpes's ARC7 funding.

• White paper: Wombat: An experimental Wi-Fi tracking system
• Thesis: Wi-Fi Tracking: Fingerprinting Attacks and Counter-Measures

• User-friendly opt-out system: users can opt out of the system by joining a fake Wi-Fi network.

Wombat is a fully functional Wi-Fi tracking platform supporting three main features: collection, storage/processing, query/output. These three features are implemented through a distributed infrastructure composed of:

• Sensor nodes: small devices with wireless monitoring capabilities. They collect information sent on wireless channels and forward it to the server.
• Central server: the central entity of the system. It receives data sent by sensor nodes and then stores it in an internal data structure. It is also in charge of answering queries related to the stored data.

To ensure communication between the sensor nodes and the server, theWombat system relies on a wired network (Ethernet). In addition, Wombat can be enriched with auser interface and anopt-out node:

• User interface: a device in charge of displaying detailed information about one or several tracked devices (see figure below). The device to display can be specified manually by its MAC address or through proximity detection.
• Opt-out node: an element in charge of implementing an opt-out mechanism for users refusing to be tracked by the system.

The system is made to work on a dedicated network (the server includes a DHCP server). Nodes can be switched off at any time (they function in read-only mode to be crash-proof).

Architecture of the Wombat system in a demonstration configuration:

Basic user interface of Wombat displaying the device’s MAC address, the list of SSIDs, as well as a mobility trace under a timeline form:

This package contains several folders:

• the server, node and optoutAP contain the files required to run wombat on the respective machines,
• the frontend folder contains various scripts which can be used to query the wombat server:
  • send_time.py is a script to send current time to the server, as required on system startup
  • draw_timeline.py is used byquery_server.py to draw the timeline
  • query_server.py can be used to query the server directly. Possible queries are:

python query_server.py nodes# to get the list of connected and fully functioning nodespython query_server.py stats# to get statistics about estimated number of devices seen by the systempython query_server.py stats<topology_file># same, but save results to a log.txt file.# <topology_file> is required to save results according to the topology of the system.# Useful when used when display_count.pypython query_server.py<mac_address># to get information about device of address <mac_address>

• display_count.py is used to display a diagram of the estimated number of devices seen along time.Use it withquery_server.pyystem aiming at improving user awereness toward physical tracking technologies and at experimenting new privacy-preserving mechanisms. using a command like this to monitor stats:watch -n 10 python query_server.py stats <topology_file>
• blind_server.py is a server to display the timeline when the server is configuredwith modesblind=true andusing_sensor=false

• the ansible folder contains ansible scripts to update the system in a single command.Running commands are indicated at the beginning of each file.
  • bootstrap.yml andsetup.yml configure a fresh archlinux installation fromscratch. See instruction inside theboostrap.yml file.
  • node.yml configures a node.
  • server.yml configures the server. Runnode.yml first.
  • optout.yml configures the optout server. Runnode.yml first.
  • push_server.yml updates server using latest code and config file, which isfaster than running the whole server.yml file.The otherserver_*.yml etc. correspond to equivalent files for various use cases.Note thatnode.yml,server.yml andoptout.yml can be run multiple times without problem.

The system can be run in different modes:

• blind_mode=false: the server has to be directly queried to give any information about devices.
• blind_mode=true,using_sensor=false: a Wi-Fi dongle is plugged to the server anddetect close devices. Timelines are sent to the front-end (frontend_ip),which must runfrontend/blind_server.py to display results
• blind_mode=true,using_sensor=true: the server has to be queried on port 4003using querydevice seen. If a device was seen in the previoussensor_window_seconds seconds,its timeline is sent back.

To change system mode, update the server configuration inansible/files/server/server_config.jsonand push it to the server usingpush_server.yml.

Required hardware: the nodes and opt-out machines should all have Wi-Fi cards handling monitor mode connected to them. We tested this system on Raspberry Pi 2 and 3 with TP-LINK TL-WN722N dongles. If running with blind_mode=True, the server should also have a Wi-Fi card. All the machines must be connected using a switch on a independant network.For instance, to run 4 nodes, a server and an optout node, you will need: 6 machines (e.g. 6 raspberry pis, and the same number of SD cards and power supplies), 6 monitor-mode-able Wi-Fi cards, one switch with enough ports, and 6 ethernet cables (+1 to connect you own machine to run front-end scripts).

The system can be easily installed on top of an existing Arch Linux install using ansibles scripts in the ansible folder.To install each component from scratch:

• download and install an Arch Linux image on a machine.
• boot the machine and log in
• type the following commands to create a new user, change his password, and update the system:

su -useradd -m -G wheel -s /bin/bash wombatpasswd wombat# chose a new passwordpacman -Syu

• note the machine's IP address
• Execute the bootstrap script with ansible:

ansible-playbook -i<ip>, --ask-sudo-pass -k bootstrap.yml --extra-vars"user=wombat"

You now have a basic system installed. You can use the different ansible scripts in the ansible/ folder depending on what the machine is going to be: a node (node.yml), the server (runnode.yml, thenserver.yml) or an optout server (runnode.yml, thenoptout.yml). Read instructions at the beginning of each of these files.

The system is made to work on a dedicated network. Once installed, remove the server from any existing network as its DHCP server may disrupt it proper functioning. Once every machines are installed and configured, link them all to a common switch and you're ready to go. You can add your own machine to the switch and query the server using thefrontend/query_server.py script. The server's IP address will be 172.23.0.1 and the rest of the nodes will be on the 172.23.0.1/24 network.

To configure the different modes presented in above section, editansible/files/server/server_config.json before install, or/etc/wombat/server_config.json on the server after install.

To have a machine configured as an automatic front-end:

• setblind_mode=True andusing_sensor=False on the server
• add the machine's MAC address in ansible/files/server/dhcpd.conf (before install) or in/etc/dhcpd.conf on the server (after install) in the "yourdevice" host and restart DHCP server. The target machine should obtain the 172.23.0.3 IP address.
• on the machine, runpython blind_server.py
• also, note that the server should have a functioning Wi-Fi card supporting monitor mode connected to it.If everything works properly, a wombat picture should appear. When a phone is moved close to the server's Wi-Fi card, the wombat picture should be replaced by the user interface presented in picture above.

• Pre-installed SD card images for raspberry 3 may be added for easier install.
• Describe all configuration options

Stage: completed project (2017), will not be updated.

This was an experimental research project, please be tolerant with code quality.

Due to the nature of this project (a Wi-Fi tracker), I voluntarily do not make this too easy to install for script kiddies (for instance by providing raw system images).

This demo was installed:

• in Cité des Sciences et de l'Industrie in Paris for over a year,
• in CNIL's LINC showroom,
• in the CITI laboratory's showroom.ystem aiming at improving user awereness toward physical tracking technologies and at experimenting new privacy-preserving mechanisms.