一个面向 ESP32 微控制器的精密 WiFi 审计库
Politician 是一个嵌入式 C++ 库,专为 ESP32 平台上的 WiFi 安全审计而设计。它提供简洁、现代的 API,用于利用先进的 802.11 协议技术捕获 WPA/WPA2/WPA3 握手包并收集企业凭据。
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 | 信道切换通告注入 |
ATTACK_PASSIVE | 0x04 | 仅监听 — 零传输 |
ATTACK_DEAUTH | 0x08 | 经典 Reason-7 解除认证 |
ATTACK_STIMULATE | 0x10 | QoS Null Data 客户端刺激 |
ATTACK_BTM | 0x20 | 802.11v BSS 过渡管理请求 |
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 flash,并使其可在没有 <functional> 的环境中使用。设置此标志时,Lambda 捕获不可用。
POLITICIAN_MAX_INSTANCES(默认 2)控制由混杂 ISR 调度器使用的静态实例注册表的大小。对于单实例部署,将其设置为 1 以消除 ISR 中的循环开销。
[env:myboard]
platform = espressif32
board = esp32dev
framework = arduino
lib_deps =
Politician
或者直接克隆到项目的 lib/ 目录中:
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
// ── CSA / Deauth ─────────────────────────────────────────────────────────
uint32_t csa_wait_ms = 4000; // Wait window after CSA/Deauth burst (ms)
uint8_t csa_beacon_count = 8; // CSA beacon frames per burst
uint8_t csa_deauth_count = 15; // Deauth frames appended to CSA burst
uint8_t deauth_burst_count = 16; // Frames per standalone deauth burst
uint8_t deauth_reason = 7; // 802.11 reason code in deauth frames
bool deauth_reason_cycling = true; // Cycle reason codes during burst (fuzzing)
// ── 802.11v BTM ──────────────────────────────────────────────────────────
uint8_t btm_burst_count = 8; // BTM Request frames per client per trigger
uint16_t btm_disassoc_timer = 3; // Disassociation Timer in TBTTs (~300ms)