\r \r

Canary Agent Safety Tripwire System\r

\r Safety monitoring and tripwire detection for AI agents. Protects against unauthorized file access, dangerous commands, and excessive activity. Auto-halts on critical violations. Honeypot tripwires detect snooping.\r \r ---\r \r Safety monitoring and tripwire detection for AI agents.\r \r Protects against unauthorized file access, dangerous commands, and excessive activity. Auto-halts on critical violations. Honeypot tripwires detect snooping.\r \r ---\r \r

What It Does\r

\r Canary provides three layers of agent safety:\r \r

1. Action Monitoring - Checks file paths and commands before execution\r
2. Tripwire Files - Honeypot files that should never be accessed\r
3. Audit Trail - Complete logs and pattern detection\r \r

Core Features\r

\r Protected Paths:\r

• Block access to sensitive directories (/etc/, ~/.ssh/, etc.)\r
• Customizable protection list\r
• Granular operation control (read, write, delete)\r \r Forbidden Patterns:\r
• Regular expression matching for dangerous commands\r
• Detects rm -rf /, chmod 777, curl | sh, etc.\r
• Extensible pattern library\r \r Rate Limiting:\r
• Limit file operations, network requests, command executions\r
• Configurable windows and thresholds\r
• Prevents runaway agents\r \r Auto-Halt:\r
• Automatically stops agent after violation threshold\r
• Prevents cascading failures\r
• Requires manual review to restart\r \r Tripwire Files:\r
• Create honeypot files that should never be accessed\r
• Detect modifications, deletions, or access\r
• Hash verification for file integrity\r \r Audit Trail:\r
• Complete action logs\r
• Violation history\r
• Pattern detection (rapid violations, repeated targets, time clusters)\r
• Export to JSON or Markdown\r \r ---\r \r

Quick Start\r

\r

Install\r

\r No dependencies! Python 3.7+ stdlib only.\r \r

# Copy config example\r
cp config_example.json config.json\r
\r
# Edit config with your protected paths\r
nano config.json\r
```\r
\r
### Basic Usage\r
\r
```python\r
from canary import CanaryMonitor\r
\r
# Initialize monitor\r
canary = CanaryMonitor('config.json')\r
\r
# Check path before access\r
is_safe, reason = canary.check_path('/etc/passwd', 'read')\r
if not is_safe:\r
    print(f"Blocked: {reason}")\r
    exit(1)\r
\r
# Check command before execution\r
is_safe, reason = canary.check_command('rm -rf /')\r
if not is_safe:\r
    print(f"Blocked: {reason}")\r
    exit(1)\r
\r
# Get status\r
status = canary.get_status()\r
print(f"Violations: {status['violation_count']}/{status['halt_threshold']}")\r
```\r
\r
### CLI Usage\r
\r
```bash\r
# Check status\r
python3 canary.py status\r
\r
# Check if path is safe\r
python3 canary.py check-path --path /etc/passwd --operation read\r
\r
# Check if command is safe\r
python3 canary.py check-command --command "rm -rf /"\r
\r
# Reset monitoring (clears violations)\r
python3 canary.py reset\r
```\r
\r
---\r
\r
## Tripwire Files\r
\r
Create honeypot files that should never be accessed:\r
\r
```bash\r
# Create tripwire\r
python3 canary_tripwire.py create \\r
  --path ~/.secrets/fake-api-key.txt \\r
  --severity critical \\r
  --description "Honeypot to detect credential snooping"\r
\r
# List all tripwires\r
python3 canary_tripwire.py list\r
\r
# Check for triggered tripwires\r
python3 canary_tripwire.py check\r
\r
# View alert history\r
python3 canary_tripwire.py alerts --limit 10\r
\r
# Remove tripwire\r
python3 canary_tripwire.py remove --path ~/.secrets/fake-api-key.txt\r
```\r
\r
### Python API\r
\r
```python\r
from canary_tripwire import TripwireManager\r
\r
manager = TripwireManager()\r
\r
# Create tripwire\r
manager.create_tripwire(\r
    path='~/.aws/fake-credentials',\r
    severity='critical',\r
    description='Detects AWS credential access'\r
)\r
\r
# Check all tripwires\r
triggered = manager.check_tripwires()\r
if triggered:\r
    print(f"⚠️  {len(triggered)} tripwire(s) triggered!")\r
    for alert in triggered:\r
        print(f"  - {alert['path']}: {alert['event']}")\r
