EpiLog¶

Turn raw logs into human-readable incident timelines.

EpiLog parses disparate log sources, normalizes them into a common schema, and produces chronological narrative reports. Built for incident responders and security analysts who need answers fast, not another dashboard.

View on GitHub

What it does¶

Most log analysis tools require you to already know what you're looking for. EpiLog takes the opposite approach: feed it your logs, and it tells you what happened, in order, in plain language.

It handles the tedious parts automatically:

Format detection: throws logs at it without specifying a format; it figures it out
Normalization: syslog, CloudTrail, Windows Events, and 10+ other formats all collapse into one common schema
Severity classification: built-in patterns for SQL injection, auth failures, OOM kills and more
Correlation: storyline mode connects related events into coherent sequences across sources

Installation¶

Requires Python 3.9+.

git clone https://github.com/skellman-io/epilog.git
cd epilog
pip install -e .

For development:

pip install -e ".[dev]"

Quick Start¶

# Drop a log file on it — format is auto-detected
epilog analyze /var/log/auth.log

# Multiple files at once
epilog analyze /var/log/auth.log /var/log/syslog

# Filter to warnings and above
epilog analyze --severity warning /var/log/auth.log

# Correlate events into narratives
epilog analyze --storyline /var/log/auth.log

# Export a Markdown incident report
epilog analyze --output markdown --output-file report.md /var/log/auth.log

# Watch a live log file (like tail -f, but smarter)
epilog analyze --follow /var/log/auth.log

Streaming Mode¶

EpiLog can monitor log files in real time, useful for live investigations and watching auth logs during an active incident.

# Follow a file
epilog analyze --follow /var/log/auth.log

# Follow multiple files simultaneously
epilog analyze --follow /var/log/auth.log /var/log/syslog

# Stream with JSON output for piping downstream
epilog analyze --follow --output json /var/log/auth.log

# Apply filters while streaming
epilog analyze --follow --severity error --filter "root" /var/log/auth.log

EpiLog remembers where it left off. Restart it and it picks up without replaying old events. State is stored at ~/.epilog/streaming_state.json. Use --no-state to disable.

Supported Log Formats¶

Format	Source	Auto-Detect
`syslog`	Standard syslog (RFC 3164/5424)	Yes
`authlog`	Linux `/var/log/auth.log`	Yes
`cloudtrail`	AWS CloudTrail JSON	Yes
`aws-waf`	AWS WAF logs	Yes
`cloudfront`	AWS CloudFront TSV access logs	Yes
`s3-access`	AWS S3 server access logs	Yes
`gcp-audit`	GCP Cloud Audit Logs	Yes
`azure-activity`	Azure Activity Logs	Yes
`apache`	Apache access/error logs	Yes
`nginx`	Nginx access/error logs	Yes
`json`	Generic JSON-structured logs	Yes
`docker`	Docker container logs	Yes
`windows-event`	Windows Event Log (XML or JSON export)	Yes
`journald`	systemd journal (`journalctl -o json`)	Yes
`kubernetes`	Kubernetes events and pod logs	Yes

Custom Severity Rules¶

Override or extend EpiLog's built-in detection with a JSON rules file.

epilog analyze --rules my-rules.json /var/log/app.log

Example rules file (.epilog-rules.json):

{
    "severity_rules": [
        {
            "name": "Payment Failure",
            "pattern": "payment.*failed|transaction.*error",
            "severity": "error",
            "field": "message"
        }
    ],
    "highlight_rules": [
        {
            "name": "Transaction ID",
            "pattern": "txn[_-]?[a-f0-9]{8,}",
            "color": "cyan",
            "priority": 15
        }
    ]
}

Place .epilog-rules.json in your project directory or ~/.epilog-rules.json for global rules.

Built-in patterns

EpiLog ships with rules for SQL injection, XSS, path traversal, command injection, auth failures, and common infrastructure failure modes. Custom rules stack on top; they don't replace the defaults unless you pass --no-rules.

Output Formats¶

Format	Flag	Use case
Terminal	(default)	Interactive analysis with color and severity indicators
JSON	`--output json`	Pipe to other tools or SIEM integrations
Markdown	`--output markdown`	Incident reports, documentation, sharing

Platform Notes¶

Windows Event Logssystemd JournaldKubernetesAWS WAF

Export from PowerShell, then analyze:

Get-WinEvent -LogName Security -MaxEvents 1000 | ConvertTo-Json > security_events.json

epilog analyze security_events.json

Security-relevant Event IDs are automatically mapped: 4625 (failed logon) → ERROR, 7045 (service installed) → WARNING.

journalctl -u sshd -o json > ssh_logs.json
epilog analyze ssh_logs.json

kubectl get events -o json > k8s_events.json
epilog analyze k8s_events.json

CrashLoopBackOff, ImagePullBackOff, and NodeNotReady are automatically flagged at appropriate severity.

WAF logs are automatically scanned for SQL injection, XSS, and blocked/rate-limited requests. Threats escalate to CRITICAL; blocks land at ERROR.

Configuration¶

EpiLog works without any config. For persistent defaults, create ~/.epilog/config.yaml:

output: terminal
min_severity: info
timezone: UTC

Use Cases¶

Incident response: build a chronological picture of what happened before you start making assumptions
Live monitoring: watch auth logs in real time during an active investigation with --follow
Multi-source correlation: combine cloud, OS and application logs into one unified timeline
Forensics: reconstruct sequences of events from historical log archives
Audit reports: export Markdown timelines for compliance documentation

Development¶

pip install -e ".[dev]"
pytest                          # run tests
pytest --cov=epilog             # with coverage
black epilog tests              # format
ruff check epilog tests         # lint
mypy epilog                     # type check