Politician 1.0.0
WiFi Auditing Library for ESP32
Loading...
Searching...
No Matches
politician::Politician Class Reference

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
 
StatsgetStats ()
 
ConfiggetConfig ()
 
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).
 

Detailed Description

The core WiFi handshake capturing engine.

Definition at line 91 of file Politician.h.


Class Documentation

◆ politician::Politician::ApCacheEntry.flags

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

◆ politician::Politician::Session.flags

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

Member Typedef Documentation

◆ _FpHookCb

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.

◆ ApFoundCb

using politician::Politician::ApFoundCb = void (*)(const ApRecord &ap)

Definition at line 290 of file Politician.h.

◆ AttackResultCb

Definition at line 295 of file Politician.h.

◆ ClientFoundCb

using politician::Politician::ClientFoundCb = void (*)(const uint8_t *bssid, const uint8_t *sta, int8_t rssi)

Definition at line 298 of file Politician.h.

◆ DisruptCb

using politician::Politician::DisruptCb = void (*)(const DisruptRecord &rec)

Definition at line 297 of file Politician.h.

◆ EapolCb

using politician::Politician::EapolCb = void (*)(const HandshakeRecord &rec)

Definition at line 289 of file Politician.h.

◆ IdentityCb

Definition at line 294 of file Politician.h.

◆ PacketCb

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.

◆ ProbeRequestCb

Definition at line 296 of file Politician.h.

◆ TargetFilterCb

using politician::Politician::TargetFilterCb = bool (*)(const ApRecord &ap)

Definition at line 291 of file Politician.h.

◆ TargetScoreCb

using politician::Politician::TargetScoreCb = int (*)(const ApRecord &ap, const char *vendor)

Definition at line 292 of file Politician.h.

Constructor & Destructor Documentation

◆ Politician()

politician::Politician::Politician ( )

Definition at line 41 of file Politician.cpp.

Member Function Documentation

◆ _setFingerprintHook()

void politician::Politician::_setFingerprintHook ( _FpHookCb  cb)
inline

Definition at line 287 of file Politician.h.

◆ begin()

Error politician::Politician::begin ( const Config cfg = Config())

Initializes the WiFi driver in promiscuous mode.

Parameters
cfgOptional configuration struct.
Returns
OK on success, or an error code.

Definition at line 89 of file Politician.cpp.

References politician::ERR_WIFI_INIT, and politician::OK.

Referenced by setup().

◆ clearAttackMaskOverrides()

void politician::Politician::clearAttackMaskOverrides ( )

Clears all per-BSSID attack mask overrides.

Definition at line 275 of file Politician.cpp.

◆ clearCapturedList()

void politician::Politician::clearCapturedList ( )

Clears the captured BSSID list.

Definition at line 188 of file Politician.cpp.

◆ clearTarget()

void politician::Politician::clearTarget ( )

Clears the specific target and resumes autonomous wardriving.

Definition at line 323 of file Politician.cpp.

◆ getAp()

◆ getApByBssid()

◆ getApCount()

int politician::Politician::getApCount ( ) const
Returns
Number of unique APs currently in the discovery cache.

Definition at line 1722 of file Politician.cpp.

Referenced by tick().

◆ getChannel()

uint8_t politician::Politician::getChannel ( ) const
inline
Returns
The current operating channel.

Definition at line 237 of file Politician.h.

◆ getClient()

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.

Parameters
bssid6-byte BSSID of the AP.
idxZero-based client index (0 to getClientCount()-1).
out_staOutput buffer for the 6-byte client MAC.
Returns
True if idx is valid, false otherwise.

Definition at line 1814 of file Politician.cpp.

◆ getClientCount()

int politician::Politician::getClientCount ( const uint8_t *  bssid) const

Returns the number of unique clients seen associated to a given AP.

Parameters
bssid6-byte BSSID of the AP.
Returns
Client count (0-4), or 0 if BSSID is not in cache.

