/forensics-investigate

Orchestrate a complete digital forensics investigation by coordinating all specialized agents through the full workflow: reconnaissance, triage, acquisition, multi-domain analysis, timeline building, IOC extraction, and report generation. Suitable for incident response and proactive threat hunting.

Usage

/forensics-investigate <target> [options]

Arguments

triage

full

targeted-ssh

container

cloud

full

recon

triage

acquire

analysis

timeline

ioc

report

.aiwg/forensics/

Behavior

When invoked, this command:

1. Initialize Investigation

   • Create investigation workspace at

     .aiwg/forensics/

   • Assign investigation ID (

     INV-<date>-<host>

     )
   • Record start time, investigator, and scope
   • Check for existing investigation to resume

2. Reconnaissance (recon-agent)

   • Profile target system and establish baseline
   • Document services, users, and network configuration
   • Save to

     profiles/<hostname>/

3. Triage (triage-agent)

   • Capture volatile data per RFC 3227 order
   • Score initial threat level
   • Identify active indicators requiring immediate attention
   • Save to

     findings/<hostname>/volatile/

4. Acquisition (acquisition-agent)

   • Collect logs, configurations, and artifacts per triage findings
   • Establish chain of custody for all evidence
   • Compute and verify SHA-256 hashes
   • Save evidence manifest to

     acquisition/

5. Analysis (parallel agent coordination)

   • Log Analyst: Auth logs, syslog, journal entries
   • Persistence Hunter: Crons, systemd units, SSH keys, rootkits
   • Network Analyst: Connections, DNS, beaconing, lateral movement
   • Container Analyst: Docker/Kubernetes artifacts (if applicable)
   • Memory Analyst: Volatility 3 analysis (if memory image available)
   • Cloud Analyst: CloudTrail, IAM, flow logs (if cloud target)
   • Save findings to

     analysis/<agent>/

6. Timeline Building (timeline-builder)

   • Correlate events across all analysis findings
   • Normalize timestamps to UTC
   • Reconstruct attack chain with MITRE ATT&CK mapping
   • Save to

     timeline/incident-timeline.md

7. IOC Extraction (ioc-analyst)

   • Extract indicators from all findings
   • Enrich with threat intelligence
   • Map to STIX 2.1 observables
   • Save to

     ioc/ioc-register.md

8. Report Generation (reporting-agent)

   • Compile executive summary and technical findings
   • Include severity-classified evidence table
   • Generate remediation plan with prioritized actions
   • Save to

     reports/forensic-report.md

9. Quality Gate

   • Verify all stages completed or explicitly skipped
   • Confirm evidence chain of custody integrity
   • Check report completeness before marking investigation closed

Profile-to-Plan Generation

When a target profile exists at

.aiwg/forensics/profiles/<hostname>-<date>/system-profile.md

forensics-investigate

1. Reading the Target Profile

The command resolves the profile path from the target argument:

1. Derive hostname from the connection string (e.g.,

   ssh://admin@web01

   →

   web01

   )
2. Scan

   .aiwg/forensics/profiles/

   for directories matching

   <hostname>-*

3. Select the most recently dated match (e.g.,

   web01-2026-02-27/

   )
4. Load

   system-profile.md

   (human-readable) and

   system-profile.json

   (machine-readable) from that directory
5. If no profile is found, log a warning and proceed with an unparameterized plan; prompt the investigator to run

   /forensics-profile

   first

The investigation plan's Target Profile Reference section is populated from the resolved path:

target_profile_path: .aiwg/forensics/profiles/web01-2026-02-27/system-profile.md
profile_date: 2026-02-27

2. Parameterizing Commands from Profile Data

The following profile fields are extracted and substituted into investigation plan commands:

{{hostname}}

last -n 50 web01

{{case_id}}

ps auxf > /tmp/INV-2026-02-27-web01_ps_snapshot.txt

{{expected_users}}

{{expected_service_pattern}}

{{expected_ports}}

{{investigation_date}}

journalctl --since "2026-02-27 00:00:00"

{{log_lookback_days}}

--since

{{timeline_window_days}}

find / -newer

{{large_file_threshold_mb}}

find / -size +100M

{{connection_count_alert_threshold}}

awk '$1 >= 20'

{{failed_login_threshold}}

{{package_manager_history_command}}

{{web_access_log}}

{{evidence_storage_path}}

{{escalation_contact}}

User and authentication commands in Phase 2 are scoped to the known account list from the profile's Users with Shell Access table. For example, if the profile documents

admin

deploy

root

/home

3. Service-Specific Check Inclusion

Phase 3 (Process and Service Audit) and Phase 7 (Log Analysis) include service-specific checks only for services listed in the profile's Services and Ports table with

Expected: Yes

The command applies these rules:

nginx

apache2

mysqld

postgresql

sshd

docker

containerd

The Phase 8 section header in the generated plan reflects the include/exclude decision explicitly:

### Phase 8: Container / Docker Audit
> INCLUDED — docker detected in target profile (3 running containers at baseline)

or:

