Implementing Canary Tokens For Network Intrusion

Implementing Canary Tokens for Network Intrusion Detection

When to Use

• When deploying deception-based tripwires across network infrastructure to detect intrusions
• When building early warning systems that alert on unauthorized access to sensitive resources
• When planting fake AWS credentials, DNS beacons, or HTTP tokens to catch attackers during lateral movement
• When integrating canary token alerts with SOC workflows via Slack, Microsoft Teams, or SIEM webhooks
• When complementing traditional IDS/IPS with zero-false-positive deception technology

Common Misconfigurations & Verification

• The token never triggers because nobody finds it: a canary planted in a path no attacker traverses is dead weight. Place tokens where recon actually lands — ~/.aws/credentials, .env, config files with enticing memos, files named passwords.docx — and make them discoverable, not buried.
• Egress/whitelisting silently swallows alerts: DNS tokens require outbound DNS to reach canarytokens.com; HTTP/AWS tokens need egress to the token server. In segmented or proxy-forced networks the resolution/callback is dropped and the trip is never recorded. AWS-key tokens also fail if the org's allowlist or SCP blocks calls to the canary's account/region — confirm the path end-to-end.
• Tokens that leak as real-looking credentials get auto-quarantined: secret scanners (GitHub push protection, GitGuardian) and EDR may delete or block a planted AWS key before an attacker uses it — exclude canary paths from scanners.
• Memo/source-IP context missing: an alert with no memo or NAT'd source IP can't be triaged; ensure each token's memo encodes its location and that the webhook payload carries src_ip.
• Verification: trigger every token type before relying on it — resolve the DNS FQDN (dig), curl the HTTP URL, and run aws sts get-caller-identity with the fake key — and confirm the Slack/Teams/SIEM alert arrives within ~60s (the Validation Checklist below). Re-test after any firewall/egress change, since that is what most often silently breaks tokens.

Prerequisites

• Python 3.8+ with requests library installed
• Network access to canarytokens.org API (or self-hosted Canarytokens instance)
• Webhook endpoint for alert delivery (Slack, Teams, email, or generic HTTP)
• For Thinkst Canary enterprise: valid console domain and API auth token
• Administrative access to target systems where tokens will be planted
• Appropriate authorization for all deployment activities

Core Concepts

What Are Canary Tokens?

Canary tokens are digital tripwires -- resources that should never be accessed during normal operations. When an attacker interacts with a canary token, it immediately triggers an alert with near-zero false positives. Unlike signature-based detection, canary tokens detect attackers by their behavior (accessing bait resources) rather than matching known patterns.

Token Types for Network Intrusion Detection

Alert Flow Architecture

[Attacker Action] --> [Token Triggered] --> [Canarytokens Server]
                                                    |
                                            [Webhook POST]
                                                    |
                          +-------------------------+-------------------------+
                          |                         |                         |
                    [Slack Alert]           [Email Alert]             [SIEM Ingestion]
                          |                         |                         |
                    [SOC Analyst]           [On-Call Page]           [Correlation Rule]

Instructions

Step 1: Generate DNS Canary Tokens

DNS tokens are the most versatile -- they trigger on any DNS resolution, even from air-gapped networks with only DNS egress. The token is an FQDN that, when resolved, alerts the token owner.

import requests

# Create DNS canary token via Canarytokens.org
response = requests.post("https://canarytokens.org/generate", data={
    "type": "dns",
    "email": "soc@company.com",
    "memo": "Production database server - /etc/app/db.conf",
    "webhook_url": "https://hooks.slack.com/services/T.../B.../xxx"
}, timeout=15)

token_data = response.json()
dns_hostname = token_data["hostname"]
# Example: abc123def456.canarytokens.com

Plant DNS tokens in locations attackers commonly inspect:

• /etc/hosts entries pointing to the canary FQDN
• Application configuration files (database_host, backup_server)
• SSH config files (~/.ssh/config) with canary hostnames
• Internal DNS zone files as decoy A records
• CI/CD pipeline environment variables

Step 2: Deploy HTTP Canary Tokens

HTTP tokens generate a unique URL that triggers on any HTTP request. They reveal the source IP, User-Agent, and other HTTP headers of the requester.

# Create HTTP token
response = requests.post("https://canarytokens.org/generate", data={
    "type": "http",
    "email": "soc@company.com",
    "memo": "Internal wiki - IT admin passwords page",
    "webhook_url": "https://hooks.slack.com/services/T.../B.../xxx"
}, timeout=15)

http_url = response.json()["url"]
# Embed in internal HTML pages, documents, or bookmark files

Placement strategies for HTTP tokens:

• Hidden <img> tags in internal wiki pages with sensitive titles
• URL shortener redirects in shared bookmark collections
• Links in internal documentation labeled "admin credentials" or "VPN configs"
• .url or .webloc shortcut files in network shares
• Browser bookmark exports in user profile backups

Step 3: Create AWS API Key Tokens

AWS key tokens are among the highest-fidelity canary tokens. They generate real-looking AWS access keys that trigger an alert whenever anyone attempts to use them against any AWS API endpoint.

# Create AWS API key canary token
response = requests.post("https://canarytokens.org/generate", data={
    "type": "aws_keys",
    "email": "soc@company.com",
    "memo": "DevOps jump box - /home/deploy/.aws/credentials",
    "webhook_url": "https://hooks.slack.com/services/T.../B.../xxx"
}, timeout=15)

aws_token = response.json()
access_key_id = aws_token["access_key_id"]
secret_access_key = aws_token["secret_access_key"]

Deploy the fake credentials:

