jmagly/forensics-timeline

/forensics-timeline

Correlate events from multiple forensic sources into a unified chronological timeline. Normalizes timestamps across log files, network captures, process events, and file system artifacts. Reconstructs the attack chain and maps events to MITRE ATT&CK techniques.

Usage

/forensics-timeline <findings-path> [options]

Arguments

| Argument | Required | Description | |----------|----------|-------------| | findings-path | Yes | Path to findings directory (e.g., .aiwg/forensics/findings/web01-2026-02-27/) | | --window | No | Time window filter: start/end in ISO 8601 (e.g., 2026-02-26T18:00:00Z/2026-02-27T06:00:00Z) | | --sources | No | Event sources to include: logs, network, process, filesystem, all (default: all) | | --mitre | No | Annotate events with MITRE ATT&CK technique IDs | | --output | No | Output path (default: .aiwg/forensics/timeline/incident-timeline.md) | | --granularity | No | Minimum event significance level: all, medium, high (default: medium) | | --format | No | Output format: markdown (default), json, csv |

Behavior

When invoked, this command:

1. Discover Evidence Sources

   • Scan findings directory for all log files, captures, and analysis outputs
   • Identify available sources: auth logs, syslog, journal, audit, network, process lists
   • Record source timestamps and timezone/offset metadata
   • Note any gaps in log coverage

2. Normalize Timestamps

   • Convert all timestamps to UTC
   • Detect and compensate for clock skew between sources
   • Handle timezone-naive log entries using system timezone from profile
   • Flag entries with ambiguous or inconsistent timestamps

3. Event Extraction

   • Parse authentication events: logins, logouts, sudo, su, failed attempts
   • Extract network events: connections established, DNS queries, port scans
   • Extract process events: spawns, exits, executions from unusual paths
   • Extract filesystem events: file modifications, creations, deletions (if auditd active)
   • Extract privilege events: uid changes, capability grants, SUID executions
   • Extract persistence events: cron modifications, service installs, key changes

4. Correlation and Deduplication

   • Match related events across sources (e.g., SSH login + process spawn)
   • Deduplicate events appearing in multiple log sources
   • Link network connections to responsible processes via PID correlation
   • Group events into logical attack phases

5. Attack Chain Reconstruction

   • Identify initial access vector (brute force, key use, web exploit, etc.)
   • Map progression: initial access, execution, persistence, lateral movement
   • Identify patient zero: first compromised account or process
   • Estimate attacker dwell time from first to last activity
   • Determine data exfiltration indicators

6. MITRE ATT&CK Mapping (when --mitre specified)

   • Map each significant event to ATT&CK technique IDs
   • Label tactics: TA0001 Initial Access, TA0002 Execution, TA0003 Persistence, etc.
   • Note relevant sub-techniques where applicable

7. Timeline Output

   • Write chronological event table
   • Include severity, source, raw event, and interpretation for each entry
   • Highlight critical events (red flags, attack milestones)
   • Generate attack chain narrative summary
   • Save incident-timeline.md

Examples

Example 1: Standard timeline

/forensics-timeline .aiwg/forensics/findings/web01-2026-02-27/

Example 2: Filtered time window

/forensics-timeline .aiwg/forensics/findings/ --window 2026-02-26T20:00:00Z/2026-02-27T04:00:00Z

Example 3: Network and process sources with MITRE mapping

/forensics-timeline .aiwg/forensics/ --sources network,process --mitre

Example 4: High-significance events only, JSON output

/forensics-timeline .aiwg/forensics/ --granularity high --format json

Output

Artifacts are saved to .aiwg/forensics/timeline/:

.aiwg/forensics/timeline/
├── incident-timeline.md      # Full chronological timeline
├── attack-chain.md           # Attack progression narrative
├── timeline.json             # Machine-readable event list
└── mitre-mapping.yaml        # ATT&CK technique annotations (if --mitre)

Sample Output

Building Timeline
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Sources discovered:
  auth.log          (72h, 14,832 entries)
  journal           (72h, 187,441 entries)
  audit.log         (72h, 92,318 entries)
  network captures  (triage snapshot)
  process list      (triage snapshot)

Timestamps normalized to UTC
Clock skew: 0s (synchronized)

Events extracted: 1,247 raw -> 312 significant
Correlations found: 48

Timeline window: 2026-02-26T22:00:00Z to 2026-02-27T02:15:00Z (4h 15m)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| Time (UTC)          | Sev      | Source   | Event                                              |
|---------------------|----------|----------|----------------------------------------------------|
| 2026-02-26 22:14:33 | HIGH     | auth.log | 847 failed SSH attempts from 185.220.101.42        |
| 2026-02-26 22:29:01 | CRITICAL | auth.log | Successful SSH login for 'deploy' from 185.220.101.42 |
| 2026-02-26 22:29:04 | HIGH     | journal  | Process spawn: /bin/bash (child of sshd PID 3821) |
| 2026-02-26 22:31:18 | HIGH     | audit    | Privilege escalation: sudo -l (deploy -> root)    |
| 2026-02-26 22:33:45 | CRITICAL | audit    | New cron entry: * * * * * /tmp/.update             |
| 2026-02-26 22:34:01 | CRITICAL | journal  | File created: /tmp/.update (executable)           |
| 2026-02-27 00:00:00 | HIGH     | journal  | Cron executed: /tmp/.update                       |
| 2026-02-27 00:00:02 | CRITICAL | journal  | Outbound connection: 185.220.101.42:4444          |

Attack Chain Summary:
  Initial Access:  22:14Z - SSH brute force (T1110.001)
  Execution:       22:29Z - Interactive shell via compromised credentials (T1059.004)
  Persistence:     22:33Z - Cron job installation (T1053.003)
  C2:              00:00Z - Reverse shell beaconing (T1071.001)
  Dwell time: 1h 46m (first access to C2 beacon)
  Patient zero: account 'deploy'

Output: .aiwg/forensics/timeline/incident-timeline.md

References

• @$AIWG_ROOT/agentic/code/frameworks/forensics-complete/agents/timeline-builder.md - Timeline Builder
• @$AIWG_ROOT/agentic/code/frameworks/forensics-complete/templates/timeline-template.md - Timeline format
• @$AIWG_ROOT/agentic/code/frameworks/forensics-complete/commands/forensics-ioc.md - IOC extraction
• @$AIWG_ROOT/agentic/code/frameworks/forensics-complete/commands/forensics-report.md - Report generation