Multi-Source Event Correlator (V1)

Overview

The Multi-Source Event Correlator is a Python command-line tool designed to validate, normalize, and correlate security events across multiple users and sources within a configurable time window.

Version 1 focuses on building a robust correlation engine with strict schema validation, deterministic processing, and pipeline-safe exit codes. It assumes input events are provided in a normalized JSON format and is intentionally scoped to establish a stable core for future ingestion and enrichment features.

---

Key Features (V1)

• Schema-locked validation

  • Ensures all events conform to a defined structure
  • Separates valid and invalid events without crashing the pipeline
  • Detailed schema error reporting with event context

• Event normalization

  • Converts timestamps to datetime objects
  • Normalizes result values into consistent boolean semantics
  • Produces a uniform internal representation for correlation

• Multi-source correlation

  • Correlates events across multiple users and source identifiers
  • Detects failed login bursts within a configurable time window
  • Designed for extension to additional event types

• Deterministic pipeline behavior

  • Structured JSON output for automation and downstream tooling
  • Explicit exit codes for CI/CD and scripting use
  • Optional quiet mode for non-interactive execution

---

Input Format

V1 expects a JSON file containing a list of events, each conforming to the following schema:

{
  "timestamp": "2026-01-02T10:15:00Z",
  "user": "alice",
  "source": "192.168.1.44",
  "action": "login",
  "result": "success"
}

Allowed Values

• action: "login"
• result: "success" or "fail"

---

Usage

python multi_source_correlator_v1.py --input events.json

Optional Flags

--window <minutes>     Time window for correlation (default: 10)
--json <file>          Export results to JSON
--quiet                Suppress console output

Example:

python multi_source_correlator_v1.py \
  --input test_errors.json \
  --window 10 \
  --json output.json

---

Output

Console Summary

* Total events processed
* Valid events
* Schema errors
* Alerts detected

JSON Output

Structured payload including: * Summary statistics * Schema validation errors * Correlated alert data

---

Exit Codes

Code	Meaning
0	Successful execution
2	Schema validation errors detected
3	Runtime error

Exit codes are enforced consistently to support automation and CI pipelines.

---

Design Decisions

• Schema first: Correlation logic operates only on validated, normalized data

• Fail safe, not fail fast: Invalid records are reported, not discarded silently

• Separation of concerns:

  • Validation
  • Normalization
  • Correlation
  • Reporting

• V1 deliberately avoids ingestion complexity to keep logic testable and maintainable

---

Scope Note (V1)

This version assumes pre-normalized JSON input. Support for multiple log formats, heterogeneous schemas, and source-specific parsers is planned for V2.

---

Planned Enhancements (V2+)

* Multi-format ingestion adapters (e.g. Apache, Windows, firewall logs)
* Source-specific parsers mapped to the normalized schema
* Cross-signal correlation (authentication, configuration, network events)
* Severity scoring and alert deduplication

---

Status

V1 complete and frozen The project is stable, tested, and ready to serve as the foundation for future expansion.

---

Author

Darren Williamson Python Utility Development * Automation * Data Analysis * AI-assisted tooling Uk Citizen / Spain-based / Remote LinkedIn: https://www.linkedin.com/in/darren-williamson3/