Posted inSecurity

How to Use Canarytokens for Early Intrusion Detection: Setting Traps in Files, URLs, and Emails

Security tutorial - IT technology blog
Security tutorial - IT technology blog

Only After an Audit Do You Realize: Nobody Knew They Were Being Watched

After auditing security on more than 10 servers over the past year, I kept seeing the same familiar vulnerabilities — SSH exposed on port 22, default credentials still in place, messy file permissions. But what worried me more was that nobody knew how long they’d already been compromised. Server logs were full of strange connections from Singapore or Netherlands IPs, config files read at 3 AM, and nothing raised an alarm. By the time anyone noticed, the damage was already done.

That’s why I started using Canarytokens — information traps embedded in files, URLs, and emails that alert you the moment a hacker touches them within seconds, instead of finding out weeks later.

What Are Canarytokens and Why Do They Work?

The name “canary” comes from a 19th-century mining practice: miners brought canaries into the tunnels. Accumulating CO gas would kill the bird before reaching a concentration harmful to humans — giving miners time to escape. Simple, but life-saving.

Canarytokens work on the same principle: you plant a “trap” inside a file, URL, or email. When a hacker opens that file, accesses that URL, or uses that information — you get an immediate alert via email with the exact IP address and timestamp.

Compared to traditional IDS/IPS, Canarytokens differs in a few key ways:

  • No software to install — create a token online in 2 minutes, paste it into a file, done
  • Zero false positives: only alerts when someone actually accesses it, never a false alarm
  • Works even after an attacker has bypassed the firewall and is already inside your network
  • Completely free via canarytokens.org — no credit card required, no token limit

Common Canarytoken Types

  • HTTP URL — a decoy URL that alerts when accessed
  • DNS Token — a fake domain that alerts when resolved
  • Word/Excel Document — an Office file with a hidden tracking pixel that alerts when opened
  • PDF Document — similar to Word
  • AWS API Key — a fake key that alerts when tested with the AWS CLI
  • Custom Image — an image embedded in an email or webpage that alerts when loaded

Hands-On: Creating and Deploying Canarytokens Step by Step

Step 1: Create a Token at canarytokens.org

Go to https://canarytokens.org/generate. No account required, no email confirmation. The interface gets straight to the point:

  1. Choose a token type — start with Web bug / URL token
  2. Enter the email address to receive alerts
  3. Add a reminder note — clearly state where this token is placed (e.g., “File backup /var/backups/credentials.txt”)
  4. Click Create my Canarytoken

You immediately receive a URL like:

https://canarytokens.org/articles/about/PFhzfmMyXXXXXX/contact.php

Step 2: Embed the Token in a Fake Credentials File

The most effective approach is to create a file that looks important and embed the token URL inside it. Place it in the locations hackers search first:

# Create a trap file in the backup directory
cat > /var/backups/credentials_backup.txt << 'EOF'
# Database Credentials Backup — DO NOT SHARE
# Last updated: 2024-01-15

[Production DB]
host: prod-db.internal
user: admin_backup
password: [REDACTED - see internal wiki]

[Verification URL - internal only]
https://canarytokens.org/articles/about/PFhzfmMyXXXXXX/contact.php

[Notes]
- Rotate password every 90 days
- Contact: [email protected]
EOF

chmod 600 /var/backups/credentials_backup.txt

When a hacker finds this file and tries to access the “verification” URL, an alert email arrives immediately — with IP address, User-Agent, and exact timestamp.

Step 3: Set a Trap in a .env or Config File

This is the technique I’ve found most effective in practice. After gaining access to a server, attackers almost always run these commands immediately:

find / -name "*.env" 2>/dev/null
find / -name ".env*" 2>/dev/null
cat /home/*/.env

Create a fake .env.backup file with an embedded token:

# /home/deploy/.env.backup — trap file
DATABASE_URL=postgres://admin:supersecret@prod-db:5432/app
SECRET_KEY=sk_live_abc123xyz789...
INTERNAL_API_ENDPOINT=https://canarytokens.org/articles/about/TOKEN_HERE/contact.php
REDIS_URL=redis://cache:6379/0
STRIPE_SECRET_KEY=sk_live_51Hxxxx...

Attacker scripts typically curl every URL found in a file — the alert arrives immediately, before they have a chance to do anything else.

Step 4: Create a Trap Using a Word Document

The MS Word Document token type generates a .docx file with a hidden tracking pixel inside. When anyone opens it, Word automatically calls back to the Canarytokens server — triggering an alert with the IP address, even when the machine is running Windows and connected to the internet.

Place trap files in enticing locations:

cp server_passwords_master.docx /home/admin/Documents/
cp employee_salaries_2024.xlsx /var/www/html/private/
cp vpn_accounts_backup.docx /opt/backups/docs/

File names need to look tempting: passwords_list.docx, credentials_master.xlsx, aws_keys_backup.docx. Any hacker who comes across these will want to open them immediately.

Step 5: Use a DNS Token for a Deeper Layer

DNS tokens operate at a lower layer than HTTP — even tools without a browser will trigger a DNS lookup when attempting to connect. This is why they’re harder to bypass than regular URL tokens.

After creating a DNS token, you receive a subdomain like abc123xyz.canarytokens.org. Embed it in a config file:

# /etc/app/database.conf — trap file
[primary]
host = prod-db.abc123xyz.canarytokens.org
port = 5432
name = production_db
user = db_admin

[replica]
host = replica.abc123xyz.canarytokens.org
port = 5432

When an attacker imports this config and pings it or runs the app — the DNS lookup fires the alert immediately, before a connection is even established.

Step 6: Self-Host Canarytokens (Advanced)

Don’t want to use an external service for privacy or compliance reasons? Canarytokens provides a Docker image for self-deployment:

git clone https://github.com/thinkst/canarytokens
cd canarytokens

# Configure
cp templates/switchboard.env.example switchboard.env
nano switchboard.env
# Set: CANARY_DOMAINS=yourdomain.com
# Set: CANARY_NXDOMAINS=yourdomain.com
# Set: [email protected]

docker-compose up -d

Self-hosting is ideal for enterprise environments that need full data control — when you don’t want trigger information sent to a third-party server.

What Does a Real Alert Look Like?

Token triggered, email arrives within seconds:

Subject: [Canarytoken Alert] Your token has been triggered!

Token:    Web bug / URL token
Reminder: credentials_backup.txt in /var/backups/

Time:       2024-01-20 03:47:22 UTC
IP Address: 45.33.32.156
ISP:        DigitalOcean, LLC
Location:   Singapore, SG
User-Agent: curl/7.68.0

An IP from Singapore, at 3 AM, using curl instead of a browser. No further evidence needed. You have everything to act immediately: block the IP, revoke credentials, check access logs around that timestamp.

Conclusion: 15 Minutes of Setup, Year-Round Alerts

Canarytokens doesn’t replace a firewall or IDS. But it fills the biggest gap those tools leave open: alerting you when an attacker is already inside and rummaging through your assets.

I recommend placing at least 4-5 tokens on every critical server:

  • 1 fake .env.backup file in the home directories of high-privilege users
  • 1 credentials file in /var/backups/ or /opt/backups/
  • 1 Word document with an enticing name in the Documents/shared folder
  • 1 DNS token embedded in a rarely-used but easy-to-find config file
  • 1 HTTP token in the README or NOTES file of an internal repo

15-20 minutes of setup, completely free. The first time someone triggers a token at 3 AM and you get the alert immediately — instead of discovering the breach 3 weeks later — you’ll understand why this is the first thing I deploy on every new server I take on.

Share:
Tags: