EVTX Ripper - Chainsaw Forensic Analysis Suite

Interactive Frontend for Windows Event Log Analysis

🎯 Overview

EVTX Ripper is a comprehensive suite for forensic analysis of Windows Event Logs (EVTX). It combines:

PowerShell Export Module - Automated EVTX collection from local machines
Chainsaw Frontend - Interactive ncurses UI for remote EVTX browsing and analysis
Centralized Configuration - Single .env file for all settings and credentials
Sigma Rule Integration - Automated threat detection using industry-standard rules

What It Does

Local Machine          Network/SMB Share         Analysis Engine
┌──────────────────┐   ┌──────────────────┐     ┌──────────────────┐
│ Export-AllEvtx   │──▶│ EVTX Repository  │◀────│ Chainsaw Backend │
│ (PowerShell)     │   │ (SMB Share)      │     │ (Hunt/Search)    │
└──────────────────┘   └──────────────────┘     └──────────────────┘
                              ▲                           ▲
                              │                           │
                       ┌───────┴───────┐          ┌──────┴──────┐
                       │ Chainsaw     │          │ Sigma Rules │
                       │ Frontend UI  │          │ Custom Rls  │
                       │ (ncurses)    │          │ Mappings    │
                       └──────────────┘          └─────────────┘

📦 What's Included

1. Configuration System (`.env`)

Central configuration file for all components:

SMB/network share credentials
Chainsaw executable and rules paths
Output formats and locations
Logging settings

2. Python Frontend (`chainsaw_frontend.py`)

Interactive terminal UI with:

🔍 SMB share browser for EVTX file discovery
🎯 Chainsaw hunt interface (Sigma rule execution)
🔎 Chainsaw search interface (pattern matching)
⚙️ Configuration viewer
💾 Results management

3. PowerShell Integration (`ChainsawIntegration.ps1`)

Helper script for:

Verifying environment configuration
Testing SMB connectivity
Exporting and syncing EVTX files
Integration with existing scripts

4. Documentation

QUICKSTART.md - Get started in 5 minutes ⭐ START HERE
SETUP.md - Comprehensive setup and advanced usage
WAZUH_CHAINSAW_SUPPLEMENT.md - Near-real-time Wazuh + Chainsaw integration
README.md - This file, architecture overview

🚀 Quick Start (5 Minutes)

Step 1: Install Dependencies

pip install -r requirements.txt

Step 2: Configure SMB Access

Edit .env file:

SMB_HOST=192.168.1.100
SMB_SHARE_NAME=EventLogs
SMB_USERNAME=analyst
SMB_PASSWORD=YourPassword
SMB_DOMAIN=COMPANY

Step 3: Verify Setup

.\ChainsawIntegration.ps1 -TestConnection

Step 4: Launch Frontend

python chainsaw_frontend.py

Step 5: Build Windows Executables (Optional)

./Build-WindowsApp.ps1 -Target both -Clean

Build output folders:

dist/EVTXRipperGUI/EVTXRipperGUI.exe
dist/EVTXRipperTUI/EVTXRipperTUI.exe

The build script now defaults to onefile packaging. This is the preferred layout for running from a UNC/network share because the bundled Python runtime extracts locally before launch instead of loading python314.dll directly from the share.

Useful flags:

-Target gui or -Target tui
-Layout onefile or -Layout onedir
-IncludeEnv (copies your .env into the dist folder)
-SkipDependencyInstall (skip requirements-build.txt install)

👉 For detailed instructions, see QUICKSTART.md

📚 Documentation Structure

├─ QUICKSTART.md          ⭐ START HERE (5-min setup)
├─ SETUP.md               📖 Complete reference guide
├─ WAZUH_CHAINSAW_SUPPLEMENT.md 🛡️ Wazuh realtime supplement
├─ README.md              📋 This file (architecture)
│
├─ .env                   ⚙️  Configuration file
├─ chainsaw_frontend.py   🐍 Python UI application
├─ ChainsawIntegration.ps1 🔧 PowerShell helper
├─ ChainsawRealtimeWazuh.ps1 🔧 Realtime Wazuh runner
│
├─ Export-AllEvtx.ps1     📤 EVTX export (existing)
├─ Export-AllEvtxRMM.ps1  📤 RMM integration (existing)
└─ requirements.txt       📦 Python dependencies

