Canarytokens: Deception-Based Threat Detection Guide
Retool's new app builder is where AI-generated code ships safely
Building apps with AI is easy. Getting them to production safely is another story.
Canarytokens are the most underused detection control in most security programs. They cost nothing, take under a minute to deploy, and produce zero false positives when placed correctly. The concept is simple: create an artifact that looks like something valuable to an attacker (a credentials file, an AWS key, a PDF with sensitive-looking content), embed a callback mechanism into it, and plant it somewhere an attacker will find it during reconnaissance or lateral movement. The moment the token is touched, you receive an alert with the attacker's IP address and a timestamp. No EDR tuning required. No SIEM rule to write. No agent to deploy. This guide covers every major token type, where to plant them for maximum coverage, and how to handle the alerts when they fire.
What Canarytokens Are and How They Work
Canarytokens are a project by Thinkst Canary, the company behind the commercial Canary deception platform. The free service at canarytokens.org generates tokens in over 20 formats, each with a unique callback mechanism embedded in the artifact. When an attacker interacts with the token, the callback fires, the Thinkst Canary infrastructure logs the interaction, and you receive an email (or webhook) alert.
The callback mechanism varies by token type. DNS tokens trigger when the embedded hostname is resolved, meaning any application or process that opens the artifact and resolves DNS will fire the alert. HTTP tokens trigger when a URL is requested. AWS key tokens trigger when the embedded access key is used to call any AWS API endpoint. Word and PDF tokens use a tracking pixel embedded in the document that fires when the file is opened in an internet-connected environment.
The critical insight is that none of this requires anything running in your environment. The Thinkst Canary infrastructure handles all the logging and alerting. You generate the token, receive the artifact file or string, plant it, and wait. When the token fires, the alert arrives at your inbox or webhook endpoint with the source IP, user agent (for HTTP tokens), and timestamp of the interaction.
Token Types and What Each Detects
Understanding which token type to use in which context is the core of effective canarytoken deployment. The wrong token in the wrong location produces nothing; the right token in the right location fires the first time an attacker pivots through that area of your environment.
DNS tokens are the most versatile. Any application that reads a file containing the embedded hostname and resolves it, even just rendering a preview, will trigger the alert. DNS tokens work well embedded in configuration files, shell scripts, and anywhere a hostname is plausible.
HTTP URL tokens are useful in environments where outbound DNS may be filtered but HTTP/HTTPS is permitted. Embedding an HTTP token URL in a document as a hyperlink, image source, or webhook endpoint value will fire when the document is opened in most environments.
Word document and PDF tokens contain a tracking pixel that fires when the document is opened in an internet-connected Office or Acrobat session. These are the right choice for files stored in document management systems, network shares, and email lures where the expected attacker behavior is opening the file to read it.
AWS access key tokens are one of the most powerful token types for cloud environments. The token generates a fake but syntactically valid AWS access key and secret. The moment anyone uses that key to call any AWS API, the alert fires. Plant these in code repositories, CI/CD configuration files, developer workstations, and anywhere AWS credentials might plausibly be found. The AWS credential format is so well-recognized by attacker tooling that most automated credential scrapers will attempt to use the key immediately after discovery.
Azure login tokens generate a fake Azure service principal that triggers an alert when authentication is attempted. Kubeconfig tokens embed a Kubernetes configuration that fires when kubectl or any Kubernetes client attempts to connect using the embedded credentials. MySQL tokens trigger when a connection to the embedded database endpoint is attempted.
Briefings like this, every morning before 9am.
Threat intel, active CVEs, and campaign alerts, distilled for practitioners. 50,000+ subscribers. No noise.
Deployment Strategies for Maximum Coverage
Effective canarytoken deployment maps directly to the attacker's reconnaissance and lateral movement playbook. Place tokens where attackers look, not where they are unlikely to reach.
Network shares are the highest-value placement for most organizations. Attackers who gain initial access almost always enumerate accessible file shares looking for credentials, configuration files, and sensitive documents. A file named passwords.txt, credentials.xlsx, or vpn-config.ovpn containing a DNS or HTTP token on a readable share will fire during the reconnaissance phase of almost any lateral movement attempt. The file does not need to contain real content; the name alone drives attacker behavior.
Code repositories are the second-highest-value placement. Hard-coded credentials in source code are one of the most common attacker finds during post-compromise reconnaissance. An AWS access key token committed to a private repository, or embedded in a .env file in the repository root, will fire the moment an attacker with repository access attempts to use the discovered key. For public repositories, this detection use case is even more urgent: automated scrapers continuously scan GitHub for valid AWS credentials and attempt to use them within minutes of publication.
Email lures work well for detecting credential phishing and account compromise. Sending a Word document or PDF canarytoken to an internal email distribution list (with the security team aware) means that any time an attacker with access to a compromised mailbox opens the attachment, the alert fires. The token can be framed as a board presentation, a compensation review, or any other document an attacker would prioritize reading.
S3 bucket tokens cover the cloud storage reconnaissance scenario. An S3 bucket with a plausible name (company-backups, company-financials, hr-records) containing files with embedded HTTP tokens will fire when an attacker who discovers the bucket downloads and opens the files. Pair this with threat hunting workflows triggered by the alert to trace the source of the access.
Developer workstation placements cover insider threat and supply chain attack scenarios. A fake Kubeconfig or AWS credentials file planted in a developer's home directory under a plausible name fires if an attacker who has compromised the workstation sweeps the filesystem for credentials.
Setting Up Your First Canarytokens
The setup process at canarytokens.org requires no account creation and no infrastructure.
Navigate to canarytokens.org and select your token type from the dropdown. Enter the email address where you want alerts delivered. Optionally add a memo that will appear in the alert to remind you where this specific token was planted (for example: "HR share - passwords.txt" or "GitHub repo - .env file"). Click Generate.
For file-based tokens (Word, PDF), download the generated file and plant it in the target location. For string-based tokens (DNS hostname, AWS key), copy the generated string and embed it in the appropriate configuration file or document. For URL tokens, copy the URL and embed it wherever a URL is plausible in context.
Webhook delivery is available as an alternative to email. In the webhook field, enter any HTTPS endpoint that accepts a POST request with a JSON body. This allows canarytokens to feed directly into your SIEM, your Slack workspace, or any incident response platform that accepts webhooks. For teams running a production security program, webhook delivery into a SIEM or ticketing system is strongly preferred over email delivery, which can be lost in noise or missed during vacation coverage.
For organizations running more than a handful of tokens, maintain a token inventory spreadsheet tracking: the token memo, the location where it is planted, the token type, the date planted, and the person responsible for investigating alerts from that token. Without an inventory, alerts from canarytokens will generate confusion about whether the interaction was legitimate or whether the token location is still valid.
Alert Handling and Incident Response
A canarytoken alert is a high-fidelity signal that warrants immediate investigation. Unlike a SIEM alert with a 30% false positive rate, a canarytoken alert means something touched a file or credential that no legitimate process should ever touch. Treat every token alert as a confirmed intrusion indicator until investigation proves otherwise.
The alert email from canarytokens.org includes the source IP address of the interaction, the timestamp, and (for HTTP and browser-based tokens) the user agent string. Start the investigation with this information.
For AWS key tokens, the source IP is the IP that called the AWS API. Cross-reference this against your VPC flow logs and CloudTrail to identify whether the IP is an internal system, a known CI/CD runner, or an external address. An external IP using an AWS key found in a private repository means the repository credentials were compromised and the key was exfiltrated.
For DNS tokens, the resolving IP may be a DNS resolver rather than the originating host. Check your internal DNS infrastructure to correlate the resolver IP to the originating workstation. If the resolving IP is an external resolver (8.8.8.8, 1.1.1.1), the interaction came from outside your network perimeter.
For document tokens, the user agent and IP in the alert help identify the environment where the document was opened. A corporate-looking user agent from an unexpected IP (for example, an AWS EC2 address or a Tor exit node) indicates the document was exfiltrated before being opened.
Once the source is identified, follow your standard incident response runbook. Preserve logs before rotating credentials, isolate the affected system before the attacker detects the investigation, and escalate based on the scope of the confirmed access. Canarytokens provide the initial signal; the response workflow should be integrated into your existing zero trust and incident response processes.
Integrating Canarytokens into a Broader Defense Program
Canarytokens work best as a complementary layer within a broader detection program, not as a standalone control. Their strength is high-fidelity detection of specific attacker behaviors (credential use, file access, lateral movement) that may not generate alerts in EDR or SIEM tools configured for volume filtering.
For threat hunting programs, canarytokens provide a forcing function: when a token fires, you have a confirmed attacker action with a timestamp and source IP. This is the ideal starting point for a hunt. The token alert anchors the investigation with a concrete starting artifact and a known time window, which dramatically reduces the scope of log review compared to hunting from a hypothesis without a confirmed event.
For zero trust architectures, canarytokens fill a detection gap. Zero trust controls access by verifying identity and device posture before allowing resource access, but they cannot always detect what an attacker does after obtaining valid credentials. A canarytoken planted alongside real credentials in a secrets management system or code repository fires when those stolen credentials are used, even if the stolen credentials themselves would pass zero trust verification.
For organizations with limited security budgets, canarytokens provide detection value that would otherwise require a commercial deception platform costing tens of thousands of dollars per year. The free tier at canarytokens.org supports unlimited tokens with email alerting and webhook delivery. Thinkst Canary's commercial Canary platform extends this model with network-level canaries (full decoy systems that emulate servers), centralized management, and dedicated support, but the free canarytokens service is sufficient for most detection use cases in organizations without a dedicated deception budget.
The bottom line
Canarytokens are the highest signal-to-noise detection control available for free. A single afternoon of deployment across your network shares, code repositories, and cloud storage will produce better attacker tripwire coverage than most custom SIEM rules. The investment is minimal: generate tokens at canarytokens.org, plant them in locations attackers visit during reconnaissance and lateral movement, configure webhook delivery to your incident response platform, and maintain a token inventory. When the alert fires, investigate immediately. No legitimate process touches a fake credentials file or uses an AWS key that was never provisioned to any real system.
Frequently asked questions
What are canarytokens and how do they work?
Canarytokens are free deception artifacts created at canarytokens.org by Thinkst Canary that trigger an alert the moment an attacker interacts with them. You generate a token in one of 20+ formats (DNS hostname, HTTP URL, Word document, PDF, AWS key, Kubeconfig, and others), plant the artifact in a location an attacker would find during reconnaissance or lateral movement, and wait. When the token is touched, the embedded callback mechanism fires and you receive an email or webhook notification with the attacker's source IP address, timestamp, and interaction details. No agent deployment, no infrastructure, and no ongoing maintenance is required.
Are canarytokens free to use?
Yes. The canarytokens.org service from Thinkst Canary is entirely free with no account creation required. You can generate unlimited tokens with email alerting and webhook delivery at no cost. Thinkst Canary also sells a commercial Canary platform that adds full decoy systems (network-level canaries that emulate servers and services), centralized management across an organization, and dedicated support. For most organizations without a dedicated deception platform budget, the free canarytokens service covers the majority of detection use cases.
Where should I place canarytokens for the best results?
The highest-value placements mirror where attackers look during post-compromise reconnaissance. Network shares with files named to suggest sensitive content (credentials files, VPN configs, password lists) catch lateral movement. Code repositories with embedded AWS key tokens catch credential scrapers and attackers who gain repository access. S3 buckets with plausible names containing document tokens catch cloud storage reconnaissance. Developer home directories with fake Kubeconfig or cloud credential files catch workstation-level intrusions. Email inboxes with Word or PDF document tokens catch account compromise scenarios where an attacker reads through a victim's mailbox.
What is the difference between canarytokens and a honeypot?
A honeypot is a full decoy system (a fake server, database, or workstation) designed to attract and observe attacker activity over time. Canarytokens are individual deception artifacts embedded in real environments alongside legitimate resources. Honeypots require infrastructure to deploy and maintain; canarytokens require nothing beyond the artifact itself. Honeypots provide rich behavioral data about attacker techniques; canarytokens provide a single high-fidelity alert at the moment of contact. The two approaches are complementary: canarytokens provide broad, low-cost coverage across many locations in your real environment, while honeypots provide deep observation of attacker behavior in isolated environments.
Can attackers detect and avoid canarytokens?
Sophisticated attackers aware of canarytoken techniques may attempt to identify tokens before interacting with them, for example by inspecting documents for tracking pixels or checking whether an AWS key is valid before using it. However, this adds friction and operational overhead to the attacker's workflow. The primary defense against token avoidance is volume and variety: a defender who plants dozens of tokens across network shares, repositories, cloud storage, and email will catch most attackers even if token-aware tooling avoids some. AWS key tokens are particularly hard to avoid without using the key, since the only way to confirm it is a token is to attempt authentication. Combining canarytokens with commercial Canary deception platforms that add network-level decoys makes avoidance significantly harder.
How do I manage and inventory canarytokens across a large environment?
Maintaining a token inventory is essential once you deploy more than a handful of tokens, because an alert without context is nearly useless. At minimum, track each token in a spreadsheet or ticketing system with the following fields: the token memo (set at generation time in canarytokens.org), the exact file path or location where the token is planted, the token type, the date of deployment, and the name of the person responsible for investigating alerts from that specific token. For teams managing hundreds of tokens, Thinkst's commercial Canary platform provides centralized token management with a dashboard, but the free canarytokens.org service supports named memos that appear verbatim in alert emails, which is sufficient for structured inventory if naming conventions are enforced. Rotate tokens annually or after any security incident that may have exposed your deployment locations to an attacker. Also review your inventory after significant infrastructure changes -- a token planted on a decommissioned share or a deleted S3 bucket is no longer providing coverage and should be regenerated in the new location.
Sources & references
Free resources
Critical CVE Reference Card 2025–2026
25 actively exploited vulnerabilities with CVSS scores, exploit status, and patch availability. Print it, pin it, share it with your SOC team.
Ransomware Incident Response Playbook
Step-by-step 24-hour IR checklist covering detection, containment, eradication, and recovery. Built for SOC teams, IR leads, and CISOs.
Get threat intel before your inbox does.
50,000+ security professionals read Decryption Digest for early warnings on zero-days, ransomware, and nation-state campaigns. Free, daily, no spam.
Unsubscribe anytime. We never sell your data.
Founder & Cybersecurity Evangelist, Decryption Digest
Cybersecurity professional with expertise in threat intelligence, vulnerability research, and enterprise security. Covers zero-days, ransomware, and nation-state operations for 50,000+ security professionals every morning.
Win a $2,495 Black Hat pass.
Full-access to Black Hat USA 2026 in Las Vegas. Subscribe free to enter.