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

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

Token Type	Trigger Mechanism	Best Placement	Detection Scenario
DNS Token	DNS resolution of FQDN	Config files, scripts, internal docs	Attacker reads configs during recon
HTTP Token	HTTP GET to unique URL	Internal wikis, bookmark files, HTML	Attacker browses internal resources
AWS API Key	AWS API call with fake creds	.aws/credentials, env files, repos	Attacker tests found credentials
Cloned Site	Visit to cloned page	Internal portals, admin panels	Attacker accesses cloned services
SVN Token	SVN checkout	Repository configs	Attacker clones repositories
SQL Server	Database login attempt	Connection strings, config files	Attacker attempts DB access

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