Politician 1.0.0
WiFi Auditing Library for ESP32
Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
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 = std::function< void(const HandshakeRecord &rec)>
 
using ApFoundCb = std::function< void(const ApRecord &ap)>
 
using TargetFilterCb = std::function< bool(const ApRecord &ap)>
 
using TargetScoreCb = std::function< int(const ApRecord &ap, const char *vendor)>
 
using PacketCb = std::function< void(const uint8_t *payload, uint16_t len, int8_t rssi, uint8_t channel, uint32_t ts_usec)>
 
using IdentityCb = std::function< void(const EapIdentityRecord &rec)>
 
using AttackResultCb = std::function< void(const AttackResultRecord &rec)>
 
using ProbeRequestCb = std::function< void(const ProbeRequestRecord &rec)>
 
using DisruptCb = std::function< void(const DisruptRecord &rec)>
 
using ClientFoundCb = std::function< void(const ClientRecord &rec)>
 
using WpsCb = std::function< void(const WpsRecord &rec)>
 
using MsChapCb = std::function< void(const MsChapRecord &rec)>
 

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 setAttackMaskForSsid (const char *ssid, uint8_t mask, bool substring=false)
 Sets an attack mask for all APs whose SSID matches the given string.
 
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.
 
uint8_t getChannelsSortedByActivity (uint8_t *out, uint8_t count) const
 Returns the N most active channels sorted by descending frame count.
 
uint8_t setAutoChannelList (uint8_t topN=13)
 Feeds the top-N most active channels (from getChannelsSortedByActivity) into setChannelList(), replacing the current hop sequence.
 
void forEachAp (void(*cb)(const ApRecord &ap, void *ctx), void *ctx=nullptr) const
 Iterates all active APs in the cache, calling cb for each one.
 
void forEachAp (std::function< void(const ApRecord &ap)> cb) const
 std::function overload of forEachAp() — supports lambda captures.
 
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 setWpsCallback (WpsCb cb)
 Sets the callback fired when a WPS Enrollee's M1 message is captured.
 
void setMsChapCallback (MsChapCb cb)
 Sets the callback fired on a bare EAP-MSCHAPv2 challenge/response exchange.
 
void setRogueApCallback (RogueApCb cb)
 Sets the callback fired when a potential evil twin or rogue AP is detected.
 
void enableKarma (bool en)
 Enable or disable the KARMA rogue AP responder at runtime.
 
void setKarmaCallback (KarmaCb cb)
 Sets the callback fired each time the KARMA responder echoes a probe.
 
void setProbeWordlist (const char *const *wordlist, uint8_t count)
 Sets an SSID wordlist for directed probes against hidden access points.
 

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 103 of file Politician.h.

Class Documentation

◆ politician::Politician::ApCacheEntry.flags

struct politician::Politician::ApCacheEntry.flags

Definition at line 686 of file Politician.h.

Class Members
uint16_t active: 1
uint16_t ft_capable: 1
uint16_t has_active_clients: 1
uint16_t is_he: 1
uint16_t is_hidden: 1
uint16_t is_vht: 1
uint16_t is_wpa3_only: 1
uint16_t pmf_capable: 1
uint16_t pmf_required: 1
uint16_t wps_enabled: 1

◆ politician::Politician::Session.flags

struct politician::Politician::Session.flags

Definition at line 763 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 351 of file Politician.h.

◆ ApFoundCb

using politician::Politician::ApFoundCb = std::function<void(const ApRecord &ap)>

Definition at line 356 of file Politician.h.

◆ AttackResultCb

using politician::Politician::AttackResultCb = std::function<void(const AttackResultRecord &rec)>

Definition at line 361 of file Politician.h.

◆ ClientFoundCb

using politician::Politician::ClientFoundCb = std::function<void(const ClientRecord &rec)>

Definition at line 364 of file Politician.h.

◆ DisruptCb

using politician::Politician::DisruptCb = std::function<void(const DisruptRecord &rec)>

Definition at line 363 of file Politician.h.

◆ EapolCb

using politician::Politician::EapolCb = std::function<void(const HandshakeRecord &rec)>

