get-the-hacker/gth/engine.py
Aliaksandr Zasinets 791459edc8 gth
2026-10-27 14:16:13 +01:00

647 lines
37 KiB
Python

"""Passive WIDS rules. Report frame facts. Do not claim human identity."""
from collections import OrderedDict, deque
import copy
import math
import re
DEFAULTS = {
"deauth_count": 20, "deauth_window": 10.0, "deauth_sequence_min": 5,
"probe_count": 30, "probe_ssids": 10, "probe_window": 30.0,
"beacon_count": 3, "beacon_window": 30.0,
"karma_ssids": 5, "karma_clients": 2, "karma_window": 60.0,
"karma_response_delay": 2.0,
"handshake_count": 8, "handshake_window": 60.0,
"auth_fail_count": 8, "auth_fail_window": 60.0,
"assoc_fail_count": 8, "assoc_fail_window": 60.0,
"wps_fail_count": 8, "wps_fail_window": 60.0,
"cooldown": 30.0, "dedup_window": 2.0,
"max_keys": 1024, "max_events_per_key": 128,
"max_total_events": 20000, "max_dedup": 16384, "max_cooldowns": 4096,
}
KINDS = frozenset({"beacon", "probe_request", "probe_response", "deauth",
"disassoc", "auth", "assoc_request", "assoc_response", "reassoc_response", "eap", "eapol_key", "wps"})
SECURITY = {"open": 0, "wep": 1, "wpa": 2, "wpa2": 3, "wpa3": 4}
MAC = re.compile(r"(?:[0-9a-f]{2}:){5}[0-9a-f]{2}\Z")
BROADCAST = "ff:ff:ff:ff:ff:ff"
COMMON_LIMITS = [
"A MAC address is a transmitter claim. It can be spoofed or changed.",
"Capture loss and channel coverage can hide frames.",
"Sensor GPS is not source GPS. Source location is unknown.",
]
RULE_KINDS = {
'deauth_burst': {'deauth', 'disassoc'}, 'active_recon': {'probe_request'},
'possible_evil_twin': {'beacon'}, 'ap_policy_change': {'beacon'},
'possible_karma': {'probe_request', 'probe_response'},
'handshake_attempt_burst': {'eapol_key'}, 'auth_failure_burst': {'auth'},
'assoc_failure_burst': {'assoc_response', 'reassoc_response'},
'wps_failure_burst': {'wps'},
}
def _ssid_identity(record):
"""Use exact SSID bytes. Legacy UTF-8 text keeps its old meaning."""
text, encoded = record.get('ssid'), record.get('ssid_hex')
if encoded is not None:
if not isinstance(encoded, str) or len(encoded) > 64 or len(encoded) % 2 or not re.fullmatch(r'[0-9a-fA-F]*', encoded):
raise ValueError('SSID bytes are not valid.')
raw = bytes.fromhex(encoded)
if text is not None and raw.decode('utf-8', errors='replace') != text:
raise ValueError('SSID text and bytes do not match.')
return encoded.lower()
if text is None:
return None
if not isinstance(text, str):
raise ValueError('SSID text is not valid.')
raw = text.encode('utf-8')
if len(raw) > 32:
raise ValueError('SSID is longer than 32 bytes.')
return raw.hex()
from .values import finite as _number, timestamp as _timestamp
def _mac(value, optional=False):
if value is None and optional:
return None
if not isinstance(value, str) or not MAC.fullmatch(value.lower()):
raise ValueError("MAC address is not valid.")
return value.lower()
class Engine:
"""Process time-ordered normalized events in one thread.
Configuration: {"trusted_aps": [...], "detection": {policy: value}}.
Other top-level fields belong to the application and are ignored.
No rule sends a radio frame or starts a process.
"""
def __init__(self, config=None):
if config is None:
config = {}
if not isinstance(config, dict):
raise ValueError("Config must be an object.")
policy = config.get("detection", {})
if not isinstance(policy, dict):
raise ValueError("Detection config must be an object.")
unknown = set(policy) - set(DEFAULTS)
if unknown:
raise ValueError("Unknown detection setting: " + str(sorted(unknown, key=str)[0]))
self.policy = dict(DEFAULTS)
self.policy.update(policy)
for key, value in self.policy.items():
if not _number(value):
raise ValueError("Detection setting must be a finite number: " + key)
if isinstance(DEFAULTS[key], int):
if not isinstance(value, int) or not 1 <= value <= 100000:
raise ValueError("Detection count must be an integer from 1 to 100000: " + key)
elif not (0 <= value <= 3600 if key in {"cooldown", "dedup_window"} else 0 < value <= 3600):
raise ValueError("Detection time is outside the safe range: " + key)
p = self.policy
threshold_keys = [k for k in p if k.endswith("_count") or k in {"probe_ssids", "karma_ssids", "karma_clients", "deauth_sequence_min"}]
if any(p[k] > p["max_events_per_key"] for k in threshold_keys):
raise ValueError("Event limit is smaller than a detection threshold.")
if p["max_total_events"] < p["max_events_per_key"]:
raise ValueError("Total event limit is smaller than the per-key limit.")
if p["deauth_sequence_min"] > p["deauth_count"] or p["probe_ssids"] > p["probe_count"]:
raise ValueError("Unique-value threshold is larger than the frame count.")
if p["karma_response_delay"] > p["probe_window"]:
raise ValueError("KARMA response delay is larger than the Probe Request window.")
baselines = config.get("trusted_aps", [])
if not isinstance(baselines, list) or len(baselines) > 4096:
raise ValueError("Trusted APs must be a list with at most 4096 entries.")
self.baselines = {}
self._ap_policies = {}
self.trusted_pairs = set()
for ap in baselines:
if not isinstance(ap, dict):
raise ValueError("Each trusted AP must be an object.")
ssid = ap.get("ssid")
if not isinstance(ssid, str) or not 1 <= len(ssid) <= 128:
raise ValueError("Trusted SSID must be a nonempty text value.")
bssid = _mac(ap.get("bssid"))
if int(bssid[:2], 16) & 1:
raise ValueError("Trusted BSSID must be a unicast MAC address.")
security = ap.get("security")
if not isinstance(security, str) or security not in SECURITY:
raise ValueError("Trusted AP security must be open, wep, wpa, wpa2, or wpa3.")
if "pmf_required" in ap and not isinstance(ap["pmf_required"], bool):
raise ValueError("PMF required must be true or false.")
identity = _ssid_identity(ap)
old = self.baselines.get(identity, [])
if any(row["bssid"] == bssid and row["security"] != security for row in old):
raise ValueError("Trusted AP has conflicting security values.")
row = {"ssid": ssid, "bssid": bssid, "security": security}
if 'ssid_hex' in ap:
row['ssid_hex'] = identity
if 'pmf_required' in ap:
row['pmf_required'] = ap['pmf_required']
if any(row['bssid'] == bssid and row != prior for prior in old if prior['bssid'] == bssid):
raise ValueError('Trusted AP has conflicting policy values.')
if row not in old:
old.append(row)
self.baselines[identity] = old
policies=self._ap_policies.setdefault(bssid,[])
if row not in policies:policies.append(row)
self.trusted_pairs.add((identity, bssid))
self.stats = {key: 0 for key in (
"events_received", "events_accepted", "invalid_events", "bad_fcs",
"out_of_order", "retries_ignored", "state_evictions", "event_evictions",
"dedup_evictions", "cooldown_evictions", "alerts", "recon_observations",
"rule_events", "policy_observations", "cooldown_suppressed", "expired_events")}
self.coverage = {'first_timestamp': None, 'last_timestamp': None, 'kinds': {},
'rules': {rule: {'enabled': bool(self.trusted_pairs) if rule in {'possible_evil_twin', 'ap_policy_change'} else True,
'eligible_events': 0, 'first_timestamp': None, 'last_timestamp': None,
'missing_fields': {}} for rule in RULE_KINDS}}
self.rule_inputs = {}
self._streams = OrderedDict()
self._dedup = OrderedDict()
self._cooldowns = OrderedDict()
self._stored = 0
self._last_time = None
self._serial = 0
self._ttl = max(p[k] for k in p if k.endswith("_window"))
def baseline_for(self, event):
"""Return the policy for exact SSID bytes. Display text is not an ID."""
try:
return self.baselines.get(_ssid_identity(event), [])
except ValueError:
return []
def ap_policy_for(self, event):
"""List allowed settings for one claimed BSSID."""
return self._ap_policies.get(event.get('bssid'),[])
def _normalize(self, event):
if not isinstance(event, dict):
raise ValueError("Event must be an object.")
ts = event.get("timestamp")
if not _timestamp(ts) or event.get("kind") not in KINDS:
raise ValueError("Event time or kind is not valid.")
e = {"timestamp": float(ts), "kind": event["kind"],
"source": _mac(event.get("source")),
"destination": _mac(event.get("destination"), True),
"bssid": _mac(event.get("bssid"), True)}
if int(e["source"][:2], 16) & 1:
raise ValueError("Source must be a unicast MAC address.")
if e["bssid"] == BROADCAST:
e["bssid"] = None
if e["bssid"] is not None and int(e["bssid"][:2], 16) & 1:
raise ValueError("BSSID must be a unicast MAC address.")
for key in ("retry", "protected", "bad_fcs"):
if key in event and not isinstance(event[key], bool):
raise ValueError("Frame flag must be true or false.")
e[key] = event.get(key, False)
for key, low, high in (("sequence", 0, 4095), ("fragment", 0, 15),
("rssi", -127, 0), ("channel", 1, 255),
("reason", 0, 65535), ("status", 0, 65535),
("eap_code", 1, 4), ("eap_type", 0, 255),
("eap_id", 0, 255), ("key_message", 1, 4),
("replay_counter", 0, 2**64 - 1),
("config_error", 0, 65535)):
value = event.get(key)
if value is not None and (not isinstance(value, int) or isinstance(value, bool) or not low <= value <= high):
raise ValueError("Frame number is not valid: " + key)
e[key] = value
for key in ("ssid", "nonce", "key_nonce", "frame_hash", "session_id"):
value = event.get(key)
if value is not None and (not isinstance(value, str) or len(value) > 128):
raise ValueError("Frame text is not valid: " + key)
e[key] = value
e['_ssid_key'] = _ssid_identity(event)
for key in ('pmf_required', 'pmf_capable', 'rsn_valid'):
value = event.get(key)
if value is not None and not isinstance(value, bool):
raise ValueError('RSN flag must be true, false, or null.')
e[key] = value
if e["nonce"] is None:
e["nonce"] = e["key_nonce"]
if e["nonce"] is not None:
e["nonce"] = e["nonce"].lower()
e["security"] = event.get("security", "unknown")
if e["security"] not in set(SECURITY) | {"unknown"}:
raise ValueError("Frame security is not valid.")
wps_type = event.get("wps_message_type", event.get("message_type"))
if wps_type is not None and (isinstance(wps_type, bool) or not isinstance(wps_type, (int, str))):
raise ValueError("WPS message type is not valid.")
if isinstance(wps_type, str) and len(wps_type) > 32:
raise ValueError("WPS message type is too long.")
e["wps_message_type"] = wps_type
gps = event.get("sensor_gps")
e["sensor_gps"] = None
if gps is not None:
if not isinstance(gps, dict):
raise ValueError("Sensor GPS must be an object or null.")
# The GPS adapter owns fix checks. Keep scalar report fields only.
allowed = {"latitude", "longitude", "altitude_m", "accuracy_m", "timestamp",
"status", "source", "mode", "lat", "lon", "error_m", "age_s",
"provider", "accuracy_kind", "reason", "fix_mode"}
e["sensor_gps"] = {k: v for k, v in gps.items() if k in allowed and
(v is None or isinstance(v, bool) or _number(v) or isinstance(v, str) and len(v) <= 128)}
e["_raw_evidence"] = event
e["_evidence_event"] = None
e["_evidence_ref"] = event.get("_evidence_ref")
return e
def _expire(self, now):
while self._streams:
key, values = next(iter(self._streams.items()))
if values[-1]["timestamp"] >= now - self._ttl:
break
self._streams.pop(key)
self._stored -= len(values)
self.stats["expired_events"] += len(values)
for cache, window in ((self._dedup, self.policy["dedup_window"]),
(self._cooldowns, self.policy["cooldown"])):
while cache and next(iter(cache.values())) < now - window:
cache.popitem(last=False)
def _is_retry_copy(self, e):
if e["sequence"] is None or self.policy["dedup_window"] == 0:
return False
fields = ("kind", "source", "destination", "bssid", "sequence", "fragment",
"_ssid_key", "security", "pmf_required", "pmf_capable", "protected", "reason", "status", "key_message",
"replay_counter", "nonce", "eap_code", "eap_type", "eap_id",
"wps_message_type", "config_error", "session_id", "frame_hash")
signature = tuple(e.get(k) for k in fields)
previous = self._dedup.get(signature)
if e["retry"] and previous is not None and e["timestamp"] - previous <= self.policy["dedup_window"]:
return True
self._dedup[signature] = e["timestamp"]
self._dedup.move_to_end(signature)
while len(self._dedup) > self.policy["max_dedup"]:
self._dedup.popitem(last=False)
self.stats["dedup_evictions"] += 1
return False
def _drop_oldest_stream(self):
_, values = self._streams.popitem(last=False)
self._stored -= len(values)
self.stats["state_evictions"] += 1
self.stats["event_evictions"] += len(values)
def _add(self, key, e, window):
# Copy raw Evidence only when a rule stores this frame.
# Stateless observations do not need a second full event copy.
if e.get('_evidence_event') is None:
raw=e.pop('_raw_evidence')
e['_evidence_event']=copy.deepcopy({k:v for k,v in raw.items() if k!='_evidence_ref'})
e['_evidence_ref']=copy.deepcopy(e['_evidence_ref'])
values = self._streams.get(key)
if values is None:
while len(self._streams) >= self.policy["max_keys"]:
self._drop_oldest_stream()
values = deque()
self._streams[key] = values
while values and values[0]["timestamp"] < e["timestamp"] - window:
values.popleft()
self._stored -= 1
self.stats["expired_events"] += 1
if len(values) >= self.policy["max_events_per_key"]:
values.popleft()
self._stored -= 1
self.stats["event_evictions"] += 1
values.append(e)
self._stored += 1
self._streams.move_to_end(key)
while self._stored > self.policy["max_total_events"]:
self._drop_oldest_stream()
rule={'deauth':'deauth_burst','probe':'active_recon','twin':'possible_evil_twin','ap_policy':'ap_policy_change',
'karma':'possible_karma','auth_fail':'auth_failure_burst','assoc_fail':'assoc_failure_burst',
'handshake':'handshake_attempt_burst','wps_fail':'wps_failure_burst'}.get(key[0])
if rule:
previous=self.rule_inputs.get(rule,{})
self.rule_inputs[rule]={'candidate_frames':len(values),'peak_candidate_frames':max(len(values),previous.get('peak_candidate_frames',0)),
'window_s':window,'observed_at':e['timestamp'],
'scope':'One stored source and AP group. Peak uses the saved session.'}
return values
def _emit(self, e, rule_id, method, evidence, limits, source=None, frames=()):
source = source or e["source"]
key = (rule_id, source, e["bssid"])
previous = self._cooldowns.get(key)
if previous is not None and e["timestamp"] - previous < self.policy["cooldown"]:
self.stats["cooldown_suppressed"] += 1
return []
self._cooldowns[key] = e["timestamp"]
self._cooldowns.move_to_end(key)
while len(self._cooldowns) > self.policy["max_cooldowns"]:
self._cooldowns.popitem(last=False)
self.stats["cooldown_evictions"] += 1
self._serial += 1
self.stats["alerts"] += 1
event_type = ('recon_observation' if rule_id == 'active_recon' else
'policy_observation' if rule_id == 'ap_policy_change' else 'wireless_evidence')
self.stats[{'recon_observation': 'recon_observations', 'policy_observation': 'policy_observations',
'wireless_evidence': 'rule_events'}[event_type]] += 1
# RSSI belongs to the actual frame sender, not an inferred client.
rssi = e["rssi"] if source == e["source"] else None
evidence = dict(evidence, frame_transmitter=e["source"],
frame_rssi_dbm=e["rssi"], sequence=e["sequence"],
source_claim="frame transmitter" if source == e["source"] else "frame receiver")
return [{"id": f"GTH-{self._serial:06d}", "rule_id": rule_id,
"attack_method": method, "result": "EVENT DETECTED",
"event_type": event_type,
"timestamp": e["timestamp"], "source": source,
"bssid": e["bssid"], "ssid": e["ssid"], "rssi": rssi,
"channel": e["channel"], "evidence": evidence,
"sensor_gps": e["sensor_gps"], "source_location": None,
"limitations": COMMON_LIMITS + limits,
"_proof_frames": [{"event":row["_evidence_event"], "reference":row["_evidence_ref"]} for row in frames]}]
def process(self, event):
"""Return new findings. Invalid events are counted and skipped."""
self.stats["events_received"] += 1
try:
e = self._normalize(event)
except (ValueError, TypeError, OverflowError):
self.stats["invalid_events"] += 1
return []
if e["bad_fcs"]:
self.stats["bad_fcs"] += 1
return []
if self._last_time is not None and e["timestamp"] < self._last_time:
self.stats["out_of_order"] += 1
return []
self._last_time = e["timestamp"]
self._expire(e["timestamp"])
if self._is_retry_copy(e):
self.stats["retries_ignored"] += 1
return []
self.stats["events_accepted"] += 1
self._cover(e)
kind, p = e["kind"], self.policy
if kind in {"deauth", "disassoc"} and e["bssid"]:
values = self._add(("deauth", e["source"], e["bssid"]), e, p["deauth_window"])
sequences = {row["sequence"] for row in values if row["sequence"] is not None}
duration = values[-1]["timestamp"] - values[0]["timestamp"]
time_bins = {math.floor(row["timestamp"] * 4) for row in values}
# Several injection tools reuse sequence zero. A sustained pattern is
# useful Evidence, but capture copies can mimic it.
self.rule_inputs['deauth_burst'].update(distinct_sequences=len(sequences),time_bins=len(time_bins))
varied_sequence = len(sequences) >= p["deauth_sequence_min"]
sustained_sequence = bool(sequences) and duration >= 1.0 and len(time_bins) >= 4
if len(values) >= p["deauth_count"] and (varied_sequence or sustained_sequence):
protected = sum(row["protected"] for row in values)
deauth_frames = sum(row["kind"] == "deauth" for row in values)
disassoc_frames = len(values) - deauth_frames
method = ("DEAUTH/DISASSOC BURST DETECTED" if deauth_frames and disassoc_frames
else "DEAUTH BURST DETECTED" if deauth_frames
else "DISASSOC BURST DETECTED")
return self._emit(e, "deauth_burst", method,
{"frame_count": len(values), "distinct_sequences": len(sequences),
"deauth_frames": deauth_frames, "disassoc_frames": disassoc_frames,
"window_seconds": p["deauth_window"], "protected_frames": protected,
"duration_seconds": duration, "distinct_250ms_bins": len(time_bins),
"sequence_pattern": "varied" if varied_sequence else "sustained reuse",
"unprotected_frames": len(values) - protected,
"reasons": sorted({row["reason"] for row in values if row["reason"] is not None})},
["An AP reset can cause a burst. This rule does not prove an attack.",
"A protected flag does not prove a valid PMF MIC.",
"Capture copies without Retry flags can mimic sustained sequence reuse."], frames=values)
elif kind == "probe_request":
values = self._add(("probe", e["source"], None), e, p["probe_window"])
ssids = {row['_ssid_key'] for row in values if row['_ssid_key']}
self.rule_inputs['active_recon']['distinct_ssids']=len(ssids)
if len(values) >= p["probe_count"] and len(ssids) >= p["probe_ssids"]:
return self._emit(e, "active_recon", "DIRECTED PROBE BURST DETECTED",
{"frame_count": len(values), "distinct_ssids": len(ssids),
"window_seconds": p["probe_window"], "ssid_sample": sorted({row['ssid'] for row in values if row['ssid']})[:10],
"ssid_hex_sample": sorted(ssids)[:10]},
["Probe Requests are normal for many devices. This is not an attack finding.",
"A silent passive scanner cannot be found from Probe Requests."], frames=values)
elif kind == "beacon" and e['_ssid_key'] and e["bssid"]:
baseline = self.baselines.get(e['_ssid_key'], [])
rank = SECURITY.get(e["security"])
if e['rsn_valid'] is False:
return []
ap_policy=self.ap_policy_for(e)
if ap_policy:
return self._ap_policy(e, ap_policy)
if baseline and rank is not None:
expected_rank = min(SECURITY[row["security"]] for row in baseline)
if rank < expected_rank:
values = self._add(("twin", e["source"], e["bssid"], e['_ssid_key'], e["security"]), e, p["beacon_window"])
sequences = {row["sequence"] for row in values if row["sequence"] is not None}
if len(values) >= p["beacon_count"] and len(sequences) >= min(p["beacon_count"], 3):
return self._emit(e, "possible_evil_twin", "AP SECURITY MISMATCH",
{"beacon_count": len(values), "window_seconds": p["beacon_window"],
"observed_security": e["security"], "trusted_aps": baseline,
"baseline_source": "explicit user config"},
["A planned guest AP or AP change can match this rule.",
"A same-BSSID clone is outside this rule."], frames=values)
elif kind == "probe_response" and e["ssid"] and e["bssid"] and e["destination"]:
requests = self._streams.get(("probe", e["destination"], None), ())
matched = next((row for row in reversed(requests) if row['_ssid_key'] == e['_ssid_key'] and
row["destination"] in {None, BROADCAST, e["source"]} and
0 <= e["timestamp"] - row["timestamp"] <= p["karma_response_delay"]
), None)
if matched is not None:
e["_matched_probe"] = matched
values = self._add(("karma", e["source"], e["bssid"]), e, p["karma_window"])
ssids = {row['_ssid_key'] for row in values}
clients = {row["destination"] for row in values}
self.rule_inputs['possible_karma'].update(distinct_ssids=len(ssids),distinct_clients=len(clients))
if len(ssids) >= p["karma_ssids"] and len(clients) >= p["karma_clients"]:
return self._emit(e, "possible_karma", "MULTI-SSID RESPONSES DETECTED",
{"matched_responses": len(values), "distinct_ssids": len(ssids),
"distinct_clients": len(clients), "window_seconds": p["karma_window"],
"ssid_sample": sorted({row['ssid'] for row in values})[:10],
"ssid_hex_sample": sorted(ssids)[:10]},
["Multi-SSID AP behavior can match this rule. This is not proof of KARMA."],
frames=sorted({id(row):row for response in values for row in (response["_matched_probe"],response)}.values(), key=lambda row:row["timestamp"]))
elif kind == "eapol_key" and e["bssid"]:
return self._handshake(e)
elif kind == "auth" and e["status"] not in {None, 0} and e["source"] == e["bssid"] and e["destination"] not in {None, BROADCAST}:
values = self._add(("auth_fail", e["destination"], e["bssid"]), e, p["auth_fail_window"])
if len(values) >= p["auth_fail_count"]:
return self._emit(e, "auth_failure_burst", "AUTH FAILURE BURST DETECTED",
{"failure_count": len(values), "window_seconds": p["auth_fail_window"],
"reported_by": e["source"], "status_codes": sorted({r["status"] for r in values})},
["Bad device settings can cause failures. This does not prove brute force.",
"The client is a receiver claim in the AP frame. Client RSSI is unknown."],
source=e["destination"], frames=values)
elif kind in {"assoc_response", "reassoc_response"} and e["status"] not in {None, 0} and e["source"] == e["bssid"] and e["destination"] not in {None, BROADCAST}:
values = self._add(("assoc_fail", e["destination"], e["bssid"]), e, p["assoc_fail_window"])
if len(values) >= p["assoc_fail_count"]:
return self._emit(e, "assoc_failure_burst", "ASSOCIATION REJECT BURST DETECTED",
{"failure_count": len(values), "window_seconds": p["assoc_fail_window"],
"reported_by": e["source"], "status_codes": sorted({r["status"] for r in values}),
"response_types": sorted({r["kind"] for r in values})},
["AP limits or client settings can cause rejects. This does not prove an attack.",
"The AP frame names the receiver. Client RSSI is unknown."],
source=e["destination"], frames=values)
elif kind == "wps" and e["bssid"]:
return self._wps(e)
return []
def _ap_policy(self, e, baseline):
same_name=[row for row in baseline if _ssid_identity(row)==e['_ssid_key']]
candidates=same_name or baseline
expected=candidates[0]
changed = {}
if not same_name:
changed['ssid']={'expected':[row['ssid'] for row in candidates],'observed':e['ssid'], 'observed_hex':e['_ssid_key']}
if e['security'] in SECURITY and not any(e['security']==row['security'] for row in candidates):
changed['security'] = {'expected': expected['security'], 'observed': e['security']}
pmf=[row['pmf_required'] for row in candidates if 'pmf_required' in row]
if len(pmf)==len(candidates) and e['pmf_required'] is not None and e['pmf_required'] not in pmf:
changed['pmf_required'] = {'expected': pmf[0], 'observed': e['pmf_required']}
if not changed:
return []
signature = tuple((key, row.get('observed_hex',row['observed'])) for key, row in sorted(changed.items()))
values = self._add(('ap_policy', e['source'], e['bssid'], e['_ssid_key'], signature), e, self.policy['beacon_window'])
sequences = {row['sequence'] for row in values if row['sequence'] is not None}
if len(values) < self.policy['beacon_count'] or len(sequences) < min(self.policy['beacon_count'], 3):
return []
return self._emit(e, 'ap_policy_change', 'AP POLICY CHANGE',
{'beacon_count': len(values), 'distinct_sequences': len(sequences),
'window_seconds': self.policy['beacon_window'], 'changes': changed,
'trusted_ap': expected, 'baseline_source': 'explicit user config'},
['An AP config change can match this rule. This is a policy observation.',
'A BSSID can be spoofed. These frames do not prove a clone or an attack.'], frames=values)
def _cover(self, e):
"""Count accepted input and rule prerequisites. This is not accuracy."""
coverage, kind, stamp = self.coverage, e['kind'], e['timestamp']
if coverage['first_timestamp'] is None:
coverage['first_timestamp'] = stamp
coverage['last_timestamp'] = stamp
coverage['kinds'][kind] = coverage['kinds'].get(kind, 0) + 1
for rule, kinds in RULE_KINDS.items():
if kind not in kinds:
continue
row, missing = coverage['rules'][rule], []
if rule not in {'active_recon', 'possible_karma'} and not e['bssid']:
missing.append('bssid')
if rule in {'active_recon', 'possible_karma', 'possible_evil_twin', 'ap_policy_change'} and not e['_ssid_key']:
missing.append('ssid')
if rule in {'possible_evil_twin', 'ap_policy_change'}:
baseline = self.baselines.get(e['_ssid_key'], [])
if rule == 'ap_policy_change':
baseline = self.ap_policy_for(e)
if not baseline:
missing.append('baseline')
if e['security'] == 'unknown':
missing.append('security')
if e['rsn_valid'] is False:
missing.append('valid_rsn')
if rule == 'ap_policy_change' and any('pmf_required' in ap for ap in baseline) and e['pmf_required'] is None:
# PMF can be unknown while a security comparison is possible.
fields = row['missing_fields']
fields['pmf_required'] = fields.get('pmf_required', 0) + 1
if rule == 'deauth_burst' and e['sequence'] is None:
missing.append('sequence')
if rule == 'possible_karma' and kind == 'probe_response':
if not e['bssid']:
missing.append('bssid')
if e['destination'] in {None, BROADCAST}:
missing.append('client')
if rule in {'auth_failure_burst', 'assoc_failure_burst'}:
if e['status'] is None:
missing.append('status')
if e['source'] != e['bssid'] or e['destination'] in {None, BROADCAST}:
missing.append('ap_response')
if rule == 'handshake_attempt_burst':
if e['key_message'] is None:
missing.append('key_message')
if e['replay_counter'] is None:
missing.append('replay_counter')
if e['key_message'] == 2 and (not e['nonce'] or not re.fullmatch('[0-9a-f]{64}', e['nonce']) or int(e['nonce'], 16) == 0):
missing.append('nonce')
if not ((e['key_message'] in {1, 3} and e['source'] == e['bssid'] and e['destination'] not in {None, BROADCAST}) or
(e['key_message'] in {2, 4} and e['destination'] == e['bssid'] and e['source'] != e['bssid'])):
missing.append('handshake_direction')
if rule == 'wps_failure_burst':
if e['wps_message_type'] is None:
missing.append('wps_message_type')
if e['config_error'] is None:
missing.append('config_error')
if e['session_id'] is None and (e['sequence'] is None or e['eap_id'] is None):
missing.append('session_key')
for reason in missing:
row['missing_fields'][reason] = row['missing_fields'].get(reason, 0) + 1
if row['enabled'] and not missing:
row['eligible_events'] += 1
if row['first_timestamp'] is None:
row['first_timestamp'] = stamp
row['last_timestamp'] = stamp
def _handshake(self, e):
message, ap = e["key_message"], e["bssid"]
if message in {1, 3} and e["source"] == ap:
client = e["destination"]
elif message in {2, 4} and e["destination"] == ap and e["source"] != ap:
client = e["source"]
else:
return []
if client in {None, BROADCAST} or e["replay_counter"] is None:
return []
if message == 2 and (not e["nonce"] or not re.fullmatch(r"[0-9a-fA-F]{64}", e["nonce"]) or int(e["nonce"], 16) == 0):
return []
p = self.policy
values = self._add(("handshake", client, ap), e, p["handshake_window"])
if message != 2:
return []
attempts = {row["nonce"] for row in values if row["key_message"] == 2}
self.rule_inputs['handshake_attempt_burst']['distinct_attempts']=len(attempts)
if len(attempts) < p["handshake_count"]:
return []
# A linked M2 -> M3 -> M4 is conservative evidence of a completed exchange.
# M3 alone or an unrelated replay counter must not suppress this rule.
completed = False
last_m2 = {}
m3 = set()
for row in values:
counter = row["replay_counter"]
if row["key_message"] == 2:
last_m2[counter] = row["timestamp"]
elif row["key_message"] == 3 and counter - 1 in last_m2:
m3.add(counter)
elif row["key_message"] == 4 and counter in m3:
completed = True
if completed:
return []
return self._emit(e, "handshake_attempt_burst", "EAPOL RETRY PATTERN DETECTED",
{"distinct_attempts": len(attempts), "window_seconds": p["handshake_window"],
"completed_exchange_seen": False, "count_basis": "distinct nonzero M2 nonce; replay counter links the exchange"},
["Missing M3 or M4 can be capture loss. This does not prove password brute force.",
"PMKID presence and missing M2 alone do not start this rule."], frames=values)
def _wps(self, e):
if e["wps_message_type"] not in {14, "WSC_NACK", "NACK"} or e["config_error"] in {None, 0}:
return []
ap = e["bssid"]
client = e["destination"] if e["source"] == ap else e["source"]
if client in {None, BROADCAST}:
return []
if e["session_id"] is None and (e["sequence"] is None or e["eap_id"] is None):
return []
p = self.policy
values = self._add(("wps_fail", client, ap), e, p["wps_fail_window"])
failures = {row["session_id"] or (row["eap_id"], row["sequence"]) for row in values}
self.rule_inputs['wps_failure_burst']['distinct_failures']=len(failures)
if len(failures) >= p["wps_fail_count"]:
return self._emit(e, "wps_failure_burst", "WPS FAILURE BURST DETECTED",
{"distinct_failure_results": len(failures), "window_seconds": p["wps_fail_window"],
"config_errors": sorted({row["config_error"] for row in values}),
"count_basis": "session ID or EAP ID and sequence"},
["Normal WPS setup faults can cause failures. This does not prove PIN brute force.",
"Without a session ID, the rule counts failure frames, not complete sessions."],
source=client, frames=values)
return []
def snapshot(self):
return {"stats": dict(self.stats), "state": {"keys": len(self._streams),
"stored_events": self._stored, "dedup_keys": len(self._dedup),
"cooldown_keys": len(self._cooldowns), "last_timestamp": self._last_time},
"policy": dict(self.policy), "rule_inputs":copy.deepcopy(self.rule_inputs), "coverage": copy.deepcopy(self.coverage), "trusted_ap_count": len(self.trusted_pairs),
"source_location": "Unknown. This engine has no source position measurements.",
"unsupported": ["Silent passive scanning", "Offline password cracking",
"Person identity", "Source GPS from one RSSI value"]}