<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: implementing-ransomware-incident-documentation
description: >-
  Create comprehensive incident documentation during ransomware events for
  legal proceedings, insurance claims, regulatory compliance, and post-incident
  improvement. Covers evidence chain of custody, timeline reconstruction,
  forensic report templates, executive briefing formats, and lessons learned.
domain: cybersecurity
subdomain: ransomware-defense
tags:
  - incident-documentation
  - chain-of-custody
  - timeline-reconstruction
  - forensic-reports
  - evidence-preservation
  - lessons-learned
  - legal-documentation
  - after-action-report
version: '1.0'
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: []
---

# Implementing Ransomware Incident Documentation

## Overview

Incident documentation serves four critical audiences: legal proceedings
(evidence admissibility), insurance claims (loss quantification),
regulatory compliance (notification records), and organizational learning
(post-incident improvement). Poor documentation during a ransomware
incident can invalidate insurance claims, weaken legal standing, and
guarantee the same attack succeeds again.

Document as you go — reconstructing events after the fact is unreliable.

## Prerequisites

| Tool | Purpose | Install |
|------|---------|---------|
| jq | JSON processing | `apt install jq` |
| pandoc | Report generation | `apt install pandoc` |
| sha256sum | Evidence integrity | Built-in |
| git | Version-controlled documentation | `apt install git` |
| exiftool | Metadata extraction | `apt install libimage-exiftool-perl` |

## Key Concepts

### Documentation Requirements by Audience

| Audience | Format | Content Focus |
|----------|--------|--------------|
| Legal/Forensic | Chain of custody forms, hash logs | Evidence integrity |
| Insurance | Incident report, loss statement | Financial impact |
| Regulators | Breach notification, DPIA | Data exposure |
| Internal | After-action report, lessons learned | Root cause |
| Executive | Briefing deck, timeline summary | Business impact |

### Evidence Chain of Custody

```
1. COLLECT  — Hash evidence immediately upon collection
2. DOCUMENT — Record who collected, when, where, how
3. STORE    — Tamper-evident storage with access controls
4. TRANSFER — Document every custody change
5. PRESENT  — Prove integrity via hash chain verification
```

## Workflow

### Step 1 — Initialize Incident Documentation Repository

```bash
INCIDENT_ID="INC-$(date +%Y-%m%d-%H%M)"
DOC_ROOT="/evidence/${INCIDENT_ID}/documentation"

mkdir -p "${DOC_ROOT}"/{timeline,evidence,chain-of-custody,reports,communications}

cd "${DOC_ROOT}"
git init
git config user.name "IR Team"
git config user.email "ir-team@company.com"

cat > "${DOC_ROOT}/incident_metadata.json" << EOF
{
  "incident_id": "${INCIDENT_ID}",
  "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "classification": "ransomware",
  "severity": "critical",
  "status": "active"
}
EOF

git add -A && git commit -m "Initialize incident documentation"
```

### Step 2 — Evidence Collection with Chain of Custody

```bash
catalog_evidence() {
  local file="$1"
  local collector="$2"
  local description="$3"
  local hash
  hash=$(sha256sum "$file" | awk '{print $1}')
  local size
  size=$(stat --format=%s "$file" 2>/dev/null || stat -f%z "$file" 2>/dev/null)

  cat >> "${DOC_ROOT}/chain-of-custody/evidence_log.jsonl" << EOF
{"timestamp":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","file":"$(basename "$file")","sha256":"${hash}","size_bytes":${size:-0},"collector":"${collector}","description":"${description}"}
EOF

  echo "[+] Evidence cataloged: $(basename "$file") — SHA256: ${hash:0:16}..."
}
```

### Step 3 — Timeline Reconstruction

```bash
add_timeline_entry() {
  local timestamp="$1"
  local source="$2"
  local event="$3"
  local mitre="$4"

  cat >> "${DOC_ROOT}/timeline/events.jsonl" << EOF
{"timestamp":"${timestamp}","source":"${source}","event":"${event}","mitre_id":"${mitre}"}
EOF
}

# Build timeline from log sources
grep -iE "failed|accepted|session" /var/log/auth.log 2>/dev/null | tail -100 > \
  "${DOC_ROOT}/timeline/auth_events.log"

journalctl --since "24 hours ago" --no-pager 2>/dev/null | \
  grep -iE "stopped|started|failed|error" | tail -100 > \
  "${DOC_ROOT}/timeline/system_events.log"
```

### Step 4 — Generate Incident Report Template

```markdown
# Ransomware Incident Report

## Executive Summary
[One paragraph: what happened, impact, current status]

## Incident Timeline
| Timestamp (UTC) | Event | Source | MITRE ID |
|-----------------|-------|--------|----------|

## Systems Affected
| Hostname | Role | Impact | Recovery Status |
|----------|------|--------|----------------|

## Data Impact Assessment
- Data types affected: [PII/PHI/PCI/financial/IP]
- Estimated records: [count]
- Exfiltration evidence: [yes/no]

## Root Cause Analysis
[Specific technical failures that allowed the attack]

## Remediation Actions
| Action | Owner | Status | Deadline |
|--------|-------|--------|----------|

## Lessons Learned
1. [Detection gap and remediation]
2. [Process improvement and owner]
```

## Verification

- [ ] Incident documentation repository initialized with git tracking
- [ ] All evidence hashed and chain of custody documented
- [ ] Timeline reconstructed with corroborating sources
- [ ] Executive briefing produced within 4 hours of declaration
- [ ] Regulatory notification documentation prepared per requirements
- [ ] After-action report completed within 14 days of incident close

## References

- NIST SP 800-86: Guide to Integrating Forensic Techniques
- SANS Incident Response Documentation Guidelines
- ISO 27035: Information Security Incident Management
- CISA Ransomware Guide: Documentation Requirements