Navigation Guide:

New Users: Start with QUICKSTART.md
Detailed Config: See SETUP.md
Wazuh SIEM Feed: See WAZUH_CHAINSAW_SUPPLEMENT.md
Architecture: Continue reading below

🏗️ System Architecture

Component Overview

┌──────────────────────────────────────────────────────────────┐
│                    EVTX Ripper Suite                         │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │          Configuration Layer (.env file)             │   │
│  │  ┌────────────────────────────────────────────────┐  │   │
│  │  │ SMB Credentials │ Paths │ Options │ Logging    │  │   │
│  │  └────────────────────────────────────────────────┘  │   │
│  └─────────┬──────────────────────┬────────────┬────────┘   │
│            │                      │            │             │
│  ┌─────────▼──────────┐  ┌───────▼────────┐  │             │
│  │  PowerShell        │  │  Python        │  │             │
│  │  Export Module     │  │  Frontend UI   │  │             │
│  │ ┌────────────────┐ │  │ ┌────────────┐ │  │             │
│  │ │ Export EVTX    │ │  │ │ File Browse│ │  │             │
│  │ │ Upload to SMB  │ │  │ │ Hunt Exec  │ │  │             │
│  │ │ PowerShell API │ │  │ │ Search Exec│ │  │             │
│  │ └────────────────┘ │  │ └────────────┘ │  │             │
│  └────────────────────┘  └────────────────┘  │             │
│            │                      │            │             │
│            └──────────┬───────────┘            │             │
│                       │                        │             │
│  ╔════════════════════╩════════════════════╗  │             │
│  ║   SMB Network I/O Layer                ║  │             │
│  ║ (SMB Handler - Remote Share Access)    ║  │             │
│  ╚═══════════════╦═════════════════════════╝  │             │
│                 │                             │             │
└─────────────────┼─────────────────────────────┼─────────────┘
                  │                             │
        SMB Share (Event Logs)      Chainsaw Binary
        ┌─────────▼─────────┐      ┌────────────▼────────────┐
        │ Remote EVTX Files │      │ Detection Engine        │
        │ (Forensics Data)  │      │ ┌────────────────────┐  │
        │                   │      │ │ Sigma Rules        │  │
        │                   │      │ │ Custom Rules       │  │
        │                   │      │ │ Mapping Files      │  │
        └───────────────────┘      │ └────────────────────┘  │
                                   └────────────────────────┘
                                           │
                                           │ Results (JSON/CSV)
                                           ▼
                                   ./chainsaw_results/

Data Flow

Export Workflow:

Local System EVTX
    ↓
Export-AllEvtx.ps1 (reads .env)
    ↓
Collects all enabled event logs
    ↓
Exports to: OUTPUT_DIRECTORY (from .env)
    ↓
(If COPY_TO_REMOTE_SHARE=true)
    ↓
Upload to: REMOTE_SHARE_ROOT\REMOTE_DIRECTORY
    ↓
SMB Share (ready for analysis)

Analysis Workflow:

chainsaw_frontend.py starts
    ↓
Loads .env configuration
    ↓
User browses SMB_HOST\SMB_SHARE_NAME
    ↓
Selects EVTX files
    ↓
Chooses Hunt or Search
    ↓
Builds Chainsaw command:
├─ Hunt: Uses --sigma, --mapping, --rules flags
└─ Search: Uses pattern, -e (regex), -t (tau expressions)
    ↓
Executes Chainsaw on selected files
    ↓
Saves results to OUTPUT_PATH
    ↓
User reviews results (CSV/JSON)

🔧 Configuration Deep Dive

Environment Variables

All configuration is managed through the .env file:

Component	Variables	Purpose
Export Module	`OUTPUT_DIRECTORY`, `COPY_TO_REMOTE_SHARE`, `REMOTE_SHARE_ROOT`, `REMOTE_DIRECTORY`, `REMOTE_USERNAME`	Control EVTX export from local machine
SMB Access	`SMB_HOST`, `SMB_PORT`, `SMB_SHARE_NAME`, `SMB_USERNAME`, `SMB_PASSWORD`, `SMB_DOMAIN`	Configure network share access
Chainsaw	`CHAINSAW_EXECUTABLE`, `CHAINSAW_SIGMA_PATH`, `CHAINSAW_RULES_PATH`, `CHAINSAW_MAPPING_FILE`	Define detection engine paths
Hunt Options	`CHAINSAW_OUTPUT_FORMAT`, `CHAINSAW_TIMEZONE`, `CHAINSAW_COLUMN_WIDTH`, `CHAINSAW_SKIP_ERRORS`	Control threat hunting behavior
Output	`OUTPUT_PATH`, `RESULTS_SUBDIRECTORY_BY_DATE`	Manage where results are saved
Logging	`LOG_LEVEL`, `LOG_FILE`	Control application logging