Definition at line 1802 of file Politician.cpp.

◆ getConfig()

Config & politician::Politician::getConfig ( )
inline
Returns
Reference to the internal configuration struct for runtime mutations.

Definition at line 249 of file Politician.h.

◆ getLastRssi()

int8_t politician::Politician::getLastRssi ( ) const
inline
Returns
Signal strength (RSSI) of the last received frame.

Definition at line 243 of file Politician.h.

◆ getStats()

Stats & politician::Politician::getStats ( )
inline
Returns
Reference to the internal statistics counter.

Definition at line 246 of file Politician.h.

Referenced by loop().

◆ getVendor()

const char * politician::Politician::getVendor ( const uint8_t *  mac)
static

Looks up the vendor name for a given MAC address (OUI).

Parameters
mac6-byte MAC address.
Returns
The vendor string (e.g., "Apple") or an empty string if unknown.

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().

◆ hasTarget()

bool politician::Politician::hasTarget ( ) const
inline
Returns
True if currently focusing on a specific target BSSID.

Definition at line 221 of file Politician.h.

◆ injectCustomFrame()

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.

Parameters
payloadThe raw 802.11 frame bytes.
lenLength of the frame.
channelThe 2.4GHz or 5GHz channel to transmit on.
lock_msOptional. If > 0, the engine disables hopping and stays on the channel for this duration.
wait_for_channelIf true, the frame is queued until the hopper naturally reaches the channel (stealth). If false, the engine immediately switches to the channel and fires.
Returns
OK on success, or an error code if the queue is full or engine is not initialized.

Definition at line 332 of file Politician.cpp.

References politician::ERR_NOT_ACTIVE, politician::ERR_WIFI_INIT, millis(), and politician::OK.

◆ isActive()

bool politician::Politician::isActive ( ) const
inline
Returns
True if the engine is currently processing frames.

Definition at line 240 of file Politician.h.

◆ isAttacking()

bool politician::Politician::isAttacking ( ) const
inline
Returns
True if an active attack (PMKID fishing or CSA/Deauth) is in progress.

Definition at line 224 of file Politician.h.

◆ lockChannel()

Error politician::Politician::lockChannel ( uint8_t  ch)

Stops hopping and locks the radio to a specific channel.

Returns
OK on success, or an error code.

Definition at line 169 of file Politician.cpp.

References setChannel().

◆ markCaptured()

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.

◆ resetStats()

void politician::Politician::resetStats ( )
inline

Resets all frame and capture statistics to zero.

Definition at line 234 of file Politician.h.

◆ setActive()

void politician::Politician::setActive ( bool  active)

Enables or disables frame processing.

Definition at line 148 of file Politician.cpp.

◆ setApFoundCallback()

void politician::Politician::setApFoundCallback ( ApFoundCb  cb)
inline

Sets the callback for when a new Access Point is discovered.

Definition at line 331 of file Politician.h.

◆ setAttackMask()

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().

◆ setAttackMaskForBssid()

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.

◆ setAttackResultCallback()

void politician::Politician::setAttackResultCallback ( AttackResultCb  cb)
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.

◆ setAutoTarget()

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.

Parameters
enableTrue to enable, false to disable and resume normal hopping.

Definition at line 442 of file Politician.cpp.

◆ setChannel()

Error politician::Politician::setChannel ( uint8_t  ch)

Manually sets the WiFi radio to a specific channel.

Parameters
chChannel number (2.4GHz: 1-14, 5GHz: 36-165)
Returns
OK on success, ERR_INVALID_CH if ch is invalid.

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().

◆ setChannelBands()

void politician::Politician::setChannelBands ( bool  ghz24,
bool  ghz5 
)

Restricts hopping to 2.4GHz, 5GHz, or both bands.

Parameters
ghz24Include 2.4GHz channels (1-13)
ghz5Include 5GHz common channels (36-165)

Definition at line 397 of file Politician.cpp.