Definition at line 355 of file Politician.h.

◆ IdentityCb

using politician::Politician::IdentityCb = std::function<void(const EapIdentityRecord &rec)>

Definition at line 360 of file Politician.h.

◆ MsChapCb

using politician::Politician::MsChapCb = std::function<void(const MsChapRecord &rec)>

Definition at line 367 of file Politician.h.

◆ PacketCb

using politician::Politician::PacketCb = std::function<void(const uint8_t *payload, uint16_t len, int8_t rssi, uint8_t channel, uint32_t ts_usec)>

Definition at line 359 of file Politician.h.

◆ ProbeRequestCb

using politician::Politician::ProbeRequestCb = std::function<void(const ProbeRequestRecord &rec)>

Definition at line 362 of file Politician.h.

◆ TargetFilterCb

using politician::Politician::TargetFilterCb = std::function<bool(const ApRecord &ap)>

Definition at line 357 of file Politician.h.

◆ TargetScoreCb

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

Definition at line 358 of file Politician.h.

◆ WpsCb

using politician::Politician::WpsCb = std::function<void(const WpsRecord &rec)>

Definition at line 365 of file Politician.h.

Constructor & Destructor Documentation

◆ Politician()

politician::Politician::Politician ( )

Definition at line 42 of file Politician.cpp.

Member Function Documentation

◆ _setFingerprintHook()

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

Definition at line 352 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 100 of file Politician.cpp.

References politician::Config::csa_wait_ms, politician::ERR_MAX_INSTANCES, politician::ERR_WIFI_INIT, politician::Config::fish_timeout_ms, politician::Config::hop_max_dwell_ms, politician::Config::hop_min_dwell_ms, politician::Config::karma_enabled, politician::OK, POLITICIAN_MAX_INSTANCES, politician::Config::smart_hopping, and politician::Config::soft_ap_ssid.

Referenced by setup().

◆ clearAttackMaskOverrides()

void politician::Politician::clearAttackMaskOverrides ( )

Clears all per-BSSID attack mask overrides.

Definition at line 377 of file Politician.cpp.

◆ clearCapturedList()

void politician::Politician::clearCapturedList ( )

Clears the captured BSSID list.

Definition at line 244 of file Politician.cpp.

◆ clearTarget()

void politician::Politician::clearTarget ( )

Clears the specific target and resumes autonomous wardriving.

Definition at line 444 of file Politician.cpp.

◆ enableKarma()

void politician::Politician::enableKarma ( bool  en)
inline

Enable or disable the KARMA rogue AP responder at runtime.

When enabled, the engine intercepts named probe requests (SSIDs != wildcard) and immediately injects a matching probe response + beacon, spoofing an open AP with that SSID. Clients configured to auto-join known networks will then associate with the engine's soft AP.

Note
Only effective when cfg.karma_enabled = true was set in begin(), or when called after begin() to toggle dynamically.
Parameters
entrue to enable, false to disable

Definition at line 495 of file Politician.h.

◆ forEachAp() [1/2]

void politician::Politician::forEachAp ( std::function< void(const ApRecord &ap)>  cb) const

std::function overload of forEachAp() — supports lambda captures.

Gated by POLITICIAN_NO_STD_FUNCTION.

Definition at line 2523 of file Politician.cpp.

References forEachAp().

◆ forEachAp() [2/2]

void politician::Politician::forEachAp ( void(*)(const ApRecord &ap, void *ctx)  cb,
void *  ctx = nullptr 
) const

Iterates all active APs in the cache, calling cb for each one.

The internal mutex is held for the entire iteration, making this safe on a multi-core FreeRTOS system. Do not call any blocking Politician API from within the callback.

Parameters
cbCallback invoked with each AP snapshot
ctxOpaque user pointer passed unchanged to cb (may be nullptr)

Definition at line 2482 of file Politician.cpp.

References politician::ApRecord::beacon_count, politician::ApRecord::beacon_interval, politician::ApRecord::bssid, politician::ApRecord::capture_count, politician::ApRecord::captured, politician::ApRecord::chan_util, politician::ApRecord::chan_width, politician::ApRecord::channel, politician::ApRecord::country, politician::ApRecord::enc, politician::ApRecord::first_seen_ms, politician::ApRecord::ft_capable, politician::ApRecord::is_he, politician::ApRecord::is_hidden, politician::ApRecord::is_vht, politician::ApRecord::last_attack_ms, 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.

