/deploying-honeytokens-and-canarytokens

name: deploying-honeytokens-and-canarytokens
description: Plants Canarytokens-based decoy artifacts (honey credentials, DNS tokens, web-bug URLs, AWS keys, documents, kubeconfigs) using Thinkst's open-source Canarytokens project and alerts via email or webhook when a token is touched. Use for high-fidelity intrusion detection in low-telemetry areas like file shares or credential stores, or to catch credential dumping and data-theft staging.
domain: cybersecurity
subdomain: deception-technology
tags:
- deception-technology
- canarytokens
- honeytokens
- breach-detection
- threat-detection
- d3fend
- decoy-credentials
- intrusion-detection
version: '1.0'
author: mahipal
license: Apache-2.0
nist_csf:
- DE.CM-01
mitre_attack:
- T1556

Deploying Honeytokens and Canarytokens

> **Authorized Use Only:** Deception assets described here are defensive controls deployed inside your own environment. Deploying tokens, decoy credentials, or honeypots on infrastructure you do not own or administer, or using them to entrap third parties, may violate computer-misuse and privacy law. Deploy only on assets you own or are explicitly authorized to instrument, and route all alert data through approved monitoring channels.

Overview

Honeytokens (a.k.a. canarytokens) are decoy artifacts — credentials, files, URLs, API keys, DNS names, database connection strings, documents — that have no legitimate operational use. Because no authorized user or process should ever touch them, **any** interaction is a high-fidelity signal of an intrusion, insider misuse, or reconnaissance. Unlike signature- or anomaly-based detection, honeytokens generate near-zero false positives: the alert *is* the compromise.

Thinkst's open-source **Canarytokens** project (https://canarytokens.org and the self-hostable `thinkst/canarytokens-docker`) generates dozens of token types that "phone home" when triggered: an HTTP/web-bug URL that fires on GET, an AWS API key that fires when used against AWS, an MS Word/PDF document that fires on open, a DNS token that fires on resolution, a Slack API token, a Kubernetes `kubeconfig`, an Azure login certificate, a `log4shell` payload, and more. Each token is bound to a unique `memo` (so you know *where* it was planted) plus an alert channel (email and/or webhook).

This skill maps to MITRE D3FEND's **Decoy File (D3-DF)**, **Decoy User Credential (D3-DUC)**, and **Honeytoken** techniques. From an ATT&CK perspective, a triggered honey credential most commonly evidences adversary attempts to abuse or modify authentication material (**T1556 – Modify Authentication Process** and related credential-access activity), giving the SOC an early, unambiguous tripwire deep inside the kill chain — typically after initial access but before lateral movement completes.

When to Use

• When you need high-fidelity intrusion detection in segments where traditional telemetry is sparse (file shares, password vaults, code repos, cloud accounts).
• When validating that an attacker who reaches a "crown-jewel" host or document store is detected, not just blocked at the perimeter.
• When seeding decoy credentials into LSASS-reachable memory, browser stores, `.aws/credentials`, or password managers to catch credential dumping and reuse.
• When instrumenting documents, repos, or wikis to catch data theft and ransomware staging.
• When building a MITRE D3FEND-aligned deception layer as part of a defense-in-depth or zero-trust program.

Prerequisites

• Docker Engine and Docker Compose v2 for self-hosting (`docker compose version`).
• A registered domain you control plus DNS delegation for DNS-based tokens (NS records pointing at your switchboard host).
• A public IPv4 address reachable on 80/443 (HTTP tokens) and 53/udp (DNS tokens).
• An SMTP relay or Mailgun account, and/or a Slack/Teams/generic webhook URL for alert delivery.
• Python 3.8+ for the helper script:

  python3 -m pip install requests

• For quick use with no hosting, an account-free token from the public service at https://canarytokens.org.

Objectives

• Stand up a self-hosted Canarytokens instance (or use the public service) with working alerting.
• Generate the major token types (HTTP, DNS, AWS key, MS Word/PDF, Slack, kubeconfig) with descriptive memos.
• Plant decoy credentials and decoy files in realistic, monitored locations.
• Validate that each token fires and that alerts reach the SOC channel.
• Catalogue deployed tokens and map them to MITRE D3FEND/ATT&CK for coverage tracking.

MITRE ATT&CK Mapping

| ID | Official Technique Name | Relevance | |----|------------------------|-----------| | T1556 | Modify Authentication Process | A triggered honey credential reveals an adversary harvesting/abusing authentication material; the decoy provides a detection tripwire for credential abuse activity. |

**Related MITRE D3FEND defensive techniques** (the offensive counter-mapping for this control):

| D3FEND ID | Technique | Role | |-----------|-----------|------| | D3-DF | Decoy File | Canary documents, fake configs, decoy archives placed and monitored. | | D3-DUC | Decoy User Credential | Honey credentials (AWS keys, AD accounts, kubeconfig) integrated with a monitored decoy asset. | | D3-DO | Decoy Object | Umbrella for honeytokens/canarytokens as monitored decoy artifacts. |

Workflow

1. Deploy a self-hosted Canarytokens switchboard

Clone the official Docker repo and create the two environment files from their distributed templates:

git clone https://github.com/thinkst/canarytokens-docker
cd canarytokens-docker
cp switchboard.env.dist switchboard.env
cp frontend.env.dist frontend.env

Set the core variables. In `frontend.env`:

CANARY_DOMAINS=canary.example.com          # general-purpose token domains (comma-separated)
CANARY_NXDOMAINS=nx.example.com            # domains reserved for PDF/DNS tokens
CANARY_PUBLIC_IP=203.0.113.10              # public IP of this host

In `switchboard.env`: