Canarytokens

Canarytokens are a simple way to tripwire things. An old concept, they can be super useful (and are trivial to use) but require some background infrastructure to get working. We provide this infrastructure for you, so you can deploy tokens in seconds and get the benefit from them immediately.

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 or patterns in log files. Canarytokens does all this and more, letting you implant traps in your production systems rather than setting up separate honeypots.

As a Canary customer, Canarytokens is available to you completely free, and generated alerts will show up in your console like any other:

Canarytoken alert

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.)

  1. Use the console to create your token (which could look like an URL or a hostname, depending on your selection.)

    Click "New Canarytoken"
    Add a memo to remember where you used the token
    Copy your token

  2. Place the generated "token" somewhere special.

  3. If an attacker ever trips on the token somehow, we will let you know that its happened.

    Alert gets generated

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:

http://45e51129ec7e.o3n.io/images/o63277vnjf6nfobn3cbey69fh/spacer.gif
                                                
then someone visiting any of these:
http://45e51129ec7e.o3n.io/images/o63277vnjf6nfobn3cbey69fh/admin.asp
http://45e51129ec7e.o3n.io/images/o63277vnjf6nfobn3cbey69fh/secrets.docx
http://45e51129ec7e.o3n.io/images/o63277vnjf6nfobn3cbey69fh/passwords.zip
http://45e51129ec7e.o3n.io/images/o63277vnjf6nfobn3cbey69fh/anything-really
                                                
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:

Lure email with token'd link

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 1x1 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.)

Over time, if you are using tokens correctly, you will deploy thousands of them all over the place. Make sure that your Reminder is a descriptive, and will be self describing. Nothing sucks more than having a token fire an alert that reads “test" - and not knowing where you placed it.

When you create a DNS based Canarytoken, the system gives you a unique Internet resolvable domain name.

Creating your DNS token
Copying your DNS token

Anyone attempting to resolve this domain name, will now trigger an alert.

Why does this matter? Once you are able to get an alert for a web based token, or a DNS based token, you have the building blocks for squillions of possible tripwires.

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.

Create an MS Word document token, by clicking "New Canarytoken" and choosing "MS Word Document"" from the drop down list.

Click "New Canarytoken"
Select "MS Word Document"

It is possible to either create a blank MS Word document token or upload a document of your own which will be made into a Canarytoken.

Upload your own MS Word document

Leave a reasonable comment to remind you where you will deploy the token and then download the generated MS Word document.

Download the Word file

Place the document wherever you want. Every time the document is opened, you will get your alert, with the tell-tale info we can muster.

Alert fires on document open
Bonus

If you are deploying a Canary with a file share using the remote-config-editor, you are able to automatically create "tokened files" on it.

Creating remotely token'd files

This way, we don’t just learn that Bob from accounting mapped to \\OFFICESHARE\Documents and copied 2018-Plans.docx, we know that 3 days later, the document was opened from Belize.

This token allows you to get a notification when someone browses to a “token’d" directory on a windows server or machine. Create a token, by clicking “New Canarytoken" and choosing “Windows Directory Browsing" from the drop down list

Click "New Canarytoken"
Select "Windows Directory Browsing"

Leave a reasonable comment to remind you where you will deploy the token and then download the generated file.

This offers you a a download of a desktop.ini file (inside of a zip file). Simply create a folder on a Windows machine of your choice, and place the desktop.ini file in it. If an attacker browses that directory, you will get your console alert

Directory was browsed

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.)

How this works

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 token monitors a bucket in your S3 account and alerts on any access to it. (Of course you should be running cloud-trail with logs going into your finely tuned SIEM already, but till that's sorted out, this token can be setup in seconds, to do what it says on the tin).

Create a token, by clicking "New Canarytoken" and choosing "AWS S3" from the drop down list

Click "New Canarytoken"
Select "AWS S3", and fill in the Bucket to Monitor

"Bucket to Monitor" is the name of your fake/canary bucket. Create a name that attackers are likely to view.

You now have the option for Automatic Creation, or a manual route.

Automatic Creation

Automatic Creation means that you enter your AWS creds in the popup, and we will automatically create the token for you. All we need is a user with the required permissions. These credentials are never stored. Once we create your token, we remove any reference to the credentials.

Once you have a user that has the required permissions, you can obtain the security credentials by following these steps. Use these security credentials to populate the "AWS Access Key ID" and "AWS Secret Access Key" fields.

Granting the minimal required permissions:

Ideally, you would make use of a user with permissions only to create and delete the token. To make this happen, you can use assign the following policy to the chosen user:

User Policy

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:CreateBucket",
                "s3:DeleteBucket",
                "s3:DeleteObject",
                "s3:DeleteObjects",
                "s3:GetBucketAcl",
                "s3:ListBucket",
                "s3:PutObject",
                "s3:PutBucketAcl",
                "s3:PutBucketLogging",
                "s3:PutBucketNotification",
                "iam:CreateRole",
                "iam:GetRole",
                "iam:GetRolePolicy",
                "iam:DeleteRole",
                "iam:DeleteRolePolicy",
                "iam:PassRole",
                "iam:PutRolePolicy",
                "lambda:CreateFunction",
                "lambda:DeleteFunction",
                "lambda:GetFunction"
            ],
            "Resource": "*"
        }
    ]
}
    

