Install this skill

npx skills add mukul975/Anthropic-Cybersecurity-Skills

Framework mappings

MITRE ATT&CK

T1005 T1059 T1070 T1074 T1119

NIST CSF 2.0

DE.AE-02 RS.AN-01 RS.AN-03 RS.MA-01

When to Use

When building a comprehensive forensic timeline from multiple evidence sources
For correlating events across file system metadata, event logs, browser history, and registry
During complex investigations requiring chronological reconstruction of activities
When standard log analysis is insufficient to establish the sequence of events
For presenting investigation findings in a visual, chronological format

Prerequisites

Plaso (log2timeline/psort) installed on forensic workstation
Forensic disk image(s) in raw (dd), E01, or VMDK format
Sufficient storage for Plaso output (can be 10x+ the image size)
Minimum 8GB RAM (16GB+ recommended for large images)
Timeline Explorer (Eric Zimmerman) or Timesketch for visualization
Understanding of timestamp types (MACB: Modified, Accessed, Changed, Born)

Workflow

Step 1: Install Plaso and Prepare the Environment

# Install Plaso on Ubuntu/Debian
sudo add-apt-repository ppa:gift/stable
sudo apt-get update
sudo apt-get install plaso-tools
 
# Or install via pip
pip install plaso
 
# Or use Docker (recommended for dependency isolation)
docker pull log2timeline/plaso
 
# Verify installation
log2timeline.py --version
psort.py --version
 
# Create output directory
mkdir -p /cases/case-2024-001/timeline/
 
# Verify the forensic image
img_stat /cases/case-2024-001/images/evidence.dd

Step 2: Generate the Plaso Storage File with log2timeline

# Basic processing of a disk image (all parsers)
log2timeline.py \
   --storage-file /cases/case-2024-001/timeline/evidence.plaso \
   /cases/case-2024-001/images/evidence.dd
 
# Process with specific parsers for faster targeted analysis
log2timeline.py \
   --parsers "winevtx,prefetch,mft,usnjrnl,lnk,recycle_bin,chrome_history,firefox_history,winreg" \
   --storage-file /cases/case-2024-001/timeline/evidence.plaso \
   /cases/case-2024-001/images/evidence.dd
 
