Metadata-Version: 2.4
Name: winsec-timeline
Version: 1.0.0
Summary: Windows Security Analysis Engine — transforms structured Windows Event Logs into attack timelines and human-readable security narratives.
Author: Security Analysis Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/security-analysis-team/winsec-timeline
Project-URL: Documentation, https://github.com/security-analysis-team/winsec-timeline#readme
Project-URL: Issues, https://github.com/security-analysis-team/winsec-timeline/issues
Keywords: windows,security,siem,soc,event-log,timeline,incident-response,threat-detection,forensics,dfir
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: evtx
Requires-Dist: python-evtx>=0.7; extra == "evtx"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: python-evtx>=0.7; extra == "dev"
Dynamic: license-file

# 🛡️ WinSec Timeline

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

[![PyPI](https://img.shields.io/pypi/v/winsec-timeline)](https://pypi.org/project/winsec-timeline/)
[![Python](https://img.shields.io/pypi/pyversions/winsec-timeline)](https://pypi.org/project/winsec-timeline/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 🚀 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

```bash
pip install winsec-timeline
```

For development:

```bash
pip install winsec-timeline[dev]
```

---

## ⚡ Quick Start

### Python API

```python
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

```bash
# 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](LICENSE) for details.
