Implementing Canary Tokens for Network Intrusion Detection Skill

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

Agent Skills: Implementing Canary Tokens for Network Intrusion Detection

Install this agent skill to your local

Skill Files