In order to use this policy, you can follow the steps here to create a new policy.

Once the custom policy is created, you can assign it to a new or existing user by following the steps here. On the "Set permissions" page, select "Attach existing policies to user directly" and select your newly created policy.

Manual Creation

Manual Creation means that we will prepare a setup script that you can run in your AWS environment to create your fake buckets.

Untick "Automate Creation"
Click "Download setup script"

Setup and activate python virtual environment:

/Users/canary/Work/canaryaws/

  • virtualenv usermodenv
  • source usermodenv/bin/activate

Install aws-cli python module

/Users/canary/Work/canaryaws/

  • pip install aws-cli

Install boto3 python module

/Users/canary/Work/canaryaws/

  • pip install boto3

Display the help prompt for the canaryaws.py module that you downloaded

/Users/canary/Work/canaryaws/

  • python canaryaws.py -h

Create your new AWS S3 token using AWS Environment variables

/Users/canary/Work/canaryaws/

  • python canaryaws.py -c

Alternatively, create your new AWS S3 token using supplied AWS Credentials

/Users/canary/Work/canaryaws/

  • python canaryaws.py -c -a [your_access_key] -s [your_secret_key] -r [your_region]
Deleting the token
Click "Disable"
Click "Delete"

You can once again decide whether to automate the process or manually delete the token.

Automatic Deletion

Using the same credentials as before (or with similar credentials with at least the same permissions) follow the below:

Tick "Automate Deletion" and fill in "AWS Access Key ID", "AWS Secret Access Key" and "AWS Region"
Optionally tick "Delete Buckets" and fill in "Confirm Source Bucket"
Manual Deletion
Untick "Automate Deletion" and click "Download delete script"
The delete script downloads then click "Delete Canarytoken"

Follow the steps in the above "Manual Creation" section to setup the virtualenv and ensure aws-cli and boto3 are installed.

Delete your new AWS S3 token using AWS Environment variables

/Users/canary/Work/canaryaws/

  • python canaryaws.py -d

Alternatively, delete your new AWS S3 token using supplied AWS Credentials

/Users/canary/Work/canaryaws/

  • python canaryaws.py -d -a [your_access_key] -s [your_secret_key] -r [your_region]

You can also provide the -b flag if you want to delete the source and log buckets as well

/Users/canary/Work/canaryaws/

  • python canaryaws.py -d -b -a [your_access_key] -s [your_secret_key] -r [your_region]

This token is placed within the JavaScript of your websites and notifies you if someone clones your site and hosts it on another domain. (This is often used for targeted Phishing attacks.)

Create a token, by clicking “New Canarytoken" and choosing “Cloned Website" from the drop down list

Click "New Canarytoken"
Select "Cloned Website", and fill in the Website Domain

Leave a reasonable comment to remind you where you will deploy the token and then click the "Display Javascript" link on your new token.

Click "Display Javascript"

Copy this JS into a file on your target server. (You can encode the file to obfuscate it using a number of obfuscators available online).

If the page loads on your server, nothing happens. If the page is ever loaded on another server, you will get your notification!

Cloned website notification
Bonus

If your site actually is used for phishing attacks, you will be notified for every user who loads the “malicious page" - This is great news, since it will often help with targeted Incident Response.

This token works much like the default HTTP token, but allows you to bind the token to an image of your choosing. i.e. upload an image to your server. The server will serve this image to people, and will notify you when it does.

Create a token, by clicking "New Canarytoken" and choosing "Web Image" from the drop down list.

Click "New Canarytoken"
Select "Web Image", and choose an image file.

Leave a reasonable comment to remind you where you will deploy the token and create the token.

Copy the link to the Web Image.

This token is now a valid link to the image you uploaded. A trick is to embed this image in an admin page for example. An attacker accessing the page will also load the image, sending you your notification that the page has been accessed.

Web image notification
Bonus

If your site actually is used for phishing attacks, you will be notified for every user who loads the “malicious page" - This is great news, since it will often help with targeted Incident Response.

This token works by binding itself to a Google Document or a Google Sheet. When the document is opened an alert will trigger.

