detect_query_bursts.py
Independent portfolio example using fictional events. Not an employer detection.
1 """Original offline lab heuristic. Counts observed LDAP search records, not connections."""
2 import argparse
3 import csv
4 import ipaddress
5 import json
6 import sys
7 from collections import defaultdict, deque
8 from datetime import datetime, timezone
9
10
11 def detect(rows, threshold=100, window_seconds=60):
12 if threshold < 1 or window_seconds < 1:
13 raise ValueError('threshold and window must be positive')
14 parsed, seen = [], {}
15 for line, row in enumerate(rows, 2):
16 try:
17 record_id = row['record_id'].strip()
18 if not record_id:
19 raise ValueError('empty record_id')
20 stamp = datetime.fromisoformat(row['timestamp'].replace('Z', '+00:00'))
21 if stamp.tzinfo is None:
22 raise ValueError('timestamp needs a UTC offset')
23 stamp = stamp.astimezone(timezone.utc)
24 source = str(ipaddress.ip_address(row['source_ip']))
25 dc = str(ipaddress.ip_address(row['dc_ip']))
26 if row['event_type'] != 'ldap_search':
27 raise ValueError('event_type must be ldap_search; do not use connection events')
28 # record_id must be unique within a DC's collection epoch/log.
29 identity, value = (dc, record_id), (stamp, source)
30 if identity in seen:
31 if seen[identity] != value:
32 raise ValueError('conflicting duplicate record_id')
33 continue
34 seen[identity] = value
35 parsed.append((stamp, source, dc, record_id))
36 except (KeyError, ValueError, AttributeError) as exc:
37 raise ValueError(f'CSV row {line}: {exc}') from exc
38 windows, active, alerts = defaultdict(deque), set(), []
39 for stamp, source, dc, record_id in sorted(parsed):
40 key = (source, dc)
41 queue = windows[key]
42 # Inclusive window: events exactly window_seconds apart count together.
43 while queue and (stamp - queue[0][0]).total_seconds() > window_seconds:
44 queue.popleft()
45 if len(queue) < threshold:
46 active.discard(key)
47 queue.append((stamp, record_id))
48 if len(queue) >= threshold and key not in active:
49 alerts.append({
50 'rule': 'observed_ldap_search_burst', 'source_ip': source,
51 'dc_ip': dc, 'window_start': queue[0][0].isoformat(),
52 'window_end': stamp.isoformat(), 'observed_count': len(queue),
53 'threshold': threshold, 'window_seconds': window_seconds,
54 'record_ids': [r for _, r in queue],
55 'assessment': 'Review required; volume alone does not establish reconnaissance.'
56 })
57 active.add(key)
58 return alerts
59
60
61 def main():
62 parser = argparse.ArgumentParser(description=__doc__)
63 parser.add_argument('csv_file')
64 parser.add_argument('--threshold', type=int, default=100)
65 parser.add_argument('--window-seconds', type=int, default=60)
66 args = parser.parse_args()
67 try:
68 with open(args.csv_file, encoding='utf-8-sig', newline='') as stream:
69 alerts = detect(csv.DictReader(stream), args.threshold, args.window_seconds)
70 print(json.dumps({'alerts': alerts}, indent=2))
71 except (OSError, ValueError, csv.Error) as exc:
72 print(f'Error: {exc}', file=sys.stderr)
73 return 2
74 return 0
75
76
77 if __name__ == '__main__':
78 sys.exit(main())