Linux Attacker Timeline Detection Engine

A modular, pipeline-based Linux detection engine that reconstructs attacker kill chains from raw system logs and maps activity to MITRE ATT&CK techniques.

This project focuses on multi-stage attack detection, structured logging, and deterministic rule execution within a clean, extensible architecture.

---

Purpose

Attackers operate in sequences — not isolated events.

This engine is designed to:

• Ingest Linux authentication & system logs
• Normalize raw log lines into structured event objects
• Apply rule-based detection logic
• Generate severity-classified alerts
• Correlate related alerts into multi-stage attack chains
• Map detections to MITRE ATT&CK tactics & techniques
• Reconstruct attacker activity timelines

The goal is to simulate a lightweight SOC-grade detection pipeline with clean architecture and CI-backed validation.

---

Architecture

The engine follows a structured pipeline: Log Input ↓ Collection ↓ Normalization ↓ Detection Engine ↓ Correlation Engine ↓ MITRE Mapping ↓ Timeline Builder ↓ Output Renderer

Each stage is isolated by responsibility, allowing independent testing and future extensibility.

---

System Architecture

The engine follows a deterministic, stage-isolated detection pipeline.

flowchart TD

A[Log File Input]
B[Collection Layer]
C[Normalization Layer]
D[Rule Engine]
E[Alert Aggregation]
F[Correlation Engine]
G[MITRE ATT&CK Mapping]
H[Timeline Builder]
I[Output Renderer]

A --> B
B --> C
C --> D
D --> E
E --> F
F --> G
G --> H
H --> I

linux-attacker-timeline/
│
├── src/
│   ├── cli.py                  # CLI entry point
│   │
│   ├── parser/                 # Raw log ingestion
│   ├── normalizer/             # Event normalization layer
│   │
│   ├── detection/
│   │   ├── rule_engine.py      # Rule execution core
│   │   ├── rule_registry.py    # Rule loading & registration
│   │   └── rules/              # Individual detection rules
│   │
│   ├── correlation/            # Multi-stage attack correlation
│   ├── timeline/               # Chronological reconstruction
│   ├── output/                 # CLI & JSON rendering
│   └── utils/                  # Logging & shared utilities
│
└── tests/                      # Pytest validation suite
## Detection Capabilities

Currently implemented detections include:

- SSH Brute Force Success
- Suspicious Login After Multiple Failures
- Sudo Privilege Escalation
- Reverse Shell Execution
- Cron-Based Persistence
- Log Tampering Detection
- Unauthorized User Creation
- Multi-Stage Attack Correlation
- MITRE ATT&CK Technique Mapping
- Timeline Reconstruction

Example correlated attack chain:
Brute Force
→ Successful Login
→ Privilege Escalation
→ Reverse Shell
→ Persistence
→ Log Tampering

This enables detection of attacker progression instead of isolated alerts.

---

## Engine Observability

The engine includes:

- Structured logging
- Log-level controls (DEBUG / INFO / WARNING / ERROR)
- Stage-based debug summaries
- Execution timing instrumentation
- Alert count aggregation
- Correlated incident summaries

Example pipeline output:

DEBUG | Parsed 17 events
DEBUG | Loaded 7 detection rules
DEBUG | Generated 7 alerts
DEBUG | Generated 1 correlated incident

---

## Design Principles

- Modular pipeline architecture
- Clear separation of parsing, detection, and correlation
- Deterministic rule-based evaluation
- Multi-stage attack awareness
- MITRE ATT&CK alignment
- Extensible rule framework
- CI-driven validation

## usage
## Quick Start

```bash
# Clone repository
git clone https://github.com/djbpm/linux-attacker-timeline
cd linux-attacker-timeline

# Create virtual environment
python -m venv venv

# Activate (Windows)
venv\Scripts\activate

# Activate (Linux/macOS)
# source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run detection engine
python -m src.cli --input src/sample.log

# Run with debug visibility
python -m src.cli --input src/sample.log --log-level DEBUG

# Run with JSON output
python -m src.cli --input src/sample.log --output json

# Run test suite
pytest
---

Current Status

Phase 1 – Detection Ladder: Complete
Completed:
	•	Detection rule framework
	•	Alert aggregation
	•	Multi-stage correlation (basic implementation)
	•	MITRE mapping
	•	Structured logging
	•	Debug instrumentation
	•	CLI interface
	•	CI validation

  Phase 2 Roadmap
	•	Intelligence-driven multi-stage correlation
	•	Enhanced JSON export schema
	•	Plugin-based rule architecture
	•	CI stability improvements
	•	Expanded test coverage

License

MIT License

Author

Kailas
sunsetmachine

Loading