← Projects

README.md

Independent portfolio example using fictional events. Not an employer detection.

1 # LDAP detection lab
2 
3 Original portfolio examples written independently of workplace detection content.
4 These offline Python 3.10+ scripts use only the standard library. They do not query
5 Active Directory, alter logging, execute reconnaissance, or transmit data.
6 All bundled hosts, IP addresses, timestamps, and events are fictional.
7 
8 ## 1. Observed search bursts
9 
10 ```sh
11 python detect_query_bursts.py sample-searches.csv --threshold 5 --window-seconds 60
12 ```
13 
14 Expected: one alert for `192.0.2.25`, containing five record IDs. The sparse
15 `192.0.2.30` records do not reach the threshold. Five is a demonstration threshold,
16 not an operational recommendation. Defaults are 100 records in 60 seconds and
17 also require local baselining. JSON is printed to stdout; use `> alerts.json` to save.
18 
19 The CSV schema is `record_id,timestamp,source_ip,dc_ip,event_type`. Each row must
20 represent one observed LDAP search, with `event_type=ldap_search`. Use an ISO 8601
21 timestamp with a UTC offset, IP addresses without port suffixes, and a record ID
22 unique within that DC's collection epoch/log. Do not combine logs across resets
23 without qualifying IDs. Out-of-order rows are sorted and exact duplicates are
24 ignored; conflicting IDs and malformed rows fail the entire run with exit code 2.
25 
26 The rolling window includes both endpoints and groups by source IP and DC IP.
27 One alert is emitted when each group reaches the threshold. A continuously elevated
28 group does not repeatedly alert; it can re-alert after its rolling count drops
29 below threshold. Counts describe the window at the threshold crossing, not the
30 eventual peak. Input is loaded into memory: this is a small offline lab, not a
31 streaming collector. Shared source IPs/NAT can merge unrelated clients.
32 
33 For real lab telemetry, normalize validated LDAP search records into this schema.
34 This script does not parse raw EVTX or assume undocumented field mappings.
35 Windows Directory Service Event 1644 can provide useful query telemetry, but its
36 diagnostic thresholds select certain expensive, inefficient, or long-running
37 searches. It is NOT a complete count of all LDAP requests. Missing events do not
38 establish absence of activity. This bundle does not enable diagnostic logging.
39 
40 ## 2. Process context from Sysmon
41 
42 ```sh
43 python detect_sysmon_ldap.py sample-sysmon.xml --dc-ip 192.0.2.10
44 ```
45 
46 Expected: one review alert for the PowerShell connection to `192.0.2.10:389`.
47 The inventory process and the destination outside the supplied DC list do not
48 match. They are negative examples, not proof those events are inherently safe.
49 
50 Input is UTF-8 XML containing one Event or an Events wrapper with the standard
51 Windows event namespace. Binary `.evtx` is not supported. Export/convert your
52 authorized lab logs to that format before using this script. The script checks
53 the Sysmon provider and Event ID 3, named fields, outbound initiated TCP,
54 an explicit DC IP list, and ports 389, 636, 3268, or 3269. Repeat `--dc-ip` for
55 additional DCs. Required missing fields and conflicting matching record IDs fail
56 the run. Use one collection epoch per computer so record IDs are unambiguous.
57 
58 The illustrative process list includes PowerShell, pwsh, cmd, Python, SharpHound,
59 and BloodHound names. Names can be changed or spoofed, and many clients use other
60 processes. Command Prompt often launches a child that actually makes the connection;
61 this script does not follow parent/child lineage. An alert is a lead for review,
62 not a verdict. Legitimate administration can match. It does not infer workstation
63 roles or identify BloodHound behavior by name alone. Verify host role, user,
64 purpose, and process lineage separately, using ProcessGuid to pivot where available.
65 
66 Sysmon Event 3 must already be collected by the lab's configuration; network
67 connection logging is disabled by default. It provides connection/process
68 metadata, NOT LDAP filters, searches per connection, or encrypted LDAP contents.
69 The script also excludes UDP/CLDAP and does not attribute queries to processes.
70 
71 ## Investigation and validation
72 
73 1. Confirm log coverage and normalize records without losing event identity.
74 2. Review asset role, account, approved administration, and expected scheduled jobs.
75 3. Inspect process lineage and query details where the telemetry supports them.
76 4. Compare with a local baseline before adjusting thresholds or exclusions.
77 5. Preserve evidence and document the disposition. Do not suppress an entire
78    process merely because one instance was expected.
79 
80 No workplace rules, company logs, hostnames, accounts, or thresholds are included.
81 The synthetic tests validate implementation behavior, not real-world detection
82 accuracy. This heuristic can miss low-rate searches, activity spread across DCs,
83 renamed tools, unlogged traffic, and long-lived LDAP sessions.
84 
85 From the repository root, run the public tests:
86 
87 ```sh
88 python -m unittest discover -s tests -p test_ldap_lab.py -v
89 ```
90 
91 ## Microsoft references
92 
93 - [Event 1644 analysis and diagnostic logging limitations](https://learn.microsoft.com/en-us/troubleshoot/windows-server/active-directory/event1644reader-analyze-ldap-query-performance)
94 - [Sysmon event types and network connection logging](https://learn.microsoft.com/en-us/sysinternals/downloads/sysmon)