<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->
# Implementing Canary File Detection — API Reference

## auditd Rules

```bash
# Watch canary file for write and attribute changes
-w /path/to/canary.docx -p wa -k canary_triggered

# Search audit log for canary events
ausearch -k canary_triggered -ts recent

# Real-time monitoring
tail -f /var/log/audit/audit.log | grep canary_triggered
```

## inotifywait (Linux Real-Time)

```bash
# Monitor directory for changes
inotifywait -m -r -e modify,delete,moved_from /srv/shares/

# Monitor specific files
inotifywait -m -e modify,delete /path/to/canary1 /path/to/canary2

# Format output for SIEM ingestion
inotifywait -m -r --format '{"time":"%T","file":"%w%f","event":"%e"}' \
  --timefmt '%FT%T' /srv/shares/
```

## Sysmon Events (Windows)

| Event ID | Description | Canary Use |
|----------|-------------|-----------|
| 11 | FileCreate | Canary replaced with encrypted version |
| 23 | FileDelete | Canary deleted by ransomware |
| 26 | FileDeleteDetected | Canary deletion with content logged |

## Wazuh FIM Configuration

```xml
<syscheck>
  <directories check_all="yes" realtime="yes" report_changes="yes">
    /srv/shares/finance/!Budget_Report_2026.xlsx
  </directories>
  <directories check_all="yes" realtime="yes" report_changes="yes">
    /srv/shares/hr/#Employee_Directory.docx
  </directories>
</syscheck>
```

## OSSEC FIM

```xml
<syscheck>
  <alert_new_files>yes</alert_new_files>
  <directories realtime="yes" check_sha256sum="yes">
    /srv/shares/finance
  </directories>
</syscheck>
```

## Key Parameters

| Parameter | Description | Example |
|-----------|-------------|---------|
| `target_dirs` | Directories to monitor | `/srv/shares, /data` |
| `canary_count` | Files per directory | `3-5` |
| `alert_threshold` | Max detection time | `60s` |
| `manifest_path` | Deployment manifest | `/etc/canary/manifest.json` |