```\r
\r
---\r
\r
## Audit Reports\r
\r
Analyze logs and generate safety reports:\r
\r
```bash\r
# Summary report\r
python3 canary_audit.py summary\r
\r
# View violations by severity\r
python3 canary_audit.py violations --severity critical\r
\r
# Timeline of recent events\r
python3 canary_audit.py timeline --hours 24\r
\r
# Detect suspicious patterns\r
python3 canary_audit.py patterns\r
\r
# Export full report\r
python3 canary_audit.py export --output report.json --format json\r
python3 canary_audit.py export --output report.md --format markdown\r
```\r
\r
### Python API\r
\r
```python\r
from canary_audit import CanaryAuditor\r
\r
auditor = CanaryAuditor('canary.log')\r
\r
# Generate summary\r
summary = auditor.generate_summary_report()\r
print(f"Total violations: {summary['total_violations']}")\r
\r
# Get critical violations\r
critical = auditor.get_violations_by_severity('critical')\r
\r
# Detect patterns\r
patterns = auditor.detect_patterns()\r
if patterns['rapid_violations']:\r
    print("⚠️  Rapid violation sequence detected!")\r
\r
# Export report\r
auditor.export_report('safety-report.md', format='markdown')\r
```\r
\r
---\r
\r
## Configuration\r
\r
See `config_example.json` for all options.\r
\r
### Essential Settings\r
\r
```json\r
{\r
  "protected_paths": [\r
    "/etc/",\r
    "~/.ssh/",\r
    "~/critical-data/"\r
  ],\r
  "forbidden_patterns": [\r
    "rm\\s+-rf\\s+/",\r
    "chmod\\s+777",\r
    "curl.*\\|\\s*sh"\r
  ],\r
  "halt_threshold": 5,\r
  "rate_limits": {\r
    "file_operations": {"limit": 100, "window": 60},\r
    "command_executions": {"limit": 20, "window": 60}\r
  }\r
}\r
```\r
\r
---\r
\r
## Integration Examples\r
\r
### With Agent Runtime\r
\r
```python\r
from canary import CanaryMonitor\r
\r
canary = CanaryMonitor('config.json')\r
\r
def safe_file_read(path):\r
    """Read file with Canary check."""\r
    is_safe, reason = canary.check_path(path, 'read')\r
    if not is_safe:\r
        raise PermissionError(reason)\r
    \r
    with open(path, 'r') as f:\r
        return f.read()\r
\r
def safe_command(cmd):\r
    """Execute command with Canary check."""\r
    is_safe, reason = canary.check_command(cmd)\r
    if not is_safe:\r
        raise PermissionError(reason)\r
    \r
    import subprocess\r
    cmd_list = cmd.split() if isinstance(cmd, str) else cmd\r
    return subprocess.run(cmd_list, capture_output=True)\r
```\r
\r
### Pre-Deployment Checks\r
\r
```python\r
# Before deploying agent, verify Canary setup\r
from canary import CanaryMonitor\r
\r
canary = CanaryMonitor('config.json')\r
\r
# Verify protected paths are configured\r
status = canary.get_status()\r
if status['protected_paths_count'] == 0:\r
    print("⚠️  No protected paths configured!")\r
    exit(1)\r
\r
# Test tripwire detection\r
from canary_tripwire import TripwireManager\r
manager = TripwireManager()\r
\r
# Create test tripwire\r
manager.create_tripwire('/tmp/canary-test.txt', severity='high')\r
\r
# Verify it exists\r
triggered = manager.check_tripwires()\r
if not any(t['path'] == '/tmp/canary-test.txt' for t in triggered):\r
    print("✅ Tripwire system operational")\r
