mirror of
https://github.com/buybitart/get-the-hacker.git
synced 2026-11-18 05:38:51 +00:00
647 lines
37 KiB
Python
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"]}
|