malware-analysis

---
name: malware-analysis
description: Orchestrate the complete malware analysis lifecycle across triage, dynamic analysis, detection engineering, and report writing. Use as the single entry point for any malware analysis task — routes to specialized sub-skills by file type and phase, carries findings between phases, and supports multi-sample batch workflows.
---

# Malware Analysis Orchestrator

Single entry point for malware analysis engagements. Routes to specialized sub-skills, carries findings between phases, and manages multi-sample workflows.

## How This Works

You describe what you need — "analyze this sample", "I have 5 files to triage", "create detection rules from my findings" — and this orchestrator:

1. Determines which sub-skill to use based on your file type and intent
2. Guides you through the analysis using that sub-skill
3. Records findings in a state file (`analysis_state.md`)
4. Recommends the next phase when the current one completes
5. Waits for your confirmation before proceeding

You never need to invoke sub-skills directly.

## Routing Logic

| Signal | Routes To |
|--------|-----------|
| Unknown file / "what is this?" / initial assessment | `malware-triage` |
| PE executable after triage, needing behavior monitoring | `malware-dynamic-analysis` |
| .NET / Office / PDF / script / archive / LNK / ELF / HTA / ISO / IMG / VHD / VHDX | `specialized-file-analyzer` |
| "Create detection rules" / post-analysis phase | `detection-engineer` |
| "Write the report" / final documentation phase | `malware-report-writer` |
| YARA rules specifically | `malware-report-writer` (not detection-engineer) |

**Triage is always the entry point for new samples.** The table above describes which *analysis* skill follows triage.

### File Type Priority Order

When routing by file type, use the `file` command output. Check in this order — first match wins:

1. "Mono/.Net assembly" → read and follow `specialized-file-analyzer/SKILL.md`
2. "Microsoft Office Document" → read and follow `specialized-file-analyzer/SKILL.md`
3. "PDF document" → read and follow `specialized-file-analyzer/SKILL.md`
4. "ELF" → read and follow `specialized-file-analyzer/SKILL.md`
5. "PE32" / "PE64" (only if .NET was NOT matched) → read and follow `malware-triage/SKILL.md`, then `malware-dynamic-analysis/SKILL.md`
6. "MS Windows shortcut" (LNK) → read and follow `specialized-file-analyzer/SKILL.md`
7. ASCII text / script content → read and follow `specialized-file-analyzer/SKILL.md`
8. Archive formats (Zip, RAR, 7z) → read and follow `specialized-file-analyzer/SKILL.md`
9. HTML Application (.hta) → read and follow `specialized-file-analyzer/SKILL.md`
10. ISO/IMG disk images → read and follow `specialized-file-analyzer/SKILL.md` (mount/extract, then analyze contents)
11. VHD/VHDX virtual hard disks → read and follow `specialized-file-analyzer/SKILL.md` (mount/extract, then analyze contents)
12. "data" / zero-byte / unrecognized → read and follow `malware-triage/SKILL.md` for manual assessment

**.NET is the key ambiguity:** `file` outputs both "PE32" and "Mono/.Net assembly" for .NET assemblies. Always check for .NET before checking for PE.

## Phase Sequence

Each sample follows this sequence:

```
Triage → [Dynamic Analysis OR Specialized File Analysis] → Detection Engineering → Report Writing
```

- **Triage** is always first — read and follow `malware-triage/SKILL.md`
- **Dynamic analysis** for PE executables — read and follow `malware-dynamic-analysis/SKILL.md`
- **Specialized file analysis** for non-PE files (.NET, Office, PDF, scripts, archives, LNK, ELF) — read and follow `specialized-file-analyzer/SKILL.md`
- **Detection engineering** consolidates IOCs into Sigma/Suricata rules — read and follow `detection-engineer/SKILL.md`
- **Report writing** is always last — read and follow `malware-report-writer/SKILL.md`

## Phase Transitions (Suggest-Next Mode)

After each phase completes:

1. **Summarize** what was found in the current phase
2. **Update** `analysis_state.md` with findings and IOCs
3. **Recommend** the next skill with reasoning based on findings
4. **Wait** for user confirmation before proceeding

**Never auto-chain phases.** Every transition requires user confirmation.

### VM Isolation Boundary

Before dynamic analysis, explicitly remind the user:

> "The next phase requires executing the sample in your isolated VM (REMnux/FlareVM). Please:
> 1. Execute the sample with monitoring tools running (Procmon, Wireshark, System Informer (formerly Process Hacker), Sysmon)
> 2. Observe for at least 15 minutes
> 3. Export evidence in text-parseable formats (CSV, JSON, TXT — not PML, PCAP, EVTX)
> 4. Return here with the exported evidence files
>
> I'll analyze the evidence when you're back."

## State File: `analysis_state.md`

Created in the user's working directory (not this skill repo) when the first sample is provided. Updated after each phase.

### Structure

