237 lines
11 KiB
Markdown
237 lines
11 KiB
Markdown
---
|
|
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.
|