DEV Community

Jude Hilgendorf
Jude Hilgendorf

Posted on

I Built an Offline Threat Hunting CLI That Parses EVTX, JSON, Syslog & CEF Logs

#cybersecurity #python #opensource #tutorial

If you've ever worked in a SOC or done any incident response, you know the pain: you've got a pile of log files from a compromised host, and you need answers fast. Maybe you don't have Splunk access. Maybe the SIEM is down. Maybe you're on a plane with a laptop full of EVTX files and zero internet.

That's why I built ThreatLens — a Python CLI that does offline log analysis and threat hunting without requiring any infrastructure.

What ThreatLens Does

ThreatLens ingests logs in multiple formats (EVTX, JSON, NDJSON, Syslog RFC 3164/5424, and CEF), runs them through 12 built-in detection modules, and outputs color-coded alerts mapped to the MITRE ATT&CK framework.

No Elasticsearch cluster. No cloud account. Just pip install threatlens and point it at your logs.

Why I Built It

I'm a cybersecurity student, and every time I practiced incident response scenarios, I hit the same wall: the tools that do log analysis well are either expensive, require complex deployment, or need network access. I wanted something I could run anywhere — on an air-gapped forensics workstation, in a Docker container during a CTF, or in a CI/CD pipeline for automated security checks.

So I started building ThreatLens as a learning project, and it grew into something I actually use regularly.

The Detection Engine: A Code Walkthrough

The part I'm most proud of is the multi-stage attack chain correlation. Most log analysis tools look at events individually. ThreatLens connects the dots.

Each detection module registers itself with a tactic and technique mapping. When ThreatLens processes a log file, it doesn't just flag individual events — it builds a timeline. If it sees a brute-force login (Initial Access), followed by a suspicious PowerShell execution (Execution), followed by a new scheduled task (Persistence), it correlates those into a potential attack chain and raises the severity.

The detection modules cover:

  • Brute-force & password spray detection
  • Lateral movement (RDP, PsExec, WMI patterns)
  • Privilege escalation monitoring
  • LOLBin abuse (living-off-the-land binary execution)
  • Encoded PowerShell commands
  • Defense evasion (log clearing, AV tampering)
  • Persistence mechanisms (scheduled tasks, services, registry run keys)
  • Kerberos attacks (Kerberoasting, Golden Ticket indicators)
  • Data exfiltration patterns
  • Multi-stage attack chain correlation

Each module uses a YAML-configurable rule format with 12 operators, so you can write custom rules without touching Python code. And if you already have Sigma rules from your team, ThreatLens supports those natively too.

Quick Start

Install from PyPI:

pip install threatlens
Enter fullscreen mode Exit fullscreen mode

Scan a single log file:

threatlens scan /path/to/security.evtx
Enter fullscreen mode Exit fullscreen mode

Scan a directory recursively with HTML report output:

threatlens scan /var/log/ -r -o report.html
Enter fullscreen mode Exit fullscreen mode

Run with custom Sigma rules:

threatlens scan logs/ --sigma-rules ./my-rules/
Enter fullscreen mode Exit fullscreen mode

Tail logs in real-time:

threatlens tail /var/log/syslog --severity high
Enter fullscreen mode Exit fullscreen mode

Push alerts to Elasticsearch:

threatlens scan logs/ --es-host https://elastic:9200
Enter fullscreen mode Exit fullscreen mode

Output Formats

ThreatLens gives you flexibility in how you consume results:

  • Terminal: Color-coded severity with MITRE technique IDs inline
  • JSON/CSV: For piping into other tools or importing to spreadsheets
  • HTML: Self-contained reports with charts and timelines
  • Elasticsearch: Push alerts directly for dashboarding

CI/CD Integration

One underrated use case: drop ThreatLens into your pipeline to scan application logs for security events. It returns proper exit codes, so you can fail a build if high-severity detections fire.

# GitHub Actions example
- name: Security log check
  run: threatlens scan ./logs/ --severity high --exit-code
Enter fullscreen mode Exit fullscreen mode

What's Next

I'm working on expanding the detection library, improving the EVTX parser performance, and adding a plugin marketplace where the community can share detection modules.

Try It Out

The repo is at github.com/TiltedLunar123/ThreatLens. If it's useful to you, a star helps a lot with visibility. Issues and PRs are welcome — especially new detection rules.

If you're a SOC analyst, threat hunter, or IR responder, I'd love to hear what detections you'd want added. Drop a comment below.

Top comments (0)