# Process with a filter file to focus on specific paths
cat << 'EOF' > /cases/case-2024-001/timeline/filter.txt
/Windows/System32/winevt/Logs
/Windows/Prefetch
/Users/*/NTUSER.DAT
/Users/*/AppData/Local/Google/Chrome
/Users/*/AppData/Roaming/Mozilla/Firefox
/$MFT
/$UsnJrnl:$J
/Windows/System32/config
EOF
 
log2timeline.py \
   --filter-file /cases/case-2024-001/timeline/filter.txt \
   --storage-file /cases/case-2024-001/timeline/evidence.plaso \
   /cases/case-2024-001/images/evidence.dd
 
# Using Docker
docker run --rm -v /cases:/cases log2timeline/plaso log2timeline \
   --storage-file /cases/case-2024-001/timeline/evidence.plaso \
   /cases/case-2024-001/images/evidence.dd
 
# Process multiple evidence sources into one timeline
log2timeline.py \
   --storage-file /cases/case-2024-001/timeline/combined.plaso \
   /cases/case-2024-001/images/workstation.dd
 
log2timeline.py \
   --storage-file /cases/case-2024-001/timeline/combined.plaso \
   /cases/case-2024-001/images/server.dd

Step 3: Filter and Export Timeline with psort

# Export full timeline to CSV (super-timeline format)
psort.py \
   -o l2tcsv \
   -w /cases/case-2024-001/timeline/full_timeline.csv \
   /cases/case-2024-001/timeline/evidence.plaso
 
# Export with date range filter (focus on incident window)
psort.py \
   -o l2tcsv \
   -w /cases/case-2024-001/timeline/incident_window.csv \
   /cases/case-2024-001/timeline/evidence.plaso \
   "date > '2024-01-15 00:00:00' AND date < '2024-01-20 23:59:59'"
 
# Export in JSON Lines format (for ingestion into SIEM/Timesketch)
psort.py \
   -o json_line \
   -w /cases/case-2024-001/timeline/timeline.jsonl \
   /cases/case-2024-001/timeline/evidence.plaso
 
# Export with specific source type filters
psort.py \
   -o l2tcsv \
   -w /cases/case-2024-001/timeline/registry_events.csv \
   /cases/case-2024-001/timeline/evidence.plaso \
   "source_short == 'REG'"
 
psort.py \
   -o l2tcsv \
   -w /cases/case-2024-001/timeline/evtx_events.csv \
   /cases/case-2024-001/timeline/evidence.plaso \
   "source_short == 'EVT'"
 
# Export for Timeline Explorer (dynamic CSV)
psort.py \
   -o dynamic \
   -w /cases/case-2024-001/timeline/timeline_explorer.csv \
   /cases/case-2024-001/timeline/evidence.plaso

Step 4: Analyze Timeline with Timesketch

# Install Timesketch (Docker deployment)
git clone https://github.com/google/timesketch.git
cd timesketch
docker compose up -d
 
# Import Plaso file into Timesketch via CLI
timesketch_importer \
   --host http://localhost:5000 \
   --username analyst \
   --password password \
   --sketch_id 1 \
   --timeline_name "Case 2024-001 Workstation" \
   /cases/case-2024-001/timeline/evidence.plaso
 
# Alternatively, import JSONL
timesketch_importer \
   --host http://localhost:5000 \
   --username analyst \
   --sketch_id 1 \
   --timeline_name "Case 2024-001" \
   /cases/case-2024-001/timeline/timeline.jsonl
 
# In Timesketch web UI:
# 1. Search for events: "data_type:windows:evtx:record AND event_identifier:4624"
# 2. Apply Sigma analyzers for automated detection
# 3. Star/tag important events
# 4. Create stories documenting the investigation narrative
# 5. Share with team members

Step 5: Perform Targeted Timeline Analysis

# Analyze specific time periods around known events
python3 << 'PYEOF'
import csv
from collections import defaultdict
from datetime import datetime
 
# Load incident window timeline
events_by_hour = defaultdict(list)
source_counts = defaultdict(int)
 
with open('/cases/case-2024-001/timeline/incident_window.csv', 'r', errors='ignore') as f:
    reader = csv.DictReader(f)
    total = 0
    for row in reader:
        total += 1
        timestamp = row.get('datetime', row.get('date', ''))
        source = row.get('source_short', row.get('source', 'Unknown'))
        description = row.get('message', row.get('desc', ''))
 
        source_counts[source] += 1
 
        # Group by hour for activity patterns
        try:
            dt = datetime.strptime(timestamp[:19], '%Y-%m-%dT%H:%M:%S')
            hour_key = dt.strftime('%Y-%m-%d %H:00')
            events_by_hour[hour_key].append({
                'time': timestamp,
                'source': source,
                'description': description[:200]
            })
        except (ValueError, TypeError):
            pass
 
print(f"Total events in incident window: {total}\n")
 
print("=== EVENTS BY SOURCE TYPE ===")
for source, count in sorted(source_counts.items(), key=lambda x: x[1], reverse=True):
    print(f"  {source}: {count}")
 
print("\n=== ACTIVITY BY HOUR ===")
for hour in sorted(events_by_hour.keys()):
    count = len(events_by_hour[hour])
    bar = '#' * min(count // 10, 50)
    print(f"  {hour}: {count:>6} events {bar}")
 
# Find hours with unusual activity spikes
avg = total / max(len(events_by_hour), 1)
print(f"\n=== ANOMALOUS HOURS (>{avg*3:.0f} events) ===")
for hour in sorted(events_by_hour.keys()):
    if len(events_by_hour[hour]) > avg * 3:
        print(f"  {hour}: {len(events_by_hour[hour])} events (SPIKE)")
PYEOF

Key Concepts

Concept	Description
Super-timeline	Unified chronological view combining all artifact timestamps from multiple sources
MACB timestamps	Modified, Accessed, Changed (metadata), Born (created) - four key file timestamp types
Plaso storage file	SQLite-based intermediate format storing parsed events before export
L2T CSV	Log2timeline CSV format with standardized columns for timeline events
Parser	Plaso module extracting timestamps from a specific artifact type (e.g., winevtx, prefetch)
Psort	Plaso sorting and filtering tool for post-processing storage files
Timesketch	Google open-source collaborative timeline analysis platform
Pivot points	Known timestamps (e.g., malware execution) used to focus investigation scope

Tools & Systems

Tool	Purpose
log2timeline (Plaso)	Primary timeline generation engine parsing 100+ artifact types
psort	Plaso output filtering, sorting, and export utility
Timesketch	Web-based collaborative forensic timeline analysis platform
Timeline Explorer	Eric Zimmerman's Windows GUI for CSV timeline analysis
KAPE	Automated triage collection feeding into Plaso processing
mactime (TSK)	Simpler timeline generation from Sleuth Kit bodyfiles
Excel/Sheets	Manual timeline review for small filtered datasets
Elastic/Kibana	Alternative visualization platform for JSONL timeline data

Common Scenarios

Scenario 1: Ransomware Attack Reconstruction Process the full disk image with Plaso, filter to the week before encryption was discovered, identify the initial access vector from browser history and event logs, trace privilege escalation through registry and Prefetch, map lateral movement from network logon events, pinpoint encryption start from MFT timestamps showing mass file modifications.

Scenario 2: Data Theft Investigation Create super-timeline from suspect's workstation, filter for USB device connection events, file access timestamps, and cloud storage browser activity, build a narrative showing data staging, compression, and exfiltration, present timeline to legal team with tagged evidence points.

Scenario 3: Multi-System Breach Analysis Process disk images from all affected systems into a single Plaso storage file, import into Timesketch for collaborative analysis, search for lateral movement patterns across system timelines, identify the patient-zero system and initial compromise vector, map the full attack chain across the environment.

Scenario 4: Insider Threat After-Hours Activity Filter timeline to non-business hours only, identify file access patterns outside normal working times, correlate with authentication events (badge access, VPN logon), search for data access to sensitive directories during these periods, build evidence package for HR/legal.

Output Format

Timeline Reconstruction Summary:
  Evidence Sources:
    Disk Image: evidence.dd (500 GB, NTFS)
    Plaso Storage: evidence.plaso (2.3 GB)
 
  Processing Statistics:
    Total events extracted: 4,567,890
    Parsers used: 45 (winevtx, prefetch, mft, usnjrnl, lnk, chrome, firefox, winreg, ...)
    Processing time: 3h 45m
 
  Incident Window (2024-01-15 to 2024-01-20):
    Events in window: 234,567
    Event Sources:
      MFT:          89,234
      Event Logs:   45,678
      USN Journal:  56,789
      Registry:     23,456
      Prefetch:     1,234
      Browser:      5,678
      LNK Files:    2,345
      Other:        10,153
 
  Key Timeline Events:
    2024-01-15 14:32 - Phishing email opened (browser)
    2024-01-15 14:33 - Malicious document downloaded
    2024-01-15 14:35 - PowerShell executed (Prefetch + Event Log)
    2024-01-15 14:36 - C2 connection established (Registry + Event Log)
    2024-01-16 02:30 - Mimikatz execution (Prefetch)
    2024-01-16 02:45 - Lateral movement to DC (Event Log)
    2024-01-17 03:00 - Data exfiltration (MFT + USN Journal)
    2024-01-18 03:00 - Log clearing (Event Log)
 
  Exported Files:
    Full Timeline:     /timeline/full_timeline.csv (4.5M rows)
    Incident Window:   /timeline/incident_window.csv (234K rows)
    Timesketch Import: /timeline/timeline.jsonl

Source materials

References and resources

Everything below is rendered for inspection. Script files are read-only and never run.

References 1

api-reference.md2.5 KB

API Reference: Timeline Reconstruction with Plaso Agent

Overview

Wraps Plaso (log2timeline/psort) via subprocess for forensic super-timeline generation, filtering, export, and automated CSV analysis for activity spikes and source distribution.

Dependencies

Package	Version	Purpose
csv	stdlib	Timeline CSV parsing
subprocess	stdlib	Plaso tool execution

External Tools Required

Tool	Purpose
log2timeline.py	Forensic timeline generation from disk images
psort.py	Timeline filtering, sorting, and export

Core Functions

`run_log2timeline(image_path, storage_file, parsers, filter_file)`

Executes log2timeline.py to parse a disk image into a Plaso storage file.

Parameters: image_path (str), storage_file (str), parsers (str, optional), filter_file (str, optional)
Timeout: 7200 seconds (2 hours)
Returns: dict with command, returncode, stdout, stderr

`run_psort_export(storage_file, output_file, output_format, date_filter)`

Exports timeline from Plaso storage to CSV, JSONL, or dynamic format.

Formats: l2tcsv, json_line, dynamic
Returns: dict with command, returncode, output_file

`create_filter_file(filter_path, paths)`

Generates a Plaso filter file targeting key forensic artifacts.

Default paths: winevt, Prefetch, NTUSER.DAT, Chrome, Firefox, MFT, USN Journal, registry

`analyze_timeline_csv(csv_path, max_rows)`

Statistical analysis of exported timeline: source distribution and hourly activity spikes (>3x average).

Returns: dict with total_events, source_counts, spike_hours, avg_events_per_hour

`generate_incident_window(storage_file, output_dir, start_date, end_date)`

Exports events within a specific date range for focused analysis.

`full_pipeline(image_path, output_dir, parsers, start_date, end_date)`

End-to-end pipeline: log2timeline -> psort export -> CSV analysis -> incident window -> JSONL export.

Default Parsers

winevtx, prefetch, mft, usnjrnl, lnk, recycle_bin,
chrome_history, firefox_history, winreg

Usage

python agent.py /cases/evidence.dd /cases/timeline/ "2024-01-15 00:00:00" "2024-01-20 23:59:59"

Output Files

File	Format	Purpose
evidence.plaso	SQLite	Plaso intermediate storage
full_timeline.csv	L2T CSV	Complete super-timeline
incident_window.csv	L2T CSV	Filtered incident period
timeline.jsonl	JSON Lines	SIEM/Timesketch import

Scripts 1

agent.py6.7 KB

Display-only source. This catalog never executes bundled scripts.

#!/usr/bin/env python3
"""Forensic timeline reconstruction agent using Plaso subprocess wrappers."""

import subprocess
import os
import sys
import csv
from datetime import datetime
from collections import defaultdict


def verify_plaso_installed():
    """Check that log2timeline.py and psort.py are available."""
    tools = {}
    for tool in ["log2timeline.py", "psort.py"]:
        result = subprocess.run(
            [tool, "--version"], capture_output=True, text=True,
            timeout=120,
        )
        tools[tool] = result.stdout.strip() if result.returncode == 0 else None
    return tools


def run_log2timeline(image_path, storage_file, parsers=None, filter_file=None):
    """Execute log2timeline.py to generate Plaso storage file."""
    cmd = ["log2timeline.py", "--storage-file", storage_file]
    if parsers:
        cmd.extend(["--parsers", parsers])
    if filter_file:
        cmd.extend(["--filter-file", filter_file])
    cmd.append(image_path)
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=7200)
    return {
        "command": " ".join(cmd),
        "returncode": result.returncode,
        "stdout": result.stdout[-500:] if result.stdout else "",
        "stderr": result.stderr[-500:] if result.stderr else "",
    }


def run_psort_export(storage_file, output_file, output_format="l2tcsv",
                     date_filter=None):
    """Export timeline from Plaso storage using psort.py."""
    cmd = ["psort.py", "-o", output_format, "-w", output_file, storage_file]
    if date_filter:
        cmd.append(date_filter)
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=3600)
    return {
        "command": " ".join(cmd),
        "returncode": result.returncode,
        "output_file": output_file,
        "stdout": result.stdout[-500:] if result.stdout else "",
    }


def create_filter_file(filter_path, paths=None):
    """Create a Plaso filter file for targeted parsing."""
    if paths is None:
        paths = [
            "/Windows/System32/winevt/Logs",
            "/Windows/Prefetch",
            "/Users/*/NTUSER.DAT",
            "/Users/*/AppData/Local/Google/Chrome",
            "/Users/*/AppData/Roaming/Mozilla/Firefox",
            "/$MFT",
            "/$UsnJrnl:$J",
            "/Windows/System32/config",
        ]
    with open(filter_path, "w") as f:
        f.write("\n".join(paths) + "\n")
    return filter_path


