Politician

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.

Key Capabilities

• PMKID Capture: Extract PMKIDs from association responses without client disconnection
• CSA (Channel Switch Announcement) Injection: Modern alternative to deauthentication attacks
• Enterprise Credential Harvesting: Capture EAP-Identity frames from 802.1X networks
• Hidden Network Discovery: Automatic SSID decloaking via probe response interception
• Device Fingerprinting: Passively identify 150+ consumer IoT/smart home brands via MAC OUI and IE signatures without network association
• Client Stimulation: Wake sleeping mobile devices using QoS Null Data frames
• WPA3/PMF Detection: Intelligent filtering to skip Protected Management Frame-enabled networks
• Export Formats: PCAPNG capture files; optional HC22000 text export for direct Hashcat ingestion

Architecture

The library is built around a non-blocking state machine that manages channel hopping, target selection, attack execution, and capture processing. All operations are contained within the politician namespace.

Core Components

Component	Description
Politician	Main engine class managing the audit lifecycle
PoliticianFormat	PCAPNG capture serialization; auxiliary HC22000 text export
PoliticianStorage	Optional SD card logging and NVS persistence
PoliticianStress	Decoupled DoS/disruption payload delivery (opt-in)
PoliticianTypes	Core data structures and enumerations

Attack Modes

Traditional deauthentication attacks are ineffective against modern WPA3 and WPA2 networks with Protected Management Frames (PMF/802.11w). Politician implements modern alternatives:

Mode	Description	Effectiveness
ATTACK_PMKID	Extract PMKID via dummy authentication	Works on all WPA2/WPA3-Transition
ATTACK_CSA	Channel Switch Announcement injection	Bypasses PMF protections
ATTACK_DEAUTH	Legacy deauthentication (Reason 7)	WPA2 without PMF only
ATTACK_STIMULATE	QoS Null Data for sleeping clients	Non-intrusive client wake-up
ATTACK_PASSIVE	Listen-only mode	Zero transmission
ATTACK_ALL	Enable all active attack vectors	Maximum aggression

Installation

PlatformIO

Add to your platformio.ini:

[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

Arduino IDE

1. Download the library as a ZIP file
2. In Arduino IDE: Sketch → Include Library → Add .ZIP Library
3. Select the downloaded ZIP file

ESP-IDF

Clone the repository into your project's components/ directory:

cd components/
git clone https://github.com/0ldev/Politician.git

Create a components/Politician/CMakeLists.txt component descriptor:

idf_component_register(
    SRCS
        "src/Politician.cpp"
        "src/PoliticianFormat.cpp"
        "src/PoliticianStress.cpp"
    INCLUDE_DIRS "src"
)

PoliticianStorage.h is not available under ESP-IDF — it emits a #error at compile time if included outside Arduino. Use ESP-IDF's VFS and nvs_flash APIs directly for any persistence you need.

Quick Start

Basic Handshake Capture

#include <Arduino.h>
#include <SD.h>
#include <Politician.h>
#include <PoliticianStorage.h>

using namespace politician;
using namespace politician::storage;

Politician engine;

void onHandshake(const HandshakeRecord &rec) {
    Serial.printf("\n[✓] Captured: %s  ch%d  rssi=%d  type=%d\n",
                  rec.ssid, rec.channel, rec.rssi, rec.type);
    // Primary output: PCAPNG — open in Wireshark or convert with hcxpcapngtool
    PcapngFileLogger::append(SD, "/captures.pcapng", rec);
}

void setup() {
    Serial.begin(115200);
    SD.begin();

    engine.setEapolCallback(onHandshake);

    Config cfg;
    engine.begin(cfg);
    engine.setAttackMask(ATTACK_ALL);
}

void loop() {
    engine.tick();
}

Bare ESP-IDF Quick Start

Under ESP-IDF, begin() calls esp_wifi_init() internally but expects NVS and the default event loop to already be initialized. Call those before begin(), then drive the engine from a FreeRTOS task.

#include <nvs_flash.h>
#include <esp_event.h>
#include <freertos/FreeRTOS.h>
#include <freertos/task.h>
#include <Politician.h>

using namespace politician;

static Politician engine;

static void on_handshake(const HandshakeRecord &rec) {
    printf("[+] Captured: %s  ch%d  rssi=%d  type=%d\n",
           rec.ssid, rec.channel, rec.rssi, rec.type);
}

static void audit_task(void *) {
    Config cfg;
    engine.setEapolCallback(on_handshake);

    if (engine.begin(cfg) != OK) {
        printf("[!] WiFi init failed\n");
        vTaskDelete(nullptr);
        return;
    }

    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);
}

API Reference

Politician Class

The main engine class. Must call tick() in your main loop.

Initialization

Error begin(const Config& cfg = Config());

Initialize the engine. Returns OK on success or an Error code on failure. Must be called before any other method.

Configuration Structure