malware-report-writer · diff
git:20260905.fd80b2a to git:20260905.e1d9a1a
1 added, 0 removed. Audit A to A.
---
name: malware-report-writer
description: Create professional malware analysis reports for enterprise security teams and incident response. Use when you need to write, structure, or improve a malware analysis report, produce executive summaries, author YARA rules, or format IOCs and detection rules for professional delivery.
---
# Malware Report Writer
Create professional, comprehensive malware analysis reports for enterprise security teams, incident response, and threat intelligence.
## Execution Model
- **You write the report.** Read `analysis_state.md` and the evidence directory yourself (triage report, `procmon_summary.txt`, `sysmon_summary.txt`, tshark exports, decoded scripts, detection rule files) and draft every section from that. Ask the user only for what the evidence cannot tell you: engagement name, analyst name, audience, classification/TLP, and gaps you have flagged.
+ - **Locate skill files.** Scripts and reference files ship in this skill's directory. Set `R="${CLAUDE_PLUGIN_ROOT:-<dir containing this SKILL.md>}"` once (when installed as a plugin `$CLAUDE_PLUGIN_ROOT` is set; otherwise it is this skill folder). Your working directory is the user's analysis workspace, so prefix every script path below with `$R`, e.g. `python3 "$R"/scripts/ioc_extract.py`.
- **Author the YARA rule from the evidence** (runtime-decrypted strings, unique UA/URI, mutex, PDB path, config markers) and **test it yourself** when `yara` is installed — see **Testing YARA rules**. If it cannot be tested, mark the rule `UNTESTED` in the report; never present an untested rule as validated.
- **Defang at write time.** Run any IOC list through `python3 scripts/ioc_extract.py` (repo root) rather than defanging by hand.
- **Output is a file.** Write `reports/<sample>_report.md` in the user's workspace (create the directory), then print the executive summary and the quality-checklist result. Never leave template placeholders in the delivered file.
- **State what was not done.** Phases skipped, network not observed, packer not defeated — these go in the report's limitations, not silently omitted.
## When to Use This Skill
Use this skill when the user needs to:
- Create a complete malware analysis report from analysis findings
- Structure analysis results into professional documentation
- Write executive summaries for malware samples
- Format IOCs and detection rules for delivery
- Review or improve existing malware reports
- Prepare report documentation for stakeholders
## Quick Start
### Creating a New Report
1. `cat analysis_state.md`; `ls` the evidence and detection directories; read the phase outputs you need
2. Copy `assets/report_template.md` to `reports/<sample>_report.md`
3. Populate each section from the evidence, citing it (file, line, event) so every claim is traceable
4. Author and test the YARA rule; paste Sigma/Suricata rules from `detection-engineer` verbatim
5. Run the Quality Checklist below and `references/best_practices.md`; fix, then deliver
### Report Structure
The standard report includes these sections in order:
1. **Executive Summary** - High-level overview for non-technical stakeholders
2. **Sample Information** - Basic file metadata and hashes
3. **Static Analysis** - File structure, strings, imports/exports, resources
4. **Dynamic Analysis** - Runtime behavior, system changes, network activity
5. **IOCs** - Organized by type (file, network, host indicators)
6. **Detection Rules** - YARA rules and optionally Sigma rules
7. **Malware Classification** - Family, type, capabilities
8. **Remediation and Mitigation** - Actionable response steps
9. **Technical Details** - Additional deep-dive analysis
10. **Conclusion** - Final summary and assessment
11. **References** - External resources and links
12. **Appendix** - Timeline, tools used, screenshots
## Key Principles
### Professional Quality
- Use precise technical language with clear explanations
- Include all three hash types (MD5, SHA1, SHA256)
- Provide full context for every finding
- Document methodology and tools used
- Include timestamps and version information
### Professional Report Requirements
Industry-standard reports require:
- Complete technical documentation of malware samples
- Professional format suitable for enterprise delivery
- Working detection rules based on malware characteristics
- Clear IOCs that can be operationalized
**Critical:** The quality of your report reflects your professionalism. Allocate sufficient time for writing and review.
### Audience Awareness
Structure content for multiple audiences:
- **Executive Summary**: Non-technical decision makers
- **Technical Sections**: Security analysts and researchers
- **IOCs/Detection**: SOC teams and detection engineers
- **Remediation**: Incident responders
## Writing Guidelines
### Executive Summary
- 2-4 paragraphs maximum
- Plain language, minimal jargon
- Answer: What? How critical? What actions?
- Include key findings in bullet points
### Technical Analysis
- Document both positive and negative findings
- Provide evidence for every claim
- Use code blocks for technical artifacts
- Include screenshots when they add value
- Connect behaviors to specific evidence
### IOCs Section
**Format:**
- Group by type (file, network, host)
- Include context for each indicator
- Provide confidence levels if uncertain
- Test IOCs for accuracy before including
**Defanging (required):** All IOCs in reports MUST be defanged to prevent accidental activation:
- URLs: `http` → `hxxp`, `https` → `hxxps` (e.g., `hxxps://malicious[.]example[.]com/payload`)
- Domains: bracket the dot before the TLD (e.g., `evil[.]com`, `sub.domain[.]net`)
- Email addresses: `@` → `[@]` (e.g., `attacker[@]evil[.]com`)
- IP addresses: bracket each dot separator (e.g., `192[.]168[.]1[.]1`)
**Avoid:**
- Environment-specific artifacts
- Personal/analyst system information
- Common legitimate values
- Untested indicators
### Detection Rules
**YARA Rules:**
- Test against sample (must detect)
- Test against clean files (must not false positive)
- Include metadata: author, date, description, hash
- Use meaningful string and variable names
- Add comments explaining detection logic
- Set appropriate conditions to balance detection and false positives
**Testing YARA rules** (run these; paste the results into the report's detection section):
```bash
command -v yara || echo "yara not installed: pip install yara-python / apt install yara — mark rule UNTESTED"
yara -w -s detections/yara/family.yar samples/sample.exe # must match; -s shows which strings hit
yara -w -s detections/yara/family.yar samples/unpacked.exe # and the unpacked/dropped stages
yara -w -r detections/yara/family.yar /usr/lib /usr/bin clean/ 2>/dev/null | head # must print nothing (clean corpus; add a Windows clean dir if available)
```
A rule that matches only on strings present in the packed sample is a hash in disguise; prefer runtime-decrypted strings, config markers, mutexes, and code patterns, and require `2 of them` or more with a `filesize` bound.
**Best practices:**
```yara
rule Malware_Family_Variant {
meta:
description = "Detects Malware_Family based on C2 configuration"
author = "Analyst Name"
date = "2025-10-25"
hash = "abc123..."
reference = "Internal analysis"
strings:
$c2_config = { 48 8B ?? ?? ?? ?? ?? 48 8D ?? ?? } // Config access pattern
$ua_string = "Mozilla/4.0 (Suspicious UA)" ascii
$mutex = "Global\\UniqueMalwareMutex" wide
condition:
uint16(0) == 0x5A4D and // MZ header
filesize < 2MB and
2 of them
}
```
### Common Mistakes to Avoid
- Over-relying on automated tool output without interpretation
- Listing findings without explaining significance
- Missing critical hashes or file metadata
- Weak or untested detection rules
- Vague remediation recommendations
- Poor grammar/spelling
- Inconsistent formatting
- Environment-specific artifacts in IOCs
## Best Practices Reference
For detailed guidance on report quality, writing style, and common pitfalls, see `references/best_practices.md`.
Key topics covered:
- Report writing principles (clarity, completeness, objectivity)
- Structure guidelines for each section
- IOC quality standards
- Detection rule best practices
- Audience considerations
- Quality checklist
- Efficient workflow strategies
## Quality Checklist
Before submitting any report, verify:
**Technical Accuracy:**
- [ ] All three hash types included and verified
- [ ] File paths are complete and accurate
- [ ] Timestamps include timezone
- [ ] Process IDs included for process activity
- [ ] Tool versions documented
**Detection Rules:**
- [ ] YARA rules tested against sample (detects correctly)
- [ ] YARA rules tested against clean files (no false positives)
- [ ] Rules include complete metadata
- [ ] Conditions are appropriate and not over-matching
**IOCs:**
- [ ] Grouped by type (file, network, host)
- [ ] Context provided for each IOC
- [ ] All IOCs defanged (hxxp/hxxps, [.] for domains and IPs, [@] for email)
- [ ] No environment-specific artifacts
- [ ] All IOCs validated
**Report Quality:**
- [ ] Executive summary is non-technical and actionable
- [ ] All sections completed
- [ ] Grammar and spelling checked
- [ ] Consistent formatting throughout
- [ ] Evidence supports all claims
- [ ] Remediation steps are specific and prioritized
**Professional Standards:**
- [ ] Report is professional and enterprise-ready
- [ ] Detection rules work and are well-documented
- [ ] Technical details demonstrate thorough analysis
- [ ] Report answers: What is it? What does it do? How to detect? How to remove?
## Output Format
Create reports in Markdown format using the template structure. For professional delivery:
1. Create report in Markdown using the template
2. Convert to PDF for professional appearance (if required)
3. Ensure all sections are complete
4. Include any screenshots as appendix items
5. Verify detection rules are included and tested
## Example Usage
**User request:** "Write the report for the ransomware sample"
**What you do:**
1. Read `analysis_state.md`, the triage report, dynamic summaries, and the Sigma/Suricata files already created.
2. Copy the template to `reports/<sample>_report.md`; fill all 12 sections from evidence, citing sources.
3. Write the YARA rule from runtime strings / ransom-note markers / mutex; run `yara` against the sample and a clean corpus; record the result.
4. Defang the IOC section with `ioc_extract.py`; remove lab artifacts.
5. Write remediation ordered by urgency (isolate → block C2 → remove persistence → recover), and the limitations section.
6. Run the Quality Checklist; ask the user only for analyst name, audience, and any gap you could not close.
7. Print the executive summary and the file path.