### Phase 8: Container / Docker Audit
> SKIPPED — no container runtime in target profile

Services not present in the profile that are found running during triage are flagged as anomalies in the triage summary and receive targeted investigation commands appended to Phase 3.

4. Deriving Expected vs. Suspicious Baselines

The profile's Services and Ports and Network Baseline sections establish what is normal. The generated plan encodes these baselines directly into triage commands:

Port baseline — The expected listening ports from the profile (e.g.,

22

80

443

3306

ss -tlnpu

# Ports not in baseline (web01 profile: 22, 80, 443, 3306)
ss -tlnpu | awk 'NR>1 {print $5}' | grep -oP ':\K[0-9]+' | sort -un \
  | grep -vE '^(22|80|443|3306)$' | while read p; do echo "UNEXPECTED PORT: $p"; done

Outbound connection baseline — The expected outbound destinations from the profile's Expected Outbound Connections table are embedded in the network phase as an allowlist. Connections to destinations outside this list are flagged for review.

User baseline — The known shell-access accounts from the profile are compared against

getent passwd

Container baseline — If the profile includes a Running Containers (Baseline) table, the generated plan compares current

docker ps

Failed login threshold — The

failed_login_threshold

10

Scope Profiles

triage

targeted-ssh

container

cloud

full

Examples

Example 1: Full investigation

/forensics-investigate ssh://admin@192.168.1.50 --scope full

Example 2: Quick triage only

/forensics-investigate ssh://admin@192.168.1.50 --scope triage

Example 3: Container sweep

/forensics-investigate ssh://root@docker-host --scope container

Example 4: Cloud audit

/forensics-investigate aws://123456789012/us-east-1 --scope cloud

Example 5: Resume interrupted investigation

/forensics-investigate ssh://admin@192.168.1.50 --resume

Example 6: Skip memory analysis

/forensics-investigate ssh://admin@host --scope full --skip-stage memory

Output

All artifacts are saved under

.aiwg/forensics/

.aiwg/forensics/
├── investigation.yaml             # Investigation metadata and state
├── profiles/
│   └── web01-2026-02-27/
│       └── system-profile.md
├── findings/
│   └── web01-2026-02-27/
│       ├── triage-summary.md
│       └── volatile/
├── acquisition/
│   ├── evidence-manifest.yaml
│   └── custody-log.yaml
├── analysis/
│   ├── logs/
│   ├── persistence/
│   ├── network/
│   └── ioc/
├── timeline/
│   └── incident-timeline.md
├── ioc/
│   └── ioc-register.md
└── reports/
    └── forensic-report.md

Sample Progress Output

Investigation: INV-2026-02-27-web01
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[14:30:00] Stage 1/8: Reconnaissance     RUNNING
[14:31:42] Stage 1/8: Reconnaissance     COMPLETE  (102s)
[14:31:42] Stage 2/8: Triage             RUNNING
[14:34:15] Stage 2/8: Triage             COMPLETE  (153s) [CRITICAL - active compromise]
[14:34:15] Stage 3/8: Acquisition        RUNNING
[14:39:02] Stage 3/8: Acquisition        COMPLETE  (287s) [14 artifacts collected]
[14:39:02] Stage 4/8: Analysis           RUNNING   (parallel: 5 agents)
[14:39:02]   Log Analyst                 RUNNING
[14:39:02]   Persistence Hunter          RUNNING
[14:39:02]   Network Analyst             RUNNING
[14:52:18]   Log Analyst                 COMPLETE  [8 findings]
[14:53:41]   Persistence Hunter          COMPLETE  [3 findings]
[14:55:09]   Network Analyst             COMPLETE  [5 findings]
[14:55:09] Stage 4/8: Analysis           COMPLETE  (976s) [16 total findings]
[14:55:09] Stage 5/8: Timeline           RUNNING
[14:57:33] Stage 5/8: Timeline           COMPLETE  (144s)
[14:57:33] Stage 6/8: IOC Extraction     RUNNING
[14:59:01] Stage 6/8: IOC Extraction     COMPLETE  (88s)  [12 IOCs extracted]
[14:59:01] Stage 7/8: Report Generation  RUNNING
[15:01:44] Stage 7/8: Report Generation  COMPLETE  (163s)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Investigation Complete: INV-2026-02-27-web01
Duration: 31m 44s

Findings: 16 total (2 CRITICAL, 5 HIGH, 6 MEDIUM, 3 LOW)
IOCs: 12 extracted (4 enriched with threat intel)
Report: .aiwg/forensics/reports/forensic-report.md

References

• @$AIWG_ROOT/agentic/code/frameworks/forensics-complete/agents/forensics-orchestrator.md - Orchestrator
• @$AIWG_ROOT/agentic/code/frameworks/forensics-complete/agents/manifest.json - All agent definitions
• @$AIWG_ROOT/agentic/code/frameworks/forensics-complete/commands/forensics-report.md - Report generation
• @$AIWG_ROOT/agentic/code/frameworks/forensics-complete/commands/forensics-status.md - Status monitoring