|
Politician 1.0.0
WiFi Auditing Library for ESP32
|
The core WiFi handshake capturing engine. More...
#include <Politician.h>
Classes | |
| struct | ApCacheEntry.flags |
| struct | Session.flags |
Public Types | |
| using | _FpHookCb = void(*)(const uint8_t *mac, const char *ssid, uint8_t ssid_len, uint8_t ch, int8_t rssi, const uint8_t *ie, uint16_t ie_len) |
| using | EapolCb = void(*)(const HandshakeRecord &rec) |
| using | ApFoundCb = void(*)(const ApRecord &ap) |
| using | TargetFilterCb = bool(*)(const ApRecord &ap) |
| using | TargetScoreCb = int(*)(const ApRecord &ap, const char *vendor) |
| using | PacketCb = void(*)(const uint8_t *payload, uint16_t len, int8_t rssi, uint8_t channel, uint32_t ts_usec) |
| using | IdentityCb = void(*)(const EapIdentityRecord &rec) |
| using | AttackResultCb = void(*)(const AttackResultRecord &rec) |
| using | ProbeRequestCb = void(*)(const ProbeRequestRecord &rec) |
| using | DisruptCb = void(*)(const DisruptRecord &rec) |
| using | ClientFoundCb = void(*)(const uint8_t *bssid, const uint8_t *sta, int8_t rssi) |
Public Member Functions | |
| Politician () | |
| Error | begin (const Config &cfg=Config()) |
| Initializes the WiFi driver in promiscuous mode. | |
| void | setLogger (LogCb cb) |
| Sets a custom logging callback to intercept library output. | |
| void | markCaptured (const uint8_t *bssid) |
| Manually adds a BSSID to the "already captured" list to skip it. | |
| void | clearCapturedList () |
| Clears the captured BSSID list. | |
| void | setIgnoreList (const uint8_t(*bssids)[6], uint8_t count) |
| Sets a list of BSSIDs that should always be ignored by the engine. | |
| void | setActive (bool active) |
| Enables or disables frame processing. | |
| Error | setChannel (uint8_t ch) |
| Manually sets the WiFi radio to a specific channel. | |
| void | startHopping (uint16_t dwellMs=0) |
| Starts autonomous channel hopping. | |
| void | stopHopping () |
| Stops autonomous channel hopping and goes idle. | |
| void | stop () |
| Full engine teardown. | |
| Error | lockChannel (uint8_t ch) |
| Stops hopping and locks the radio to a specific channel. | |
| void | setChannelList (const uint8_t *channels, uint8_t count) |
| Restricts hopping to a specific list of channels. | |
| void | setChannelBands (bool ghz24, bool ghz5) |
| Restricts hopping to 2.4GHz, 5GHz, or both bands. | |
| Error | setTargetBySsid (const char *ssid) |
| Searches the AP cache by SSID and locks onto the strongest match. | |
| void | tick () |
| Main worker method. | |
| void | setAttackMask (uint8_t mask) |
| Configures which attack techniques are enabled globally. | |
| void | setAttackMaskForBssid (const uint8_t *bssid, uint8_t mask) |
| Overrides the attack mask for a specific BSSID. | |
| void | clearAttackMaskOverrides () |
| Clears all per-BSSID attack mask overrides. | |
| void | setDisconnectionStrategy (DisconnectStrategy strategy) |
| Configures how the engine handles disconnection when both CSA and Deauth are enabled. | |
| Error | setTarget (const uint8_t *bssid, uint8_t channel) |
| Focuses the engine on a single BSSID. | |
| void | clearTarget () |
| Clears the specific target and resumes autonomous wardriving. | |
| bool | hasTarget () const |
| bool | isAttacking () const |
| void | setAutoTarget (bool enable) |
| Continuously locks onto the strongest uncaptured AP in the cache. | |
| void | resetStats () |
| Resets all frame and capture statistics to zero. | |
| uint8_t | getChannel () const |
| bool | isActive () const |
| int8_t | getLastRssi () const |
| Stats & | getStats () |
| Config & | getConfig () |
| int | getApCount () const |
| bool | getAp (int idx, ApRecord &out) const |
| Reads an AP from the discovery cache by index. | |
| bool | getApByBssid (const uint8_t *bssid, ApRecord &out) const |
| Looks up an AP in the discovery cache by BSSID. | |
| int | getClientCount (const uint8_t *bssid) const |
| Returns the number of unique clients seen associated to a given AP. | |
| bool | getClient (const uint8_t *bssid, int idx, uint8_t out_sta[6]) const |
| Reads a client MAC from the per-AP client table. | |
| void | _setFingerprintHook (_FpHookCb cb) |
| void | setTargetScoreCallback (TargetScoreCb cb) |
| Sets the callback for calculating a custom priority score during autoTarget. | |
| Error | injectCustomFrame (const uint8_t *payload, size_t len, uint8_t channel, uint32_t lock_ms=0, bool wait_for_channel=false) |
| Injects a custom 802.11 frame. | |
| void | setEapolCallback (EapolCb cb) |
| Sets the callback for when a handshake (EAPOL or PMKID) is captured. | |
| void | setApFoundCallback (ApFoundCb cb) |
| Sets the callback for when a new Access Point is discovered. | |
| void | setTargetFilter (TargetFilterCb cb) |
| Sets an early filter callback. | |
| void | setPacketLogger (PacketCb cb) |
| Sets the callback for raw promiscuous mode packets. | |
| void | setIdentityCallback (IdentityCb cb) |
| Sets the callback for passive 802.1X Enterprise Identity harvesting. | |
| void | setAttackResultCallback (AttackResultCb cb) |
| Sets the callback fired when an attack attempt exhausts all options without capturing. | |
| void | setProbeRequestCallback (ProbeRequestCb cb) |
| Sets the callback fired on every probe request frame. | |
| void | setDisruptCallback (DisruptCb cb) |
| Sets the callback fired on deauthentication and disassociation frames. | |
| void | setClientFoundCallback (ClientFoundCb cb) |
| Sets the callback fired when a new client (STA) is first seen associated to an AP. | |
| void | setRogueApCallback (RogueApCb cb) |
| Sets the callback fired when a potential evil twin or rogue AP is detected. | |
Static Public Member Functions | |
| static const char * | getVendor (const uint8_t *mac) |
| Looks up the vendor name for a given MAC address (OUI). | |
The core WiFi handshake capturing engine.
Definition at line 91 of file Politician.h.
| struct politician::Politician::ApCacheEntry.flags |
Definition at line 495 of file Politician.h.
| Class Members | ||
|---|---|---|
| uint8_t | active: 1 | |
| uint8_t | ft_capable: 1 | |
| uint8_t | has_active_clients: 1 | |
| uint8_t | is_hidden: 1 | |
| uint8_t | is_wpa3_only: 1 | |
| uint8_t | pmf_capable: 1 | |
| uint8_t | pmf_required: 1 | |
| uint8_t | wps_enabled: 1 | |
| struct politician::Politician::Session.flags |
Definition at line 562 of file Politician.h.
| Class Members | ||
|---|---|---|
| uint8_t | active: 1 | |
| uint8_t | has_m1: 1 | |
| uint8_t | has_m2: 1 | |
| uint8_t | has_m3: 1 | |
| uint8_t | has_m4: 1 | |
| using politician::Politician::_FpHookCb = void (*)(const uint8_t *mac, const char *ssid, uint8_t ssid_len, uint8_t ch, int8_t rssi, const uint8_t *ie, uint16_t ie_len) |
Definition at line 286 of file Politician.h.
| using politician::Politician::ApFoundCb = void (*)(const ApRecord &ap) |
Definition at line 290 of file Politician.h.
| using politician::Politician::AttackResultCb = void (*)(const AttackResultRecord &rec) |
Definition at line 295 of file Politician.h.
| using politician::Politician::ClientFoundCb = void (*)(const uint8_t *bssid, const uint8_t *sta, int8_t rssi) |
Definition at line 298 of file Politician.h.
| using politician::Politician::DisruptCb = void (*)(const DisruptRecord &rec) |
Definition at line 297 of file Politician.h.
| using politician::Politician::EapolCb = void (*)(const HandshakeRecord &rec) |
Definition at line 289 of file Politician.h.
| using politician::Politician::IdentityCb = void (*)(const EapIdentityRecord &rec) |
Definition at line 294 of file Politician.h.
| using politician::Politician::PacketCb = void (*)(const uint8_t *payload, uint16_t len, int8_t rssi, uint8_t channel, uint32_t ts_usec) |
Definition at line 293 of file Politician.h.
| using politician::Politician::ProbeRequestCb = void (*)(const ProbeRequestRecord &rec) |
Definition at line 296 of file Politician.h.
| using politician::Politician::TargetFilterCb = bool (*)(const ApRecord &ap) |
Definition at line 291 of file Politician.h.
| using politician::Politician::TargetScoreCb = int (*)(const ApRecord &ap, const char *vendor) |
Definition at line 292 of file Politician.h.
| politician::Politician::Politician | ( | ) |
Definition at line 41 of file Politician.cpp.
|
inline |
Definition at line 287 of file Politician.h.
Initializes the WiFi driver in promiscuous mode.
| cfg | Optional configuration struct. |
Definition at line 89 of file Politician.cpp.
References politician::ERR_WIFI_INIT, and politician::OK.
Referenced by setup().
| void politician::Politician::clearAttackMaskOverrides | ( | ) |
Clears all per-BSSID attack mask overrides.
Definition at line 275 of file Politician.cpp.
| void politician::Politician::clearCapturedList | ( | ) |
Clears the captured BSSID list.
Definition at line 188 of file Politician.cpp.
| void politician::Politician::clearTarget | ( | ) |
Clears the specific target and resumes autonomous wardriving.
Definition at line 323 of file Politician.cpp.
| bool politician::Politician::getAp | ( | int | idx, |
| ApRecord & | out | ||
| ) | const |
Reads an AP from the discovery cache by index.
| idx | Zero-based index (0 to getApCount()-1). |
| out | Populated with the AP's details on success. |
Definition at line 1730 of file Politician.cpp.
References politician::ApRecord::beacon_interval, politician::ApRecord::bssid, politician::ApRecord::captured, politician::ApRecord::chan_util, politician::ApRecord::channel, politician::ApRecord::country, politician::ApRecord::enc, politician::ApRecord::first_seen_ms, politician::ApRecord::ft_capable, politician::ApRecord::is_hidden, politician::ApRecord::last_seen_ms, politician::ApRecord::max_rate_mbps, politician::ApRecord::network_type, politician::ApRecord::pmf_capable, politician::ApRecord::pmf_required, politician::ApRecord::rssi, politician::ApRecord::ssid, politician::ApRecord::ssid_len, politician::ApRecord::sta_count, politician::ApRecord::total_attempts, politician::ApRecord::venue_group, politician::ApRecord::venue_type, and politician::ApRecord::wps_enabled.
| bool politician::Politician::getApByBssid | ( | const uint8_t * | bssid, |
| ApRecord & | out | ||
| ) | const |
Looks up an AP in the discovery cache by BSSID.
| bssid | 6-byte BSSID to search for. |
| out | Populated with the AP's details on success. |
Definition at line 1768 of file Politician.cpp.
References politician::ApRecord::beacon_interval, politician::ApRecord::bssid, politician::ApRecord::captured, politician::ApRecord::chan_util, politician::ApRecord::channel, politician::ApRecord::country, politician::ApRecord::enc, politician::ApRecord::first_seen_ms, politician::ApRecord::ft_capable, politician::ApRecord::is_hidden, politician::ApRecord::last_seen_ms, politician::ApRecord::max_rate_mbps, politician::ApRecord::network_type, politician::ApRecord::pmf_capable, politician::ApRecord::pmf_required, politician::ApRecord::rssi, politician::ApRecord::ssid, politician::ApRecord::ssid_len, politician::ApRecord::sta_count, politician::ApRecord::total_attempts, politician::ApRecord::venue_group, politician::ApRecord::venue_type, and politician::ApRecord::wps_enabled.
| int politician::Politician::getApCount | ( | ) | const |
Definition at line 1722 of file Politician.cpp.
Referenced by tick().
|
inline |
Definition at line 237 of file Politician.h.
| bool politician::Politician::getClient | ( | const uint8_t * | bssid, |
| int | idx, | ||
| uint8_t | out_sta[6] | ||
| ) | const |
Reads a client MAC from the per-AP client table.
| bssid | 6-byte BSSID of the AP. |
| idx | Zero-based client index (0 to getClientCount()-1). |
| out_sta | Output buffer for the 6-byte client MAC. |
Definition at line 1814 of file Politician.cpp.
| int politician::Politician::getClientCount | ( | const uint8_t * | bssid | ) | const |
Returns the number of unique clients seen associated to a given AP.
| bssid | 6-byte BSSID of the AP. |
Definition at line 1802 of file Politician.cpp.
|
inline |
Definition at line 249 of file Politician.h.
|
inline |
Definition at line 243 of file Politician.h.
|
inline |
Definition at line 246 of file Politician.h.
Referenced by loop().
|
static |
Looks up the vendor name for a given MAC address (OUI).
| mac | 6-byte MAC address. |
Definition at line 1909 of file Politician.cpp.
References politician::fingerprint::_FP_OUI_DB, politician::fingerprint::_FP_OUI_DB_COUNT, politician::fingerprint::_FP_VENDORS, and politician::fingerprint::BuiltinOui::vendor_idx.
Referenced by tick().
|
inline |
Definition at line 221 of file Politician.h.
| Error politician::Politician::injectCustomFrame | ( | const uint8_t * | payload, |
| size_t | len, | ||
| uint8_t | channel, | ||
| uint32_t | lock_ms = 0, |
||
| bool | wait_for_channel = false |
||
| ) |
Injects a custom 802.11 frame.
| payload | The raw 802.11 frame bytes. |
| len | Length of the frame. |
| channel | The 2.4GHz or 5GHz channel to transmit on. |
| lock_ms | Optional. If > 0, the engine disables hopping and stays on the channel for this duration. |
| wait_for_channel | If true, the frame is queued until the hopper naturally reaches the channel (stealth). If false, the engine immediately switches to the channel and fires. |
Definition at line 332 of file Politician.cpp.
References politician::ERR_NOT_ACTIVE, politician::ERR_WIFI_INIT, millis(), and politician::OK.
|
inline |
Definition at line 240 of file Politician.h.
|
inline |
Definition at line 224 of file Politician.h.
| Error politician::Politician::lockChannel | ( | uint8_t | ch | ) |
Stops hopping and locks the radio to a specific channel.
Definition at line 169 of file Politician.cpp.
References setChannel().
| void politician::Politician::markCaptured | ( | const uint8_t * | bssid | ) |
Manually adds a BSSID to the "already captured" list to skip it.
Definition at line 196 of file Politician.cpp.
|
inline |
Resets all frame and capture statistics to zero.
Definition at line 234 of file Politician.h.
| void politician::Politician::setActive | ( | bool | active | ) |
Enables or disables frame processing.
Definition at line 148 of file Politician.cpp.
|
inline |
Sets the callback for when a new Access Point is discovered.
Definition at line 331 of file Politician.h.
| void politician::Politician::setAttackMask | ( | uint8_t | mask | ) |
Configures which attack techniques are enabled globally.
Definition at line 243 of file Politician.cpp.
References ATTACK_CSA, ATTACK_PASSIVE, and ATTACK_PMKID.
Referenced by setup().
| void politician::Politician::setAttackMaskForBssid | ( | const uint8_t * | bssid, |
| uint8_t | mask | ||
| ) |
Overrides the attack mask for a specific BSSID.
When the engine targets this BSSID the override mask is used instead of the global mask. The override table holds up to 8 entries; oldest is evicted if full.
Definition at line 252 of file Politician.cpp.
|
inline |
Sets the callback fired when an attack attempt exhausts all options without capturing.
Useful for logging failed targets or adjusting strategy at runtime.
Definition at line 352 of file Politician.h.
| void politician::Politician::setAutoTarget | ( | bool | enable | ) |
Continuously locks onto the strongest uncaptured AP in the cache.
After each attack attempt (success or failure), automatically moves to the next best target.
| enable | True to enable, false to disable and resume normal hopping. |
Definition at line 442 of file Politician.cpp.
| Error politician::Politician::setChannel | ( | uint8_t | ch | ) |
Manually sets the WiFi radio to a specific channel.
| ch | Channel number (2.4GHz: 1-14, 5GHz: 36-165) |
Definition at line 158 of file Politician.cpp.
References politician::ERR_INVALID_CH, politician::ERR_NOT_ACTIVE, politician::isValidChannel(), and politician::OK.
Referenced by lockChannel().
| void politician::Politician::setChannelBands | ( | bool | ghz24, |
| bool | ghz5 | ||
| ) |
Restricts hopping to 2.4GHz, 5GHz, or both bands.
| ghz24 | Include 2.4GHz channels (1-13) |
| ghz5 | Include 5GHz common channels (36-165) |
Definition at line 397 of file Politician.cpp.
References politician::CHANNEL_5GHZ_COMMON, and POLITICIAN_MAX_CHANNELS.
| void politician::Politician::setChannelList | ( | const uint8_t * | channels, |
| uint8_t | count | ||
| ) |
Restricts hopping to a specific list of channels.
| channels | Array of channel numbers (2.4GHz: 1-14, 5GHz: 36-165) |
| count | Number of channels in array |
Definition at line 376 of file Politician.cpp.
References politician::isValidChannel(), and POLITICIAN_MAX_CHANNELS.
|
inline |
Sets the callback fired when a new client (STA) is first seen associated to an AP.
Fired at most once per unique BSSID+STA pair (tracked per AP cache entry, up to 4 clients).
Definition at line 370 of file Politician.h.
|
inline |
Configures how the engine handles disconnection when both CSA and Deauth are enabled.
| strategy | STRATEGY_AUTO_FALLBACK (default) or STRATEGY_SIMULTANEOUS. |
Definition at line 207 of file Politician.h.
|
inline |
Sets the callback fired on deauthentication and disassociation frames.
Exposes source, destination, BSSID, reason code, and direction for attack/roaming detection.
Definition at line 364 of file Politician.h.
|
inline |
Sets the callback for when a handshake (EAPOL or PMKID) is captured.
Definition at line 326 of file Politician.h.
Referenced by setup().
|
inline |
Sets the callback for passive 802.1X Enterprise Identity harvesting.
Definition at line 346 of file Politician.h.
| void politician::Politician::setIgnoreList | ( | const uint8_t(*) | bssids[6], |
| uint8_t | count | ||
| ) |
Sets a list of BSSIDs that should always be ignored by the engine.
Definition at line 177 of file Politician.cpp.
|
inline |
Sets a custom logging callback to intercept library output.
Definition at line 105 of file Politician.h.
|
inline |
Sets the callback for raw promiscuous mode packets.
Definition at line 341 of file Politician.h.
|
inline |
Sets the callback fired on every probe request frame.
Exposes the probing client MAC and requested SSID for device history reconstruction.
Definition at line 358 of file Politician.h.
|
inline |
Sets the callback fired when a potential evil twin or rogue AP is detected.
Triggered when a newly observed BSSID advertises the same SSID as an already-cached AP on the same channel.
Definition at line 376 of file Politician.h.
| Error politician::Politician::setTarget | ( | const uint8_t * | bssid, |
| uint8_t | channel | ||
| ) |
Focuses the engine on a single BSSID.
Definition at line 291 of file Politician.cpp.
References politician::ERR_ALREADY_CAPTURED, politician::ERR_NOT_ACTIVE, politician::ERR_WIFI_INIT, and politician::OK.
Referenced by setTargetBySsid(), and tick().
| Error politician::Politician::setTargetBySsid | ( | const char * | ssid | ) |
Searches the AP cache by SSID and locks onto the strongest match.
Equivalent to calling setTarget() on the best matching AP.
| ssid | Null-terminated SSID string to search for. |
Definition at line 421 of file Politician.cpp.
References politician::ERR_NOT_ACTIVE, politician::ERR_NOT_FOUND, and setTarget().
|
inline |
Sets an early filter callback.
If it returns false, the AP is ignored completely.
Definition at line 336 of file Politician.h.
|
inline |
Sets the callback for calculating a custom priority score during autoTarget.
Definition at line 310 of file Politician.h.
| void politician::Politician::startHopping | ( | uint16_t | dwellMs = 0 | ) |
Starts autonomous channel hopping.
| dwellMs | Time in milliseconds to stay on each channel (0 = use config). |
Definition at line 203 of file Politician.cpp.
References politician::Config::hop_dwell_ms, millis(), and politician::Config::smart_hopping.
Referenced by setup().
| void politician::Politician::stop | ( | ) |
Full engine teardown.
Aborts any in-progress attack, clears the target, stops hopping, and disables frame processing in one call. Use this instead of combining stopHopping() + clearTarget() + setActive(false).
Definition at line 224 of file Politician.cpp.
| void politician::Politician::stopHopping | ( | ) |
Stops autonomous channel hopping and goes idle.
Definition at line 217 of file Politician.cpp.
| void politician::Politician::tick | ( | ) |
Main worker method.
Must be called frequently from loop().
Definition at line 487 of file Politician.cpp.
References politician::Config::ap_expiry_ms, politician::ApRecord::beacon_interval, politician::ApRecord::bssid, politician::ApRecord::captured, politician::Stats::captures, politician::ApRecord::chan_util, politician::ApRecord::channel, politician::ApRecord::country, politician::Stats::data, politician::Stats::dropped, politician::Stats::eapol, politician::ApRecord::enc, politician::Stats::failed_csa, politician::Stats::failed_pmkid, politician::ApRecord::first_seen_ms, politician::ApRecord::ft_capable, getApCount(), getVendor(), politician::Config::hop_dwell_ms, politician::Config::hop_max_dwell_ms, politician::Config::hop_min_dwell_ms, politician::ApRecord::is_hidden, politician::ApRecord::last_seen_ms, politician::ApRecord::max_rate_mbps, politician::Stats::mgmt, millis(), politician::Config::min_beacon_count, politician::ApRecord::pmf_capable, politician::ApRecord::pmf_required, politician::Stats::pmkid_found, politician::Stats::rb_max, politician::Config::require_active_clients, politician::ApRecord::rssi, politician::Stats::sae_found, politician::Config::session_timeout_ms, setTarget(), politician::Config::skip_immune_networks, politician::Config::smart_hopping, politician::ApRecord::ssid, politician::ApRecord::ssid_len, politician::ApRecord::sta_count, politician::Stats::total, politician::ApRecord::total_attempts, and politician::ApRecord::wps_enabled.
Referenced by loop().