forensics-investigate

What this skill does

# /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`

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

```yaml
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 | grep -v '<pattern>'` |
| 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 lis