Deploys canary files (honeytokens) across file systems to detect ransomware
SKILL.md
Deploying Decoy Files for Ransomware Detection
When to Use
Setting up early-warning detection for ransomware on file servers or endpoints
Supplementing EDR/AV with a deception-based detection layer that catches unknown ransomware variants
Creating high-fidelity ransomware alerts that have very low false-positive rates (legitimate users have no reason to touch decoy files)
Testing ransomware response procedures by validating that canary file modifications trigger the expected alerting pipeline
Protecting high-value file shares (finance, HR, legal) with tripwire files that indicate unauthorized encryption activity
Do not use decoy files as the sole ransomware defense. They are a detection mechanism, not a prevention mechanism, and should complement backups, EDR, and access controls.
Prerequisites
Python 3.8+ with watchdog library for cross-platform file system monitoring
Administrative access to target file shares or endpoints for canary placement
File integrity monitoring (FIM) tool or SIEM integration for alert routing
Understanding of target directory structure to place canaries in high-value locations
Windows: NTFS change journal or ReadDirectoryChangesW API access
Linux: inotify support in kernel (standard in modern kernels)
Workflow
Step 1: Design Canary File Strategy
Plan file placement for maximum detection coverage:
Canary File Placement Strategy:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Naming Convention:
- Use names that sort FIRST and LAST alphabetically in each directory
- Ransomware typically enumerates directories A-Z or Z-A
- Examples: _AAAA_budget_2024.docx, ~zzzz_report_final.xlsx
Placement Locations:
- Root of every file share (\\server\share\_AAAA_canary.docx)
- Desktop, Documents, Downloads on each endpoint
- Department-specific shares (Finance, HR, Legal)
- Backup staging directories
- Home directories of high-privilege accounts
File Types:
- .docx, .xlsx, .pdf (most targeted by ransomware)
- .sql, .bak (database files, high value)
- Mix of file types to detect ransomware that targets specific extensions
Step 2: Generate Realistic Canary Files
Create decoy files with realistic content and metadata:
import os
import time
def create_canary_docx(filepath, content="Q4 Financial Summary - Confidential"):
"""Create a realistic .docx canary file using python-docx."""
from docx import Document
doc = Document()
doc.add_heading("Financial Report - CONFIDENTIAL", level=1)
doc.add_paragraph(content)
doc.add_paragraph(f"Generated: {time.strftime('%Y-%m-%d')}")
doc.save(filepath)
def create_canary_txt(filepath):
"""Create a simple text canary with known content for hash verification."""
content = "CANARY_TOKEN_DO_NOT_MODIFY\n"
content += f"Created: {time.strftime('%Y-%m-%dT%H:%M:%S')}\n"
content += "This file is monitored for unauthorized changes.\n"
with open(filepath, "w") as f:
f.write(content)
Step 3: Deploy File System Watcher
Monitor canary files for any modification, rename, or deletion:
from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler
class CanaryHandler(FileSystemEventHandler):
def __init__(self, canary_paths, alert_callback):
self.canary_paths = set(canary_paths)
self.alert_callback = alert_callback
def on_modified(self, event):
if event.src_path in self.canary_paths:
self.alert_callback("MODIFIED", event.src_path)
def on_deleted(self, event):
if event.src_path in self.canary_paths:
self.alert_callback("DELETED", event.src_path)
def on_moved(self, event):
if event.src_path in self.canary_paths:
self.alert_callback("RENAMED", event.src_path)
Step 4: Configure Alerting and Response
Define automated responses when canary files are triggered:
Alert Response Matrix:
━━━━━━━━━━━━━━━━━━━━━
Event: Canary MODIFIED
→ Severity: CRITICAL
→ Action: Alert SOC, identify modifying process (PID), isolate endpoint
Event: Canary DELETED
→ Severity: HIGH
→ Action: Alert SOC, check for ransomware note in same directory
Event: Canary RENAMED (new extension added)
→ Severity: CRITICAL
→ Action: Alert SOC, check extension against known ransomware extensions
→ Automated: Kill modifying process, disable network interface
Event: Multiple canaries triggered within 60 seconds
→ Severity: EMERGENCY
→ Action: Network-wide isolation, activate incident response plan
Step 5: Validate Detection Coverage
Test that canary files detect actual ransomware behavior:
# Simulate ransomware encryption (safe test - modifies canary content)
echo "ENCRYPTED_BY_TEST" > /path/to/canary/_AAAA_budget.docx
# Simulate ransomware rename (adds extension)
mv /path/to/canary/report.xlsx /path/to/canary/report.xlsx.locked
# Verify alerts were generated in SIEM/alerting system
Verification
Confirm all canary files are present and unmodified using stored hash baselines
Verify that modifying any canary file generates an alert within the expected timeframe (under 30 seconds)
Test that alert routing to SOC/SIEM is functional with a controlled modification
