---
name: malware-report-writing
description: >
  Generate structured malware analysis reports from investigation findings.
  Produces professional reports with executive summary, detailed technical findings,
  indicators of compromise (IOCs), MITRE ATT&CK mapping, detection signatures,
  and remediation recommendations. Supports Markdown, HTML, and JSON output formats.
  Use after completing analysis stages to compile and communicate results to
  stakeholders including SOC analysts, incident responders, and management.
---

# Malware Report Writing

Compile analysis findings into structured, actionable reports suitable for
technical and non-technical audiences. Reports include executive summaries,
detailed findings, IOCs, ATT&CK mappings, detection rules, and remediation steps.

## Prerequisites

- **Python 3.8+**: `json`, `datetime`, `pathlib` (standard library)
- **Python packages (optional)**: `jinja2` (for HTML reports), `markdown` (for HTML conversion)
- **Input**: Analysis results in JSON format from prior analysis stages
- **Templates**: Report templates in `assets/` directory

## Step-by-Step Instructions

### Step 1: Gather Analysis Artifacts

Collect all outputs from prior analysis stages into a single directory or JSON file.

**Required inputs:**
- Sample metadata (hashes, file type, size)
- Static analysis findings (strings, imports, sections)
- Dynamic/behavioral analysis results (API calls, network activity, file operations)
- IOCs extracted (IPs, domains, URLs, file hashes, mutexes, registry keys)
- MITRE ATT&CK technique mappings

**Optional inputs:**
- Sandbox reports (CAPE, Any.Run, Hybrid Analysis)
- YARA rule matches
- Memory forensics findings
- Network traffic captures
- Code similarity results

**Prepare input JSON:**
```json
{
  "sample": {
    "file_name": "sample.exe",
    "sha256": "abc123...",
    "file_type": "PE32 executable",
    "file_size": 245760
  },
  "findings": [],
  "iocs": {},
  "mitre_attack": [],
  "detection_rules": [],
  "remediation": []
}
```

### Step 2: Generate the Report

Use the report generator script to compile findings into a formatted report.

**Generate Markdown report:**
```bash
python3 scripts/report_generator.py \
  --input analysis_results.json \
  --output report.md \
  --format markdown \
  --classification TLP:AMBER
```

**Generate HTML report:**
```bash
python3 scripts/report_generator.py \
  --input analysis_results.json \
  --output report.html \
  --format html \
  --classification TLP:AMBER
```

**Generate JSON report (machine-readable):**
```bash
python3 scripts/report_generator.py \
  --input analysis_results.json \
  --output report.json \
  --format json
```

**Generate executive summary only:**
```bash
python3 scripts/report_generator.py \
  --input analysis_results.json \
  --output exec_summary.md \
  --format markdown \
  --executive-summary-only
```

### Step 3: Review the Executive Summary

The executive summary should answer these questions for non-technical stakeholders:

1. **What was found?** - Malware family, type, and severity
2. **What does it do?** - High-level behavior description
3. **What is the impact?** - Business risk and affected systems
4. **What should we do?** - Immediate actions required

See `assets/executive-summary-template.md` for the template.

### Step 4: Document Technical Findings

For each finding, document:

- **Observation**: What was observed (factual)
- **Analysis**: What it means (interpretation)
- **Evidence**: Supporting data (hashes, strings, screenshots)
- **ATT&CK mapping**: Relevant MITRE technique IDs

Order findings by severity (Critical > High > Medium > Low > Informational).

### Step 5: Compile IOC Table

Organize IOCs by type for easy ingestion into security tools:

| Type | Value | Context | Confidence |
|------|-------|---------|------------|
| SHA256 | abc123... | Main payload | High |
| Domain | evil.example.com | C2 server | High |
| IP | 1.2.3.4 | C2 infrastructure | Medium |
| URL | http://evil.example.com/gate.php | C2 callback | High |
| Mutex | Global\MalwareMutex | Execution marker | High |
| Registry | HKCU\Software\Run\Persist | Persistence key | High |

### Step 6: Map MITRE ATT&CK Techniques

Document observed techniques with evidence:

```
T1566.001 - Phishing: Spearphishing Attachment
  Evidence: Malicious DOCX delivered via email

T1059.001 - Command and Scripting Interpreter: PowerShell
  Evidence: Encoded PowerShell command in macro

T1053.005 - Scheduled Task/Job: Scheduled Task
  Evidence: Scheduled task "UpdateCheck" created for persistence
```

### Step 7: Write Detection Rules

Include actionable detection signatures:

- **YARA rules**: For file-based detection
- **Snort/Suricata rules**: For network detection
- **Sigma rules**: For log-based detection
- **Custom IOC lists**: For SIEM/EDR ingestion

### Step 8: Provide Remediation Steps

Outline remediation in priority order:

1. **Immediate containment**: Isolate affected systems, block IOCs
2. **Eradication**: Remove malware artifacts, clean persistence
3. **Recovery**: Restore from backups, rebuild if necessary
4. **Prevention**: Patch vulnerabilities, update detection rules

### Step 9: Quality Review

Before finalizing, verify:

- [ ] All hashes are correct and consistently formatted
- [ ] IOCs are deduplicated and validated
- [ ] ATT&CK mappings are accurate
- [ ] No sensitive internal data is leaked in the report
- [ ] Classification markings are correct (TLP level)
- [ ] Recommendations are actionable and specific

See `references/writing-guidelines.md` for comprehensive style guidance.

## Output Format

The report generator produces structured output per the following schema:

```json
{
  "report_metadata": {
    "title": "Malware Analysis Report",
    "report_id": "MAR-2025-0042",
    "date": "2025-01-15",
    "classification": "TLP:AMBER",
    "analyst": "Analyst Name"
  },
  "executive_summary": "...",
  "sample_info": {},
  "findings": [],
  "iocs": {},
  "mitre_attack": [],
  "detection_rules": [],
  "remediation": [],
  "appendices": []
}
```

## Tips

- Write for your audience: executive summaries for management, technical details for analysts
- Use consistent terminology throughout the report
- Include confidence levels for attribution and IOC assessments
- Reference the full report template in `assets/report-template.md`
- Always apply appropriate TLP classification markings
- Keep findings factual; separate observations from interpretations
- Include timestamps in UTC for all time-based observations
- Attach raw data (PCAPs, memory dumps) as appendices when possible