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. Runs the analysis using that sub-skill: Claude executes the static tooling, parses exported evidence, writes rules and reports itself
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.

Execution Model

• Claude does the work on the host. Hashing, file, PE parsing, strings, IOC extraction, macro/PDF/script deobfuscation, .NET decompilation, Procmon/Sysmon/tshark parsing, rule authoring and testing, report writing — all run by Claude with Bash. Do not turn a step into "ask the user to run X and paste the output" unless the tool is missing and cannot be installed.
• The only thing the analyst does by hand is execute the sample in the isolated VM and export text evidence. malware-dynamic-analysis produces the runbook for that.
• Never execute a sample or any extracted stage on the host. Static tooling only. Never upload a sample anywhere without explicit consent (hash lookups are fine).
• Locate skill files. The sub-skill SKILL.md files and the scripts below ship in this skill's directory tree. Set R="${CLAUDE_PLUGIN_ROOT:-<dir containing this SKILL.md>}" once — when installed as a plugin $CLAUDE_PLUGIN_ROOT points at the install; otherwise it is this skill folder. The working directory is the user's analysis workspace, so read sub-skills and run scripts by absolute path, e.g. python3 "$R"/scripts/ioc_extract.py and read "$R"/malware-triage/SKILL.md.

• Bundled scripts (paths below are relative to $R):

  Script	Used by	Purpose
  scripts/ioc_extract.py	all phases	extract + defang IOCs from any text (--format csv/json, --refang)
  malware-triage/scripts/pe_info.py	triage	PE headers, sections, entropy, imports, packing verdict, signature, overlay, resources (needs pefile)
  malware-triage/scripts/hash_calculator.py	triage	MD5/SHA1/SHA256
  malware-dynamic-analysis/scripts/procmon_summary.py	dynamic	Procmon CSV → process tree, file/registry writes, network, persistence flags
  malware-dynamic-analysis/scripts/sysmon_summary.py	dynamic	Sysmon JSON/CSV/evtx_dump → tree, network + beaconing, DNS, injection, persistence

  Run --self-test on any of them if in doubt.

• Host tool check at engagement start (once), then degrade gracefully and say what is missing:

  command -v file strings upx 7z yara tshark olevba oledump.py pdfid.py ilspycmd js-beautify readelf jq; python3 -c "import pefile" 2>&1 | tail -1

• Big outputs go to files under the engagement workspace; inspect with wc -l, head, grep, and the summary scripts — never cat a strings dump or a Procmon CSV.

Routing Logic

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, hand the user the runbook from malware-dynamic-analysis/SKILL.md Part A, tailored with the triage predictions (process names to filter, expected protocol, expected persistence), and state the boundary explicitly:

"The next phase requires executing the sample in your isolated VM (REMnux/FlareVM). Follow the runbook: snapshot → start Procmon/Wireshark/System Informer/Sysmon → execute → observe 15+ min → export evidence with the A4 commands (Procmon CSV, Sysmon JSON, tshark text, autoruns CSV, dropped files) → revert. Bring the evidence/ directory back and I'll parse it."

If the user returns with PML/PCAP/EVTX, give the conversion command from the dynamic skill's Converting Binary Evidence table (tshark and evtx_dump can run on the host) rather than refusing the files.

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

# 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: Run the full phase sequence on high-priority samples one at a time, confirming with the user at each phase transition
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:

Paths are relative to the directory containing this SKILL.md (the sub-skills are not registered as separate skills — this orchestrator reads them by path). 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