Home

Welcome to the Canarytokens wiki!

---

Overview

Canarytokens is our take on tokens which are used to alert you when someone is looking at something they shouldn't. It allows you to embed links (HTTP or DNS) into almost anything that when touched would resolve or GET request a url. It allows you detect unwanted snooping around your valuables (technically speaking).

Please check out our Canarytokens docker images for easy installation of your own Canarytokens server. It's useful and a ton of fun.

FAQ

How can I create my own AWS ID URL for a private Canarytokens Server?

Unfortunately, we haven't yet released our code for generating AWS ID Canarytokens, but the original work and consequent open source works are available. I've linked to them in this issue.

Why aren't my MS Doc (Excel or Word) triggering once downloaded?

It is common for Windows to put a network block on downloaded files. In order for this document to trigger you will need to unblock the document. You can do this by right clicking on the document, selecting "Properties" and unchecking the "Unblock" checkbox at the bottom of the "Properties".

How can I list all created Canarytokens on my private Canarytokens Server?

There really isn't a very nice way to do this, but i'll provide the steps that we would take. Essentially, you are going to drop into a redis shell in the redis container of your Canarytokens docker. And from there, you can start to look around (like listing all canarydrop objects).

1. Gain access to the server running your Canarytokens docker containers (via ssh or some other means)
2. Run: sudo docker exec -ti redis redis-cli
3. Run: keys canarydrop:*. This will be list all the created Canarytokens.

If you would like to inspect the underlying data of a particular Canarytoken (canarydrop:xxxxxxxx), you can run hgetall canarydrop:xxxxxxxx. This will show you the Canarytoken type, the email/webhook its linked to, and a bunch more data.

How can I run the Canarytokens Server without using docker?

We highly recommend the Canarytokens Docker approach. There has been a bunch of thought put into it and it works well (and easily!).

If you are really set on running a Canarytokens Server without docker, we have outlined an approach in this issue. Again, we do not recommend this!

Adding a new token

Our test workflow checks that pre-commit is happy, so be sure to install it and run pre-commit install in the repo before committing for the first time.

When adding a new token here are a set of steps / checkboxes that are useful to follow.

1. Add a file canarytokens/{new_token}.py. Use this file to define all new_token specific logic.
2. Create tests in tests/units/test_new_token.py. Check that a significant amount of this token specific code is covered by test. Use: cd tests; coverage run --source=../canarytokens/{new_token}.py -m pytest units/test_new_token.py and view coverage: coverage report -m
3. Adding new_token models. Add {new_token_type}TokenRequest, {new_token_type}TokenResponse and {new_token_type} to canarytokens/models.py::Class TokenTypes. Add {new_token_type}TokenHit and {new_token_type}TokenHistory. Finally add these as entries to AnyTokenHit, AnyTokenHistory, AnyTokenRequest, AnyTokenResponse. This allows parse_obj_as(AnyTokenXXX, data) to return hydrated object.
4. Token creation happens in ./frontend/app.py. Add a create_response handler. This handler should hold all Token specific creation logic. example:

@create_response.register
def _(
    token_request_details: {new_token_type}TokenRequest,canarydrop:Canarydrop,
)->{new_token_type}TokenResponse:
    ...
    # Save canarydrop with token specific details

5. Download happens in ./frontend/app.py. Add a create_download_response handler. This handler should hold all the token download specifics. Create a Download{new_token_type}Request and Download{new_token_type}Response Example:

@create_download_response.register
def _(download_request_details:DownloadCMDRequest, canarydrop: Canarydrop)->DownloadCMDResponse:
    """Creates a download response for CMD token.
    This holds a plain text `{token_value}.reg` file.
    """
    return DownloadCMDResponse(...)

That should be all that is needed to create a new token.