# Place in ~/.aws/credentials on honeypot or jump servers
[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
region = us-east-1

# Also plant in:
# - .env files in code repositories
# - Docker environment configurations
# - Terraform state files (decoy)
# - Jenkins/CI credential stores

Step 4: Configure Webhook Alert Integration

Set up real-time alerting to your SOC through multiple channels:

# Slack webhook integration
def send_slack_alert(webhook_url, alert_data):
    """Forward canary token alert to Slack channel."""
    payload = {
        "text": f":rotating_light: *Canary Token Triggered*",
        "attachments": [{
            "color": "#FF0000",
            "fields": [
                {"title": "Token Memo", "value": alert_data.get("memo", "Unknown"), "short": True},
                {"title": "Source IP", "value": alert_data.get("src_ip", "Unknown"), "short": True},
                {"title": "Token Type", "value": alert_data.get("channel", "Unknown"), "short": True},
                {"title": "Triggered At", "value": alert_data.get("time", "Unknown"), "short": True},
            ],
            "footer": "Canarytokens Alert System",
        }]
    }
    requests.post(webhook_url, json=payload, timeout=10)

# Generic webhook receiver (Flask) for SIEM ingestion
from flask import Flask, request, jsonify
import json, logging

app = Flask(__name__)
logging.basicConfig(filename="/var/log/canary_alerts.json", level=logging.INFO)

@app.route("/canary-webhook", methods=["POST"])
def receive_alert():
    alert = request.json or request.form.to_dict()
    logging.info(json.dumps({
        "event_type": "canarytoken_triggered",
        "memo": alert.get("memo"),
        "src_ip": alert.get("src_ip"),
        "token_type": alert.get("channel"),
        "time": alert.get("time"),
        "manage_url": alert.get("manage_url"),
        "additional_data": alert.get("additional_data", {}),
    }))
    return jsonify({"status": "received"}), 200

Step 5: Enterprise Deployment with Thinkst Canary API

For organizations using Thinkst Canary, leverage the API for mass deployment and centralized management:

import canarytools

# Connect to Thinkst Canary console
console = canarytools.Console(
    domain="yourcompany",
    api_key="your_api_auth_token"
)

# Create tokens programmatically at scale
token_types = {
    "dns": "DNS beacon in config files",
    "aws-id": "AWS credentials on jump servers",
    "http": "Web bug in internal documentation",
    "doc-msword": "Word document in finance share",
    "slack-api": "Fake Slack bot token in source code",
}

for kind, memo in token_types.items():
    result = console.tokens.create(memo=memo, kind=kind)
    print(f"[+] Created {kind} token: {result}")

# Monitor for triggered alerts
alerts = console.tokens.alerts()
for alert in alerts:
    print(f"[ALERT] {alert.memo} triggered from {alert.src_ip}")

Step 6: Token Placement Strategy by Network Zone

DMZ / Public-Facing:

• HTTP tokens in admin panel login pages (hidden image tag)
• DNS tokens in web server configuration files
• AWS keys in .env files on staging servers

Internal Network / Corporate:

• DNS tokens in Active Directory Group Policy scripts
• AWS keys in developer workstation backup directories
• HTTP tokens in internal SharePoint/Confluence pages titled "Emergency Credentials"
• Word document tokens in network shares (\\fileserver\IT\passwords.docx)

Production / Data Center:

• DNS tokens in database configuration files
• AWS keys in CI/CD environment variables
• SQL Server tokens in connection strings on application servers
• SVN/Git tokens in repository configuration files

Cloud Infrastructure:

• AWS key tokens in S3 bucket policies (decoy)
• DNS tokens in CloudFormation/Terraform templates
• HTTP tokens in Lambda function environment variables
• Cloned-site tokens mimicking cloud admin consoles

Examples

Full Deployment Script

# Deploy a comprehensive canary token network
python scripts/agent.py --action full_deploy \
    --email soc@company.com \
    --webhook https://hooks.slack.com/services/T.../B.../xxx \
    --output deployment_report.json

Monitor Triggered Tokens

# Check for triggered alerts
python scripts/agent.py --action monitor \
    --console-domain yourcompany \
    --api-key YOUR_AUTH_TOKEN

Generate Token Inventory

# Create inventory of all deployed tokens
python scripts/agent.py --action inventory \
    --output token_inventory.json

Validation Checklist

• DNS tokens resolve correctly and generate alerts within 60 seconds
• HTTP tokens return a valid response and log source IP
• AWS key tokens trigger alerts when used with aws sts get-caller-identity
• Webhook alerts arrive in Slack/Teams/SIEM within acceptable latency
• Token memo fields contain sufficient context for SOC triage
• Deployment locations are documented in token inventory
• Alert escalation procedures are defined and tested
• Tokens do not interfere with legitimate operations
• Self-hosted Canarytokens instance (if used) is hardened and monitored
• Token rotation schedule is established (quarterly recommended)

References

• Canarytokens Documentation: https://docs.canarytokens.org/guide/
• Thinkst Canary Platform: https://canary.tools/
• Thinkst Canary API: https://docs.canary.tools/canarytokens/actions.html
• Canarytokens Open Source: https://github.com/thinkst/canarytokens
• Zeltser Honeytoken Setup Guide: https://zeltser.com/honeytokens-canarytokens-setup/
• Grafana Canary Token Case Study: https://grafana.com/blog/2025/08/25/canary-tokens-learn-all-about-the-unsung-heroes-of-security-at-grafana-labs/
• AWS Infrastructure Canarytoken: https://blog.thinkst.com/2025/09/introducing-the-aws-infrastructure-canarytoken.html