{"id":18302546,"url":"https://github.com/gemesa/esp32-phantom","last_synced_at":"2025-04-12T14:40:38.012Z","repository":{"id":168753117,"uuid":"644504289","full_name":"gemesa/esp32-phantom","owner":"gemesa","description":"ESP32 Rust-based WiFi and BLE sandbox","archived":false,"fork":false,"pushed_at":"2023-06-08T18:03:03.000Z","size":43,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-26T09:11:38.496Z","etag":null,"topics":["ble","embedded","embedded-hal","esp-ble","esp-wifi","esp32","hal","pcap","promiscuous","rust","wifi","wifi-monitor","wifi-packet-capture"],"latest_commit_sha":null,"homepage":"https://shadowshell.io/","language":"Rust","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/gemesa.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-23T16:49:04.000Z","updated_at":"2024-09-03T16:39:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"527b6f32-57f3-40b2-8539-5eb93d947256","html_url":"https://github.com/gemesa/esp32-phantom","commit_stats":null,"previous_names":["gemesa/esp32-phantom"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemesa%2Fesp32-phantom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemesa%2Fesp32-phantom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemesa%2Fesp32-phantom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemesa%2Fesp32-phantom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gemesa","download_url":"https://codeload.github.com/gemesa/esp32-phantom/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248582346,"owners_count":21128359,"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":["ble","embedded","embedded-hal","esp-ble","esp-wifi","esp32","hal","pcap","promiscuous","rust","wifi","wifi-monitor","wifi-packet-capture"],"created_at":"2024-11-05T15:20:26.275Z","updated_at":"2025-04-12T14:40:38.005Z","avatar_url":"https://github.com/gemesa.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# esp32-phantom\n\nesp32-phantom is a Rust sandbox to explore the WiFi and BLE capabilities of the ESP32, for example:\n- WiFi monitoring\n- promiscuous mode\n- pcap logging\n- crypto price monitoring\n\nIf you are serious about security analysis/pen testing I suggest to use an Alfa adapter instead such as [AWUS036AXML](https://alfa-network.eu/alfa-usb-adapter-awus036axml) or [AWUS036ACHM](https://alfa-network.eu/awus036achm) in combination with [hcxdumptool](https://github.com/ZerBea/hcxdumptool). Both of them are supported with excellent in-kernel drivers. \n\n## Toolchain installation and firmware building\n\n### Prerequisites\n\n- [Rust](https://www.rust-lang.org/tools/install)\n- [Rust for Xtensa](https://esp-rs.github.io/book/installation/index.html)\n\nTLDR installation steps:\n\n```\n$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n$ cargo install espflash\n$ cargo install espup\n$ espup install\n$ . $HOME/export-esp.sh\n$ cd \u003cyour-esp32-phantom-repo\u003e\n$ rustup override set esp\n```\n### How to build\n\n\n```\n$ cargo build --release --examples --features \"esp32,wifi\"\n```\n## Examples\n\n### Blinky\n\n```\n$ espflash /dev/ttyUSB0 target/xtensa-esp32-none-elf/release/examples/blinky\n```\n\n### WiFi monitoring\n\n```\n$ espflash /dev/ttyUSB0 target/xtensa-esp32-none-elf/release/examples/wifi-mon\n$ screen /dev/ttyUSB0 115200\n$ # press EN/RST button\nets Jun  8 2016 00:22:57\n\nrst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)\nconfigsip: 0, SPIWP:0xee\nclk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00\nmode:DIO, clock div:2\nload:0x3fff0048,len:12\nho 0 tail 12 room 4\nload:0x3fff0054,len:4800\nload:0x40078000,len:17448\nload:0x4007c428,len:4840\nentry 0x4007c6a0\nConfiguration status: Ok(())\nController status: Ok(true)\nAPs:\nxxxxx | XXXXXXXXXXXX | 3 | -32 | WPA2Personal\nxxxxx | XXXXXXXXXXXX | 7 | -79 | WPA2Personal\nxxxxx | XXXXXXXXXXXX | 7 | -79 | WPA2Personal\nxxxxx | XXXXXXXXXXXX | 11 | -86 | WPA2Personal\n```\n\n### Promiscuous mode\n\nThis mode can not be activated with the current latest version [(8e35b68)](https://github.com/esp-rs/esp-wifi/tree/8e35b68c4aaed2c6a4d1159dd1c1287a5a2359be) of esp-wifi because `queue_msg_waiting()` is not implemented yet and this function is mandatory for promiscuous mode:\n\n```\ncat esp-wifi/src/wifi/os_adapter.rs\n...\npub unsafe extern \"C\" fn queue_msg_waiting(_queue: *mut crate::binary::c_types::c_void) -\u003e u32 {\n    todo!(\"queue_msg_waiting\")\n}\n...\n```\n\n```\n$ espflash /dev/ttyUSB0 target/xtensa-esp32-none-elf/release/examples/prom-mon\n$ screen /dev/ttyUSB0 115200\n$ # press EN/RST button\nets Jun  8 2016 00:22:57\n\nrst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)\nconfigsip: 0, SPIWP:0xee\nclk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00\nmode:DIO, clock div:2\nload:0x3fff0048,len:12\nho 0 tail 12 room 4\nload:0x3fff0054,len:4800\nload:0x40078000,len:17448\nload:0x4007c428,len:4840\nentry 0x4007c6a0\nWiFi started!\n              \n               \n               !! A panic occured in 'esp-wifi/esp-wifi/src/wifi/os_adapter.rs', at line 599, column 5\n                                                                                                       \n                                                                                                       PanicInfo {\n                                                                                                                      payload: Any { .. },\n                        message: Some(\n                                              not yet implemented: queue_msg_waiting,\n                                                                                         ),\n                                                                                               location: Location {\n                                                                                                                           file: \"esp-wifi/esp-wifi/src/wifi/os_adapter.rs\",\n                                                              line: 599,\n                                                                                col: 5,\n                                                                                           },\n                                                                                                 can_unwind: true,\n                                                                                                                  }\n                                                                                                                    \n                                                                                                                    Backtrace:\n         \n         0x4008afa8\n                   0x401045e4\n                             0x400870e0\n                                       0x40087312\n                                                 0x40083d80\n                                                           0x400d8e03\n                                                                     0x400d5e04\n                                                                               0x40000000\n```\n\nThe following functions have been added to the esp-wifi submodule to test promiscuous mode:\n\n- `initialize_prom()` (initialize internals + call `wifi_init_prom()`)\n- `wifi_init_prom()` (initialize WiFi)\n- `recv_cb_prom()` (callback function, called when a packet is received)\n\nThese changes can not be committed to the submodule directly so the patch file `esp-wifi-promiscuous.patch` has been created. How to apply and build:\n\n```\n$ cd esp-wifi\n$ git apply ../esp-wifi-promiscuous.patch\n$ cd ..\n$ cargo build --release --examples --features \"esp32,wifi\"\n```\n\n[prom-mon.c](https://www.hackster.io/p99will/esp32-wifi-mac-scanner-sniffer-promiscuous-4c12f4) has been used as a reference to set promiscuous mode.\n\n### pcap logging\n\npcap (packet capture) is a container for packets captured on the WiFi network. Promiscuous mode is a prerequisite for this.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgemesa%2Fesp32-phantom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgemesa%2Fesp32-phantom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgemesa%2Fesp32-phantom/lists"}