Referenced by forEachAp().

◆ getAp()

bool politician::Politician::getAp ( int  idx,
ApRecord &  out 
) const

Reads an AP from the discovery cache by index.

Parameters
idxZero-based index (0 to getApCount()-1).
outPopulated with the AP's details on success.
Returns
True if idx is valid, false otherwise.

Definition at line 2398 of file Politician.cpp.

References politician::ApRecord::beacon_count, politician::ApRecord::beacon_interval, politician::ApRecord::bssid, politician::ApRecord::capture_count, politician::ApRecord::captured, politician::ApRecord::chan_util, politician::ApRecord::chan_width, politician::ApRecord::channel, politician::ApRecord::country, politician::ApRecord::enc, politician::ApRecord::first_seen_ms, politician::ApRecord::ft_capable, politician::ApRecord::is_he, politician::ApRecord::is_hidden, politician::ApRecord::is_vht, politician::ApRecord::last_attack_ms, 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.

◆ getApByBssid()

bool politician::Politician::getApByBssid ( const uint8_t *  bssid,
ApRecord &  out 
) const

Looks up an AP in the discovery cache by BSSID.

Parameters
bssid6-byte BSSID to search for.
outPopulated with the AP's details on success.
Returns
True if found, false if the BSSID is not in cache.

Definition at line 2442 of file Politician.cpp.

References politician::ApRecord::beacon_count, politician::ApRecord::beacon_interval, politician::ApRecord::bssid, politician::ApRecord::capture_count, politician::ApRecord::captured, politician::ApRecord::chan_util, politician::ApRecord::chan_width, politician::ApRecord::channel, politician::ApRecord::country, politician::ApRecord::enc, politician::ApRecord::first_seen_ms, politician::ApRecord::ft_capable, politician::ApRecord::is_he, politician::ApRecord::is_hidden, politician::ApRecord::is_vht, politician::ApRecord::last_attack_ms, 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.

◆ getApCount()

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

Definition at line 2390 of file Politician.cpp.

Referenced by tick().

◆ getChannel()

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

Definition at line 264 of file Politician.h.

◆ getChannelsSortedByActivity()

uint8_t politician::Politician::getChannelsSortedByActivity ( uint8_t *  out,
uint8_t  count 
) const

Returns the N most active channels sorted by descending frame count.

Uses the per-channel frame counters accumulated since the last resetStats() call.

Parameters
outOutput array to receive sorted channel numbers
countMaximum number of channels to return
Returns
Actual number of channels written (≤ count)

Definition at line 518 of file Politician.cpp.

References politician::Stats::channel_frames.

Referenced by setAutoChannelList().

◆ 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 2542 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 2530 of file Politician.cpp.

◆ getConfig()

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

Definition at line 276 of file Politician.h.

◆ getLastRssi()

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

Definition at line 270 of file Politician.h.

◆ getStats()

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

Definition at line 273 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 2657 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 248 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 453 of file Politician.cpp.

References politician::ERR_INVALID_ARG, politician::ERR_NOT_ACTIVE, politician::ERR_QUEUE_FULL, 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 267 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 251 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 225 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 252 of file Politician.cpp.

◆ resetStats()

void politician::Politician::resetStats ( )
inline

Resets all frame and capture statistics to zero.

Definition at line 261 of file Politician.h.

◆ setActive()

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

Enables or disables frame processing.

Definition at line 204 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 417 of file Politician.h.

◆ setAttackMask()

void politician::Politician::setAttackMask ( uint8_t  mask)

Configures which attack techniques are enabled globally.

Definition at line 307 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 316 of file Politician.cpp.

◆ setAttackMaskForSsid()

void politician::Politician::setAttackMaskForSsid ( const char *  ssid,
uint8_t  mask,
bool  substring = false 
)

Sets an attack mask for all APs whose SSID matches the given string.

