Deploying Decoy Files for Ransomware Detection Skill

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

Agent Skills: Deploying Decoy Files for Ransomware Detection

Install this agent skill to your local

Skill Files