– Quick, Free, Detection for the Masses


This is part 2 in a series of posts on our 2015 BlackHat talk, and covers our Canarytokens work.

You’ll be familiar with web bugs, the transparent images which track when someone opens an email. They work by embedding a unique URL in a page’s image tag, and monitoring incoming GET requests.

Imagine doing that, but for file reads, database queries, process executions, patterns in log files, Bitcoin transactions or even Linkedin Profile views. Canarytokens does all this and more, letting you implant traps in your production systems rather than setting up separate honeypots.

Canarytokens is available for free at, or you can download and run your own installation (source and Docker images are available.)

Why should you care?

Network breaches happen. From mega-corps, to governments. From unsuspecting grandmas to well known security pros. This is (kinda) excusable. What isn’t excusable, is only finding out about it, months or years later.

Canary tokens are a free, quick, painless way to help defenders discover they’ve been breached (by having attackers announce themselves.)

How tokens works (in 3 short steps):

  1. Visit the site and get a free token (which could look like an URL or a hostname, depending on your selection.) 
  2. If an attacker ever uses the token somehow, we will give you an out of band (email or sms) notification that it’s been visited.
  3. As an added bonus, we give you a bunch of hints and tools that increase the likelihood of an attacker tripping on a canary token.

More Details:

Tokens consist of a unique identifier (which can be embedded in either HTTP URLs or in hostnames.) Whenever that URL is requested, or the hostname is resolved, we send a notification email to the address tied to the token. You can get one in seconds, using just your browser.
To obtain a token:

  1. Visit
  2. Enter your email address. (It’s only used to notify you when the token is triggered, mails are not used for any other purpose.)
  3. Enter a comment which describes where you’re using the token. If the token is triggered in six months time, a comment will help you remember where you placed the token. Be specific (e.g. “file watch on” or “Password lure email in inbox”. We envisage having loads of tokens, so a good description is necessary. 
  4. Click “Generate Token” to obtain your token. 
  5. Copy the token and drop it somewhere it will be stumbled over.

How do attackers trip over a token?

Recall that a typical token is a unique URL and/or hostname. The URL component is pretty flexible. This means that if your token is:

For example, you could send yourself an email with a link to the token plus some lure text:
Simply keep it in your inbox unread since you know not to touch it. An attacker who has grabbed your mail-spool doesn’t. So if your emails are stolen, then an attacker reading them should be attracted to the mail and visit the link – and while your week is about to get worse, at least you know. 
If you like, you could even use the same token as an embedded image. This way it works like the classic 1×1 transparent GIF. Now an attacker reading your inbox could trip over it just because his mail client renders remote images. (In this way you can use free Canarytokens as a classic web/mail-bug, to receive a notification when an email you send has been read.)

Production Usage

Canarytokens can be used as simple web-bugs, but they are incredibly flexible as we’ll see.

You may have a fancy SIEM that lets you know when stuff happens, but you’ll find that with a little creativity, there’s a bunch of places that you could get wins from a token (that can be deployed in seconds) that you couldn’t easily get to otherwise.

Do you trust the admins/support at DropBox to leave your files alone? (or Office365? or HipChat?)

Simply generate a token and drop it in your folder, or mention it in your HipChat channel. If some admin is browsing contents in their spare time (or is being coerced to do so by a 3rd party) they will trip over your URL and you’ll be notified.

Tokens + helper tools


Every time someone gets owned, and their homedir gets published, theres a bit of speculation on “how they got taken.” While we may not always know the answer to that question, there is something we _do_ know. Files in their home directory were read. (This will include files that were never likely to be read by anyone, so this could be a really high quality marker that bad stuff has happened!)

We include a no-dependency C program (Canaryfy) that will compile and run on Linux. Generate a token, then use it to watch a file. If the watched file is ever read.. you will get your notification..
On OSX, without iNotify events, we make use of DTrace to get the same result.
You could use DTrace to monitor binaries executing too, so XXX will take a token as input, and will notify you if someone runs uname, id, ifconfig or hostname on your machine.

desktop.ini share + zip-files

Windows provides an even cooler way to get notified, in the guise of the venerable old desktop.ini configuration file. Dropping a desktop.ini file in a folder allows Explorer to set a custom icon for a file. Since this icon can reside on a remote server (via a UNC path), using DNS we can effectively make use of a token as our iconfile.
This means anytime someone browses the directory in Explorer,  a notification is sent! It’s an actual file tripwire without any agents or log file monitoring.
(WinZIP and WinRAR both maintain directory structures and honour desktop.ini – you can download a Zip file with the desktop.ini already packaged after you generate your token, and you’ll get notified if someone opens (expands) the Zip file.


Inserting Canary rows into a database, and then watching if they are ever accessed is a pretty common piece of advice when reading about database security. Interestingly, we will wager that most people who have given this advice, have never actually tried making this happen. Its surprisingly painful, and likely not possible in the version of the database you’re running!
It isn’t natively possible to have MSSQL server trigger an action on a SELECT statement, but what one can do is create a custom VIEW which triggers a DNS query when a SELECT is run against the VIEW.
(it’s also possible to set permissions on the VIEW so anyone can run a select on it without seeing its source).

Then, if anyone queries the, say, the user_password view:

The DNS lookup is triggered an a notification is sent:

Since the DNS query is built in T-SQL, we have fine-grained control of the query. It means we can embed additional information like the querying user in the notification.
On MySQL, we make use of another simple tool called canarytokend. This simple utility tails the MySQL log file, matches preset regexes and triggers alerts through the canarytokens console.
Canarytokend is useful since its highly extensible; it simply tails log files and triggers tokens (MySQL is just the example log file). You can use it to watch any kind of log, and fire emails on matches.

Document Open

Honeydoc files are relatively well known. Simply placing a token in the document meta-data, give us a reliable ping when the document is opened. Canarytokens generates both a Word document and a PDF document.

One trick: the PDF document will trigger a notification by Adobe Reader regardless of whether the user allows network communications!

JS Page copied

The Canarytoken server can also notify you if a web page you care about is copied (and hosted on another site). This is usually step0 in a well executed phishing campaign. To make this happen, we simply create our token from, then:

Imgur, Bitcoin and LinkedIn

Imgur, LinkedIn and Bitcoin give us other channels for the Canarytokens server. We can use these sites as oracles to determine if they have been accessed, or touched.

This isn’t new!

Agreed, the basic concept is old. Lance Spitzner spoke about honeytokens in 2003 and Spafford & Kim mentioned the concept back in 1994
In fact, map makers have been mixing fake data with real data for hundreds of years to catch map thieves.

What Canarytokens does however, is makes this concept trivially useable by everyone, and implements a bunch of techniques and approaches which haven’t been publicly discussed.

What if attackers blacklist the domain? Doesn’t that work?

This would work! That’s why we suggest that you download the canarytokens docker image and run your own server. (You can grab the source to build it yourself from here)

Future announcements

We will announce new channels, and new developments on Canarytokens through our @thinkstcanary twitter account.

21 comments On – Quick, Free, Detection for the Masses

  • Neat tool, I assume the attacker could deny outbound smtp traffic to stop notifications. I am thinking of using this in conjunction with an alert if I stop receiving test smtp messages from the box.

  • Its not working the map and location missing

  • I see two other options. One is to release a bunch of instructions on how to get all the programs involved up and running (like you'd have to install and configure redis even) alongside your code. You chose to release a container instead of this because that sounds really annoying, of course.And then the only other option I see is to release it as a VM image, a virtual appliance. But if Anonymous could run that, then they could just as easily make their own VM and install Docker on it and run your container.So really the only thing they could be asking for to do is the first option, since if they can run VMs, they can run Docker. And that makes me think they maybe don't understand what's involved here. What production environment would disallow Docker but would allow installing all the various things inside the container?

  • HI,Thanks for the intiative and for making it free & open source !- Anyone has tested the Document Open in Word please ? How ??? Any clues/recommendations will help.- Same for PDF, or file watching in windows which is what i'm going to test too.Thanks !

  • Would it be possible to use CanaryTokens without using mandrill? My company will not allow the use of a third party smtp/email forwarding company.

  • It would be nice if this and were available via https.

  • @Anonymous x 2: Thanks for the report. We've pushed a new docker-compose.yml into the canarytokens-docker Github which makes the container commands explicit. Can you try that and let us know if it doesn't work out?

  • So….I'm the same guy as above. It looks like the problem is that the switchboard and the frontend images are running an incorrect command and exiting immediately:dude@bigcanary:~/canarytokens-docker⟫ sudo docker-compose ps Name Command State Ports———————————————————————————canarytokensdocker_frontend_1 /bin/bash Exit 0canarytokensdocker_nginx_1 nginx -g daemon off; Exit 128canarytokensdocker_redis_1 / redis-server Exit 0canarytokensdocker_switchboard_1 /bin/bash Exit 0In the config.json for the switchboard and frontend, I can see that the Cmd entry contains only /bin/bash. On another working system, the Cmd entry contains more than /bin/bash. If I edit the config.json file, the changes are wiped out when I run “docker-compose up.” So, any insight on what I can do to fix the broken system would be appreciated.

  • So….I'm trying to run “docker-compose up” to get this running and receive the following nginx errors:nginx_1 | 2015/12/11 21:41:21 [emerg] 1#1: host not found in upstream “frontend” in /etc/nginx/nginx.conf:33nginx_1 | nginx: [emerg] host not found in upstream “frontend” in /etc/nginx/nginx.conf:33If I perform a packet capture on port 53 while this command runs, I can see DNS requests to my external DNS server for a hostname of “frontend.” This host obviously does not exist in my external DNS and I'm not sure why it would be querying the external DNS in the first place…Suggestions on how to fix this?

  • The HTTP canary tokens work great, but correct me if I'm wrong, if a network is using DNS forwarding, then the DNS lookups reflect the IP address of the DNS forwarders, not the network where the token was triggered, correct?

  • Excellent ideas, thanks a lot for this inspiring project!

  • Hiya Anonymous.Thanks.. We appreciate your appreciation.. and we are sorry to have caused you annoyance.Could you maybe explain why Docker is so horrible here? (We know a few people who are happily using the images). It seemed to us like the quickest way to help get people up and running.

  • I appreciate the effort, I am even using the tokens under my own DNS to point at However, I wanted to use this on my own servers. I'm sorry, but docker is not an acceptable deployment path for most people. This project needs to have some rudimentary install directions for those of us NOT using docker. I'm somewhat annoyed that the install directions basically say to use Docker….. and that's it. Love the service, love what you guys do. But please PLEASE don't announce that it's available for deployment on our systems if you have a jumble of files on Git and don't even have install instructions.Once again, Docker should NOT be the go-to deployment schema supported for this. It should be an alternative to a “normal” install, included only after you have everything else complete.Sorry if it sounded like a rant. I'm just very excited about this project and want to use it more in production…. but cant.

  • Thinkst: Elegant, and seems effective. Without code changes, would it be possible to configure SMTP servers, other than Mandrill, within switchboard.env for the Docker implementation?Looking forward to a reply,Interested

  • Will this system send out repeated notifications for each trip or only the first event triggers a notification?

  • According to this Reddit comment it works, though we haven't tried it.

  • Will it still work if if CNAME to point to

  • This comment has been removed by the author.

  • Definitely, that's a risk to the site. It's why we've published the source as well as Docker images; you can rely on our site but the better approach will be to run your own with multiple domains, used only in your own tokens. Any attacker would need to first discover your custom domains before blocking them.(We mention this at the end of the page, and link to the Docker images and source there too.)

  • But couldn't the bad guy work around this with blocking outgoing traffic to that URL first?

Leave a Reply

Site Footer

Authored with 💚 by Thinkst