
最新の802.11技術を活用したESP32向けの最新WiFi監査ライブラリ。PMKID抽出とCSAインジェクション(PMF回避)によりWPA/WPA2/WPA3ハンドシェイクをキャプチャ。エンタープライズ認証情報を収集し、デュアルバンド(ESP32-C6で2.4GHz/5GHz)に対応、PCAPNG/Hashcatにエクスポート。クリーンなC++ API、9つのサンプル付き。
ESP32マイクロコントローラ向けの高度なWiFi監査ライブラリ
Politicianは、ESP32プラットフォーム上でのWiFiセキュリティ監査向けに設計された組み込みC++ライブラリです。高度な802.11プロトコル技術を用いて、WPA/WPA2/WPA3ハンドシェイクのキャプチャやエンタープライズ認証情報の収集を行うための、クリーンでモダンなAPIを提供します。
ClientFoundCb は (const uint8_t *bssid, const uint8_t *sta, int8_t rssi) から (const ClientRecord &rec) に変更されました。既存のコールバックを更新してください:
// Before
engine.setClientFoundCallback([](const uint8_t *bssid, const uint8_t *sta, int8_t rssi) { … });
// After
engine.setClientFoundCallback([](const ClientRecord &rec) {
// rec.bssid, rec.sta, rec.rssi — same data plus rand_mac, vendor, timestamps
});
このライブラリは、チャネルホッピング、ターゲット選択、攻撃実行、キャプチャ処理を管理するノンブロッキングステートマシンを中心に構築されています。すべての操作は politician 名前空間内に含まれます。
| ヘッダー | 説明 |
|---|---|
Politician.h | メインエンジンクラス — すべてのプロジェクトでこれをインクルード |
PoliticianTypes.h | 公開構造体、列挙型、コンパイル時機能ゲート |
PoliticianStorage.h | SDカードロガーとNVS永続化(Arduinoのみ) |
PoliticianFormat.h | PCAPNGおよびHC22000のシリアライズプリミティブ |
PoliticianStress.h | オプトインのDoSペイロード(SAEフラッド、プローブフラッド、ビーコンフラッド) |
PoliticianProbe.h | 隠しSSIDプロービング用のオプトインPROGMEMワードリスト |
PoliticianWPS.h | オプトインのWPS M1出力ヘルパーとビットマスク定数 |
PoliticianSense.h | オプトインのRSSIベースのパッシブモーション・プレゼンスセンシング |
| モード | ビット | 説明 |
|---|---|---|
ATTACK_PMKID | 0x01 | 偽のアソシエーションによるPMKIDフィッシング |
ATTACK_CSA | 0x02 | Channel Switch Announcementインジェクション |
ATTACK_PASSIVE | 0x04 | リッスンのみ — 送信ゼロ |
ATTACK_DEAUTH | 0x08 | クラシックなReason-7デアソシエーション |
ATTACK_STIMULATE | 0x10 | QoS Null Dataによるクライアント刺激 |
ATTACK_BTM | 0x20 | 802.11v BSS Transition Management Request |
ATTACK_ALL | 0x3F | すべてのアクティブ攻撃ベクター |
Politician.h をインクルードする前に、またはビルドシステム経由(-DNAME)で、以下のいずれかを定義してください:
; platformio.ini
build_flags =
-DPOLITICIAN_NO_DB ; Strip 14KB OUI database (no vendor lookups)
-DPOLITICIAN_NO_PCAPNG ; Strip PCAPNG serialization
-DPOLITICIAN_NO_HC22000 ; Strip Hashcat HC22000 formatter
-DPOLITICIAN_NO_LOGGING ; Strip all internal Serial log output
-DPOLITICIAN_NO_STD_FUNCTION ; Use raw fn pointers instead of std::function
-DPOLITICIAN_NO_MSCHAPV2 ; Strip bare EAP-MSCHAPv2 capture
-DPOLITICIAN_NO_KARMA ; Strip KARMA rogue AP responder
-DPOLITICIAN_MAX_INSTANCES=1 ; Limit to one instance (saves a pointer array slot)
POLITICIAN_NO_STD_FUNCTION は、すべてのコールバック型を std::function<> から生の関数ポインタに戻します。これにより約2KBのフラッシュメモリを節約でき、<functional> がない環境でも使用できるようになります。このフラグを設定すると、ラムダのキャプチャは使用できません。
POLITICIAN_MAX_INSTANCES(デフォルトは 2)は、プロミスキャスなISRディスパッチャが使用する静的インスタンスレジストリのサイズを制御します。単一インスタンスのデプロイでは 1 に設定すると、ISR内のループオーバーヘッドを排除できます。
[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
プロジェクトの components/ ディレクトリにクローンし、CMakeLists.txt を作成します:
idf_component_register(
SRCS "src/Politician.cpp" "src/PoliticianFormat.cpp" "src/PoliticianStress.cpp"
INCLUDE_DIRS "src"
)
PoliticianStorage.hは Arduino 専用であり、ESP-IDF では#errorを出力します。ESP-IDF の VFS とnvs_flashAPI を直接使用してください。
#include <Arduino.h>
#include <SD.h>
#include <Politician.h>
#include <PoliticianStorage.h>
using namespace politician;
using namespace politician::storage;
Politician engine;
PcapngFileLogger pcap; // Streaming logger — one open(), many write() calls
void onHandshake(const HandshakeRecord &rec) {
Serial.printf("[✓] %s ch%d rssi=%d type=%d\n",
rec.ssid, rec.channel, rec.rssi, rec.type);
pcap.write(rec);
}
void setup() {
Serial.begin(115200);
SD.begin();
pcap.open(SD, "/captures.pcapng", 4 * 1024 * 1024); // optional auto-rotation at 4MB
engine.setEapolCallback(onHandshake);
engine.begin();
engine.setAttackMask(ATTACK_ALL);
}
void loop() {
engine.tick();
}
#include <nvs_flash.h>
#include <esp_event.h>
#include <Politician.h>
using namespace politician;
static Politician engine;
static void audit_task(void *) {
engine.setEapolCallback([](const HandshakeRecord &rec) {
printf("[+] %s ch%d\n", rec.ssid, rec.channel);
});
engine.begin();
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);
}
Error begin(const Config &cfg = Config());
WiFiドライバをプロミスキャスモードで初期化します。他のどのメソッドよりも前に呼び出す必要があります。起動時に無効なConfig値をクランプし、警告を出します。現場に展開する前に設定の誤りを明らかにするには、事前にvalidateConfig()を使用してください:
Config cfg;
cfg.hop_min_dwell_ms = 400;
cfg.hop_max_dwell_ms = 200; // wrong — min > max
const char *warnings[8];
int n = politician::validateConfig(cfg, warnings, 8);
for (int i = 0; i < n; i++) Serial.println(warnings[i]);
// → "hop_min_dwell_ms >= hop_max_dwell_ms — max will be clamped to min+50ms"
engine.begin(cfg); // begins normally; begin() clamps automatically
validateConfig() は politician 名前空間内の無料のインライン関数です — アロケーションゼロ、依存関係ゼロ。
begin() は、min + 50 ms の補正後に最小ドウェル時間を表現できないスマートホッピング設定を拒否します。すでに初期化されたエンジンに対して begin() を呼び出すと、まず前のランタイムが停止されるため、再開始は決定的です。stop() を複数回呼び出しても安全です。キャプチャを無効化し、インスタンスの登録を解除し、ワーカーリソースを解放します。デストラクタもアクティブなエンジンを停止します。WiFi ドライバの所有権はプロセス全体にわたり、後のインスタンスによって再利用されます。
struct Config {
// ── Channel Hopping ──────────────────────────────────────────────────────
uint16_t hop_dwell_ms = 200; // Static dwell time per channel (ms)
bool smart_hopping = true; // Dynamic dwell based on traffic activity
uint16_t hop_min_dwell_ms = 50; // Minimum dwell (smart hopping floor)
uint16_t hop_max_dwell_ms = 400; // Maximum dwell (smart hopping ceiling)
uint32_t m1_lock_ms = 800; // Stay on channel after seeing M1 (ms)
// ── PMKID Fishing ────────────────────────────────────────────────────────
uint32_t fish_timeout_ms = 2000; // Timeout per PMKID association attempt
uint8_t fish_max_retries = 2; // PMKID retries before pivoting to CSA