-
Notifications
You must be signed in to change notification settings - Fork 253
Home
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.
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.
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".
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).
- Gain access to the server running your Canarytokens docker containers (via
ssh
or some other means) - Run:
sudo docker exec -ti redis redis-cli
- 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.
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!
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.
- Add a file
canarytokens/{new_token}.py
. Use this file to define allnew_token
specific logic. - 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
- Adding
new_token
models. Add{new_token_type}TokenRequest
,{new_token_type}TokenResponse
and{new_token_type}
tocanarytokens/models.py::Class TokenTypes
. Add{new_token_type}TokenHit
and{new_token_type}TokenHistory
. Finally add these as entries toAnyTokenHit, AnyTokenHistory, AnyTokenRequest, AnyTokenResponse
. This allowsparse_obj_as(AnyTokenXXX, data)
to return hydrated object. - Token creation happens in
./frontend/app.py
. Add acreate_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
- Download happens in
./frontend/app.py
. Add acreate_download_response
handler. This handler should hold all the token download specifics. Create aDownload{new_token_type}Request
andDownload{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.