Create a token by clicking "New Canarytoken" and choosing either "Google Document" or "Google Sheet" from the drop down list.

Click "New Canarytoken"
Select "Google Document" or "Google Sheet", and enter in the Google email address of the person with which the document will be shared.

Leave a reasonable comment to remind yourself where you will deploy the token. Then, enter the Google email address with which the doc/sheet will be shared. Once all the fields have been specified, create the token.

Once the token has been created there are two ways to continue. You can either follow the Document link that appears in the "Create your Canarytoken" modal - which will lead to a brand new document and a very easy setup process - OR, close the modal window and manually setup the Canarytoken yourself. Both processes are outlined below.

Quick setup

To continue with the Quick setup, click on the Document link that appears in the modal after the Canarytoken has been created. This will open up a Google doc/sheet that has been shared with the Google account specified earlier.

Click on the Document link to open the shared document and to continue the setup process.

In the Google document will be a list of instructions to follow. First of all a copy will need to be made of the document. This will create a new document in your own Drive account.

Note: Please do not rename the document until after the new copy has been made!

Make a copy of the shared document.

On the copied document a new set of instructions will have appeared. At this step you may rename and share the document with whoever you like. The more people with which the document is shared the greater the document visibility.

Note: When the document is shared with anyone it must be shared with edit permissions enabled. This is important or else the Canarytoken alerts will not fire.

Once the document has been shared the Canarytoken needs to be activated. To activate the Canarytoken click on the Canarytokens tab in the document's menu items.

Activate the Canarytoken.

At this point Google will prompt you to grant the Canarytoken a set of permissions. The list of permissions is the bare minimum required for the Canarytoken to function correctly.

And that's it! If you accepted the permissions your Canarytoken is now activated! The document's help should have self-destructed which means you're free to add whatever content to the document you'd like.

Manual setup

For the manual setup, instead of clicking on the Document link after the Canarytoken is created, close the creation window and click on the download link found on your Canarytoken in the Canarytokens list.

Click "Download Google Docs App Script" to download a copy of the Canarytoken.

Copy the contents of the script and then open up the document/sheet the token is to be added to. In the documents menu tab navigate to the "Tools" dropdown and click on the "Script editor..." option.

Select the "Script editor..." option from the "Tools" dropdown menu.
Paste the contents of the script into the Google Apps Script editor and save the file.

The Google Apps Script editor will open. Paste the contents copied earlier here and save (you may name the script whatever you like).

From here the steps depend on which type of document (doc/sheet) we are adding the Canarytoken to. Please make sure you follow the steps outlined below for the correct document type.

Google Document

If you are adding the Canarytoken to a Google Document follow the steps in this section. In the Google Apps Script editor, in the "Edit" dropdown menu click the "Current project's triggers" option.

In the Google Apps Script editor, in the "Edit" dropdown menu, click the "Current project's triggers" option.
Add a Time-driver trigger to the script attached to the Google Document.

Add a Time-driven trigger to the "createTriggers" function to run every minute. Additionally, click on the notifications link under the trigger and remove your email from this list. This will prevent any unnecessary script failure emails from being sent. (Occasionally Google server errors occur)

After the trigger has been created the editor may be closed. Refreshing your Google Document should activate the triggers. And that's it! Your Google Document's Canarytoken is active! All onOpen alerts will be sent to your console.

Google Sheet

If you are adding the Canarytoken to a Google Sheet follow the steps in this section. In the Google Apps Script editor, in the "Edit" dropdown menu click the "Current project's triggers" option.

In the Google Apps Script editor, in the "Edit" dropdown menu, click the "Current project's triggers" option.
Add a "From spreadsheet", "On open", trigger to the script attached to the Google Sheet.

Add a "From spreadsheet", "On open", trigger to the "pingCanary" function and save. And that's it! Your Google Sheets' Canarytoken is active! All onOpen alerts will be sent to your console.

You can administer your server on your /settings page. This allows you to enable the Canarytoken service, setup a custom domain for your service, or setup a default landing page.

Settings panel

Your canarytokens will be created with an unusual looking domain (like: 45e51129ec7e.o3n.io). Use this setting to create your tokens from a custom domain.

Custom domains

If someone finds one of your tokens, and then surfs to it’s root, they will find the following page by default:

Default webroot

Using the Custom Site option, you can edit the HMTL that is rendered for the site's webroot.

Custom webroot

What happens if you deploy a token, that an attacker trips, and then discovers? Can the attack trip it repeatedly just to annoy you?

Aside from the fact that your Canarytoken server will attempt to rate limit alerts, any token my be disabled by clicking on the "Disable" button

Token enabled
Token disabled