Politician

Uma biblioteca sofisticada de auditoria WiFi para microcontroladores ESP32

O Politician é uma biblioteca C++ embarcada projetada para auditoria de segurança WiFi em plataformas ESP32. Ela fornece uma API limpa e moderna para capturar handshakes WPA/WPA2/WPA3 e colher credenciais empresariais usando técnicas avançadas de protocolo 802.11.

Capacidades Principais

• Captura de PMKID: Extrair PMKIDs de respostas de associação sem desconexão do cliente
• Injeção de CSA (Channel Switch Announcement): Alternativa moderna a ataques de desautenticação
• Colheita de Credenciais Empresariais: Capturar quadros EAP-Identity de redes 802.1X
• Descoberta de Redes Ocultas: Desmascaramento automático de SSID via interceptação de respostas de probe
• Impressão Digital de Dispositivos: Identificar passivamente mais de 150 marcas de IoT/smart home para consumidores através de assinaturas MAC OUI e IE sem associação à rede
• Estimulação de Clientes: Acordar dispositivos móveis adormecidos usando quadros QoS Null Data
• Detecção de WPA3/PMF: Filtragem inteligente para ignorar redes com Protected Management Frames habilitados
• Formatos de Exportação: Arquivos de captura PCAPNG; exportação opcional de texto HC22000 para ingestão direta no Hashcat

Arquitetura

A biblioteca é construída em torno de uma máquina de estados não bloqueante que gerencia o salto de canais, seleção de alvos, execução de ataques e processamento de captura. Todas as operações estão contidas no namespace politician.

Componentes Principais

Componente	Descrição
Politician	Classe principal do motor que gerencia o ciclo de vida da auditoria
PoliticianFormat	Serialização de captura PCAPNG; exportação auxiliar de texto HC22000
PoliticianStorage	Registro opcional em cartão SD e persistência NVS
PoliticianStress	Entrega de payload de DoS/desrupção desacoplada (opt-in)
PoliticianTypes	Estruturas de dados e enumerações principais

Modos de Ataque

Ataques de desautenticação tradicionais são ineficazes contra redes WPA3 e WPA2 modernas com Protected Management Frames (PMF/802.11w). O Politician implementa alternativas modernas:

Modo	Descrição	Eficácia
ATTACK_PMKID	Extrair PMKID via autenticação fictícia	Funciona em todos WPA2/WPA3-Transition
ATTACK_CSA	Injeção de Channel Switch Announcement	Ignora proteções PMF
ATTACK_DEAUTH	Desautenticação legada (Reason 7)	Apenas WPA2 sem PMF
ATTACK_STIMULATE	QoS Null Data para clientes adormecidos	Acordo de cliente não intrusivo
ATTACK_PASSIVE	Modo apenas escuta	Zero transmissão
ATTACK_ALL	Habilitar todos os vetores de ataque ativos	Agressão máxima

Instalação

PlatformIO

Adicione ao seu platformio.ini:

[env:myboard]
platform = espressif32
board = esp32dev
framework = arduino
lib_deps = 
    Politician
```
Ou clone diretamente no diretório `lib/` do seu projeto:```bash
cd lib/
git clone https://github.com/0ldev/Politician.git
```
### Arduino IDE

1. Baixe a biblioteca como um arquivo ZIP
2. No Arduino IDE: **Sketch** → **Include Library** → **Add .ZIP Library**
3. Selecione o arquivo ZIP baixado

### ESP-IDF

Clone o repositório no diretório `components/` do seu projeto:```bash
cd components/
git clone https://github.com/0ldev/Politician.git
```
Crie um descritor 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` não está disponível sob ESP-IDF — ele emite um `#error` em tempo de compilação se incluído fora do Arduino. Use as APIs VFS e `nvs_flash` do ESP-IDF diretamente para qualquer persistência que você precisar.

## Início 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();
}
```
### Início Rápido com ESP-IDF Básico

No ESP-IDF, `begin()` chama `esp_wifi_init()` internamente, mas espera que NVS e o loop de eventos padrão já estejam inicializados. Chame-os antes de `begin()`, então execute o motor a partir de uma tarefa 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);
}
```
## Referência da API

### Classe Politician

A classe principal do motor. Deve chamar `tick()` no seu loop principal.

#### Inicialização```cpp
Error begin(const Config& cfg = Config());
```
Inicialize o motor. Retorna `OK` em caso de sucesso ou um código `Error` em caso de falha. Deve ser chamado antes de qualquer outro método.