🛡️ EvtxCase

From raw EVTX to host intrusion timelines.

Offline endpoint forensics CLI that parses Sysmon, Windows Defender, PowerShell, and Security EVTX files into process trees, investigation timelines, IOCs, and evidence-backed findings.

---

Table of Contents

• Features
• Quick Start
• CLI Reference
• Example Terminal Output
• Interactive HTML Dashboard
• Project Structure
• Methodology
• Configuration
• Contributing
• Author
• License

Features

Feature	Description
Universal EVTX Parser	Dynamic extraction engine that handles any Event ID and provider without hardcoded schemas.
Process Tree Reconstruction	Correlates Sysmon EID 1 / Security EID 4688 into a full parent → child process forest.
Network & DNS Correlation	Maps Sysmon EID 3 (Network) and EID 22 (DNS) events to the exact process that initiated them.
Windows Defender Integration	Extracts EID 1116/1117/5001 alerts and links them to the responsible process.
PowerShell Deep Analysis	Parses EID 4104 ScriptBlock logs and auto-decodes Base64 payloads (UTF-16LE / UTF-8).
Sigma Rule Engine	Lightweight offline Sigma YAML evaluator with wildcard matching and MITRE ATT&CK tagging.
Local IOC Matching	O(1) lookups against flat files (bad-ips.txt, bad-hashes.txt).
VirusTotal Enrichment	Optional --vt-api-key flag for online hash/IP/domain reputation checks with local caching and rate limiting.
LOLBin Detection	Flags suspicious certutil, powershell -enc, and other living-off-the-land techniques.
Whitelist Noise Reduction	Regex-based whitelist prunes known-good branches only if they have no suspicious children or network activity.
Interactive HTML Dashboard	Standalone report with Chart.js doughnut/bar charts, vis-network process tree and network graph, findings table, and IOC copy-to-clipboard.
Multi-Format Export	--format html,json,csv,markdown — generate any combination in a single run.
PDF Export	One-click browser export via html2pdf.js with print-optimised CSS.

Quick Start

Prerequisites

• Python 3.10+
• Exported .evtx files from a Windows endpoint

Installation

git clone https://github.com/1tsprune/EVTXCase.git
cd EVTXCase
python -m venv .venv
source .venv/bin/activate        # Linux / macOS
# .venv\Scripts\activate         # Windows
pip install -e .

Basic Usage

# Analyse a directory of EVTX files
evtxcase analyze logs/ --output cases/incident-001 --format html,json,csv,markdown

Full Example

evtxcase analyze logs/ \
  --output cases/incident-001 \
  --format html,markdown,json,csv \
  --sigma rules/sigma/ \
  --ioc-file config/ \
  --whitelist config/whitelist.yaml \
  --vt-api-key YOUR_API_KEY

CLI Reference

Usage: evtxcase analyze [OPTIONS] LOGS_DIR

Arguments:
  LOGS_DIR    Directory containing .evtx log files.    [required]

Options:
  -o, --output       Output directory for reports.     [default: output]
  -f, --format       Comma-separated formats.          [default: html]
  --sigma            Path to Sigma rules directory.
  --ioc-file         Path to IOC config directory.
  --whitelist, -w    Path to whitelist YAML.            [default: config/whitelist.yaml]
  --vt-api-key       VirusTotal API key for enrichment.
  --version, -V      Show version and exit.

Example Terminal Output

EvtxCase 1.0.0 🚀

[+] Input Directory: logs/
[+] Loading Configurations:
    - Whitelist: 10 rules loaded
    - Sigma Rules: 1 rules loaded
    - Local Threat Intel: 4 IOCs loaded
[+] Parsed Microsoft-Windows-Sysmon%4Operational.evtx (14,532 events)
[+] Parsed Microsoft-Windows-Windows Defender%4Operational.evtx (12 events)

[+] Engine:
    - Events Filtered (Noise Reduction): 6,211 events ignored
    - Process Nodes Reconstructed: 834
    - Timeline events correlated: 14,544
    - Base64 Payloads Decoded: 3
    - IOCs Extracted: 45

