Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Timeline Generation

Timeline generation extracts and aggregates timestamps from analyzed files and artifacts to create a chronological view of file activity. This is particularly useful for forensic investigations, incident response, and understanding file access patterns across systems.

Overview

The timeline feature:

  • Extracts timestamps (created, modified, accessed) from all analyzed files
  • Generates output in multiple formats (CSV, JSON, JSON Lines)
  • Supports filtering by tags for multi-system analysis
  • Includes file metadata and pattern match counts
  • Sorts events chronologically for timeline analysis

Usage

Basic Timeline Generation

Generate a CSV timeline after analysis:

# Analyze files and generate timeline
sus /path/to/analyze --generate-timeline csv

# Output: ./output/timeline.csv

Timeline Formats

Three output formats are supported:

CSV Format (Default)

sus /path --generate-timeline csv --timeline-output investigation/timeline.csv

CSV format is RFC 4180 compliant and can be imported into spreadsheet applications for analysis.

JSON Format

sus /path --generate-timeline json --timeline-output timeline.json

JSON format provides a structured array of timeline events suitable for programmatic processing.

JSON Lines Format

sus /path --generate-timeline jsonl --timeline-output timeline.jsonl

JSON Lines (one event per line) is ideal for streaming processing and log analysis tools.

Filtering Timeline Events

Filter by Tags (Multi-System Analysis)

When analyzing multiple systems with tags, filter timeline to specific systems:

# Analyze multiple servers with tags
sus /evidence --tag-dir '/server1:server1' --tag-dir '/server2:server2' \
    --generate-timeline csv --timeline-filter-tag server1

This generates a timeline containing only events from server1.

Multiple Tags

sus /evidence --generate-timeline csv \
    --timeline-filter-tag webserver \
    --timeline-filter-tag database

Control Timestamp Types

By default, all timestamp types (created, modified, accessed) are included. You can exclude specific types:

# Only modification timestamps (exclude created and accessed)
sus /path --generate-timeline csv \
    --timeline-include-created=false \
    --timeline-include-accessed=false

Timeline Event Fields

Each timeline event contains:

FieldDescription
timestampISO 8601 timestamp of the event
timestamp_typeType of timestamp (created, modified, accessed, collected)
file_pathFull path to the file
file_nameFile name without directory
sha256SHA256 hash of file content
mime_typeMIME type detected from file extension
tagTag associated with file (for multi-system analysis)
pattern_match_countNumber of patterns matched in this file
is_symbolic_linkWhether file is a symbolic link
is_extractedWhether file was extracted from an archive
is_decodedWhether file was decoded from an encoding

Forensic Workflows

Incident Response Timeline

Combine artifact collection with timeline generation for complete incident response:

# Collect artifacts and generate timeline
sus /evidence --target KAPE_Triage \
    --collect \
    --generate-timeline csv \
    --timeline-output investigation/incident-timeline.csv

This creates:

  • output/collected/ - Collected suspicious files
  • output/collected/manifest.json - Collection manifest
  • investigation/incident-timeline.csv - Timeline of all file activity

Multi-System Investigation

Analyze multiple systems and generate tagged timeline:

# Collect from multiple servers
sus /mnt/forensics \
    --tag-dir '/mnt/forensics/web01:web01' \
    --tag-dir '/mnt/forensics/db01:db01' \
    --tag-dir '/mnt/forensics/app01:app01' \
    --target KAPE_Triage \
    --collect \
    --generate-timeline csv

# Generate separate timelines per system
sus --server-only --generate-timeline csv --timeline-filter-tag web01 --timeline-output web01-timeline.csv
sus --server-only --generate-timeline csv --timeline-filter-tag db01 --timeline-output db01-timeline.csv

Evidence of Execution Timeline

Focus on program execution artifacts:

sus /windows/system32 \
    --target KAPE_EvidenceOfExecution \
    --generate-timeline json \
    --timeline-output execution-timeline.json

Browser Activity Timeline

Generate timeline of browser usage:

sus /Users \
    --target KAPE_BrowserHistory \
    --generate-timeline csv \
    --timeline-output browser-activity.csv

CSV Timeline Format

Example CSV output:

