Metadata-Version: 2.4
Name: ais-storyteller
Version: 0.1.0
Summary: Autonomous incident reconstruction — turns raw Linux host logs into MITRE-mapped attack narratives
License: MIT
Keywords: dfir,security,incident-response,mitre-attack,forensics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Security
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: pandas>=2.0
Requires-Dist: python-dateutil>=2.8
Requires-Dist: tabulate>=0.9
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"

# Cyber Incident Storyteller

An autonomous DFIR tool that turns raw Linux host logs into a readable incident report — no cloud dependency, no LLM, no SIEM required.

Drop in a log file, get back a Markdown report with a timeline, MITRE ATT&CK technique mapping, and a sequence diagram showing exactly what the attacker did and when.

---

## What it does

1. **Parses** Linux host logs into a normalized event stream
2. **Hunts** for attacker IPs using a Trigger-Pivot algorithm — finds brute-force sources, then follows everything they touched
3. **Correlates** events into ranked attack chains with severity scoring
4. **Reports** a human-readable incident document with MITRE mappings and a Mermaid.js sequence diagram

```
logs/auth.log  ──►  parse  ──►  ingest  ──►  hunt  ──►  report.md
```

---

## Quickstart

**Requirements:** Python 3.12+

```bash
git clone https://github.com/lironabraham/cyber-incident-storyteller
cd cyber-incident-storyteller
pip install .
```

> **Windows note:** if `ais` is not found after install, either add Python's Scripts folder to PATH (`setx PATH "%PATH%;%LOCALAPPDATA%\Programs\Python\Python312\Scripts"` then restart your terminal), or use `py src/storyteller.py` in place of `ais` throughout.

**See it work immediately (no log file needed):**

```bash
ais demo
# Windows fallback: py src/storyteller.py demo
```

Generates a synthetic multi-stage attack, runs the full pipeline, and prints the report.

**Analyze your own log:**

```bash
ais analyze logs/auth.log --fmt auth_log --output reports/incident.md
```

Open `reports/incident.md` in any Markdown viewer that renders Mermaid diagrams (GitHub, VS Code with Mermaid plugin, Obsidian).

**Docker:**

```bash
docker build -t ais .
docker run --rm ais demo

# Mount your own logs:
docker run --rm -v $(pwd)/logs:/workspace/logs ais analyze logs/auth.log
```

---

## CLI reference

```
ais analyze <log_path>
    --fmt           auth_log|syslog|audit_log|web_access|sysmon_linux  (default: auth_log)
    --output        path to write the Markdown report                   (default: reports/incident.md)
    --processed-dir directory for SHA-256 hashes and event cache        (default: data/processed)
    --threshold     min failed logins to flag an IP as attacker         (default: 5)

ais verify <log_path>
    --processed-dir directory containing the stored SHA-256 hash        (default: data/processed)

ais demo    — self-contained demo with synthetic attack log

Exit codes: 0 success · 1 error · 2 integrity verification failure
```

---

## Supported log formats

| Format key | Source | What it covers |
|---|---|---|
| `auth_log` | `/var/log/auth.log` | SSH brute force, logins, sudo, PAM failures |
| `syslog` | `/var/log/syslog` | Service start/stop, cron jobs, OOM kills, USB |
| `audit_log` | `/var/log/audit/audit.log` | Process execution, shell spawns, credential file access |
| `web_access` | `/var/log/nginx/access.log` | HTTP attacks, web shells, scanning, admin access |
| `sysmon_linux` | Linux Sysmon XML | Process creation, network connections, file deletion |

---

## Report structure

Every generated report contains:

- **Executive Summary (BLUF)** — one paragraph, board-readable
- **Attack Timeline** — chronological table of every attacker action with MITRE technique and severity
- **Sequence Diagram** — Mermaid.js diagram showing attacker -> server interactions
- **Threat Actor Detail** — per-IP breakdown of tactics used
- **Recommendations** — prioritised response actions
- **Forensic Integrity** — SHA-256 hash of every source log, stored in `data/processed/`

---

## MITRE ATT&CK coverage

The tool maps events to 40+ ATT&CK techniques across all major tactics:

| Tactic | Example techniques |
|---|---|
| Initial Access | T1078 Valid Accounts, T1190 Exploit Public-Facing Application |
| Execution | T1059.004 Unix Shell, T1059.006 Python |
| Persistence | T1053.003 Cron, T1543.002 Systemd Service, T1136.001 Create Account |
| Privilege Escalation | T1548.003 Sudo |
| Defense Evasion | T1070.002 Clear Logs, T1070.003 Clear History, T1070.004 File Deletion |
| Credential Access | T1003.008 /etc/shadow, T1110 Brute Force, T1110.002 Password Cracking |
| Discovery | T1082 System Info, T1057 Process Discovery, T1049 Network Connections |
| Lateral Movement | T1021.004 SSH |
| Collection | T1560.001 Archive, T1025 Removable Media |
| Exfiltration | T1048 Alt Protocol (scp/ftp/rsync) |
| C2 | T1071 Application Layer Protocol |

Command-level mapping covers 53 tools including `wget`, `curl`, `nc`, `nmap`, `hydra`, `hashcat`, `john`, `useradd`, `tar`, `scp`, and more.

---

## Severity model

Severity is context-aware, not static:

| Condition | Severity |
|---|---|
| 1-4 failed logins from an IP | `low` |
| 5-19 failed logins from an IP | `medium` |
| 20+ failed logins from an IP | `high` |
| Successful login after 5+ failures | `critical` |
| Web shell (POST to .php/.asp returning 200) | `critical` |
| Web attack pattern in URL | `high` |
| Sudo command | `high` |
| Shell spawned (bash/sh) | `high` |
| /etc/shadow or /etc/passwd access | `high` |
| Service stopped (auditd/ufw/fail2ban) | `medium` |

---

## Forensic integrity

Every log file ingested gets a SHA-256 hash written to `data/processed/<stem>.sha256`. Verify a log hasn't been tampered with after ingestion:

```bash
ais verify logs/auth.log
# exit 0 = intact, exit 2 = tampered or not yet ingested
```

---

## Running tests

```bash
py -m pytest tests/          # 284 tests
py -m pytest tests/ --cov=src
```

---

## Project layout

```
src/
  storyteller.py   — CLI entrypoint (ais analyze / verify / demo)
  parser.py        — log parsers (5 formats)
  schema.py        — StandardEvent dataclass + TypedDicts
  ingest.py        — normalization, severity scoring, SHA-256 hashing
  mitre.py         — MITRE ATT&CK lookup (40+ techniques, 53 commands)
  hunter.py        — Trigger-Pivot attack chain engine
  reporter.py      — Markdown + Mermaid report generator
  generate_lab.py  — synthetic attack log generators
  __init__.py      — public library API

pyproject.toml     — pip-installable package (ais-storyteller)
Dockerfile         — multi-stage build, ENTRYPOINT ais
tests/             — 284 tests across all modules
logs/              — input log files (read-only, never modified)
data/processed/    — normalized JSON + SHA-256 hashes (generated)
reports/           — generated incident reports (generated)
docs/              — forensic integrity design whitepaper
```
