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

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)
 

Class Documentation

◆ politician::__attribute__

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

◆ politician::ApRecord

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

◆ politician::AttackResultRecord

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

◆ politician::ClientRecord

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.

◆ politician::Config

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

◆ politician::DeviceFingerprint

struct politician::DeviceFingerprint

One fingerprint entry in the built-in or user-defined database.

Definition at line 470 of file PoliticianTypes.h.

Class Members
uint8_t confidence
uint8_t ht_cap_info[2]
uint8_t ht_cap_mask[2]
uint8_t ie_flags
uint8_t ie_flags_mask
const char * model
uint8_t oui[3]
const char * probeSsid
uint8_t rate_sig[4]
const char * vendor

◆ politician::DeviceRecord

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]

◆ politician::DisruptRecord

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

◆ politician::EapIdentityRecord

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

◆ politician::HandshakeRecord

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

◆ politician::HandshakeRecord.__unnamed3__

union politician::HandshakeRecord.__unnamed3__

Definition at line 263 of file PoliticianTypes.h.

Class Members
uint8_t eapol_m2[256]
uint8_t sae_data[256]

◆ politician::HandshakeRecord.__unnamed5__

union politician::HandshakeRecord.__unnamed5__

Definition at line 269 of file PoliticianTypes.h.

Class Members
uint16_t eapol_m2_len
uint16_t sae_len

◆ politician::KarmaRecord

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

◆ politician::MsChapRecord

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]

◆ politician::ProbeRequestRecord

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

◆ politician::RogueApRecord

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

◆ politician::Stats

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.

Class Members
uint32_t beacons
uint32_t captures
uint16_t channel_frames[200]
uint32_t ctrl
uint32_t data
volatile uint32_t dropped
uint32_t eapol
uint32_t failed_csa
uint32_t failed_pmkid
uint32_t mgmt
uint32_t pmkid_found
uint32_t rb_max
uint32_t sae_found
uint32_t total

◆ politician::WpsRecord

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.

Class Members
uint16_t auth_type_flags
uint8_t bssid[6]
uint8_t channel
uint16_t config_methods
char device_name[33]
char manufacturer[65]
char model_name[33]
char model_number[33]
uint16_t primary_dev_type_cat
uint8_t rf_bands
int8_t rssi
char serial_number[33]
uint8_t sta[6]

Typedef Documentation

◆ ApFoundCb

typedef void(* politician::ApFoundCb) (const ApRecord &ap)

Definition at line 77 of file PoliticianTypes.h.

◆ AttackResultCb

typedef void(* politician::AttackResultCb) (const AttackResultRecord &rec)

Definition at line 304 of file PoliticianTypes.h.

◆ ClientFoundCb

typedef void(* politician::ClientFoundCb) (const ClientRecord &rec)

Definition at line 321 of file PoliticianTypes.h.

◆ DisruptCb

typedef void(* politician::DisruptCb) (const DisruptRecord &rec)

Definition at line 83 of file PoliticianTypes.h.

◆ EapolCb

typedef void(* politician::EapolCb) (const HandshakeRecord &rec)

Definition at line 80 of file PoliticianTypes.h.

◆ IdentityCb

typedef void(* politician::IdentityCb) (const EapIdentityRecord &rec)

Definition at line 81 of file PoliticianTypes.h.

◆ KarmaCb

using politician::KarmaCb = typedef std::function<void(const KarmaRecord &rec)>

Definition at line 362 of file PoliticianTypes.h.

◆ LogCb

using politician::LogCb = typedef std::function<void(const char *msg)>

Definition at line 61 of file PoliticianTypes.h.

◆ MsChapCb

typedef void(* politician::MsChapCb) (const MsChapRecord &rec)

Definition at line 86 of file PoliticianTypes.h.

◆ PacketCb

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.

◆ ProbeRequestCb

typedef void(* politician::ProbeRequestCb) (const ProbeRequestRecord &rec)

Definition at line 82 of file PoliticianTypes.h.

◆ RogueApCb

using politician::RogueApCb = typedef std::function<void(const RogueApRecord &rec)>

Definition at line 337 of file PoliticianTypes.h.

◆ SenseCb

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.

