
Modern WiFi auditing library for ESP32 using advanced 802.11 techniques. Captures WPA/WPA2/WPA3 handshakes via PMKID extraction and CSA injection (bypasses PMF). Harvests enterprise credentials, supports dual-band (2.4GHz/5GHz on ESP32-C6), exports to PCAPNG/Hashcat. Clean C++ API with 9 examples.
A sophisticated WiFi auditing library for ESP32 microcontrollers
Politician is an embedded C++ library designed for WiFi security auditing on ESP32 platforms. It provides a clean, modern API for capturing WPA/WPA2/WPA3 handshakes and harvesting enterprise credentials using advanced 802.11 protocol techniques.
ClientFoundCb was changed from (const uint8_t *bssid, const uint8_t *sta, int8_t rssi) to (const ClientRecord &rec). Update existing callbacks:
// Before
engine.setClientFoundCallback([](const uint8_t *bssid, const uint8_t *sta, int8_t rssi) { … });
// After
engine.setClientFoundCallback([](const ClientRecord &rec) {
// rec.bssid, rec.sta, rec.rssi — same data plus rand_mac, vendor, timestamps
});
The library is built around a non-blocking state machine managing channel hopping, target selection, attack execution, and capture processing. All operations are contained within the politician namespace.
| Header | Description |
|---|---|
Politician.h | Main engine class — include this in every project |
PoliticianTypes.h | Public structs, enums, and compile-time feature gates |
PoliticianStorage.h | SD card loggers and NVS persistence (Arduino only) |
PoliticianFormat.h | PCAPNG and HC22000 serialization primitives |
PoliticianStress.h | Opt-in DoS payloads (SAE flood, probe flood, beacon flood) |
PoliticianProbe.h | Opt-in PROGMEM wordlist for hidden SSID probing |
PoliticianWPS.h | Opt-in WPS M1 print helpers and bitmask constants |
PoliticianSense.h | Opt-in passive RSSI-based motion and presence sensing |
| Mode | Bit | Description |
|---|---|---|
ATTACK_PMKID | 0x01 | PMKID fishing via fake association |
ATTACK_CSA | 0x02 | Channel Switch Announcement injection |
ATTACK_PASSIVE | 0x04 | Listen-only — zero transmission |
ATTACK_DEAUTH | 0x08 | Classic Reason-7 deauthentication |
ATTACK_STIMULATE | 0x10 | QoS Null Data client stimulation |
ATTACK_BTM | 0x20 | 802.11v BSS Transition Management Request |
ATTACK_ALL | 0x3F | All active attack vectors |
Define any of these before including Politician.h or via your build system (-DNAME):
; platformio.ini
build_flags =
-DPOLITICIAN_NO_DB ; Strip 14KB OUI database (no vendor lookups)
-DPOLITICIAN_NO_PCAPNG ; Strip PCAPNG serialization
-DPOLITICIAN_NO_HC22000 ; Strip Hashcat HC22000 formatter
-DPOLITICIAN_NO_LOGGING ; Strip all internal Serial log output
-DPOLITICIAN_NO_STD_FUNCTION ; Use raw fn pointers instead of std::function
-DPOLITICIAN_NO_MSCHAPV2 ; Strip bare EAP-MSCHAPv2 capture
-DPOLITICIAN_NO_KARMA ; Strip KARMA rogue AP responder
-DPOLITICIAN_MAX_INSTANCES=1 ; Limit to one instance (saves a pointer array slot)
POLITICIAN_NO_STD_FUNCTION reverts all callback types from std::function<> to raw function pointers — saving ~2KB flash and enabling use in environments without <functional>. Lambda captures are unavailable when this flag is set.
POLITICIAN_MAX_INSTANCES (default 2) controls the size of the static instance registry used by the promiscuous ISR dispatcher. Set to 1 for single-instance deployments to eliminate the loop overhead in the ISR.
[env:myboard]
platform = espressif32
board = esp32dev
framework = arduino
lib_deps =
Politician
Or clone directly into your project's lib/ directory:
cd lib/
git clone https://github.com/0ldev/Politician.git
Clone into your project's components/ directory and create a CMakeLists.txt:
idf_component_register(
SRCS "src/Politician.cpp" "src/PoliticianFormat.cpp" "src/PoliticianStress.cpp"
INCLUDE_DIRS "src"
)
PoliticianStorage.his Arduino-only and emits a#errorunder ESP-IDF. Use ESP-IDF's VFS andnvs_flashAPIs directly.
#include <Arduino.h>
#include <SD.h>
#include <Politician.h>
#include <PoliticianStorage.h>
using namespace politician;
using namespace politician::storage;
Politician engine;
PcapngFileLogger pcap; // Streaming logger — one open(), many write() calls
void onHandshake(const HandshakeRecord &rec) {
Serial.printf("[✓] %s ch%d rssi=%d type=%d\n",
rec.ssid, rec.channel, rec.rssi, rec.type);
pcap.write(rec);
}
void setup() {
Serial.begin(115200);
SD.begin();
pcap.open(SD, "/captures.pcapng", 4 * 1024 * 1024); // optional auto-rotation at 4MB
engine.setEapolCallback(onHandshake);
engine.begin();
engine.setAttackMask(ATTACK_ALL);
}
void loop() {
engine.tick();
}
#include <nvs_flash.h>
#include <esp_event.h>
#include <Politician.h>
using namespace politician;
static Politician engine;
static void audit_task(void *) {
engine.setEapolCallback([](const HandshakeRecord &rec) {
printf("[+] %s ch%d\n", rec.ssid, rec.channel);
});
engine.begin();
engine.setAttackMask(ATTACK_ALL);
for (;;) { engine.tick(); vTaskDelay(pdMS_TO_TICKS(1)); }
}
extern "C" void app_main(void) {
nvs_flash_init();
esp_event_loop_create_default();
xTaskCreate(audit_task, "politician", 8192, nullptr, 5, nullptr);
}
Error begin(const Config &cfg = Config());
Initializes the WiFi driver in promiscuous mode. Must be called before any other method. Clamps and warns on invalid Config values at startup. Use validateConfig() beforehand to surface misconfigurations before deploying in the field:
Config cfg;
cfg.hop_min_dwell_ms = 400;
cfg.hop_max_dwell_ms = 200; // wrong — min > max
const char *warnings[8];
int n = politician::validateConfig(cfg, warnings, 8);
for (int i = 0; i < n; i++) Serial.println(warnings[i]);
// → "hop_min_dwell_ms >= hop_max_dwell_ms — max will be clamped to min+50ms"
engine.begin(cfg); // begins normally; begin() clamps automatically
validateConfig() is a free inline function in the politician namespace — zero allocations, zero dependencies.