Skip to main content

​
Quick Start Guide

This guide will walk you through launching Chronos-DFIR, uploading your first forensic artifact, and generating an interactive timeline with threat detections.
Before starting, ensure you’ve completed the installation steps and have Python 3.12+ with all dependencies installed.

​
Launch the Application

1

Start the Server

Open a terminal in the Chronos-DFIR directory and launch the Uvicorn server:
uvicorn app:app --host 0.0.0.0 --port 8000 --reload
You should see output similar to:
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using StatReload
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
The --reload flag enables auto-restart when code changes are detected. Remove it in production.
2

Access the Web Interface

Open your browser and navigate to:
http://localhost:8000
You’ll see the Chronos-DFIR dark-mode interface with the drag-and-drop upload area in the sidebar.
3

Verify System Status

The application performs startup checks:
  • Clears temporary upload/output directories
  • Initializes the case database (DuckDB)
  • Loads 86+ Sigma detection rules
  • Compiles YARA rulesets
Check the terminal output for:
INFO:     Sigma Engine: loaded 86 rules from rules/sigma
INFO:     Asset version hash: a3f21c89
INFO:     Startup cleanup complete

​
Upload Your First Artifact

1

Select an Artifact Type

Chronos-DFIR supports multiple forensic formats:

Windows Event Logs

.evtx files from System32/winevt/Logs/

NTFS Master File Table

.mft raw exports or parsed CSV

macOS Property Lists

.plist files from LaunchAgents/Daemons

Generic Reports

CSV, JSON, Excel, SQLite exports from tools like Plaso, KAPE, or Volatility
For this example, we’ll use a Windows Security Event Log (Security.evtx).
2

Drag and Drop the File

Click Select File in the sidebar or drag your .evtx file directly into the drop zone.The system will:
  1. Stream the upload (handles 6GB+ files without memory issues)
  2. Calculate SHA256 hash for chain of custody
  3. Parse the format (using evtx library for binary parsing)
  4. Normalize columns to standard schema (Time, EventID, Level, Provider, etc.)
  5. Apply Sigma rules to detect threats during parsing
  6. Run YARA scans on extracted text content
Large files (100K+ events) may take 30-60 seconds to process. Progress is shown in the upload modal.
3

Review Upload Summary

Once processing completes, you’ll see a summary:
{
  "status": "success",
  "processed_records": 38464,
  "file_category": "generic",
  "chain_of_custody": {
    "sha256": "a3f21c89...",
    "file_size_bytes": 52428800,
    "original_filename": "Security.evtx"
  }
}
Click Load View to open the timeline grid.

​
Explore the Timeline

1

Navigate the Event Grid

The main grid displays events in reverse-chronological order (newest first):
ColumnDescriptionSource
No.Display row number (cosmetic)Auto-generated
TimeEvent timestamp (ISO 8601 format)EventTime / TimeCreated
EventIDWindows Event IDSystem/EventID
LevelSeverity (Information, Warning, Error, Critical)System/Level
ProviderEvent source (e.g., Microsoft-Windows-Security-Auditing)System/Provider/@Name
ComputerHostnameSystem/Computer
UserAccount nameEventData/TargetUserName
ProcessExecutable nameEventData/ProcessName
Chronos uses Tabulator.js virtual DOM rendering to handle millions of rows. Only visible rows are rendered in the browser.
2

View the Histogram

Below the grid, the interactive Chart.js histogram shows event distribution over time:
  • X-axis: Time buckets (auto-scaled: seconds, minutes, hours, or days based on data span)
  • Y-axis: Event count per bucket
  • Color coding:
    • 🔴 Red: Critical/High severity events or Sigma rule matches
    • 🟡 Yellow: Above-average activity (anomaly detection)
    • 🔵 Blue: Normal baseline activity
Histogram Features:
  • Hover over bars to see exact counts and time ranges
  • Click Log Scale to view sparse events alongside high-volume activity
  • Export chart as PNG (screenshot) or Excel (raw data)
The histogram automatically recalculates when you apply filters to the grid.
3

Filter and Search

Use the toolbar to narrow down events:Global Search:
# Search for PowerShell activity
powershell.exe

# Search for specific user
DOMAIN\Administrator

# Search for IP addresses
192.168.1.100
Time Range Filter:Click the Start Time and End Time pickers to select a window, then click Filter to apply.Column Filters:Click any column header to filter by specific values:
  • EventID = 4624 (Successful Logon)
  • Level = Error
  • Provider = Microsoft-Windows-Sysmon
Hide Empty Columns:Click the Hide Empty toggle to automatically hide columns with 100% null values in the current filtered view.
4

Review Threat Detections

Click Context Report (brain icon) to open the Forensic Insight modal showing:Dashboard Cards:
  • Total Events: Raw event count
  • Risk Level: Low / Medium / High / Critical (based on Sigma hits and anomalies)
  • EPS: Events per second (temporal density metric)
  • Top Tactic: Most common MITRE ATT&CK tactic or Event ID
  • Primary Identity: Most active user or IP address
