/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:

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
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
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
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
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
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
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