How You Can Set up Honeytokens Using Canarytokens to Detect Intrusions

A honeytoken is data or a computing resource that exists for the purpose of alerting you when someone accesses it. This type of a honeypot could take many form, such as a user account that no one should use, a file that no one should access and a link on which no one should click. While there are several approaches to implementing honeytokens, open source toolkit Canarytokens, created by Thinkst Applied Research, makes it easy to start experimenting with this approach to detecting and tracking cyber-adversaries.

Getting to Know Canarytokens

Thinkst sees honeytokens as a “quick, painless way to help defenders discover they’ve been breached (by having attackers announce themselves).” To accomplish this, you can use the Canarytokens web application to generate tokens such as:

  • A URL an adversary might visit
  • A domain or hostname an adversary might resolve
  • A Word or PDF document an adversary might open
  • A Bitcoin wallet from which an adversary might withdraw funds

When the intruder accesses or makes use of the honeytoken generated by Canarytokens, the tool will notify you via email and share a few details about the event.

The easiest way to get a sense for Canarytokens’ capabilities is to utilize the pre-deployed version of the tool hosted by Thinkst at The site allows you to generate and monitor honeytokens without having to setup and configure your own infrastructure. The downsides to this approach include having to give up control over the data that the tool generates and the inability to customize the domain names that it uses for tracking.

Deploying Your Own Canarytokens Application

If you’d like to retain full control over the use of honeytokens, you can set up your own instance of Canarytokens. This is a relatively painless process, though it does require registering a domain name and installing Canarytokens software on an Internet-accessible server.

You can host Canarytokens on an inexpensive Linux system at a public cloud provider such as DigitalOcean (the link includes my referral code). I like this provider in part because it offers a low-end virtual private server instance for as little as $5 per month. You can start by deploying a “droplet” running Ubuntu there in a few clicks:

Once the new system is active, log into it and execute the following commands to install Canarytokens software there. (The lines may have been wrapped to fit your screen.)

apt-key adv --keyserver hkp:// --recv-keys 58118E89F3A912897C070ADBF76221572C52609D
add-apt-repository -y "deb ubuntu-$(lsb_release -sc) main"
apt-get update
apt-get -y dist-upgrade
apt-get -y install docker-engine python-pip python-dev libyaml-dev
pip install -U docker-compose
git clone
cd canarytokens-docker

Separately from the instructions above, you’ll need to register your own domain name, which you will use exclusively for Canarytokens. You’ll need to use the registrar’s interface to designate the publicly-accessible system where the toolkit will run as the domain’s DNS server. (I used Google Domains for this purpose, which keeps registration details private without additional fees.) If you’ll use Canarytokens’ PDF tokens, you’ll need two domains.

Once you’ve registered the domain name, configured it properly and installed Canarytokens software, you’ll need to modify two configuration files: frontenv.env and switchboard.env.

In the frontenv.env file you should specify the domain name that you’ve registered and configured for Canarytokens as the CANARY_DOMAINS parameter. If you’ve registered a second domain for PDF tokens, specify it as the CANARY_NXDOMAINS parameter; otherwise, set that parameter to the same value as CANARY_DOMAINS.

In the switchboard.env file, specify in the CANARY_PUBLIC_DOMAIN parameter the domain you’ve listed as CANARY_DOMAINS in the other file. Also, specify the public IP address of your server as CANARY_PUBLIC_IP. Customize CANARY_ALERT_EMAIL parameters to your liking. To receive email alerts, you’ll need to first open and set up a free Mailgun account, then specify the corresponding details as CANARY_MAILGUN parameters.

This is how my Canarytokens configuration files looked. Yours, of course, will have different values for domain names, the IP address and Mailgun details.

Once you’ve configured Canarytokens, you can launch the application by running the “docker-compose up” command, which will automatically download the appropriate Docker images the first time you run it.

Afterwards, use your browser to visit the /generate URL on the server where you’ve activated Canarytokens, using its IP address or the domain name you’ve set up for the app. Keep in mind that the URL will be publicly accessible to anyone who comes across it, as the app doesn’t presently support admin user authentication by default.

Running Your Canarytokens Application

You will see the following screen after directing your browser to your Canarytokens instance, which will give you the opportunity to generate a new token, after specifying the email address where the app will send the alert whenever the token is accessed.

I suggest starting your experiments with the default DNS/HTTP token. This token can be triggered in many ways, including access to the Canarytokens-generated URL, hostname resolution, document file opening, etc.

For instance, when I accessed a URL that corresponded to the token above, the application emailed me the following alert. As you can see, the alert includes the IP address of the system from which I accessed the link and the browser’s User-Agent header. If you fail to receive the notification, check your Mailgun setup and your email spam folder.

This token could also be triggered whenever the intruder resolves its hostname. Note that in the DNS-triggered alert below, the notice includes the IP address of the adversary’s DNS server. This information can help triage the person’s location, because even if he or she is using a VPN, DNS queries are often not tunneled through the VPN.

If you use Canarytokens to generate a Microsoft Word document, you will be alerted whenever someone opens the .docx file. The notification will look just like the one for an HTTP token, but the User-Agent header will include Microsoft Office version details. Canarytokens accomplishes this by including in the Word document’s footer a reference to an invisible image file. Keep in mind that modern versions of Word won’t access the file in Protected View; the person will need to click the “Enable Editing” button to trigger the honeytoken.

To turn off the Canarytokens application, press Ctrl+C in the terminal window where you’ve launched it. The app preserves state in the dump.rdb file that it creates. This way, it will remember your earlier tokens the next time you start Canarytokens. If you want to start with a clean slate, simply remove the file.

Start Experimenting with Honeytokens

Honeytokens offer an enticing way of detecting adversaries’ attempts to interact with our data, infrastructure and applications. Since legitimate users should not be interacting with these honeypot resources, any activity associated with them is suspect, offering an intrusion detection and threat research method with a relatively low rate of false positives. Implementing deception-based defensive techniques in a safe and useful manner can be tricky. Canarytokens offers a convenient way of starting to experiment with honeytokens without too many difficulties and with an attractive value proposition. Give them a try—see what you learn.

To learn more about honeypots and deception, see my other articles on this topic:


About the Author

Lenny Zeltser is a seasoned business and technology leader with extensive information security experience. He presently oversees the financial success and expansion of infosec services and SaaS products at NCR. He also trains incident response and digital forensics professionals at SANS Institute. Lenny frequently speaks at industry events, writes articles and has co-authored books. He has earned the prestigious GIAC Security Expert designation, has an MBA from MIT Sloan and a Computer Science degree from the University of Pennsylvania.

Learn more