by Thinkst Applied Research
Canarytokens helps track activity and actions on your network.
- At least one domain name. If you want to enable PDF-opening tracking, at least two domains.
- Internet-facing Docker host. You can install Docker on a Linux host quickly.
Setup (in Ubuntu)
- Boot your Docker host, and take note of the public IP.
- Configure your domains so that their nameservers point to the public IP of the Docker host. This requires a change at your Registrar. Simply changing NS records in the zonefile is insufficient.
- Clone the Docker setup:
$ git clone https://github.com/thinkst/canarytokens-docker $ cd canarytokens-docker
- Install Docker compose (if not already present):
$ sudo apt-get install python-pip python-dev $ sudo pip install -U docker-compose #if this breaks with PyYAML errors, install the libyaml development package # sudo apt-get install libyaml-dev
- Configuration is held in the two .env files. Edit these. Uncomment 'CANARY_PUBLIC_DOMAIN' in
switchboard.evand set it to one of the domains defined for 'CANARY_DOMAIN' in
frontend.ev(if you do not uncomment and set it, the Public IP will be used). If you are using Mailgun to send emails, uncomment 'CANARY_MAILGUN_DOMAIN_NAME' and 'CANARY_MAILGUN_API_KEY' from
switchboard.evand set the values. If you are using Mandrill or Sendgrid instead, uncomment the appropriate API key setting and set it. Here's example files for a setup that generates tokens on example1.com, example2.com and example3.com (PDFs), running on a host with public domain 'my.domain' and IP 184.108.40.206, using Mailgun Domain Name 'x.y' and API Key 'zzzzzzzzzz':
#These domains are used for general purpose tokens CANARY_DOMAINS=example1.com,example2.com #These domains are only used for PDF tokens CANARY_NXDOMAINS=example3.com #Requires a Google API key to generate incident map #CANARY_GOOGLE_API_KEY=
- switchboard.ev (Example using Mailgun for email)
CANARY_MAILGUN_DOMAIN_NAME=x.y CANARY_MAILGUN_API_KEY=zzzzzzzzzz #CANARY_MANDRILL_API_KEY= #CANARY_SENDGRID_API_KEY= CANARY_PUBLIC_IP=220.127.116.11 CANARY_PUBLIC_DOMAIN=my.domain CANARY_ALERT_EMAIL_FROM_ADDRESSfirstname.lastname@example.org CANARY_ALERT_EMAIL_FROM_DISPLAY="Example Canarytokens" CANARY_ALERT_EMAIL_SUBJECT="Canarytoken"
- Finally, download and initiate the images:
$ docker-compose up
- The frontend and switchboard will now be running in the foreground. The frontend is accessible at http://example1.com/generate
The tokens are saved in a Redis database file which exists outside of the Docker containers. Look for
dump.rdb in the
If you want to wipe all your tokens, delete dump.rdb.
Its 2018: I want HTTPS!
We have a separate docker compose file which will automate (mostly) getting you up and running a Canarytokens server with HTTPS. You will need to do the following:
- Edit the
certbot.env. You will need to provide your domain and email address (these are necessary for the certbot's registration process). E.g.
Now when you want to bring up your server, you will use
docker-compose -f docker-compose-letsencrypt.yml upwhich will run the server in the foreground so you can make sure everything gets started alright.
If everything is running, you may want to CTRL+C, run
docker-compose -f docker-compose-letsencrypt.yml downto get to a clean slate and then rerun
docker-compose -f docker-compose-letsencrypt.yml up -dwith the added
-dto run the server in the background (in daemon mode)
Please keep in mind that using the HTTPS method will use the email you specified and the domain name to register the certificate. You can read about the lets encrypt process (using cerbot) over here. The process involves verifying that you are the owner of the domain you have specified and registering you with lets encrypt.
THERE IS A RATE LIMIT. So don't keep bringing this server up and down otherwise you will quickly hit a lets encrypt certificate generation limit. To avoid this, for testing purposes you may add
cerbot-nginx/start.shwhich will test whether lets encrypt gives you the certificate.