References politician::CHANNEL_5GHZ_COMMON, and POLITICIAN_MAX_CHANNELS.

◆ setChannelList()

void politician::Politician::setChannelList ( const uint8_t *  channels,
uint8_t  count 
)

Restricts hopping to a specific list of channels.

Parameters
channelsArray of channel numbers (2.4GHz: 1-14, 5GHz: 36-165)
countNumber of channels in array

Definition at line 376 of file Politician.cpp.

References politician::isValidChannel(), and POLITICIAN_MAX_CHANNELS.

◆ setClientFoundCallback()

void politician::Politician::setClientFoundCallback ( ClientFoundCb  cb)
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.

◆ setDisconnectionStrategy()

void politician::Politician::setDisconnectionStrategy ( DisconnectStrategy  strategy)
inline

Configures how the engine handles disconnection when both CSA and Deauth are enabled.

Parameters
strategySTRATEGY_AUTO_FALLBACK (default) or STRATEGY_SIMULTANEOUS.

Definition at line 207 of file Politician.h.

◆ setDisruptCallback()

void politician::Politician::setDisruptCallback ( DisruptCb  cb)
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.

◆ setEapolCallback()

void politician::Politician::setEapolCallback ( EapolCb  cb)
inline

Sets the callback for when a handshake (EAPOL or PMKID) is captured.

Definition at line 326 of file Politician.h.

Referenced by setup().

◆ setIdentityCallback()

void politician::Politician::setIdentityCallback ( IdentityCb  cb)
inline

Sets the callback for passive 802.1X Enterprise Identity harvesting.

Definition at line 346 of file Politician.h.

◆ setIgnoreList()

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.

◆ setLogger()

void politician::Politician::setLogger ( LogCb  cb)
inline

Sets a custom logging callback to intercept library output.

Definition at line 105 of file Politician.h.

◆ setPacketLogger()

void politician::Politician::setPacketLogger ( PacketCb  cb)
inline

Sets the callback for raw promiscuous mode packets.

Definition at line 341 of file Politician.h.

◆ setProbeRequestCallback()

void politician::Politician::setProbeRequestCallback ( ProbeRequestCb  cb)
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.

◆ setRogueApCallback()

void politician::Politician::setRogueApCallback ( RogueApCb  cb)
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.

◆ setTarget()

Error politician::Politician::setTarget ( const uint8_t *  bssid,
uint8_t  channel 
)

Focuses the engine on a single BSSID.

Returns
OK on success, ERR_ALREADY_CAPTURED if BSSID is on the captured/ignore list.

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().

◆ setTargetBySsid()

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.

Parameters
ssidNull-terminated SSID string to search for.
Returns
OK on success, ERR_NOT_FOUND if SSID is not in cache, ERR_ALREADY_CAPTURED if BSSID is already captured, ERR_NOT_ACTIVE if not initialized.

Definition at line 421 of file Politician.cpp.

References politician::ERR_NOT_ACTIVE, politician::ERR_NOT_FOUND, and setTarget().

◆ setTargetFilter()

void politician::Politician::setTargetFilter ( TargetFilterCb  cb)
inline

Sets an early filter callback.

If it returns false, the AP is ignored completely.

Definition at line 336 of file Politician.h.

◆ setTargetScoreCallback()

void politician::Politician::setTargetScoreCallback ( TargetScoreCb  cb)
inline

Sets the callback for calculating a custom priority score during autoTarget.

Definition at line 310 of file Politician.h.

◆ startHopping()

void politician::Politician::startHopping ( uint16_t  dwellMs = 0)

Starts autonomous channel hopping.

Parameters
dwellMsTime 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().

◆ stop()

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.

◆ stopHopping()

void politician::Politician::stopHopping ( )

Stops autonomous channel hopping and goes idle.

Definition at line 217 of file Politician.cpp.

◆ tick()

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().


The documentation for this class was generated from the following files: