seikaikyo/deploying-decoy-files-for-ransomware-detection

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
• Validate that automated response actions (process kill, network isolation) execute correctly
• Check that canary files survive normal backup and restore operations
• Ensure legitimate users and processes are excluded from false-positive alerts (backup agents, AV scans)

Key Concepts

| Term | Definition | |------|------------| | Canary File | A decoy file placed in a directory that is monitored for any access or modification, serving as a tripwire for unauthorized activity | | Honeytoken | A broader category of deception artifacts (files, credentials, database records) designed to alert when accessed | | File Integrity Monitoring | Continuous monitoring of file attributes (hash, size, permissions, timestamps) to detect unauthorized changes | | ReadDirectoryChangesW | Windows API for monitoring file system changes in a directory; used by the watchdog library on Windows | | inotify | Linux kernel subsystem for monitoring file system events; provides near-instant notification of file changes |

Tools & Systems

• watchdog (Python): Cross-platform file system event monitoring library supporting Windows, Linux, and macOS
• Canarytokens (Thinkst): Free hosted service for generating various types of canary tokens including files, URLs, and DNS tokens
• OSSEC/Wazuh: Open-source HIDS with built-in file integrity monitoring and alerting capabilities
• Elastic Endpoint: Uses canary files internally for ransomware protection and key capture
• Sysmon: Windows system monitor that logs file creation events (Event ID 11) for canary file monitoring