Canarytokens: Token Anything, Anywhere

InfoSec superstar (and long-time Canary fan) theGrugq recently mused on twitter about generating alerts when certain binaries are run on your hosts.


We definitely think it has its uses, and we figured it would be worth discussing a quick way to make this happen (using the existing http://canarytokens.org)

TL;DR: You can pass arbitrary data to a web-token allowing you to use it as a reliable, generic alerter of sorts.


We often refer to our Web and DNS Canarytokens as our token ‘primitives’. With these two tokens, you can create traps for attackers nearly anywhere, on any system for any kind of scenario. In fact, nearly all of our other token types are built on top of the Web and DNS tokens.

A brief overview of how they work:

Web token


  1. Visit http://canarytokens.org and create a web token with the label “Fake email in the finance folder of Adrian’s inbox”.
  2. The server gives me a unique Canarytoken/link. I place it in the finance folder of Adrian’s inbox.
  3. If an attacker clicks/follows the link, I get an alert.
The association between this unique token URL and my label tells me someone MUST be accessing that fake email in the finance folder in my Inbox.
DNS token
  1. Visit http://canarytokens.org and create a DNS token with a label, describing where I plan to hide it.
  2. The server gives me a unique DNS name.
  3. If an attacker (or software the attacker is using) causes the DNS name to be looked up, I get an alert
The mere act of resolving this DNS hostname causes the alert to trigger.
The lovely thing about tokens is that you can now use those base tokens, to mint heaps of creative alternatives.

Back to theGrugq's Question

There are many cases where you can get the alert you need simply by dropping the Canarytoken natively: a link in an email folder, a link shared in a private zoom chat, a link shared in a private slack channel, etc. In those cases, when an attacker views the link, we get a notification that a link that should never have been seen, has been seen (and the free Canarytoken server will go a little further to then geolocate the attacker, tell you about her browser, etc)


On typical Linux boxes, everything’s a file and the operating system is heavily script-driven. There’s much we can use to our advantage here. It means that in a pinch, we can create and trip our own web token, just to get a reliable, coherent message out.

One advantage of the Web Canarytoken is that web servers expect to receive a User Agent string from web browsers.



We can use this field to smuggle out some data related to the attacker!



Now, since we can use curl, wget or even just bash, we can use this technique in a bunch of places.

We can create users with login-scripts that trip the token and leave their ssh-keys lying around. We could also wrap binaries that are usually run by attackers with a wrapper that first trips the token.

Lets create a simple wrapper for netcat:

Now, an attacker who runs nc, actually runs your script. It looks the same to her, but you’ve received your alert letting you know that bad stuff is afoot:



There are a few ways to use this wrapper. To set the tripwire for a single user, set an alias in .zshrc, .profile, .bashrc or your equivalent.

alias nc='~/.local/bin/nc.sh'

To set the trap globally on the system, drop a similar alias in /etc/profile, /etc/zshrc or your equivalent. Another alternative would be replacing the in-path binary with a script and/or using symlinks to ensure nc.sh runs before the nc binary (but beware package updates breaking this approach).

Maybe this server doesn’t have outbound Internet access? No problem - simply swap the curl/wget approach with a DNS lookup command and a DNS token.

Dominic White was also kind enough to code up and donate a wrapper as well. This shows there are many ways to implement this idea. For details on compiling, he has some guidance on that as well.


Why tokens work

Not every dropped token will get tripped, and some tokens may be discovered, but this really isn't a problem. In the real world, an attacker isn’t usually thinking “is this a trap” every step of the way, they’re thinking “this could be the jackpot”. Sooner or later, they tip their hand and announce their presence. (And if they do suspect traps/tripwires, that’s also to your advantage - it’s going to slow them down considerably because now they will second-guess everything).

Even if a dropped Canarytoken isn’t a perfect match for the environment, an attacker's M.O. forces them to follow the lead.

Any red-teamer/attacker will tell you that successful breaches are usually a death by a thousand cuts. You find a file on one machine that points to a new network. You find credentials on that network that give you access to a jump box. If I find an AWS-API key on your machine, I will never be able to ignore it saying: “I don't think they run any AWS infrastructure”. Instead, it's much more likely I've stumbled on someone's skunkworks, and chances are it's ripe for the taking.

It doesn’t matter if an Excel document named 20200504_daily_settlement.xlsx is discovered on a Linux server instead of a Windows server. A criminal on the hunt for payment data to steal has to open it.

Token anything, anywhere. Embed tokens multiple layers deep. Make attackers question their sanity and their desire to continue the attack.