forensics-investigate

namespace	aiwg
name	forensics-investigate
platforms	["all"]
description	Full multi-agent investigation workflow
commandHint	{"argumentHint":"<target> [--scope triage|full|targeted-ssh|container|cloud] [--skip-stage stage]","category":"forensics-investigation"}

/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

Argument	Required	Description
target	Yes	SSH connection string, cloud target, or findings directory path
--scope	No	Investigation scope: triage, full, targeted-ssh, container, cloud (default: full)
--skip-stage	No	Skip a specific stage: recon, triage, acquire, analysis, timeline, ioc, report
--resume	No	Resume a previously interrupted investigation from last checkpoint
--output	No	Output directory (default: .aiwg/forensics/)
--parallel	No	Run analysis agents in parallel where possible (default: true)
--notify	No	Webhook URL for stage completion notifications

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

Profile-to-Plan Generation

When a target profile exists at .aiwg/forensics/profiles/<hostname>-<date>/system-profile.md, forensics-investigate reads it before generating the investigation plan. This enables the plan to contain parameterized, host-specific commands instead of generic placeholders.

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:

Profile Field	Plan Variable	Example Usage
Hostname	{{hostname}}	last -n 50 web01
Case ID	{{case_id}}	ps auxf > /tmp/INV-2026-02-27-web01_ps_snapshot.txt
Users with shell access	{{expected_users}}	Auth log grep patterns scoped to known accounts
Running services list	{{expected_service_pattern}}	`lsof -i
Listening ports	{{expected_ports}}	Connection count alert comparison
Investigation date	{{investigation_date}}	journalctl --since "2026-02-27 00:00:00"
Log lookback window	{{log_lookback_days}}	--since timestamps for auth and syslog queries
Timeline window	{{timeline_window_days}}	find / -newer reference marker
Large file threshold	{{large_file_threshold_mb}}	find / -size +100M
Connection alert threshold	{{connection_count_alert_threshold}}	awk '$1 >= 20' in network phase
Failed login threshold	{{failed_login_threshold}}	Alert threshold in auth analysis
Package manager	{{package_manager_history_command}}	Distro-appropriate package history command
Log file paths	{{web_access_log}}	Service-specific log path substitution
Evidence storage path	{{evidence_storage_path}}	Evidence collection target directory
Escalation contact	{{escalation_contact}}	Red flag notification target

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, and root, the SSH key sweep is limited to those home directories rather than iterating all of /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:

Service Present in Profile	Checks Included
nginx or apache2	Web access log parsing, HTTP error pattern grep
mysqld or postgresql	Database error log check, unusual connection sources
sshd	SSH auth failure threshold, authorized_keys sweep
docker / containerd	Phase 8 (Container / Docker Audit) is included; otherwise skipped
No container runtime listed	Phase 8 is excluded from the generated plan with a note
Cloud metadata service detected	Cloud Analyst agent is added to the Phase 5 parallel pool

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) are embedded in the Phase 6 network check. Any port reported by ss -tlnpu that is not in this list is flagged inline:

# 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 output at investigation time. New accounts not in the profile are flagged in Phase 2 as potential persistence artifacts.

Container baseline — If the profile includes a Running Containers (Baseline) table, the generated plan compares current docker ps output against that baseline. Containers not present at profile time are flagged as anomalous in Phase 8.

Failed login threshold — The failed_login_threshold from the profile's Investigation Scope Configuration block (default: 10) is substituted into the auth log grep commands. Accounts exceeding this threshold in Phase 2 are surfaced as priority findings.

Scope Profiles

Scope	Stages	Use Case
triage	recon, triage	Initial rapid assessment
targeted-ssh	recon, triage, acquire, logs, persistence, network	SSH-compromised host
container	recon, triage, acquire, container, network	Container escape or image compromise
cloud	recon, acquire, cloud, ioc, report	Cloud account breach
full	All stages	Comprehensive incident response

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