Deploys canary files (honeytokens) across file systems to detect ransomware encryption activity in real time. Uses strategically placed decoy documents monitored via file integrity monitoring or OS-level watchdogs to trigger alerts when ransomware modifies or encrypts them. Activates for requests involving ransomware canary deployment, honeyfile setup, deception-based ransomware detection, or file integrity monitoring for encryption.
Deploys canary files (honeytokens) across file systems to detect ransomware encryption activity in real time. Uses strategically placed decoy documents monitored via file integrity monitoring or OS-level watchdogs to trigger alerts when ransomware modifies or encrypts them. Activates for requests involving ransomware canary deployment, honeyfile setup, deception-based ransomware detection, or file integrity monitoring for encryption.
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.
Common Misconfigurations & Verification
Canaries placed where ransomware reaches them last: if a decoy sorts in the middle of a directory, encryption may trip your backups before it touches the canary. Place files that sort BOTH first and last (_AAAA_*.docx and ~zzzz_*.xlsx) in every monitored directory so you catch A-Z and Z-A enumerators early.
Canaries only in a few "high-value" shares: ransomware often hits the first writable share it finds. Seed the root of every share, every endpoint Desktop/Documents, and backup staging dirs, not just Finance/HR/Legal.
Watcher misses rename-to-new-extension: many ransomware families encrypt by writing file.locked and deleting the original, which fires on_moved/on_deleted, not on_modified. Confirm the handler watches all four event types, not just modification.
Backup agents and AV cause false positives: if those processes touch decoys you will desensitize the SOC. Exclude known-good PIDs/paths and confirm canaries survive a backup+restore cycle unmodified.
Verification: trigger each canary for real — echo ENCRYPTED > _AAAA_budget.docx and mv report.xlsx report.xlsx.locked — and confirm an alert reaches the SOC in under 30 seconds and any automated process-kill/NIC-disable action actually executes.
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
defcreate_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)
defcreate_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"withopen(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
classCanaryHandler(FileSystemEventHandler):
def__init__(self, canary_paths, alert_callback):
self.canary_paths = set(canary_paths)
self.alert_callback = alert_callback
defon_modified(self, event):
if event.src_path inself.canary_paths:
self.alert_callback("MODIFIED", event.src_path)
defon_deleted(self, event):
if event.src_path inself.canary_paths:
self.alert_callback("DELETED", event.src_path)
defon_moved(self, event):
if event.src_path inself.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
