Back to papers

Building a Deception Layer with Canary Tokens

· TomeSpell Security · 4 min read

Traditional security focuses on keeping attackers out. Deception flips this model — it assumes breach and plants tripwires that detect intruders the moment they interact with something they shouldn’t.

Canary tokens are one of the simplest and most effective deception tools. They’re files, credentials, or URLs that appear valuable to an attacker but serve only one purpose: alerting you when they’re accessed.

Why canary tokens work

Unlike vulnerability scanning or intrusion detection, canary tokens have a unique property: near-zero false positive rate. A legitimate user has no reason to open a file called aws-credentials-backup in a honeypot directory. If that file is accessed, something is wrong.

This makes canary tokens ideal for:

  • Early breach detection — know about unauthorized access in minutes, not months
  • Insider threat visibility — detect employees accessing files outside their scope
  • Supply chain monitoring — plant tokens in code repositories or build artifacts

Token types and where to deploy them

Document tokens

PDF and Office documents that phone home when opened. Place them where attackers look during post-exploitation:

# Place canary documents in high-value locations
cp Q3-Financial-Report.pdf /mnt/shared/finance/
cp incident-response-plan.docx /mnt/shared/it-security/
cp employee-salaries-2026.xlsx /mnt/shared/hr/confidential/

The documents look real. When an attacker (or curious insider) opens one, the embedded trigger fires with their IP, user agent, and timestamp.

Credential tokens

Fake credentials planted where attackers harvest them:

# Create a fake AWS credentials file on a production host
mkdir -p /home/deploy/.aws
cat > /home/deploy/.aws/credentials << 'EOF'
[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
region = us-east-1
EOF
chmod 600 /home/deploy/.aws/credentials

When these credentials are used against any API, the canary fires. The attacker reveals their infrastructure while getting nothing of value.

Binary tokens

Native executables that trigger on execution. Disguise them as tools that an attacker would reach for:

# Place canary binaries in common tool paths
cp canary-kubectl-debug /usr/local/bin/kubectl-debug
cp canary-db-backup /opt/scripts/db-backup
chmod +x /usr/local/bin/kubectl-debug /opt/scripts/db-backup

Common disguises for different environments:

EnvironmentFilenameLocation
Kuberneteskubectl-debug/usr/local/bin/
Database serversdb-backup/opt/scripts/
Bastion hostsvpn-connect/usr/local/bin/
CI runnersdeploy-prod/opt/ci/

What a trigger looks like

When a canary token fires, you receive a structured event with full context:

{
  "token": "ct_a3f2e8b1c4d59670",
  "canary_name": "Q3-Financial-Report.pdf",
  "type": "pdf",
  "triggered_at": "2026-03-25T14:32:01Z",
  "source_ip": "185.62.190.44",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
  "geolocation": {
    "country": "RU",
    "city": "Moscow"
  }
}

This single event tells you: someone at 185.62.190.44 in Moscow opened your fake financial report using a Windows machine. That’s a high-confidence indicator of compromise — no tuning required.

Integrating alerts

Route canary triggers to your incident response channels:

# Example alert routing configuration
alerts:
  canary_trigger:
    severity: high
    channels:
      - slack: "#security-incidents"
      - email: "[email protected]"
    runbook: "https://wiki.internal/runbooks/canary-triggered"
    auto_actions:
      - isolate_source_ip
      - capture_forensics

Deployment best practices

Name tokens realistically. test-canary.pdf won’t fool anyone. Use names that match what an attacker expects to find: salary-review-2026.xlsx, prod-database-backup.sh, vpn-config.ovpn.

Place tokens where attackers look. Home directories, credential stores, shared drives, source code repositories, backup locations, and CI/CD configuration.

Layer your tokens. Use multiple types across multiple locations. A single canary is a tripwire. A dozen canaries is a detection grid that’s nearly impossible to avoid.

Treat every trigger as real. Canary tokens have near-zero false positives. A trigger means unauthorized access occurred. Have a runbook ready and act on it.

Canary tokens cost almost nothing to deploy and maintain. They generate no false positives. And they catch the one thing that every other security tool misses: the attacker who’s already inside your network, looking around.

Start with three canaries in your highest-value locations. Scale from there.

← Back to papers