def analyze_timeline_csv(csv_path, max_rows=500000):
    """Analyze exported timeline CSV for patterns and anomalies."""
    events_by_hour = defaultdict(int)
    source_counts = defaultdict(int)
    total = 0
    with open(csv_path, "r", errors="ignore") as f:
        reader = csv.DictReader(f)
        for row in reader:
            if total >= max_rows:
                break
            total += 1
            source = row.get("source_short", row.get("source", "Unknown"))
            source_counts[source] += 1
            timestamp = row.get("datetime", row.get("date", ""))
            try:
                dt = datetime.strptime(timestamp[:19], "%Y-%m-%dT%H:%M:%S")
                hour_key = dt.strftime("%Y-%m-%d %H:00")
                events_by_hour[hour_key] += 1
            except (ValueError, TypeError):
                pass
    avg_per_hour = total / max(len(events_by_hour), 1)
    spikes = {
        h: c for h, c in events_by_hour.items() if c > avg_per_hour * 3
    }
    return {
        "total_events": total,
        "source_counts": dict(sorted(source_counts.items(), key=lambda x: -x[1])),
        "spike_hours": dict(sorted(spikes.items())),
        "unique_hours": len(events_by_hour),
        "avg_events_per_hour": round(avg_per_hour, 1),
    }


