Using Canary Tokens: The basic principles

Canary tokens detect intruders by tricking intruders into thinking they are real access tokens (passwords) that can be used to gain further access. In fact they provide no access at all, and when a hacker tries to use the token they are detected. How and where the tokens are placed is critical to their effectiveness.

Each canary token is a genuine set of AWS credentials: an AWS_ACCESS_KEY_ID along with an AWS_SECRET_ACCESS_KEY.

These need to be discoverable to an intruder looking for access keys, but they also mustn't be accidentally used by a genuine application (which would cause false positive alerts to be sent, and may disrupt the application).

Canary tokens should not be in placed deliberately public locations (such as the client-side code of a mobile app).

Use unique tokens

It's important that canary tokens are specific to individual security domains. Use a unique token for a single group of servers that run the same application, and a different token for each third party application.

This means that when an alert about token is sent, you can identify which system has been compromised from the token.

It is more useful to place a canary token alongside the other configuration or secrets for an application, such as in instance data or a parameter store vault for an cloud server, rather than including it a base container image used by many different applications.

You understand your company any applications best, so following these principles you can place your canary tokens wherever you like. However these are our suggestions to get started:

Setup on servers

If you manage servers, then one option is to place canary credentials into a disused profile in the normal AWS credentials file. On Linux, this file is at ~/.aws/credentials, on Windows, at %USERPROFILE%\.aws\credentials.

Add a section like this to the file, replacing the values with ones from for the Traitorbird canary token that you want to use:

Make sure the profile name (in square brackets) is not one that you will actually use, but plausibly corresponds any existing ones. A random suggestion is included in the snippet above.

Setup in source repositories

To add a canary token to a source code repository, you could add a .env file in a hidden subdirectory using a name like or use a .env file with a suffix like . You could also use the .env file at the application's root, but be careful that this does not interfere with actual application configuration.

Third party services

Third party services associated with development, like Continuous Integration or Test services (CircleCI, Jenkins, Travis CI, etc.) are ideal for deploying canary tokens to, as are services like logging or monitoring services which receive log output from deployed applications.

Where the service uses environment variables place the token credentials alongside other environment variables, but in a way that it won't normally be used. For example, in CircleCI you can create a new Organisation context for the canary token values:

Setup in CircleCI

1. Create a new context

In your CircleCI organisation settings, choose Contexts, then "Create a new Context:

2. Choose a name for the context

Use a name like , to suggest that this context might include valuable credentials, so that if an intruder has access to your CircleCI, they are likely to attempt to use it:

2. Add the credentials from your Traitorbird canary token to the context

Add the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY from a new canary token as environment variables in the context:

If an attacker gains access to your CircleCI account, or to CircleCI's own infrastructure, and they are scanning for credentials that might be valuable they will now be likely to find your canary credentials, and as soon as they attempt to use them you will be alerted, warning you immediately of the threat.

Guide Contents