[+] Findings (Categorized):
  [Execution]          HIGH   Sigma Hit: Certutil Download              (RecordID=1102)
  [Execution]          HIGH   Base64 PowerShell Payload Decoded         (RecordID=840)
  [Defense Evasion]    HIGH   Windows Defender detected malware         (RecordID=445)
  [Command & Control]  CRIT   Matched IOC: Known C2 IP (185.x.x.x)    (RecordID=1190)

[+] Rendering HTML Dashboard... Done! 📊

Output written to: cases/incident-001
  -> cases/incident-001/report.html (Interactive Dashboard)

Interactive HTML Dashboard

The standalone HTML report opens in any browser with no server required. It includes:

• Executive Summary — Metric cards, severity doughnut chart, MITRE ATT&CK tactics chart
• Activity Timeline — Bar chart of event volume over time
• Process Tree — Textual + interactive vis-network graph (red nodes = suspicious)
• Network Graph — Force-directed process ↔ IP/domain correlation map
• Findings Table — Sortable by severity, click to expand evidence
• IOCs — Deduplicated IPs, domains, hashes, file paths with copy-to-clipboard

Project Structure

EVTXCase/
├── pyproject.toml
├── README.md
├── LICENSE
├── .gitignore
├── config/
│   ├── whitelist.yaml          # Noise reduction rules
│   ├── bad-ips.txt             # Local threat intel (IPs)
│   ├── bad-hashes.txt          # Local threat intel (hashes)
│   └── sigma/                  # Sigma detection rules
│       └── example_lolbin.yml
├── templates/
│   └── report.html             # Jinja2 HTML dashboard template
└── src/evtxcase/
    ├── __init__.py              # Version
    ├── cli.py                   # Typer CLI entrypoint
    ├── config.py                # Whitelist YAML loader
    ├── models.py                # Pydantic data models
    ├── process_tree.py          # 3-pass correlation engine
    ├── parsers/
    │   ├── universal.py         # Dynamic EVTX parser
    │   ├── sysmon.py            # Sysmon-specific extensions
    │   ├── defender.py          # Defender-specific extensions
    │   └── powershell.py        # Base64 decode for EID 4104
    ├── detectors/
    │   ├── engine.py            # Detection orchestrator
    │   ├── iocs.py              # Local + VT IOC matcher
    │   ├── sigma_wrapper.py     # Lightweight Sigma evaluator
    │   ├── cmd_detector.py      # LOLBin / Base64 detector
    │   └── vt_client.py         # VirusTotal v3 client
    └── output/
        └── html.py              # Jinja2 report generator

Methodology

EvtxCase follows a six-phase workflow:

1. Ingest — Discover and open .evtx files
2. Parse — Dynamically extract System metadata and flatten EventData
3. Correlate — Build process trees, attach network/file/DNS/alert events
4. Extract & Match — Run Sigma rules, IOC matching, LOLBin detection, VT enrichment
5. Validate — Whitelist noise reduction, finding deduplication
6. Report — Generate HTML dashboard, Markdown, JSON, and CSV outputs

Configuration

Whitelist (config/whitelist.yaml)

whitelist:
  - image: "C:\\\\Windows\\\\System32\\\\svchost\\.exe"
  - image: "C:\\\\Windows\\\\System32\\\\lsass\\.exe"
  - image: "C:\\\\Windows\\\\System32\\\\services\\.exe"

Rules support regex patterns (case-insensitive). A whitelisted process is pruned only if it has no suspicious children, network connections, or Defender alerts.

Local IOCs

Place one indicator per line in config/bad-ips.txt and config/bad-hashes.txt. Lines starting with # are ignored.

Sigma Rules

Drop standard Sigma YAML files into config/sigma/. The engine supports selection blocks with exact match and * wildcard patterns.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes
4. Push to the branch and open a Pull Request

Author

Eky Januarta 1tsprune.com | GitHub: @1tsprune

License

This project is licensed under the MIT License. See the LICENSE file for details.