{"id":13606623,"url":"https://github.com/ETS-PoliTO/esp32-sniffer","last_synced_at":"2025-04-12T08:31:42.229Z","repository":{"id":45971349,"uuid":"160811109","full_name":"ETS-PoliTO/esp32-sniffer","owner":"ETS-PoliTO","description":"ESP32 firmware that sniffs PROBE REQUEST packets sent from smartphones looking for a Wi-Fi connection in order to extract different types of information","archived":false,"fork":false,"pushed_at":"2023-12-18T22:52:06.000Z","size":468,"stargazers_count":194,"open_issues_count":5,"forks_count":31,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-11-07T11:44:33.680Z","etag":null,"topics":["component","esp32","esp32-idf","esp32-spiffs","esp32-wroom","filesystem","framework","iot","mqtt","multithreading","probe-requests","real-time-location","smartphones","sniffer","sntp","spiffs","task-management","tasks","tracking-system","wifi-connection"],"latest_commit_sha":null,"homepage":"https://j4nn0.github.io/doc/ets_presentation.pdf","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ETS-PoliTO.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-12-07T10:47:17.000Z","updated_at":"2024-11-02T15:43:43.000Z","dependencies_parsed_at":"2023-12-19T01:48:24.987Z","dependency_job_id":"ff35aab2-69f1-48d7-b504-2a48f2b4878b","html_url":"https://github.com/ETS-PoliTO/esp32-sniffer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ETS-PoliTO%2Fesp32-sniffer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ETS-PoliTO%2Fesp32-sniffer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ETS-PoliTO%2Fesp32-sniffer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ETS-PoliTO%2Fesp32-sniffer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ETS-PoliTO","download_url":"https://codeload.github.com/ETS-PoliTO/esp32-sniffer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248539929,"owners_count":21121260,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["component","esp32","esp32-idf","esp32-spiffs","esp32-wroom","filesystem","framework","iot","mqtt","multithreading","probe-requests","real-time-location","smartphones","sniffer","sntp","spiffs","task-management","tasks","tracking-system","wifi-connection"],"created_at":"2024-08-01T19:01:10.753Z","updated_at":"2025-04-12T08:31:37.219Z","avatar_url":"https://github.com/ETS-PoliTO.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# ESP32 Sniffer\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"ETS\" src=\"https://user-images.githubusercontent.com/25306548/70620809-7a028600-1c18-11ea-939c-5358bb2c61f7.png\" height=\"140\" /\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"\"\u003e\u003cimg alt=\"Software License\" src=\"https://img.shields.io/cran/l/devtools\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://youtu.be/NMywky9Ts_w\"\u003e\u003cimg alt=\"Demo\" src=\"https://img.shields.io/badge/demo-youtube-blue.svg\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://twitter.com/giannofederico\"\u003e\u003cimg alt=\"Twitter\" src=\"https://img.shields.io/twitter/follow/giannofederico.svg?style=social\u0026label=Follow\"\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\nThis project is using [Espressif IoT Development Framework](https://github.com/espressif/esp-idf) (ESP-IDF) and has been tested on ESP-WROOM-32 module and esp-idf `v3.2`.\n\nAn overview of the full project (i.e. ESP32 firmware, server and GUI) can be found [here](https://j4nn0.github.io/doc/ets_presentation.pdf).\n\nThis firmware is written with the purpose to sniff Probe Request packets sent by smartphones that are looking for Wi-Fi connection. When the Wi-Fi connection is active on a smartphone, it will send in broadcast (in all channels frequencies) a probe request messagge asking if there are any free Wi-Fi or some known ones (i.e. the smartphone knows the password for that Wi-Fi). The ESP32 will sniff it and extract different types of information.\n\nThe following information is taken from each sniffed packet:\n\n- MAC of the smartphone that has sent the request\n- SSID of the wifi to which the request is sent\n- The Timestamp of when the request was sent\n- Received Signal Strength Indicator (RSSI)\n- Sequence Number (SN)\n- HT Capabilities Info\n\nAfter each minute these informations are sent to a [server](https://github.com/ETS-PoliTO/ETS-Server) and processed. Finally, it is possible to see the processed informations (smartphones real time location, smartphone frequency, etc.) through a [GUI](https://github.com/ETS-PoliTO/GUI-Application).\n\n### Demo \n[![Watch the video](https://img.youtube.com/vi/NMywky9Ts_w/maxresdefault.jpg)](https://youtu.be/NMywky9Ts_w)\n\n# Table of Contents\n- [Firmware Overview](#firmware-overview)\n- [ESP-IDF Environment Configuration](#esp-idf-environment-configuration)\n- [Usage](#usage)\n- [File Configuration](#file-configuration)\n    - [Variables Configuration](#variables-configuration)\n    - [Add Customised Menu](#add-customised-menu)\n- [Components](#components)\n- [Resources](#resources)\n\n# Firmware Overview\n\nThe firmware consits in two main threads/tasks:\n\n- Sniffer Task\n    \n    - Sniff Probe Request packet and save infomation described above into a file.\n\n- Wi-Fi Task\n\n    - Each minute, take the information saved by the **Sniffer Task** and send it to the server.\n    - A `lock` is used in order to manage critical section for I/O operations in the file.\n\nThe ESP32 is configured in `WIFI_MODE_APSTA` mode: i.e. it creates \"*soft-AP and station control block*\" and starts \"*soft-AP and station*\". Thanks to this, the ESP32 is able to sniff and send informations to the server at the same time avoiding to lose packets information while sending data.\n\nHere is the full list of information fields that can be in a Probe Request (source IEEE 802.11-2012):\n\n![cwap-probe-10](https://user-images.githubusercontent.com/25306548/134971992-9df8ba5c-b93c-4d83-b12f-0f991b4ddbeb.png)\n\nAnd here below a packet sniffed with Wireshark in which you can see, for each field, the number of bits and their position within the packet:\n\n![cwap-probe-03](https://user-images.githubusercontent.com/25306548/134974167-d0b1aaf1-dfc9-46ee-9513-271c3b876716.png)\n\n# ESP-IDF Environment Configuration\n\nThis section might be outdated, checkout the [official site](https://esp-idf.readthedocs.io/en/latest/get-started/index.html) for more info and for the latest guide on how to get started with ESP-IDF.\n\n1. Setup Toolchain\n\n\t- [Windows](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/windows-setup.html)\n\t- [Linux](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/linux-setup.html)\n\t- [Mac OS](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/macos-setup.html)\n\t\n2. Get ESP-IDF\n\n\tBesides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries.\n\n\t   cd ~/esp\n\t   git clone --recursive https://github.com/espressif/esp-idf.git\n\t\t\n3. Checkout to version `v3.x`\n\n\t   cd esp-idf\n\t   git checkout release/v3.2\n\t\t\n4. Setup path to ESP-IDF\n\n\tThe toolchain programs access ESP-IDF using `IDF_PATH` environment variable.\n\tThis variable should be set up on your PC, otherwise projects will not build.\n\t\n\t- [Windows](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/add-idf_path-to-profile.html#add-idf-path-to-profile-windows)\n\t- [Linux \u0026 Mac OS](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/add-idf_path-to-profile.html#add-idf-path-to-profile-linux-macos)\n\t\n5. Install the Required Python Packages\n\n\t   python -m pip install --user -r $IDF_PATH/requirements.txt\n\n# Usage\n\t\n1. Make sure you have exported the path\n\t\n\t   export IDF_PATH=~/esp/esp-idf\n\t   export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin\n\n2. Clone the repo\n\t\n\t   git clone https://github.com/ETS-PoliTO/esp32-sniffer.git\n\t   cd esp32-sniffer\n\n3. Establish serial connection between ESP32 and your PC\n\t\n\t   make menuconfig\n\n\t Go to `Serial flasher config`, then `Default serial port` and set the port in which ESP32 is connected\n\t \n\t Note that, if you are using a bridge, probably you need to download some driver:\n\t \n\t - [CP210x](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers)\n\t - [FTDI](https://www.ftdichip.com/Drivers/VCP.htm)\n\t \n\t [This](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/establish-serial-connection.html) provides a  guide on how establish serial connection between ESP32 and PC. \n\n4. Build code and flash the ESP32\n\n\t   make all \u0026\u0026 make flash\n\n5. See logs\n\n\t   make monitor\n\n# File Configuration\n\nThe file `/main/Kconfig.projbuild` contains two different menus:\n\n- SPIFFS (SPI Flash File System)\n\n\tIt contains some important information about the SPIFFS partion:\n\t\n\t- SPIFFS Base address\n\t- SPIFFS Size\n\t- SPIFFS Logical block size\n\t- SPIFFS Logical page size\n\t\n\t[SPIFFS](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/storage/spiffs.html) is a file system that supports wear leveling, file system consistency checks and more.\n\n- Configurations\n\n\tIt contains different variables:\n\n\t- `ESP32_ID`: ID of the ESP32\n\t- `WIFI_SSID`: SSID of WiFi (network name)\n\t- `WIFI_PASS`: WiFi password (WPA or WPA2)\n\t- `BROKER_ADDR`: IP of the MQTT broker\n\t- `BROKER_PSW`: password of the MQTT broker\n\t- `BROKER_PORT`: port of the MQTT broker\n\t- `CHANNEL`: channel in which ESP32 will sniff PROBE REQUEST\n\t- `SNIFFING_TIME`: time of sniffing\n\t- etc...\n\n### Variables Configuration\n\nIn order to configure the variables above:\n\n1. Open your terminal within the project folder and run\n\t\n       make menuconfig \n\t\n2. Select the menu you want to modify\n3. Edit variables as you like\n\n### Add Customised Menu\n\nYou can also add different menus with different variables:\n\n1. Open `Kconfig.projbuild`\n2. Start a new menu\n\n       menu YOUR_MENU_NAME\n     \n3. Add the variables you need\n4. End menu\n\n       endmenu\n\n# Components\n\n- SPIFFS\n\n\tYou need to create a [partition table](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/partition-tables.html).\n\t\n\t[SPIFFS components](https://github.com/espressif/esp-idf/tree/master/components/spiffs)\n\n- ESP32 MQTT\n\n\tIt has been used ESP32 MQTT Library.\n\t\n\t[MQTT documentation](https://github.com/espressif/esp-mqtt/tree/c5ff6dd05fd357803f419916aa98ad7dd0f8e535)\n\t\n- MD5\n\n\tHash function used on sniffed packets in order to get a unique identifier.\n\n# Resources\n\n- Official [esp-idf git repo](https://github.com/espressif/esp-idf) to see some examples and information about the used data structure.\n- Latest Documentation version for [Espressif IoT Development Framework](https://docs.espressif.com/projects/esp-idf/en/latest/).\n- [ESP32 forum](https://esp32.com/) to ask questions and find community resources.\n- [ESP32-IDF Documentation](http://esp32.info/docs/esp_idf/html/index.html) for browseable modules, namespaces, data structures and files.\n\nCheck also this demonstration [video](https://youtu.be/NMywky9Ts_w) to see how ESP32 works.\n\n###### Seneca\n\u003e Longum iter est per praecepta, breve et efficax per exempla\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FETS-PoliTO%2Fesp32-sniffer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FETS-PoliTO%2Fesp32-sniffer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FETS-PoliTO%2Fesp32-sniffer/lists"}