timestamp,timestamp_type,file_path,file_name,sha256,mime_type,tag,pattern_matches,is_symbolic_link,is_extracted,is_decoded
2024-01-15T10:23:45Z,created,/var/log/auth.log,auth.log,abc123...,text/plain,server1,3,false,false,false
2024-01-15T10:24:12Z,modified,/var/log/auth.log,auth.log,abc123...,text/plain,server1,3,false,false,false
2024-01-15T11:05:33Z,accessed,/etc/passwd,passwd,def456...,text/plain,server1,0,false,false,false

JSON Timeline Format

Example JSON output:

[
  {
    "timestamp": "2024-01-15T10:23:45Z",
    "timestamp_type": "created",
    "file_path": "/var/log/auth.log",
    "file_name": "auth.log",
    "sha256": "abc123...",
    "mime_type": "text/plain",
    "tag": "server1",
    "pattern_match_count": 3,
    "is_symbolic_link": false,
    "is_extracted": false,
    "is_decoded": false,
    "metadata": {}
  }
]

Integration with Analysis Tools

Plaso/log2timeline Integration

While sus doesn't directly output Plaso format, the CSV and JSON formats can be imported into analysis tools:

# Generate JSON Lines for easy parsing
sus /evidence --generate-timeline jsonl --timeline-output events.jsonl

# Process with custom scripts or import into Elastic/Splunk

Timeline Visualization

The CSV format can be imported into:

  • Excel/LibreOffice - Spreadsheet analysis and visualization
  • Timeline Explorer - Forensic timeline viewer
  • Elastic/Kibana - Enterprise SIEM platforms (via JSON/JSONL)
  • Splunk - Security monitoring (via JSON/JSONL)
  • Custom Python scripts - Using pandas for analysis

Best Practices

Performance Considerations

  1. Large Datasets: For very large datasets (millions of files), JSON Lines format is more efficient for streaming processing

  2. Filtering: Use tag filtering to reduce timeline size when analyzing multiple systems

  3. Timestamp Selection: Exclude unnecessary timestamp types to reduce timeline size:

# Only modification times (smallest timeline)
sus /path --generate-timeline csv \
    --timeline-include-created=false \
    --timeline-include-accessed=false

Forensic Integrity

  1. Timeline Generation: Generate timeline immediately after analysis to preserve timestamp context

  2. Documentation: Include timeline metadata in investigation notes:

    • Analysis start/end time
    • Profile used
    • Systems analyzed
    • Timeline filters applied

  3. Chain of Custody: Timeline files should be treated as evidence artifacts

Advanced Examples

Complete Forensic Collection with Timeline

# Full forensic triage with collection and timeline
sus /mnt/evidence \
    --profile profiles/composite/forensic-investigation.toml \
    --collect \
    --generate-timeline csv \
    --output-dir /cases/case-001/analysis

Output structure:

/cases/case-001/analysis/
├── analysis.db                    # Analysis database
├── collected/                     # Collected artifacts
│   ├── default/                   # Artifacts by tag
│   └── manifest.json             # Collection manifest
├── timeline.csv                   # Timeline of all activity
└── files/                         # File metadata

Timeline-Only Generation from Existing Analysis

If you've already performed analysis and want to generate a timeline later:

# Re-run with --server-only and --generate-timeline
sus --server-only \
    --output-dir ./existing-output \
    --generate-timeline json \
    --timeline-output new-timeline.json

Custom Timeline Processing

Process JSON Lines timeline with jq:

# Extract only files with pattern matches
jq 'select(.pattern_match_count > 0)' timeline.jsonl

# Get timeline for specific file type
jq 'select(.mime_type == "text/x-shellscript")' timeline.jsonl

# Find files modified in specific time range
jq 'select(.timestamp_type == "modified" and .timestamp >= "2024-01-01")' timeline.jsonl

Future Enhancements

Planned features for timeline generation:

  1. Collection Timestamps: Include when artifacts were collected (from manifest)
  2. Plaso Format Export: Direct export to Plaso/log2timeline format
  3. Web UI Timeline Viewer: Interactive timeline visualization in web interface
  4. Timeline Correlation: Automatic correlation of related events
  5. Super Timeline: Merge multiple timeline sources (filesystem, registry, logs)

See Also

References