\r
# Cleanup\r
manager.remove_tripwire('/tmp/canary-test.txt', delete_file=True)\r
```\r
\r
---\r
\r
## Use Cases\r
\r
### 1. Autonomous Agent Safety\r
\r
Deploy Canary alongside autonomous agents to prevent:\r
- Accidental system file deletion\r
- Credential exfiltration\r
- Runaway command execution\r
\r
### 2. Multi-Agent Systems\r
\r
Each agent gets its own Canary instance with custom rules:\r
- Research agent: limited network access\r
- Coding agent: no production deployments\r
- Admin agent: full access but strict audit\r
\r
### 3. Development/Testing\r
\r
Use Canary during agent development:\r
- Catch dangerous patterns early\r
- Test rate limiting behavior\r
- Verify safety mechanisms work\r
\r
### 4. Production Monitoring\r
\r
Run Canary in production:\r
- Real-time violation alerts\r
- Audit trail for compliance\r
- Pattern detection for anomalies\r
\r
---\r
\r
## Architecture\r
\r
```\r
┌─────────────────┐\r
│   Your Agent    │\r
└────────┬────────┘\r
         │\r
         ▼\r
┌─────────────────┐      ┌──────────────────┐\r
│ CanaryMonitor   │◄────►│  config.py       │\r
│ (canary.py)     │      │  (your rules)    │\r
└────────┬────────┘      └──────────────────┘\r
         │\r
         ├─────► canary.log (action log)\r
         │\r
         ▼\r
┌─────────────────┐      ┌──────────────────┐\r
│ TripwireManager │◄────►│ .canary_tripwires│\r
│ (tripwire.py)   │      │ (honeypot files) │\r
└────────┬────────┘      └──────────────────┘\r
         │\r
         └─────► alerts.log\r
         \r
         \r