Parameters
ssidThe SSID string to match
maskAttack mask to apply (ATTACK_PASSIVE, ATTACK_PMKID, etc.)
substringIf true, matches any AP whose SSID contains ssid as a substring. If false (default), requires an exact match.

Overrides are applied after per-BSSID overrides and before the global mask. If an AP matches both a BSSID override and an SSID override, the BSSID override takes precedence. Up to MAX_SSID_OVERRIDES entries are stored; subsequent calls overwrite the oldest entry on overflow.

Definition at line 339 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 438 of file Politician.h.

◆ setAutoChannelList()

uint8_t politician::Politician::setAutoChannelList ( uint8_t  topN = 13)

Feeds the top-N most active channels (from getChannelsSortedByActivity) into setChannelList(), replacing the current hop sequence.

Call this periodically (e.g., every 60s) to adapt the hopper to live traffic.

Parameters
topNNumber of top channels to keep (clamped to POLITICIAN_MAX_CHANNELS)
Returns
Number of channels in the new hop list

Definition at line 547 of file Politician.cpp.

References getChannelsSortedByActivity(), POLITICIAN_MAX_CHANNELS, and setChannelList().

◆ 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 605 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 214 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 555 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 497 of file Politician.cpp.

References politician::isValidChannel(), and POLITICIAN_MAX_CHANNELS.

Referenced by setAutoChannelList().

◆ 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 456 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 234 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 450 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 412 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 432 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 233 of file Politician.cpp.

◆ setKarmaCallback()

void politician::Politician::setKarmaCallback ( KarmaCb  cb)
inline

Sets the callback fired each time the KARMA responder echoes a probe.

The record contains the client MAC, requested SSID, channel, and spoofed AP MAC. Zero overhead if not set.

Definition at line 502 of file Politician.h.

◆ setLogger()

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

Sets a custom logging callback to intercept library output.

Definition at line 117 of file Politician.h.

◆ setMsChapCallback()

void politician::Politician::setMsChapCallback ( MsChapCb  cb)
inline

Sets the callback fired on a bare EAP-MSCHAPv2 challenge/response exchange.

Only fires when an AP serves MSCHAPv2 directly without a TLS tunnel (no PEAP/TTLS). The captured MsChapRecord contains everything needed for offline cracking with asleap or hashcat mode 5500. Zero overhead if not set.

Definition at line 473 of file Politician.h.

◆ setPacketLogger()

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

Sets the callback for raw promiscuous mode packets.

Definition at line 427 of file Politician.h.

Referenced by politician::PoliticianSense::begin().

◆ 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 444 of file Politician.h.

◆ setProbeWordlist()

void politician::Politician::setProbeWordlist ( const char *const *  wordlist,
uint8_t  count 
)
inline

Sets an SSID wordlist for directed probes against hidden access points.

When set and probe_hidden_interval_ms > 0, the engine cycles through each SSID per hidden AP instead of sending a wildcard probe. Each hidden AP maintains its own position in the wordlist so no word is skipped.

The array must remain valid for the lifetime of the engine (use PROGMEM / static storage). Pass nullptr to revert to wildcard-only probing.

Parameters
wordlistArray of null-terminated SSID strings (max 32 chars each)
countNumber of entries in the array

Definition at line 517 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 480 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 412 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 579 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 422 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 396 of file Politician.h.

◆ setWpsCallback()

void politician::Politician::setWpsCallback ( WpsCb  cb)
inline

Sets the callback fired when a WPS Enrollee's M1 message is captured.

The M1 message is the first EAP-WSC frame sent by the Enrollee and is unencrypted, revealing device attributes (name, manufacturer, model, auth/config capabilities). Only fired if the callback is set — has zero overhead otherwise.

Definition at line 464 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 259 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 280 of file Politician.cpp.

References POLITICIAN_MAX_INSTANCES.

◆ stopHopping()

void politician::Politician::stopHopping ( )

Stops autonomous channel hopping and goes idle.

Definition at line 273 of file Politician.cpp.

◆ tick()

void politician::Politician::tick ( )

Main worker method.

Must be called frequently from loop().

Definition at line 768 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: