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 Canarytokens works (in 3 short steps):
- Visit the site and get a free token (which could look like an URL or a hostname, depending on your selection.)
- 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.
- 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.
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:
- Visit http://canarytokens.org.
- Enter your email address. (It’s only used to notify you when the token is triggered, mails are not used for any other purpose.)
- 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 192.168.100.2:/repos/repo3/README.txt” or “Password lure email in [email protected] inbox”. We envisage having loads of tokens, so a good description is necessary.
- Click “Generate Token” to obtain your token.
- 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:
then someone visiting any of these:
would still activate your token. This gives us a the simplest use-case for a token, an old fashioned web-bug.
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.)
Kippo – SSH Honeypot
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.
T-Pot Linux – Multi Honeypot Platform
MSSQL & MYSQL
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.
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 canarytokens.org, 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
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 honeytokens.org 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
To test Canary Tokens use their website for testing – CanaryTokens