```markdown
# Malware Analysis — [Engagement Name/Date]

**Analyst:** [name]
**Started:** [date]
**Status:** [In Progress / Complete]

---

## Samples

### Sample 1: [filename]
- **File Type:** [type]
- **MD5:** [hash]
- **SHA1:** [hash]
- **SHA256:** [hash]
- **Size:** [bytes]
- **Priority:** [Immediate / Standard / Low]
- **Classification:** [Trojan / Ransomware / etc. or Pending]
- **Threat Level:** [Critical / High / Medium / Low or Pending]
- **Current Phase:** [Triage / Dynamic Analysis / Specialized Analysis / Detection / Reporting / Complete / Benign]

#### Triage Findings
- [findings appended after triage phase]

#### Analysis Findings
- [findings appended after dynamic/specialized analysis]

#### IOCs Identified
- [accumulated IOCs, defanged]

#### Detection Rules Created
- [list of rules created and their locations]

---

## Next Steps
- [orchestrator's recommendation for what to do next and why]
```

### State File Rules

- **Create** when the user begins an engagement (first sample provided)
- **Append** findings after each phase — never overwrite previous findings
- **Replace** the "Next Steps" section at each transition (not append)
- **Resume** from state file if the user returns in a new conversation — read `analysis_state.md` to restore context
- **All IOCs must be defanged** at the point they are recorded to the state file, regardless of which phase produces them

## Multi-Sample Batch Workflow

1. **Intake**: Prompt for all known samples upfront — "How many samples do you have? Let's list them all before we begin."
2. **Batch triage**: Quick triage pass on all samples (5-10 min each — hashes, file type, reputation check, classification per the triage skill's "Quick Triage" tier)
3. **Priority ranking**: Rank samples as Immediate / Standard / Low based on triage findings
4. **Sequential deep analysis**: Guide the user through deep analysis of high-priority samples one at a time, following the full phase sequence per sample
5. **State tracking**: Update state file per-sample so the user can see which samples are triaged, analyzed, and reported

## Conventions Enforced

- All IOCs in state files and reports must be **defanged** (`hxxp://`, `[.]com`, `[@]`)
- Reports always include all three hash types: MD5, SHA1, SHA256
- Evidence must be in text-parseable formats (CSV, JSON, TXT)
- Detection rules (YARA, Sigma, Suricata) must be tested before inclusion
- MITRE ATT&CK technique IDs must be tagged in Sigma rules
- Sigma rules require unique UUIDs
- Custom Suricata rules use SIDs starting at 1000000+

### IOC Defanging Ownership

Each phase defangs IOCs before appending them to the state file. The `detection-engineer` sub-skill handles bulk defanging, format conversion (STIX, CSV, OpenIOC), and confidence assessment during its dedicated phase.

## Edge Cases

- **User wants to skip a phase**: Allow it, note the skip in the state file, and proceed to the requested phase
- **User provides evidence without explicit routing**: Infer the phase from evidence type (Procmon CSV → dynamic analysis, Sysmon JSON → dynamic analysis, olevba output → specialized file analysis, etc.)
- **Session restart**: Read `analysis_state.md` to restore context and resume from the last recorded phase
- **Single sample, known type**: Skip batch triage and go directly to the appropriate skill
- **User explicitly requests a specific sub-skill**: Defer to the user's choice
- **Benign sample**: If triage determines a sample is clean/benign, mark its phase as `Benign` in the state file, note the reasoning, and move to the next sample. Do not proceed with further analysis phases.
- **Unrecognized file type**: If `file` output doesn't match any known routing pattern, default to `malware-triage/SKILL.md` for manual assessment. Note the unknown type in the state file.
- **State file conflicts**: If an existing `analysis_state.md` is found, ask whether to resume the existing engagement or start a new one (with a timestamped filename like `analysis_state_2026-03-15.md`)
- **Running from the skill repo**: If the working directory appears to be this skill repository itself (contains `malware-triage/`, `detection-engineer/`, etc. as subdirectories), warn the user and ask them to switch to their analysis workspace before creating a state file

## Sub-Skill Reference

The orchestrator delegates to these sub-skills by reading their SKILL.md files at execution time:

| Sub-Skill | Path | Purpose |
|-----------|------|---------|
| Malware Triage | `malware-triage/SKILL.md` | Rapid assessment, classification, prioritization |
| Dynamic Analysis | `malware-dynamic-analysis/SKILL.md` | Safe execution, behavior monitoring in isolated VMs |
| Specialized File Analyzer | `specialized-file-analyzer/SKILL.md` | Non-PE file analysis (.NET, Office, PDF, scripts, archives, LNK, ELF) |
| Detection Engineer | `detection-engineer/SKILL.md` | Sigma rules, Suricata rules, hunting queries, IOC defanging |
| Report Writer | `malware-report-writer/SKILL.md` | Professional reports, YARA rules, quality checklists |

When entering a phase, read the corresponding SKILL.md file and follow its instructions. Carry forward the accumulated state from previous phases.

## MCP Server Integrations (Optional)

MCP servers can automate manual steps like hash lookups and IOC enrichment. If available, use them to accelerate the workflow — but they are not required.

See `references/mcp_integrations.md` for setup instructions and a mapping of which MCP servers benefit which skills. The two highest-impact integrations are:

1. **VirusTotal MCP** — automates hash/URL/domain reputation checks during triage
2. **Threat Intel MCP** — unified access to MalwareBazaar, ThreatFox, AbuseIPDB, and GreyNoise for IOC validation