See .env file for detailed comments on each setting.

🎮 User Interface Walkthrough

Main Menu

 ╔════════════════════════════════════════════╗
 ║ Chainsaw Forensic Event Log Analysis Frontend ║
 ╠════════════════════════════════════════════╣
 ║ 1. Browse SMB Share & Select EVTX Files   ║
 ║ 2. Run Chainsaw Hunt                      ║
 ║ 3. Run Chainsaw Search                    ║
 ║ 4. Configure Settings                    ║
 ║ 5. View Selected Files                    ║
 ║ 0. Exit                                   ║
 ║                                           ║
 ║ Selected files: 3                         ║
 ║ Press: 1-5 to select, q to quit           ║
 ╚════════════════════════════════════════════╝

Workflow Example: Hunt for Malicious Activity

Start Frontend
    │
    ├─→ [1] Browse SMB Share
    │       ├─→ Connect to \\fileserver\logs
    │       ├─→ Navigate folders
    │       ├─→ [Space] Select: Security.evtx
    │       ├─→ [Space] Select: System.evtx
    │       └─→ [ESC] Return to menu
    │
    ├─→ [2] Hunt
    │       ├─→ Configure: Sigma ON, Rules ON
    │       ├─→ Format: CSV
    │       ├─→ [6] Execute
    │       └─→ Results → ./chainsaw_results/hunt_20240115_103000.csv
    │
    └─→ Review results in Excel or PowerShell

📊 Example Analyses

Hunt Analysis (Sigma Rules)

Detects malicious activity patterns:

timestamp,detections,Event ID,Computer,Rule,Severity
2024-01-15 10:30:00,Mimikatz Detected,4688,DESKTOP-ABC,T1008,High
2024-01-15 11:45:00,Pass-the-Hash,4776,DESKTOP-XYZ,T1550,Critical

Search Analysis (Pattern Matching)

Finds specific strings or regex patterns:

{
  "results": [
    {
      "timestamp": "2024-01-15T10:30:00Z",
      "pattern_matched": "mimikatz",
      "computer": "DESKTOP-ABC",
      "event_id": 4688,
      "source": "Process Command Line"
    }
  ]
}

🔐 Security Considerations

Credential Management

✅ Store credentials in .env file
✅ Restrict file permissions: icacls .env /grant:r "%USERNAME%:F"
✅ Use service accounts with minimal privileges
❌ Don't commit .env to version control
❌ Don't share credentials via email

Network Security

Use SMB over VPN for remote access
Restrict SMB port 445 via firewall
Use strong domain passwords
Consider using managed service accounts

Data Protection

Store results in secure location
Don't include sensitive data in logs
Follow data retention policies
Audit access to forensic files

🐛 Troubleshooting

Common Issues

SMB Connection Failed

.\ChainsawIntegration.ps1 -TestConnection
# Check: SMB_HOST, credentials, network connectivity

Chainsaw Not Found

chainsaw --version  # Verify in PATH
# Or set full path: CHAINSAW_EXECUTABLE=C:\tools\chainsaw\chainsaw.exe

Python Module Error

pip install -r requirements.txt --force-reinstall

Permission Denied

Verify SMB account permissions
Check file ownership
Try with elevated privileges

See: SETUP.md for detailed troubleshooting guide

🚀 Advanced Usage

Command-Line Integration

# Direct Chainsaw command (bypass frontend)
chainsaw hunt C:\evtx_files -s sigma/ --mapping sigma-event-logs-all.yml

Scripting & Automation

# Export and analyze automatically
.\ChainsawIntegration.ps1 -ExportEvtx
# Then: python chainsaw_frontend.py (in automated mode)

Custom Rules

