Politician

Una biblioteca de auditoría WiFi sofisticada para microcontroladores ESP32

Politician es una biblioteca C++ embebida diseñada para la auditoría de seguridad WiFi en plataformas ESP32. Proporciona una API limpia y moderna para capturar handshakes WPA/WPA2/WPA3 y recolectar credenciales empresariales utilizando técnicas avanzadas del protocolo 802.11.

Capacidades Clave

• Captura de PMKID: Extrae PMKIDs de respuestas de asociación sin desconexión del cliente
• Inyección CSA (Anuncio de Cambio de Canal): Alternativa moderna a los ataques de desautenticación
• Recolección de Credenciales Empresariales: Captura tramas EAP-Identity de redes 802.1X
• Descubrimiento de Redes Ocultas: Desenmascaramiento automático de SSID mediante interceptación de respuestas de sonda
• Huella de Dispositivos: Identifica pasivamente más de 150 marcas de dispositivos IoT/domótica mediante OUI MAC y firmas IE sin asociación a la red
• Estimulación de Clientes: Activa dispositivos móviles en reposo usando tramas QoS Null Data
• Detección de WPA3/PMF: Filtrado inteligente para omitir redes con Tramas de Gestión Protegidas habilitadas
• Formatos de Exportación: Archivos de captura PCAPNG; exportación opcional de texto HC22000 para ingestión directa en Hashcat

Arquitectura

La biblioteca está construida alrededor de una máquina de estados no bloqueante que gestiona el salto de canales, la selección de objetivos, la ejecución de ataques y el procesamiento de capturas. Todas las operaciones están contenidas dentro del espacio de nombres politician.

Componentes Principales

Componente	Descripción
Politician	Clase del motor principal que gestiona el ciclo de vida de la auditoría
PoliticianFormat	Serialización de capturas PCAPNG; exportación auxiliar de texto HC22000
PoliticianStorage	Registro opcional en tarjeta SD y persistencia NVS
PoliticianStress	Entrega de payloads DoS/perturbación desacoplada (opt-in)
PoliticianTypes	Estructuras de datos y enumeraciones principales

Modos de Ataque

Los ataques de desautenticación tradicionales son ineficaces contra redes modernas WPA3 y WPA2 con Tramas de Gestión Protegidas (PMF/802.11w). Politician implementa alternativas modernas:

Modo	Descripción	Efectividad
ATTACK_PMKID	Extrae PMKID mediante autenticación ficticia	Funciona en todas las transiciones WPA2/WPA3
ATTACK_CSA	Inyección de Anuncio de Cambio de Canal	Evita las protecciones PMF
ATTACK_DEAUTH	Desautenticación heredada (Reason 7)	Solo WPA2 sin PMF
ATTACK_STIMULATE	QoS Null Data para clientes en reposo	Activación de cliente no intrusiva
ATTACK_PASSIVE	Modo solo escucha	Transmisión cero
ATTACK_ALL	Habilita todos los vectores de ataque activos	Agresión máxima

Instalación

PlatformIO

Añade a tu platformio.ini:```ini [env:myboard] platform = espressif32 board = esp32dev framework = arduino lib_deps = Politician

O clona directamente en el directorio `lib/` de tu proyecto:```bash
cd lib/
git clone https://github.com/0ldev/Politician.git

Arduino IDE

1. Descarga la biblioteca como un archivo ZIP
2. En Arduino IDE: Sketch → Incluir Librería → Añadir Librería .ZIP
3. Selecciona el archivo ZIP descargado

ESP-IDF

Clona el repositorio en el directorio components/ de tu proyecto:```bash cd components/ git clone https://github.com/0ldev/Politician.git

Crear un descriptor de componente `components/Politician/CMakeLists.txt`:```cmake
idf_component_register(
    SRCS
        "src/Politician.cpp"
        "src/PoliticianFormat.cpp"
        "src/PoliticianStress.cpp"
    INCLUDE_DIRS "src"
)

PoliticianStorage.h no está disponible en ESP-IDF — emite un #error en tiempo de compilación si se incluye fuera de Arduino. Usa las APIs VFS y nvs_flash de ESP-IDF directamente para cualquier persistencia que necesites.

Inicio Rápido

Captura Básica de 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(); }

### Inicio rápido con ESP-IDF básico

En ESP-IDF, `begin()` llama a `esp_wifi_init()` internamente, pero espera que NVS y el bucle de eventos predeterminado ya estén inicializados. Llama a esos antes de `begin()`, luego ejecuta el motor desde una tarea de 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);
}

Referencia de la API

Clase Politician

La clase principal del motor. Debe llamar a tick() en su bucle principal.

Inicialización```cpp

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

Inicializa el motor. Devuelve `OK` en caso de éxito o un código `Error` en caso de fallo. Debe ser llamado antes de cualquier otro método.