Anthropic-Cybersecurity-Skills/skills/deploying-ransomware-canary-files/references/api-reference.md

API Reference: Deploying Ransomware Canary Files

Canary File Deployment

Function	Parameters	Returns
deploy_canary_files(target_dirs, custom_files)	List of directories, optional custom file dict	Manifest with deployed file paths and hashes
compute_sha256(filepath)	File path string	SHA-256 hex digest
compute_entropy(filepath)	File path string	Shannon entropy float (0-8)

Monitoring Functions

Function	Parameters	Returns
start_monitoring(manifest_path, config)	Path to manifest JSON, alert config dict	Blocks until interrupted
verify_canary_integrity(manifest_path)	Path to manifest JSON	Dict with intact/modified/missing counts
simulate_ransomware_test(manifest_path)	Path to manifest JSON	List of test results

CanaryFileHandler Events

Event	Handler Method	Trigger
File modified	on_modified(event)	Content change detected
File deleted	on_deleted(event)	Canary file removed
File renamed	on_moved(event)	Canary file renamed or moved
New file created	on_created(event)	Ransom note detection in monitored dirs

Alert Channels

Channel	Function	Required Config
Slack	send_slack_alert(data, webhook_url)	slack_webhook URL
Email	send_email_alert(data, host, port, sender, recipients)	SMTP server details
Syslog	send_syslog_alert(data, server, port)	Syslog server address
File	Automatic	Writes to canary_alerts.jsonl

Ransomware Extension Detection

Extensions Monitored
.encrypted, .locked, .lockbit, .crypt, .enc
.ransom, .pay, .aes, .rsa, .cry
.ryk, .revil, .conti, .hive, .black, .basta

CLI Usage

# Deploy canary files
python agent.py --action deploy --dirs /srv/shares /home/admin/Documents

# Monitor canary files with Slack alerts
python agent.py --action monitor --slack-webhook https://hooks.slack.com/...

# Verify canary file integrity
python agent.py --action verify

# Test detection pipeline
python agent.py --action test

Python Libraries

Library	Version	Purpose
watchdog	>=3.0	Filesystem event monitoring
requests	>=2.28	Slack webhook integration
psutil	>=5.9	Process information gathering
hashlib	stdlib	SHA-256 file hashing
smtplib	stdlib	SMTP email alerts

References

• Elastic Security Labs: Ransomware Canary Files: https://www.elastic.co/security-labs/ransomware-in-the-honeypot-how-we-capture-keys
• Huntress Ransomware Canaries: https://support.huntress.io/hc/en-us/articles/4404005167763
• Python Watchdog Documentation: https://python-watchdog.readthedocs.io/
• CISA #StopRansomware Guide: https://www.cisa.gov/stopransomware/ransomware-guide