wifidefense

Documentation

Overview

Package wifidefense provides defensive, blue-team analysers over sequences of already-decoded 802.11 frames. It does no RF work — the caller supplies frame fields (e.g. from wifi_80211 decodes) and the analyser reports deterministic observations.

Wrap-vs-native judgement

Native. The 802.11 deauthentication / disassociation flood is the canonical WiFi denial-of-service (aircrack-ng's aireplay-0, the Marauder / ESP32 "deauth" attack, MDK4). Detecting it from a capture is a pure, deterministic transform over management-frame metadata — frame subtype, the destination address, the source/BSSID, and the 802.11 reason code — with no SDR, adapter, or crypto at analysis time. Like internal/tpms's AnalyzeFrames and internal/subghz's AnalyzeRollback, every flagged condition is an OBSERVATION with its benign explanation stated, never a definitive attack verdict.

Index

• Constants
• type AP
• type Analysis
  • func AnalyzeDeauth(frames []Frame, floodThreshold int) (*Analysis, error)
• type Frame
• type Observation
• type RogueAnalysis
  • func AnalyzeRogueAP(aps []AP) (*RogueAnalysis, error)
• type RogueObservation

Constants

const DefaultFloodThreshold = 10

DefaultFloodThreshold is the deauth+disassoc count above which the volume signal fires when no threshold is supplied.

Types

type AP

type AP struct {
	SSID     string `json:"ssid"`
	BSSID    string `json:"bssid"`
	Security string `json:"security,omitempty"`
	Channel  int    `json:"channel,omitempty"`
}

AP is one already-decoded beacon / probe-response observation supplied by the caller (e.g. from wifi_80211 + wifi_rsn_decode). Security is the posture string — "Open", "WPA2-Personal (PSK)", "WPA3-Personal (SAE)", etc. (whatever wifi_rsn_decode derived, or "Open" when no RSN IE).

type Analysis

type Analysis struct {
	FramesAnalyzed  int            `json:"frames_analyzed"`
	DeauthFrames    int            `json:"deauth_frames"`
	DisassocFrames  int            `json:"disassoc_frames"`
	BroadcastFrames int            `json:"broadcast_frames"`
	ReasonCodes     map[string]int `json:"reason_codes,omitempty"`
	Observations    []Observation  `json:"observations"`
	Notes           []string       `json:"notes,omitempty"`
}

Analysis is the structured result of AnalyzeDeauth.

func AnalyzeDeauth

func AnalyzeDeauth(frames []Frame, floodThreshold int) (*Analysis, error)

AnalyzeDeauth inspects a sequence of 802.11 frames for the signatures of a deauthentication / disassociation flood. floodThreshold is the deauth+disassoc count above which the volume signal fires (<=0 uses DefaultFloodThreshold).

Three deterministic signals are surfaced, each with its benign explanation:

• broadcast_deauth (warning): deauth/disassoc frames addressed to the broadcast address kick every client in the BSS at once. There is no benign reason to broadcast-deauth, so this is the clearest flood signature; the only innocent explanation is a misbehaving AP/driver.
• deauth_flood (warning): the deauth+disassoc count exceeds the threshold. Consistent with an aireplay/MDK4/Marauder flood OR a very unstable RF environment / a busy AP shedding load — correlate with the reason-code mix.
• targeted_client (info): one destination receives a disproportionate share of the deauths from one BSSID — a targeted disconnect (e.g. to force a handshake recapture) rather than an indiscriminate flood.

type Frame

type Frame struct {
	Subtype string `json:"subtype"`          // "deauth" | "disassoc" | other
	Src     string `json:"src,omitempty"`    // transmitter address
	Dst     string `json:"dst,omitempty"`    // destination address
	BSSID   string `json:"bssid,omitempty"`  // BSS identifier
	Reason  int    `json:"reason,omitempty"` // 802.11 reason code
}

Frame is one already-decoded 802.11 management frame supplied by the caller. Only the deauthentication (subtype "deauth") and disassociation (subtype "disassoc") subtypes drive the analysis; other subtypes are counted toward the total and otherwise ignored.

type Observation

type Observation struct {
	Kind     string `json:"kind"`     // "broadcast_deauth" | "deauth_flood" | "targeted_client"
	Severity string `json:"severity"` // "info" | "warning"
	Detail   string `json:"detail"`
}

Observation is one flagged signal. It is an OBSERVATION with interpretation, never a verdict — the benign explanation is always stated so the operator correlates rather than concludes.

type RogueAnalysis

type RogueAnalysis struct {
	APsAnalyzed  int                `json:"aps_analyzed"`
	UniqueSSIDs  int                `json:"unique_ssids"`
	UniqueBSSIDs int                `json:"unique_bssids"`
	Observations []RogueObservation `json:"observations"`
	Notes        []string           `json:"notes,omitempty"`
}

RogueAnalysis is the structured result of AnalyzeRogueAP.

func AnalyzeRogueAP

func AnalyzeRogueAP(aps []AP) (*RogueAnalysis, error)

AnalyzeRogueAP inspects a set of beacon/probe-response observations for rogue-AP / evil-twin signatures. Observations are grouped by SSID and by BSSID; ordering matters only for the per-BSSID change signal.

Three deterministic signals, each with its benign explanation:

• security_mismatch (warning): one SSID is advertised with more than one distinct security posture (e.g. Open AND WPA2). This is the classic evil-twin / downgrade lure — a rogue AP cloning a protected network's name with weaker (or no) security to harvest associations. Benign explanation: a site mid-migration running mixed APs, or inconsistent posture labelling by the caller.
• bssid_changed_security (warning): a single BSSID's security posture changes across the capture — consistent with a spoofed/cloned BSSID or an AP hijack. Benign explanation: a genuine reconfiguration during the capture window.
• ssid_multiple_bssid (info): one SSID is served by several BSSIDs with a consistent posture — normal for enterprise roaming / mesh, but surfaced so the operator can confirm every BSSID is theirs.

Hidden SSIDs (empty name) are excluded from the SSID-grouped signals.

type RogueObservation

type RogueObservation struct {
	Kind     string `json:"kind"`     // "security_mismatch" | "bssid_changed_security" | "ssid_multiple_bssid"
	Severity string `json:"severity"` // "info" | "warning"
	SSID     string `json:"ssid,omitempty"`
	BSSID    string `json:"bssid,omitempty"`
	Detail   string `json:"detail"`
}

RogueObservation is one flagged rogue-AP / evil-twin signal — an OBSERVATION with its benign explanation stated, never a verdict.