Discover Intrusions with Canarytokens

What is Canarytokens?

In my previous post, I talked about canary tokens, an easy way to discover network and system intrusions. While canary tokens are not difficult to set up, Thinkst has made it really easy by running a self-service portal based on their open source canarytokens project. You can create a variety of tokens, and have the alert sent to an email address of your choice. The tokens are hosted on the canarytokens.org domain, so if you are just kicking the tires on this service, you are all set. If you, however, want to host the tokens on your own server/domain, read on!

Deploy Canarytokens on a DigitalOcean Droplet

For this deployment, I'll use DigitalOcean; if you don't have an account, sign up here - you’ll receive a $200, 60-day credit when you add a valid payment method. You also need a domain - if you don't already own one, head over to Cloudflare Registrar or Namecheap and register your domain first. Finally, you'll need an email provider to send alerts - Mailgun, Mandrill and Sendgrid are supported options. I'll use a free sandbox domain from Mailgun here; feel free to use the same or configure a different provider.

Set up your DigitalOcean team and project, and deploy the Docker 1-Click Droplet from the marketplace. This droplet includes the Docker CE and Docker Compose packages, along with their respective dependencies. In addition to package installation, the droplet also configures Docker according to the official recommendations. Click Create Docker Droplet, select the data center region, the CPU option, an authentication option, the hostname, and click Create Droplet.

Once the droplet is ready, select it and launch the Droplet Console as root from the menu options. Note the droplet IP address and add a DNS A record (say, canary.example.com) at your domain registrar that points to the IP address. Run the following commands to install canarytokens.

# Clone the canarytokens GitHub repository
git clone https://github.com/thinkst/canarytokens-docker
cd canarytokens-docker

# Make local copies of the environment files
cp switchboard.env.dist switchboard.env
cp frontend.env.dist frontend.env

Update the local copies of the environment files as follows. For switchboard.env:

• Set CANARY_PUBLIC_IP to droplet IP address
• Uncomment CANARY_PUBLIC_DOMAIN, set to the configured domain
• Set CANARY_MAILGUN_DOMAIN_NAME to Mailgun domain
• Set CANARY_MAILGUN_API_KEY to Mailgun API key
• Set CANARY_ALERT_EMAIL_FROM_ADDRESS to From Address for email alerts
• Set CANARY_ALERT_EMAIL_FROM_DISPLAY to Display Name for email alerts
• Set CANARY_ALERT_EMAIL_SUBJECT to Subject for email alerts
• Set CANARY_WG_PRIVATE_KEY_SEED to the WireGuard key seed

For frontend.env:

• Set CANARY_PUBLIC_IP to droplet IP address
• Set CANARY_DOMAINS, set to the configured domain
• Comment CANARY_NXDOMAINS (need additional domain only for PDF tokens)
• Set CANARY_WG_PRIVATE_KEY_SEED to the WireGuard key seed

Use the following command to generate the WireGuard key seed for both files:

dd bs=32 count=1 if=/dev/urandom 2>/dev/null | base64

Finally, download and run the images using docker-compose up. The frontend will be available at http://<domain>/generate. To run canarytokens in the background, use docker-compose up -d instead. If you want to add HTTPS to your canarytokens deployment, follow the steps outlined here.

Note: If you get an error message stating "Error starting userland proxy: listen tcp4 0.0.0.0:53: bind: address already in use", run the following commands:

systemctl stop systemd-resolved
systemctl disable systemd-resolved

Create Canarytokens for Various Use Cases

Now that your self-hosted canarytokens instance is up and ready, you can generate and trigger various types of tokens. As an example, I'm generating a QR code with a recipient email address and the alert description.

If you scan the QR code with your phone, the associated URL gets triggered and you receive a email notification on your configured address within a few seconds. For each type of generated token, canarytokens offers some guidance on usage. Generate a few different tokens and trigger them to see canarytokens in action.