|
Politician 1.0.0
WiFi Auditing Library for ESP32
|
Namespaces | |
| namespace | fingerprint |
| namespace | format |
| namespace | PoliticianWPS |
| namespace | probe |
| namespace | storage |
| namespace | stress |
| PoliticianStress: Decoupled DoS / Disruption Payload Delivery System. | |
Classes | |
| struct | __attribute__ |
| struct | ApRecord |
| Snapshot of a discovered Access Point from the internal cache. More... | |
| struct | AttackResultRecord |
| Identifies the AP and failure reason for a failed attack, delivered to the AttackResultCb callback. More... | |
| struct | ClientRecord |
| Snapshot of a client station observed associated with an AP. More... | |
| struct | Config |
| Configuration for the Politician engine. More... | |
| struct | DeviceFingerprint |
| One fingerprint entry in the built-in or user-defined database. More... | |
| struct | DeviceRecord |
| A matched device, delivered to the DeviceFoundCb callback. More... | |
| struct | DisruptRecord |
| A deauthentication or disassociation frame observed on the air, delivered to the DisruptCb callback. More... | |
| struct | EapIdentityRecord |
| A harvested 802.1X Enterprise plaintext identity, delivered to the IdentityCb callback. More... | |
| struct | HandshakeRecord |
| A captured handshake or PMKID record delivered to the EapolCb callback. More... | |
| union | HandshakeRecord.__unnamed3__ |
| union | HandshakeRecord.__unnamed5__ |
| struct | KarmaRecord |
| Delivered to the KarmaCb callback when the KARMA responder replies to a named probe request. More... | |
| struct | MsChapRecord |
| Bare EAP-MSCHAPv2 challenge/response pair harvested passively. More... | |
| class | Politician |
| The core WiFi handshake capturing engine. More... | |
| class | PoliticianSense |
| Passive RSSI-based motion and presence detector. More... | |
| struct | ProbeRequestRecord |
| A probe request frame observed on the air, delivered to the ProbeRequestCb callback. More... | |
| struct | RogueApRecord |
| Fired when a second BSSID advertising the same SSID is observed on the same channel. More... | |
| struct | Stats |
| Cumulative frame and capture counters for the engine session. More... | |
| struct | WpsRecord |
| WPS M1 device attributes harvested from an EAP-WSC exchange. More... | |
Typedefs | |
| using | SenseCb = std::function< void(SenseEvent event, float variance)> |
| Callback fired on SENSE_STILL ↔ SENSE_MOTION transitions. | |
| using | LogCb = std::function< void(const char *msg)> |
| typedef void(* | ApFoundCb) (const ApRecord &ap) |
| typedef int(* | TargetScoreCb) (const ApRecord &ap, const char *vendor) |
| typedef void(* | PacketCb) (const uint8_t *payload, uint16_t len, int8_t rssi, uint8_t channel, uint32_t ts_usec) |
| typedef void(* | EapolCb) (const HandshakeRecord &rec) |
| typedef void(* | IdentityCb) (const EapIdentityRecord &rec) |
| typedef void(* | ProbeRequestCb) (const ProbeRequestRecord &rec) |
| typedef void(* | DisruptCb) (const DisruptRecord &rec) |
| typedef void(* | WpsCb) (const WpsRecord &rec) |
| typedef void(* | MsChapCb) (const MsChapRecord &rec) |
| typedef void(* | AttackResultCb) (const AttackResultRecord &rec) |
| typedef void(* | ClientFoundCb) (const ClientRecord &rec) |
| using | RogueApCb = std::function< void(const RogueApRecord &rec)> |
| using | KarmaCb = std::function< void(const KarmaRecord &rec)> |
Enumerations | |
| enum | SenseEvent : uint8_t { SENSE_MOTION = 0 , SENSE_STILL = 1 } |
| State transition delivered to the SenseCb callback. More... | |
| enum | Error { OK = 0 , ERR_WIFI_INIT = 1 , ERR_INVALID_CH = 2 , ERR_NOT_ACTIVE = 3 , ERR_ALREADY_CAPTURED = 4 , ERR_NOT_FOUND = 5 , ERR_MAX_INSTANCES = 6 , ERR_INVALID_ARG = 7 , ERR_QUEUE_FULL = 8 } |
| enum | DisconnectStrategy : uint8_t { STRATEGY_AUTO_FALLBACK = 0 , STRATEGY_SIMULTANEOUS = 1 } |
| enum | AttackResult : uint8_t { RESULT_PMKID_EXHAUSTED = 1 , RESULT_CSA_EXPIRED = 2 } |
Functions | |
| static bool | isValidChannel (uint8_t ch) |
| int | validateConfig (const Config &cfg, const char **out, uint8_t maxOut) |
| Validates a Config struct and returns human-readable warning strings for values that will be silently clamped or that may cause unexpected behavior. | |
Variables | |
| static const uint8_t | CHANNEL_5GHZ_COMMON [] |
| static const uint8_t | CIPHER_UNKNOWN = 0 |
| static const uint8_t | CIPHER_TKIP = 1 |
| TKIP (00-0F-AC:2) — legacy, crackable offline. | |
| static const uint8_t | CIPHER_CCMP = 2 |
| CCMP/AES (00-0F-AC:4) — current standard. | |
| static const uint8_t | EAP_METHOD_IDENTITY = 0x01 |
| EAP Identity (always 0x01 for harvested records) | |
| static const uint8_t | EAP_METHOD_TLS = 0x0D |
| EAP-TLS (RFC 5216) — mutual cert auth. | |
| static const uint8_t | EAP_METHOD_TTLS = 0x15 |
| EAP-TTLS (RFC 5281) — outer tunnel, inner MSCHAPv2. | |
| static const uint8_t | EAP_METHOD_PEAP = 0x19 |
| PEAP (draft-josefsson-pppext-eap-tls-eap) — outer tunnel. | |
| static const uint8_t | EAP_METHOD_MSCHAPV2 = 0x1A |
| Bare EAP-MSCHAPv2 (no tunnel — crackable) | |
| struct politician::__attribute__ |
Definition at line 43 of file Politician.h.
| Class Members | ||
|---|---|---|
| uint8_t | addr1[6] | |
| uint8_t | addr2[6] | |
| uint8_t | addr3[6] | |
| uint16_t | duration | |
| uint16_t | frame_ctrl | |
| ieee80211_hdr_t | hdr | |
| uint8_t | payload[0] | |
| uint16_t | seq_ctrl | |
| struct politician::ApRecord |
Snapshot of a discovered Access Point from the internal cache.
Populated by getAp(), getApByBssid(), and the ApFoundCb callback.
Definition at line 189 of file PoliticianTypes.h.
| Class Members | ||
|---|---|---|
| uint16_t | beacon_count | Number of beacons observed from this AP in the current session. |
| uint16_t | beacon_interval | |
| uint8_t | bssid[6] | |
| uint8_t | capture_count | Number of successful handshake/PMKID captures for this BSSID. |
| bool | captured | |
| uint8_t | chan_util | |
| uint8_t | chan_width | |
| uint8_t | channel | |
| char | country[3] | |
| uint8_t | enc | |
| uint32_t | first_seen_ms | |
| bool | ft_capable | |
| bool | is_he | |
| bool | is_hidden | |
| bool | is_vht | |
| uint32_t | last_attack_ms | millis() of the most recent attack initiation (0 = never attacked) |
| uint32_t | last_seen_ms | |
| uint8_t | max_rate_mbps | |
| uint8_t | network_type | |
| bool | pmf_capable | |
| bool | pmf_required | |
| int8_t | rssi | |
| char | ssid[33] | |
| uint8_t | ssid_len | |
| uint16_t | sta_count | |
| uint8_t | total_attempts | |
| uint8_t | venue_group | |
| uint8_t | venue_type | |
| bool | wps_enabled | |
| struct politician::AttackResultRecord |
Identifies the AP and failure reason for a failed attack, delivered to the AttackResultCb callback.
Definition at line 297 of file PoliticianTypes.h.
| Class Members | ||
|---|---|---|
| uint8_t | bssid[6] | |
| AttackResult | result | |
| char | ssid[33] | |
| uint8_t | ssid_len | |
| struct politician::ClientRecord |
Snapshot of a client station observed associated with an AP.
Delivered to the ClientFoundCb callback and enriched with vendor lookup, timing, and MAC-randomization detection.
Definition at line 311 of file PoliticianTypes.h.
| Class Members | ||
|---|---|---|
| uint8_t | bssid[6] | BSSID of the AP this client is associated with. |
| uint32_t | first_seen_ms | millis() when this client was first seen on this BSSID |
| uint32_t | last_seen_ms | millis() of the most recent frame from this client |
| bool | rand_mac | True if the locally administered bit is set (MAC randomization) |
| int8_t | rssi | Signal strength at time of observation (dBm) |
| uint8_t | sta[6] | Client (station) MAC address. |
| char | vendor[32] | OUI vendor string; empty if POLITICIAN_NO_DB is defined. |
| struct politician::Config |
Configuration for the Politician engine.
Definition at line 106 of file PoliticianTypes.h.
| Class Members | ||
|---|---|---|
| uint32_t | ap_expiry_ms = 300000 | |
| uint8_t | btm_burst_count = 8 | |
| uint16_t | btm_disassoc_timer = 3 | |
| uint8_t | capture_filter = LOG_FILTER_HANDSHAKES | LOG_FILTER_PROBES | |
| bool | capture_group_keys = false | |
| bool | capture_half_handshakes = false | |
| uint8_t | csa_beacon_count = 8 | |
| uint8_t | csa_deauth_count = 15 | |
| uint32_t | csa_wait_ms = 4000 | |
| uint8_t | deauth_burst_count = 16 | |
| uint8_t | deauth_reason = 7 | |
| bool | deauth_reason_cycling = true | |
| uint8_t | enc_filter_mask = 0xFF | |
| uint8_t | fish_max_retries = 2 | |
| uint32_t | fish_timeout_ms = 2000 | |
| uint16_t | hop_dwell_ms = 200 | |
| uint16_t | hop_max_dwell_ms = 400 | |
| uint16_t | hop_min_dwell_ms = 50 | |
| bool | karma_enabled = false | |
| uint8_t | karma_max_ssids = 16 | |
| bool | karma_open_only = true | |
| uint32_t | m1_lock_ms = 800 | |
| uint8_t | max_total_attempts = 0 | |
| uint8_t | min_beacon_count = 0 | |
| int8_t | min_rssi = -100 | |
| uint16_t | probe_aggr_interval_s = 30 | |
| uint32_t | probe_hidden_interval_ms = 0 | |
| bool | require_active_clients = false | |
| uint32_t | session_timeout_ms = 60000 | |
| bool | skip_immune_networks = true | |
| bool | smart_hopping = true | |
| const char * | soft_ap_ssid = nullptr | |
| char | ssid_filter[33] = {} | |
| bool | ssid_filter_exact = true | |
| uint8_t | sta_filter[6] = {} | |
| bool | unicast_deauth = true | |
| struct politician::DeviceFingerprint |
One fingerprint entry in the built-in or user-defined database.
Definition at line 470 of file PoliticianTypes.h.
| struct politician::DeviceRecord |
A matched device, delivered to the DeviceFoundCb callback.
Definition at line 485 of file PoliticianTypes.h.
| Class Members | ||
|---|---|---|
| uint8_t | channel | |
| uint8_t | confidence | |
| uint8_t | mac[6] | |
| uint8_t | match_flags | |
| char | model[32] | |
| int8_t | rssi | |
| char | vendor[32] | |
| struct politician::DisruptRecord |
A deauthentication or disassociation frame observed on the air, delivered to the DisruptCb callback.
Definition at line 399 of file PoliticianTypes.h.
| Class Members | ||
|---|---|---|
| uint8_t | bssid[6] | |
| uint8_t | channel | |
| uint8_t | dst[6] | |
| bool | rand_mac | |
| uint16_t | reason | |
| int8_t | rssi | |
| uint8_t | src[6] | |
| uint8_t | subtype | |
| struct politician::EapIdentityRecord |
A harvested 802.1X Enterprise plaintext identity, delivered to the IdentityCb callback.
Definition at line 377 of file PoliticianTypes.h.
| Class Members | ||
|---|---|---|
| uint8_t | bssid[6] | |
| uint8_t | channel | |
| uint8_t | client[6] | |
| uint8_t | eap_method | EAP method negotiated by the AP (EAP_METHOD_* constant); 0 if not yet observed. |
| char | identity[65] | |
| int8_t | rssi | |
| struct politician::HandshakeRecord |
A captured handshake or PMKID record delivered to the EapolCb callback.
The type field identifies the capture path; fields not relevant to that path are zeroed.
Definition at line 247 of file PoliticianTypes.h.
| Class Members | ||
|---|---|---|
| union HandshakeRecord.__unnamed3__ | __unnamed__ | |
| union HandshakeRecord.__unnamed5__ | __unnamed__ | |
| uint8_t | anonce[32] | |
| uint8_t | bssid[6] | |
| uint8_t | channel | |
| uint8_t | cipher | Pairwise cipher suite: CIPHER_TKIP / CIPHER_CCMP / CIPHER_UNKNOWN. |
| uint8_t | eapol_m3[256] | |
| uint16_t | eapol_m3_len | |
| uint8_t | eapol_m4[256] | |
| uint16_t | eapol_m4_len | |
| uint8_t | enc | |
| bool | has_anonce | |
| bool | has_m3 | |
| bool | has_m4 | |
| bool | has_mic | |
| bool | has_snonce | |
| bool | is_full | |
| uint8_t | mic[16] | |
| uint8_t | pmkid[16] | |
| int8_t | rssi | |
| uint8_t | sae_seq | |
| uint8_t | snonce[32] | |
| char | ssid[33] | |
| uint8_t | ssid_len | |
| uint8_t | sta[6] | |
| uint8_t | type | |
| union politician::HandshakeRecord.__unnamed3__ |
Definition at line 263 of file PoliticianTypes.h.
| Class Members | ||
|---|---|---|
| uint8_t | eapol_m2[256] | |
| uint8_t | sae_data[256] | |
| union politician::HandshakeRecord.__unnamed5__ |
Definition at line 269 of file PoliticianTypes.h.
| Class Members | ||
|---|---|---|
| uint16_t | eapol_m2_len | |
| uint16_t | sae_len | |
| struct politician::KarmaRecord |
Delivered to the KarmaCb callback when the KARMA responder replies to a named probe request.
Contains the client that probed and the SSID that was echoed.
The engine injects a probe response and one beacon spoofed as an AP with that exact SSID and an open authentication mode, enticing the client to auto-associate.
Definition at line 352 of file PoliticianTypes.h.
| Class Members | ||
|---|---|---|
| uint8_t | ap_mac[6] | |
| uint8_t | channel | |
| uint8_t | client[6] | |
| int8_t | rssi | |
| char | ssid[33] | |
| uint8_t | ssid_len | |
| struct politician::MsChapRecord |
Bare EAP-MSCHAPv2 challenge/response pair harvested passively.
Only available when the AP serves MSCHAPv2 without a TLS tunnel (no PEAP/TTLS). The nt_response can be cracked offline with tools like asleap or hashcat (-m 5500).
Crack with hashcat: echo "username::::peer_challenge_hex:nt_response_hex:server_challenge_hex" | hashcat -m 5500
Definition at line 442 of file PoliticianTypes.h.
| Class Members | ||
|---|---|---|
| uint8_t | bssid[6] | |
| uint8_t | channel | |
| uint8_t | nt_response[24] | |
| uint8_t | peer_challenge[16] | |
| int8_t | rssi | |
| uint8_t | server_challenge[16] | |
| uint8_t | sta[6] | |
| char | username[65] | |
| struct politician::ProbeRequestRecord |
A probe request frame observed on the air, delivered to the ProbeRequestCb callback.
Definition at line 388 of file PoliticianTypes.h.
| Class Members | ||
|---|---|---|
| uint8_t | channel | |
| uint8_t | client[6] | |
| bool | rand_mac | |
| int8_t | rssi | |
| char | ssid[33] | |
| uint8_t | ssid_len | |
| struct politician::RogueApRecord |
Fired when a second BSSID advertising the same SSID is observed on the same channel.
This indicates a potential evil twin or rogue AP. Both the known AP and the newcomer are included.
Definition at line 327 of file PoliticianTypes.h.
| Class Members | ||
|---|---|---|
| uint8_t | channel | |
| uint8_t | known_bssid[6] | |
| uint8_t | rogue_bssid[6] | |
| int8_t | rssi | |
| char | ssid[33] | |
| uint8_t | ssid_len | |
| struct politician::Stats |
Cumulative frame and capture counters for the engine session.
Accessible via getStats(), reset with resetStats().
Definition at line 223 of file PoliticianTypes.h.
| struct politician::WpsRecord |
WPS M1 device attributes harvested from an EAP-WSC exchange.
Delivered to the WpsCb callback when a WPS Enrollee sends its M1 message. Only M1 (Enrollee → AP) is unencrypted; subsequent messages cannot be parsed passively.
Definition at line 416 of file PoliticianTypes.h.
| typedef void(* politician::ApFoundCb) (const ApRecord &ap) |
Definition at line 77 of file PoliticianTypes.h.
| typedef void(* politician::AttackResultCb) (const AttackResultRecord &rec) |
Definition at line 304 of file PoliticianTypes.h.
| typedef void(* politician::ClientFoundCb) (const ClientRecord &rec) |
Definition at line 321 of file PoliticianTypes.h.
| typedef void(* politician::DisruptCb) (const DisruptRecord &rec) |
Definition at line 83 of file PoliticianTypes.h.
| typedef void(* politician::EapolCb) (const HandshakeRecord &rec) |
Definition at line 80 of file PoliticianTypes.h.
| typedef void(* politician::IdentityCb) (const EapIdentityRecord &rec) |
Definition at line 81 of file PoliticianTypes.h.
| using politician::KarmaCb = typedef std::function<void(const KarmaRecord &rec)> |
Definition at line 362 of file PoliticianTypes.h.
| using politician::LogCb = typedef std::function<void(const char *msg)> |
Definition at line 61 of file PoliticianTypes.h.
| typedef void(* politician::MsChapCb) (const MsChapRecord &rec) |
Definition at line 86 of file PoliticianTypes.h.
| typedef void(* politician::PacketCb) (const uint8_t *payload, uint16_t len, int8_t rssi, uint8_t channel, uint32_t ts_usec) |
Definition at line 79 of file PoliticianTypes.h.
| typedef void(* politician::ProbeRequestCb) (const ProbeRequestRecord &rec) |
Definition at line 82 of file PoliticianTypes.h.
| using politician::RogueApCb = typedef std::function<void(const RogueApRecord &rec)> |
Definition at line 337 of file PoliticianTypes.h.
| using politician::SenseCb = typedef std::function<void(SenseEvent event, float variance)> |
Callback fired on SENSE_STILL ↔ SENSE_MOTION transitions.
Definition at line 88 of file PoliticianSense.h.
| typedef int(* politician::TargetScoreCb) (const ApRecord &ap, const char *vendor) |
Definition at line 78 of file PoliticianTypes.h.
| typedef void(* politician::WpsCb) (const WpsRecord &rec) |
Definition at line 84 of file PoliticianTypes.h.
| enum politician::AttackResult : uint8_t |
| Enumerator | |
|---|---|
| RESULT_PMKID_EXHAUSTED | |
| RESULT_CSA_EXPIRED | |
Definition at line 291 of file PoliticianTypes.h.
| enum politician::DisconnectStrategy : uint8_t |
| Enumerator | |
|---|---|
| STRATEGY_AUTO_FALLBACK | |
| STRATEGY_SIMULTANEOUS | |
Definition at line 285 of file PoliticianTypes.h.
| enum politician::Error |
Definition at line 90 of file PoliticianTypes.h.
| enum politician::SenseEvent : uint8_t |
State transition delivered to the SenseCb callback.
| Enumerator | |
|---|---|
| SENSE_MOTION | RSSI variance spiked above threshold — movement detected. |
| SENSE_STILL | RSSI variance returned to baseline — area quiet. |
Definition at line 80 of file PoliticianSense.h.
|
static |
Definition at line 26 of file Politician.cpp.
References CHANNEL_5GHZ_COMMON.
Referenced by politician::Politician::setChannel(), and politician::Politician::setChannelList().
|
inline |
Validates a Config struct and returns human-readable warning strings for values that will be silently clamped or that may cause unexpected behavior.
Call this before engine.begin(cfg) to surface misconfigurations early.
| cfg | The Config to validate. |
| out | Output array; each element is set to a static warning string. |
| maxOut | Capacity of out. |
Example:
Definition at line 165 of file PoliticianTypes.h.
References politician::Config::csa_beacon_count, politician::Config::csa_wait_ms, politician::Config::deauth_burst_count, politician::Config::fish_timeout_ms, politician::Config::hop_dwell_ms, politician::Config::hop_max_dwell_ms, politician::Config::hop_min_dwell_ms, politician::Config::min_rssi, politician::Config::probe_aggr_interval_s, and politician::Config::smart_hopping.
|
static |
Definition at line 20 of file Politician.cpp.
Referenced by isValidChannel(), and politician::Politician::setChannelBands().
|
static |
CCMP/AES (00-0F-AC:4) — current standard.
Definition at line 244 of file PoliticianTypes.h.
|
static |
TKIP (00-0F-AC:2) — legacy, crackable offline.
Definition at line 243 of file PoliticianTypes.h.
|
static |
Definition at line 242 of file PoliticianTypes.h.
|
static |
EAP Identity (always 0x01 for harvested records)
Definition at line 370 of file PoliticianTypes.h.
|
static |
Bare EAP-MSCHAPv2 (no tunnel — crackable)
Definition at line 374 of file PoliticianTypes.h.
|
static |
PEAP (draft-josefsson-pppext-eap-tls-eap) — outer tunnel.
Definition at line 373 of file PoliticianTypes.h.
|
static |
EAP-TLS (RFC 5216) — mutual cert auth.
Definition at line 371 of file PoliticianTypes.h.
|
static |
EAP-TTLS (RFC 5281) — outer tunnel, inner MSCHAPv2.
Definition at line 372 of file PoliticianTypes.h.