Metadata-Version: 2.4
Name: soc-chronicle
Version: 0.1.0
Summary: Open-source attack investigation and incident narrative engine
Project-URL: Homepage, https://github.com/Sazidul0/SOC-Chronicle
Project-URL: Documentation, https://github.com/Sazidul0/SOC-Chronicle
Project-URL: Repository, https://github.com/Sazidul0/SOC-Chronicle
Author: soc-chronicle contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: forensics,incident-response,security,soc,threat-hunting
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: duckdb>=1.1
Requires-Dist: httpx>=0.28.0
Requires-Dist: networkx>=3.4
Requires-Dist: pydantic-settings>=2.7
Requires-Dist: pydantic>=2.10
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.9
Requires-Dist: structlog>=24.4
Requires-Dist: typer>=0.15
Provides-Extra: ai
Requires-Dist: httpx>=0.28.0; extra == 'ai'
Provides-Extra: all
Requires-Dist: bandit[toml]>=1.7; extra == 'all'
Requires-Dist: duckdb>=1.1; extra == 'all'
Requires-Dist: httpx>=0.28.0; extra == 'all'
Requires-Dist: mkdocs-material>=9.6; extra == 'all'
Requires-Dist: mypy>=1.14; extra == 'all'
Requires-Dist: pip-audit>=2.7; extra == 'all'
Requires-Dist: pre-commit>=3.7; extra == 'all'
Requires-Dist: pytest-asyncio>=0.25; extra == 'all'
Requires-Dist: pytest-cov>=6.0; extra == 'all'
Requires-Dist: pytest>=8.3; extra == 'all'
Requires-Dist: ruff>=0.9; extra == 'all'
Requires-Dist: types-networkx>=3.0; extra == 'all'
Requires-Dist: types-pyyaml>=6.0; extra == 'all'
Provides-Extra: analytics
Requires-Dist: duckdb>=1.1; extra == 'analytics'
Provides-Extra: dev
Requires-Dist: bandit[toml]>=1.7; extra == 'dev'
Requires-Dist: mkdocs-material>=9.6; extra == 'dev'
Requires-Dist: mypy>=1.14; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: types-networkx>=3.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# soc-chronicle

[![PyPI version](https://img.shields.io/pypi/v/soc-chronicle.svg)](https://pypi.org/project/soc-chronicle/)
[![Python versions](https://img.shields.io/pypi/pyversions/soc-chronicle.svg)](https://pypi.org/project/soc-chronicle/)
[![License](https://img.shields.io/github/license/Sazidul0/SOC-Chronicle.svg)](https://github.com/Sazidul0/SOC-Chronicle/blob/main/LICENSE)
[![Build Status](https://github.com/Sazidul0/SOC-Chronicle/actions/workflows/ci.yml/badge.svg)](https://github.com/Sazidul0/SOC-Chronicle/actions)
[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey)](https://github.com/Sazidul0/SOC-Chronicle)
[![GitHub Stars](https://img.shields.io/github/stars/Sazidul0/SOC-Chronicle.svg)](https://github.com/Sazidul0/SOC-Chronicle/stargazers)
[![GitHub Forks](https://img.shields.io/github/forks/Sazidul0/SOC-Chronicle.svg)](https://github.com/Sazidul0/SOC-Chronicle/network/members)
[![GitHub Issues](https://img.shields.io/github/issues/Sazidul0/SOC-Chronicle.svg)](https://github.com/Sazidul0/SOC-Chronicle/issues)
[![Downloads](https://img.shields.io/pypi/dm/soc-chronicle.svg)](https://pypi.org/project/soc-chronicle/)

Open-source **Attack Investigation & Incident Narrative Engine** — transforms raw cybersecurity alerts into complete, evidence-driven attack narratives.

## Vision

soc-chronicle sits between existing detection platforms (SIEM, EDR, XDR, Cloud Security, IDS/IPS) and incident response workflows. Unlike traditional SIEMs that collect and search logs, soc-chronicle focuses on:

- **Investigation automation** — correlate events, build attack graphs, reconstruct timelines
- **Evidence correlation** — every conclusion traces back to supporting evidence
- **Root cause analysis** — patient zero, initial compromise, blast radius
- **Deterministic analysis** — explainable outputs, no black-box scoring

## Quick Start

```bash
# Install
pip install -e ".[dev]"

# Run an investigation
chronicle investigate examples/alert.json --logs examples/logs

# Export report
chronicle investigate examples/alert.json --logs examples/logs -o report.md

# Extract IOCs
chronicle enrich indicators.txt

# Build timeline from logs
chronicle timeline examples/logs/
```

## Python API

```python
from soc_chronicle import InvestigationEngine

engine = InvestigationEngine()
report = engine.investigate(
    alert="examples/alert.json",
    logs="./examples/logs",
)

print(report.summary)
print(report.narrative)
print(f"Risk: {report.risk.total_score}/100")
print(f"Patient zero: {report.patient_zero}")
```

## Architecture

```
Security Alert → Alert Intake → IOC Extraction + Log Normalization (OCSF)
                                      ↓
                              Correlation Engine
                                      ↓
              Attack Graph ← Timeline Engine → Risk Engine
                                      ↓
                        Incident Narrative Generator
                                      ↓
                    Markdown / JSON / HTML Reports
```

## Core Modules

| Module | Description |
|--------|-------------|
| `intake` | Alert ingestion (JSON, YAML, files) with deduplication |
| `ioc` | IOC extraction with regex pipelines and defanging |
| `normalization` | Log parsing (Sysmon, CrowdStrike, ECS, CloudTrail, etc.) → OCSF |
| `correlation` | Temporal and entity-based event correlation |
| `graph` | Attack graph construction and analysis (NetworkX) |
| `timeline` | Chronological attack reconstruction |
| `root_cause` | Patient zero and initial compromise analysis |
| `risk` | Evidence-based, explainable risk scoring |
| `mitre` | MITRE ATT&CK technique mapping |
| `narrative` | Analyst-friendly incident narratives with citations |
| `hunting` | Sigma, Splunk, Elastic, Sentinel, Wazuh query generation |
| `report` | Markdown, HTML, JSON export |
| `threat_intel` | Async enrichment (VirusTotal, AbuseIPDB, pluggable) |
| `plugins` | Extensible parser, enrichment, and exporter plugins |

## Configuration

Create `chronicle.yaml`:

```yaml
log_level: INFO
correlation_window_seconds: 3600
threat_intel:
  virustotal:
    enabled: true
    api_key: "${VT_API_KEY}"
```

## Plugin Development

Register plugins via entry points in `pyproject.toml`:

```toml
[project.entry-points."soc_chronicle.plugins"]
my_parser = "my_package:MyLogParser"
```

Implement `LogParserPlugin`, `EnrichmentProviderPlugin`, or `ExporterPlugin` from `soc_chronicle.plugins.registry`.

## Development

```bash
pip install -e ".[dev]"
pytest
ruff check src tests
mypy src/soc_chronicle
mkdocs serve
```

## Docker

```bash
docker build -t soc-chronicle .
docker run soc-chronicle investigate /app/examples/alert.json --logs /app/examples/logs
```

## Design Principles

- **Deterministic** over probabilistic reasoning
- **Explainable** outputs backed by evidence
- **Vendor-neutral** architecture
- **Plugin-based** extensibility
- **Offline-capable** local processing
- **Security-first** design

## License

Apache-2.0
