EventLens-Public/docs/CORRELATION.md

Correlation design

Correlation is deterministic and explainable. EventLens says records are temporally or semantically related; it does not invent causality.

Every incident carries a stable rule_id, bounded total time window, explicit predicate, grouping key, human-readable reason and exact evidence event IDs. Incident IDs are SHA-256-derived from the rule and ordered evidence IDs, so repeated analysis of identical normalized evidence yields the same identifiers.

Ordering and identity

• Parser timestamps are normalized to timezone-aware UTC values. A valid event timestamp wins; a valid parser-record timestamp is an explicit fallback. Invalid or missing timestamps remain null with timestamp_source/timestamp_valid metadata and are excluded from temporal correlation, so no synthetic 1970 evidence is created.
• Correlation sorts by (timestamp, event.id) before grouping and returns incidents by (start, rule_id, id).
• EVTX record IDs are retained as stable event IDs. When a parser record has no record ID, the parser ordinal plus canonical event content produces a deterministic hash; duplicate records at the same timestamp do not silently share an ID.
• Evidence IDs are copied exactly into every incident. Repeated signatures remain in the evidence timeline and are represented by original_count versus compressed_count in incident metadata.

Rules and boundaries

• windows.crash.application-report — Application Error 1000 and/or Windows Error Reporting 1001 from the exact Application provider/channel within 120 seconds, grouped by known host/process. The word “sequence” is reserved for evidence containing both records.
• windows.service.failure — abnormal Service Control Manager 7023/7024/7031/7034 events from the System channel within 120 seconds, grouped by known host/service.
• windows.network.dns-timeout — DNS Client 1014 events from the System channel in a bounded 120-second window per known host.
• windows.auth.failed-logon — Security Auditing 4625 events from the Security channel in a bounded 120-second window per known host/account. One event is recorded evidence; two are repeated failures; three or more are called a burst.
• windows.system.startup — Kernel-General 12 or EventLog 6005 startup signals in a bounded 300-second window per known host.
• windows.system.shutdown.normal — Kernel-General 13 or EventLog 6006 normal-shutdown evidence in a bounded 300-second window per known host.
• windows.system.shutdown.unexpected — Kernel-Power 41 or EventLog 6008 unexpected-shutdown/restart evidence in a bounded 300-second window per known host. The reason describes evidence, not a cause.
• windows.generic.attention — preserves unmatched warning/error evidence rather than hiding it.

A rule requires its provider and channel context; a coincidental Event ID from another provider is not classified as that rule. Missing/placeholder host, process, service or account values create an event-isolated group and the reason says that grouping was unavailable; they never become a shared unknown-* key. Events without a reliable timestamp remain evidence but do not enter temporal groups.

A group is split when adding the next event would make the total span from the first event exceed the rule window. Equality at the boundary is included; one millisecond beyond it is split. This prevents a long chain of near-adjacent records from creating an unbounded incident.

Repeated identical provider/event/summary signatures remain in the evidence timeline but are compressed in the incident summary; source records and evidence IDs are never removed. Events may support more than one specifically matching rule when their predicates independently match; no rule is treated as proof of root cause.