Sigma Rule Detections:Expandable sections for each triggered rule:
Rule: PowerShell Execution Policy Bypass
Level: High
MITRE: T1059.001 (Command and Scripting Interpreter: PowerShell)
Matched Rows: 12
Evidence: [Sample rows with CommandLine, User, Process columns]
Click View all in Grid to filter the main timeline to only matching events.YARA Matches:Any triggered YARA signatures (ransomware, C2 frameworks, etc.):
Rule: LockBit_Ransomware_Indicators
Namespace: ransomware
Strings Matched: 3
Meta: {family: "LockBit 3.0", severity: "critical"}
YARA scans only process the first 5MB of ingested data for performance. For exhaustive binary analysis, use dedicated YARA tools.

​
Export Results

1

Choose Export Format

Click the Export dropdown in the toolbar:

CSV Format

UTF-8 encoded with BOM for Excel compatibility. Hex values wrapped in formulas to prevent conversion.

Excel Spreadsheet

XLSX with text formatting for all columns. Preserves hex, GUIDs, and hashes.

JSON Structure

Array of event objects. Compatible with SOAR platforms (Splunk, Cortex XSOAR).

Context (AI-Ready)

Forensic summary JSON optimized for LLM ingestion. Includes Sigma hits, YARA, IOCs, risk scoring.
All exports respect active filters (search, time range, column filters, row selection).
2

Generate HTML Report

Click Graphical Report to generate a standalone HTML file containing:
  • Dashboard summary cards
  • Embedded histogram (Chart.js with Base64-encoded data)
  • All Sigma detections with evidence tables
  • MITRE kill chain mapping
  • Cross-source correlations
  • Session profiles
  • Risk justification log
The report is self-contained (no external dependencies) and can be:
  • Emailed to stakeholders
  • Printed to PDF via browser (Ctrl+P / Cmd+P)
  • Opened offline for presentations
The HTML report uses print-friendly CSS with forced colors for readability on paper.
3

Export for AI Analysis

For large datasets that exceed LLM token limits:
  1. Select Zip (Split Artifacts) from the Export dropdown
  2. Choose split size: 50MB or 99MB chunks
  3. Select format: CSV or JSON
  4. Click Download
The system will:
  • Split filtered data into N files within the size limit
  • Create a ZIP archive with sequential filenames
  • Include a manifest.json with metadata
Each chunk can be uploaded individually to ChatGPT, Claude, or Gemini for analysis.

​
Common Workflows

​
Workflow 1: Ransomware Timeline Reconstruction

# 1. Upload Security.evtx + System.evtx from infected host
# 2. Sigma rules auto-detect:
#    - T1490: Inhibit System Recovery (vssadmin delete shadows)
#    - T1486: Data Encrypted for Impact (.lockbit extension)
#    - T1055: Process Injection (CreateRemoteThread API)
# 3. Filter timeline to EventID 4688 (Process Creation)
# 4. Sort by Time ascending to see attack progression
# 5. Export filtered CSV for timeline report

​
Workflow 2: Lateral Movement Detection

# 1. Upload Sysmon.evtx (EventID 3: Network Connections)
# 2. Filter by DestinationPort = 445 (SMB)
# 3. Sigma rules flag:
#    - T1021.002: SMB/Windows Admin Shares
#    - T1570: Lateral Tool Transfer
# 4. Cross-reference User column with privileged accounts
# 5. Export Context JSON for AI threat briefing

​
Workflow 3: Web Shell Hunting

# 1. Upload IIS access logs (CSV format)
# 2. Sigma rules detect:
#    - SQL Injection patterns in URL parameters
#    - Webshell POST requests to .aspx files
#    - Command execution via eval() functions
# 3. Filter by HTTP Status = 200 (successful requests)
# 4. Export matched rows as Excel for investigation

​
Keyboard Shortcuts

ShortcutAction
Ctrl+F / Cmd+FFocus global search box
Ctrl+Shift+R / Cmd+Shift+RHard reset (clear cache and filters)
Ctrl+E / Cmd+EOpen export menu
Ctrl+P / Cmd+PPrint current view or report
EscClose modal dialogs

​
Troubleshooting

If the interface shows stale data after updates, perform a hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS).
Issue: Upload fails with “Memory Error” Solution: The file may be too large. Try: 
# Split large EVTX files with evtx_dump
evtx_dump Security.evtx --no-indent -o security.json
split -l 100000 security.json chunk_
# Upload chunks individually
Issue: Sigma rules not triggering Check that field names match rule expectations: 
# Rules expect standardized column names
# Use "Manage Cols" to rename:
CommandLine → Command_Line  # if rule uses underscores
Issue: Chart not updating after filters Clear the browser cache: 
# Chrome/Edge: Shift+F5
# Firefox: Ctrl+Shift+R
# Safari: Cmd+Option+R

​
Next Steps

Advanced Features

Learn about case management, multi-file correlation, and custom Sigma rules

API Reference

Integrate Chronos-DFIR into automated DFIR pipelines via REST API
Need Help? Check the troubleshooting guide or review the architecture documentation for deep-dive technical details.

Build docs developers (and LLMs) love

Get started for freeTalk to us