Level A: Canary Tokens¶

Canary tokens are URLs embedded in knowledge packs that look like legitimate security research references. Each URL contains a UUID subdomain that identifies the installation. When someone follows the link, a callback reveals the stolen copy.

How It Works¶

1. During provisioning, provision-canaries.py generates a UUID per installation
2. 2-3 canary URLs are injected into each of the 32 knowledge pack files
3. URLs appear in "Further Reading" sections as realistic research references
4. A canary server on *.sec-research.bedefended.com logs all callbacks

URL Format¶

https://{topic}.{uuid}.sec-research.bedefended.com/{path}

Example in knowledge-sqli.md:

## Further Reading
- WAF bypass patterns database: https://waf-bypass-db.a1b2c3d4.sec-research.bedefended.com/cloudflare-v2
- SQLi cheatsheet collection: https://sqli-cheatsheets.a1b2c3d4.sec-research.bedefended.com/2025-update

Infrastructure¶

• DNS: Wildcard *.sec-research.bedefended.com pointing to canary server
• Server: scripts/canary-server.py -- lightweight HTTP server
• Response: Generic 404 page (does not reveal canary nature)
• Logging: logs/canary-server.jsonl with full request metadata

Alert Flow¶

sequenceDiagram
    participant Thief as Thief/AI
    participant Canary as Canary Server
    participant Email as app@bedefended.com

    Thief->>Canary: GET /cloudflare-v2
    Note over Canary: Extract UUID from subdomain
    Note over Canary: Check whitelist
    Canary->>Email: Alert email with UUID, IP, UA
    Canary->>Thief: 404 Not Found

False Positive Analysis¶

• Knowledge packs are never exposed to clients (server-side only)
• BeDefended pentesters have known UUIDs (whitelisted)
• Any unknown UUID = confirmed IP theft
• Rate: effectively 0%

Provisioning¶

# Auto-generate UUID
python scripts/provision-canaries.py

# Specific UUID
python scripts/provision-canaries.py --installation-id a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Preview without modifying files
python scripts/provision-canaries.py --dry-run

Files¶