ieee80211

Documentation

Overview

Package ieee80211 decodes IEEE 802.11 management frames — the beacon / probe / authentication / association / deauthentication / disassociation frames captured by every WiFi sniffer (Marauder, hcxdumptool, aircrack-ng, Wireshark). Pure offline parser; no transport, no hardware.

Wrap-vs-native judgement: IEEE 802.11 is a fully public standard. The walker is bit-level decoding over a 24-byte MAC header + per-subtype body + Information Element loop. Wrapping a FAP for this would add an SD-card install step + a firmware-fork dependency for a pure parser. Native delivers offline analysis — operators paste a captured frame and inspect every MAC-layer field without a WiFi adapter attached.

Pairs with the existing wifi_eapol_decode (which handles the EAPOL data frames inside the 4-way handshake) — together they cover the WiFi management + key-exchange surface.

What this package covers:

• Frame Control (16 bits): Protocol Version / Type / Subtype / To DS / From DS / More Frag / Retry / Power Mgt / More Data / Protected Frame / Order flags
• 24-byte MAC header (addresses + duration + sequence control)
• Per-subtype body decode:
• Beacon (subtype 8): timestamp + beacon interval + capability info + Information Elements
• Probe Response (5): same as Beacon
• Probe Request (4): Information Elements only
• Authentication (11): auth algorithm + sequence + status code + IEs
• Association Request (0) / Response (1): capability + IEs
• Disassociation (10) / Deauthentication (12): reason code lookup
• Information Element walker for the common types: SSID (0), Supported Rates (1), DS Parameter Set (3), TIM (5), Country (7), RSN (48 = WPA2/WPA3), Vendor Specific (221 — WPA1, WPS, Microsoft, etc.)

What this package does NOT cover (deliberately out of scope):

• Data frames (Type=2) — wifi_eapol_decode handles the EAPOL data frames, the rest are typically encrypted
• Control frames (Type=1) — RTS / CTS / ACK / Block Ack, mostly opaque single-frame protocols
• QoS Data subtype fields past the basic header (those need the QoS Control / HT Control bytes — happy to add when a caller materialises)
• HT / VHT / HE Capabilities IE field-decoding (just the IE walker surfaces them as hex; full decode is a follow-on Spec)
• FCS validation (the trailing 4-byte CRC, often stripped by capture tools)

Index

• type CapabilityInfo
• type Frame
  • func Decode(hexBlob string) (Frame, error)
  • func DecodeBytes(b []byte) (Frame, error)
• type FrameControl
• type FrameType
  • func (t FrameType) String() string
• type InformationElement

Types

type CapabilityInfo

type CapabilityInfo struct {
	Raw           int  `json:"raw"`
	ESS           bool `json:"ess"`
	IBSS          bool `json:"ibss"`
	Privacy       bool `json:"privacy"`
	ShortPreamble bool `json:"short_preamble"`
	ShortSlotTime bool `json:"short_slot_time"`
	SpectrumMgmt  bool `json:"spectrum_mgmt"`
	QoS           bool `json:"qos"`
}

CapabilityInfo is the decoded 16-bit Capability Info field (present in Beacon / Probe Response / Association Request/Response).

type Frame

type Frame struct {
	FrameControl FrameControl `json:"frame_control"`
	// Duration is the 2-byte duration field (microseconds or
	// AID, context-dependent).
	Duration int `json:"duration"`
	// DA is the Destination Address (Address 1).
	DA string `json:"destination_address"`
	// SA is the Source Address (Address 2).
	SA string `json:"source_address"`
	// BSSID is the BSSID (Address 3).
	BSSID string `json:"bssid"`
	// SequenceNumber (12 bits) and FragmentNumber (4 bits)
	// from the Sequence Control field.
	SequenceNumber int `json:"sequence_number"`
	FragmentNumber int `json:"fragment_number"`
	// Body fields populated per subtype.
	Timestamp           *uint64              `json:"timestamp,omitempty"`
	BeaconInterval      *int                 `json:"beacon_interval,omitempty"`
	Capabilities        *CapabilityInfo      `json:"capabilities,omitempty"`
	AuthAlgorithm       *int                 `json:"auth_algorithm,omitempty"`
	AuthSequence        *int                 `json:"auth_sequence,omitempty"`
	StatusCode          *int                 `json:"status_code,omitempty"`
	ReasonCode          *int                 `json:"reason_code,omitempty"`
	ReasonCodeName      string               `json:"reason_code_name,omitempty"`
	ListenInterval      *int                 `json:"listen_interval,omitempty"`
	InformationElements []InformationElement `json:"information_elements,omitempty"`
	// PayloadHex is the raw input for callers that want to
	// cross-reference with the original.
	PayloadHex string `json:"payload_hex"`
}

Frame is the top-level decoded management frame.

func Decode

func Decode(hexBlob string) (Frame, error)

Decode parses a hex-encoded 802.11 management frame. Tolerates ':' / '-' / '_' / whitespace separators.

func DecodeBytes

func DecodeBytes(b []byte) (Frame, error)

DecodeBytes is the byte-slice variant of Decode.

type FrameControl

type FrameControl struct {
	Raw int `json:"raw"`
	// Protocol Version (bits 1..0) — always 0 in current spec.
	ProtocolVersion int `json:"protocol_version"`
	// Type (bits 3..2) — Management / Control / Data / Extension.
	Type     int    `json:"type"`
	TypeName string `json:"type_name"`
	// Subtype (bits 7..4) — type-specific.
	Subtype         int    `json:"subtype"`
	SubtypeName     string `json:"subtype_name"`
	ToDS            bool   `json:"to_ds"`
	FromDS          bool   `json:"from_ds"`
	MoreFragments   bool   `json:"more_fragments"`
	Retry           bool   `json:"retry"`
	PowerManagement bool   `json:"power_management"`
	MoreData        bool   `json:"more_data"`
	ProtectedFrame  bool   `json:"protected_frame"`
	Order           bool   `json:"order"`
}

FrameControl is the decoded 16-bit Frame Control field.

type FrameType

type FrameType int

FrameType is the 2-bit type field at bits 3..2 of byte 0.

const (
	FrameTypeManagement FrameType = 0
	FrameTypeControl    FrameType = 1
	FrameTypeData       FrameType = 2
	FrameTypeExtension  FrameType = 3
)

func (FrameType) String

func (t FrameType) String() string

type InformationElement

type InformationElement struct {
	ID      int    `json:"id"`
	IDHex   string `json:"id_hex"`
	Name    string `json:"name"`
	Length  int    `json:"length"`
	DataHex string `json:"data_hex"`
	// Decoded carries per-IE field decode. Populated for the
	// common types we dissect (SSID, Rates, DS, RSN, Vendor
	// Specific). nil for IEs we leave as raw hex.
	Decoded map[string]any `json:"decoded,omitempty"`
}

InformationElement is one IE in a beacon / probe response / association frame.