Add .txt files to ./chainsaw/rules/ for custom detections.

📖 Additional Resources

Chainsaw Docs: https://github.com/WithSecureLabs/chainsaw
Sigma Rules: https://github.com/SigmaHQ/sigma
Windows Event IDs: https://www.ultimatewindowssecurity.com/
EVTX Format: https://github.com/omerbenamram/evtx

🤝 Contributing

Contributions welcome! Areas for enhancement:

Additional output format support (HTML, PDF)
Real-time event monitoring
Custom rule builder UI
Performance optimization
Multi-language support

📝 License

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

📞 Support & Issues

For help:

Check application logs: ./evtxripper.log
Review SETUP.md troubleshooting section
Run diagnostic: .\ChainsawIntegration.ps1 -TestConnection
Verify Chainsaw: chainsaw --version
Check configuration: .\ChainsawIntegration.ps1 -ShowConfig

🎓 Quick Reference

Start Here

# 1. Install
pip install -r requirements.txt

# 2. Configure
notepad .env  # Edit SMB settings

# 3. Test
.\ChainsawIntegration.ps1 -TestConnection

# 4. Run
python chainsaw_frontend.py

File Purposes

File	Purpose
`.env`	All configuration (edit this!)
`chainsaw_frontend.py`	Main interactive UI
`ChainsawIntegration.ps1`	PowerShell helper/integration
`ChainsawRealtimeWazuh.ps1`	Rolling-window Chainsaw feed to Wazuh
`QUICKSTART.md`	5-minute setup guide
`SETUP.md`	Complete reference manual
`WAZUH_CHAINSAW_SUPPLEMENT.md`	Wazuh deployment and rule mapping

Common Tasks

# Export EVTX from this machine
.\ChainsawIntegration.ps1 -ExportEvtx

# Launch frontend to analyze
python chainsaw_frontend.py

# Run hunt directly
chainsaw hunt ./evtx_files -s sigma/ --mapping mapping.yml

Next Step: 👉 Read QUICKSTART.md for step-by-step setup

Happy hunting! 🔍

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
chainsaw		chainsaw
ps		ps
sigma		sigma
wazuh		wazuh
.env.realtime.sample		.env.realtime.sample
Build-WindowsApp.ps1		Build-WindowsApp.ps1
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
SETUP.md		SETUP.md
VERIFICATION_CHECKLIST.md		VERIFICATION_CHECKLIST.md
WAZUH_CHAINSAW_SUPPLEMENT.md		WAZUH_CHAINSAW_SUPPLEMENT.md
bg.jpg		bg.jpg
chainsaw_gui.py		chainsaw_gui.py
evtx_core.py		evtx_core.py
requirements-build.txt		requirements-build.txt
requirements.txt		requirements.txt
results_viewer.py		results_viewer.py

Folders and files

Latest commit

History

Repository files navigation

EVTX Ripper - Chainsaw Forensic Analysis Suite

Interactive Frontend for Windows Event Log Analysis

🎯 Overview

What It Does

📦 What's Included

1. Configuration System (.env)

2. Python Frontend (chainsaw_frontend.py)

3. PowerShell Integration (ChainsawIntegration.ps1)

4. Documentation

🚀 Quick Start (5 Minutes)

Step 1: Install Dependencies

Step 2: Configure SMB Access

Step 3: Verify Setup

Step 4: Launch Frontend

Step 5: Build Windows Executables (Optional)

📚 Documentation Structure

🏗️ System Architecture

Component Overview

Data Flow

🔧 Configuration Deep Dive

Environment Variables

🎮 User Interface Walkthrough

Main Menu

Workflow Example: Hunt for Malicious Activity

📊 Example Analyses

Hunt Analysis (Sigma Rules)

Search Analysis (Pattern Matching)

🔐 Security Considerations

Credential Management

Network Security

Data Protection

🐛 Troubleshooting

Common Issues

🚀 Advanced Usage

Command-Line Integration

Scripting & Automation

Custom Rules

📖 Additional Resources

🤝 Contributing

📝 License

📞 Support & Issues

🎓 Quick Reference

Start Here

File Purposes

Common Tasks

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. Configuration System (`.env`)

2. Python Frontend (`chainsaw_frontend.py`)

3. PowerShell Integration (`ChainsawIntegration.ps1`)

Packages