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

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:

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.