def generate_incident_window(storage_file, output_dir, start_date, end_date):
    """Export events within a specific incident time window."""
    output_file = os.path.join(output_dir, "incident_window.csv")
    date_filter = f"date > '{start_date}' AND date < '{end_date}'"
    return run_psort_export(storage_file, output_file, date_filter=date_filter)


def full_pipeline(image_path, output_dir, parsers=None, start_date=None, end_date=None):
    """Run the full timeline reconstruction pipeline."""
    os.makedirs(output_dir, exist_ok=True)
    storage_file = os.path.join(output_dir, "evidence.plaso")
    if parsers is None:
        parsers = "winevtx,prefetch,mft,usnjrnl,lnk,recycle_bin,chrome_history,firefox_history,winreg"
    filter_path = os.path.join(output_dir, "filter.txt")
    create_filter_file(filter_path)
    results = {"steps": []}
    l2t_result = run_log2timeline(image_path, storage_file, parsers=parsers, filter_file=filter_path)
    results["steps"].append({"step": "log2timeline", **l2t_result})
    if l2t_result["returncode"] != 0:
        results["error"] = "log2timeline failed"
        return results
    full_csv = os.path.join(output_dir, "full_timeline.csv")
    export_result = run_psort_export(storage_file, full_csv)
    results["steps"].append({"step": "psort_export", **export_result})
    if os.path.exists(full_csv):
        results["analysis"] = analyze_timeline_csv(full_csv)
    if start_date and end_date:
        window_result = generate_incident_window(storage_file, output_dir, start_date, end_date)
        results["steps"].append({"step": "incident_window", **window_result})
        window_csv = os.path.join(output_dir, "incident_window.csv")
        if os.path.exists(window_csv):
            results["incident_analysis"] = analyze_timeline_csv(window_csv)
    jsonl_output = os.path.join(output_dir, "timeline.jsonl")
    run_psort_export(storage_file, jsonl_output, output_format="json_line")
    return results


def print_report(results):
    print("Timeline Reconstruction Report")
    print("=" * 50)
    for step in results.get("steps", []):
        status = "OK" if step.get("returncode") == 0 else "FAILED"
        print(f"  [{status}] {step['step']}: {step.get('command', '')[:80]}")
    if "analysis" in results:
        a = results["analysis"]
        print(f"\nTotal Events: {a['total_events']}")
        print(f"Avg/Hour: {a['avg_events_per_hour']}")
        print("\nSource Breakdown:")
        for src, cnt in list(a["source_counts"].items())[:10]:
            print(f"  {src:15s}: {cnt:>8}")
        if a["spike_hours"]:
            print("\nActivity Spikes:")
            for hour, cnt in a["spike_hours"].items():
                print(f"  {hour}: {cnt} events")


if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("Usage: python agent.py <disk_image> <output_dir> [start_date] [end_date]")
        sys.exit(1)
    image = sys.argv[1]
    out_dir = sys.argv[2]
    start = sys.argv[3] if len(sys.argv) > 3 else None
    end = sys.argv[4] if len(sys.argv) > 4 else None
    result = full_pipeline(image, out_dir, start_date=start, end_date=end)
    print_report(result)

Keep exploring