← Projects

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())