┌─────────────────┐\r
│ CanaryAuditor   │───► reports (JSON/MD)\r
│ (audit.py)      │\r
└─────────────────┘\r
```\r
\r
---\r
\r
## Best Practices\r
\r
### Start Conservative\r
\r
Begin with strict rules, relax as needed:\r
\r
```python\r
protected_paths = [\r
    '/',  # Protect entire filesystem initially\r
]\r
\r
halt_threshold = 3  # Low threshold to catch issues early\r
```\r
\r
### Use Tripwires Strategically\r
\r
Place tripwires in sensitive locations:\r
- Fake credential files\r
- Empty "secrets" directories\r
- Decoy config files\r
\r
### Review Logs Regularly\r
\r
```bash\r
# Daily audit\r
python3 canary_audit.py summary\r
\r
# Weekly deep dive\r
python3 canary_audit.py patterns\r
python3 canary_audit.py export --output weekly-report.md --format markdown\r
```\r
\r
### Test Your Configuration\r
\r
```python\r
# Verify Canary blocks what it should\r
canary = CanaryMonitor('config.json')\r
\r
# These should all be blocked\r
assert not canary.check_path('/etc/passwd', 'delete')[0]\r
assert not canary.check_command('rm -rf /')[0]\r
assert not canary.check_command('chmod 777 /tmp')[0]\r
\r
print("✅ Canary configuration verified")\r
```\r
\r
---\r
\r
## Limitations\r
\r
See [LIMITATIONS.md](LIMITATIONS.md) for details.\r
\r
**Key constraints:**\r
- Pattern matching is regex-based (not semantic analysis)\r
- No built-in alerting (logs only)\r
- Tripwires detect access, not intent\r
- Rate limiting is per-session (doesn't survive restarts)\r
\r
---\r
\r
## License\r
\r
MIT License - See [LICENSE](LICENSE)\r
\r
**Author:** Shadow Rose\r
\r
---\r
\r
## Why This Exists\r
\r
AI agents can do a lot of damage quickly:\r
- One bad command can delete critical files\r
- Runaway loops can exhaust resources\r
- Compromised agents can exfiltrate credentials\r
\r
Canary provides defense-in-depth:\r
- **Preventive:** Block dangerous actions before they happen\r
- **Detective:** Tripwires catch snooping behavior\r
- **Forensic:** Complete audit trail for post-incident analysis\r
\r
Simple, zero-dependency safety for autonomous agents.\r
\r
\r
---\r
\r
\r
## ⚠️ Security Note — Config File\r
\r
Configuration is loaded from a JSON file. This is safe to share — no code execution.\r
\r
- Config path is validated for existence and size (1MB cap) before loading\r
- Must be a `.json` file — `CanaryMonitor` raises `ValueError` if given a non-JSON path\r
- Keep your config under version control; treat it as security policy\r
\r
## ⚠️ Security Note — Tripwire Deployment\r
\r
- **Paths are fully resolved** — `~` and relative paths are expanded via `Path.expanduser().resolve()` before creation and lookup. `'~/.aws/fake-credentials'` will be placed in your actual home directory, not a literal `~` path.\r
- **Use decoy paths only** — never point tripwires at real files containing sensitive data. Tripwires are honeypots; treat them as bait, not protection.\r
- **`create_tripwire` will not overwrite existing files** — it checks for pre-existing files and refuses to proceed. Use dedicated empty paths for tripwires.\r
- **Test in a sandbox first** — verify where logs, tripwires, and registry files are created before deploying. Confirm protected paths and auto-halt behavior in an isolated environment.\r
- **Protect log and alert directories** — set filesystem permissions so alert logs are not world-readable. Canary writes plaintext logs; restrict access accordingly.\r
- **Canary only blocks when called** — it is not an OS-level enforcement mechanism. Layer it with containers, filesystem permissions, and `auditd` for production deployments.\r
\r
## ⚠️ Disclaimer\r
\r
This software is provided "AS IS", without warranty of any kind, express or implied.\r
\r
**USE AT YOUR OWN RISK.**\r
\r
- The author(s) are NOT liable for any damages, losses, or consequences arising from \r
  the use or misuse of this software — including but not limited to financial loss, \r
  data loss, security breaches, business interruption, or any indirect/consequential damages.\r
- This software does NOT constitute financial, legal, trading, or professional advice.\r
- Users are solely responsible for evaluating whether this software is suitable for \r
  their use case, environment, and risk tolerance.\r
- No guarantee is made regarding accuracy, reliability, completeness, or fitness \r
  for any particular purpose.\r
- The author(s) are not responsible for how third parties use, modify, or distribute \r
  this software after purchase.\r
\r
By downloading, installing, or using this software, you acknowledge that you have read \r
this disclaimer and agree to use the software entirely at your own risk.\r
\r
\r
**SECURITY DISCLAIMER:** This software provides supplementary security measures and \r
is NOT a replacement for professional security auditing, penetration testing, or \r
compliance frameworks. No software can guarantee complete protection against all \r
threats. Users operating in regulated industries (healthcare, finance, legal) should \r
consult qualified security professionals and verify compliance with applicable \r
regulations (GDPR, HIPAA, SOC2, etc.) independently.\r
---\r
\r
## Support & Links\r
\r
| | |\r
|---|---|\r
| 🐛 **Bug Reports** | [email protected] |\r
| ☕ **Ko-fi** | [ko-fi.com/theshadowrose](https://ko-fi.com/theshadowrose) |\r
| 🛒 **Gumroad** | [shadowyrose.gumroad.com](https://shadowyrose.gumroad.com) |\r
| 🐦 **Twitter** | [@TheShadowyRose](https://twitter.com/TheShadowyRose) |\r
| 🐙 **GitHub** | [github.com/TheShadowRose](https://github.com/TheShadowRose) |\r
| 🧠 **PromptBase** | [promptbase.com/profile/shadowrose](https://promptbase.com/profile/shadowrose) |\r
\r
*Built with [OpenClaw](https://github.com/openclaw/openclaw) — thank you for making this possible.*\r
\r
---\r
\r
🛠️ **Need something custom?** Custom OpenClaw agents & skills starting at $500. If you can describe it, I can build it. → [Hire me on Fiverr](https://www.fiverr.com/s/jjmlZ0v)\r
\r
> **📦 Install note:** The slug `canary` was already taken on ClawHub.\r
> Install this skill using: `clawhub install canary-sr`\r