winsec-timeline 1.0.0

Windows Security Analysis Engine — transforms structured Windows Event Logs into attack timelines and human-readable security narratives.

🛡️ WinSec Timeline

Windows Security Analysis Engine — Transforms structured Windows Event Logs into attack timelines and clear, human-readable security narratives.

---

🚀 Features

• Attack Timeline Generation — Chronologically ordered, high-signal event sequences
• Process Tree Visualization — Clear parent-child relationship mapping with suspicious chain highlighting
• Behavioral Pattern Detection — Identifies Office macro attacks, encoded commands, lateral movement, persistence mechanisms
• Automated Verdict & Confidence Scoring — Machine-readable verdicts with explainable confidence percentages
• Multiple Output Formats — Plain text, JSON, and stunning HTML reports
• CLI & Library Modes — Use as a standalone tool or integrate into your Python pipeline
• Production-Grade — Deterministic, consistent output suitable for automated security pipelines

---

📦 Installation

pip install winsec-timeline

For development:

pip install winsec-timeline[dev]

---

⚡ Quick Start

Python API

from winsec_timeline import SecurityAnalyzer

analyzer = SecurityAnalyzer()

data = {
    "timeline": [
        {
            "timestamp": "2024-03-15T09:15:23Z",
            "event": "Process Created",
            "process": "WINWORD.EXE",
            "parent": "explorer.exe",
            "details": "User opened Word document"
        },
        {
            "timestamp": "2024-03-15T09:15:45Z",
            "event": "Process Created",
            "process": "powershell.exe",
            "parent": "WINWORD.EXE",
            "details": "PowerShell spawned with encoded command"
        }
    ],
    "process_tree": {
        "root": "explorer.exe",
        "children": [
            {
                "name": "WINWORD.EXE",
                "children": [
                    {"name": "powershell.exe", "children": []}
                ]
            }
        ]
    },
    "flags": [
        "office_spawned_powershell",
        "encoded_command"
    ]
}

report = analyzer.analyze(data)
print(report.to_text())

CLI

# Analyze from JSON file
winsec-timeline analyze input.json

# Output as JSON
winsec-timeline analyze input.json --format json

# Generate HTML report
winsec-timeline analyze input.json --format html --output report.html

---

📊 Output Structure

Every analysis produces:

Section	Description
Timeline	Chronologically ordered high-signal events
Process Tree	Parent-child execution chains
Key Observations	Behavioral patterns & suspicious indicators
Summary	3–5 line executive summary
Verdict	Likely Malicious / Suspicious / Benign
Confidence	0–100% score based on indicator severity

---

🔍 Detection Capabilities

Pattern	Description
Office → Shell	Office apps spawning cmd/powershell
Encoded Commands	Base64/obfuscated command execution
Network Activity	External connections post-execution
Persistence	Scheduled tasks, services, registry
Process Injection	Suspicious parent-child chains
Rapid Staging	Multi-stage execution within short timeframes

---

📄 License

MIT License — see LICENSE for details.