◆ TargetScoreCb

typedef int(* politician::TargetScoreCb) (const ApRecord &ap, const char *vendor)

Definition at line 78 of file PoliticianTypes.h.

◆ WpsCb

typedef void(* politician::WpsCb) (const WpsRecord &rec)

Definition at line 84 of file PoliticianTypes.h.

Enumeration Type Documentation

◆ AttackResult

enum politician::AttackResult : uint8_t
Enumerator
RESULT_PMKID_EXHAUSTED 
RESULT_CSA_EXPIRED 

Definition at line 291 of file PoliticianTypes.h.

◆ DisconnectStrategy

Enumerator
STRATEGY_AUTO_FALLBACK 
STRATEGY_SIMULTANEOUS 

Definition at line 285 of file PoliticianTypes.h.

◆ Error

Enumerator
OK 
ERR_WIFI_INIT 
ERR_INVALID_CH 
ERR_NOT_ACTIVE 
ERR_ALREADY_CAPTURED 
ERR_NOT_FOUND 
ERR_MAX_INSTANCES 

Returned by begin() when all POLITICIAN_MAX_INSTANCES slots are occupied.

ERR_INVALID_ARG 
ERR_QUEUE_FULL 

Definition at line 90 of file PoliticianTypes.h.

◆ SenseEvent

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.

Function Documentation

◆ isValidChannel()

static bool politician::isValidChannel ( uint8_t  ch)
static

◆ validateConfig()

int politician::validateConfig ( const Config cfg,
const char **  out,
uint8_t  maxOut 
)
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.

Parameters
cfgThe Config to validate.
outOutput array; each element is set to a static warning string.
maxOutCapacity of out.
Returns
Number of warnings written (0 = configuration looks clean).

Example:

const char *warnings[8];
int n = politician::validateConfig(cfg, warnings, 8);
for (int i = 0; i < n; i++) Serial.println(warnings[i]);
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...

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.

Variable Documentation

◆ CHANNEL_5GHZ_COMMON

const uint8_t politician::CHANNEL_5GHZ_COMMON[]
static
Initial value:
= {
36, 40, 44, 48,
149, 153, 157, 161, 165
}

Definition at line 20 of file Politician.cpp.

Referenced by isValidChannel(), and politician::Politician::setChannelBands().

◆ CIPHER_CCMP

const uint8_t politician::CIPHER_CCMP = 2
static

CCMP/AES (00-0F-AC:4) — current standard.

Definition at line 244 of file PoliticianTypes.h.

◆ CIPHER_TKIP

const uint8_t politician::CIPHER_TKIP = 1
static

TKIP (00-0F-AC:2) — legacy, crackable offline.

Definition at line 243 of file PoliticianTypes.h.

◆ CIPHER_UNKNOWN

const uint8_t politician::CIPHER_UNKNOWN = 0
static

Definition at line 242 of file PoliticianTypes.h.

◆ EAP_METHOD_IDENTITY

const uint8_t politician::EAP_METHOD_IDENTITY = 0x01
static

EAP Identity (always 0x01 for harvested records)

Definition at line 370 of file PoliticianTypes.h.

◆ EAP_METHOD_MSCHAPV2

const uint8_t politician::EAP_METHOD_MSCHAPV2 = 0x1A
static

Bare EAP-MSCHAPv2 (no tunnel — crackable)

Definition at line 374 of file PoliticianTypes.h.

◆ EAP_METHOD_PEAP

const uint8_t politician::EAP_METHOD_PEAP = 0x19
static

PEAP (draft-josefsson-pppext-eap-tls-eap) — outer tunnel.

Definition at line 373 of file PoliticianTypes.h.

◆ EAP_METHOD_TLS

const uint8_t politician::EAP_METHOD_TLS = 0x0D
static

EAP-TLS (RFC 5216) — mutual cert auth.

Definition at line 371 of file PoliticianTypes.h.

◆ EAP_METHOD_TTLS

const uint8_t politician::EAP_METHOD_TTLS = 0x15
static

EAP-TTLS (RFC 5281) — outer tunnel, inner MSCHAPv2.

Definition at line 372 of file PoliticianTypes.h.