search

thinkst / canarytokens-docker

Docker configuration to quickly setup your own Canarytokens.
BSD 3-Clause "New" or "Revised" License
603 stars 112 forks source link

readme

Dockerized Canarytokens

by Thinkst Applied Research

Overview

Canarytokens help track activity and actions on your network.

If you have any issues please check out our FAQ over here, or create an issue and we'll try to get back to you as soon as possible.

Table of Contents

Code of Conduct

This project and everyone participating in it is governed by the Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to github@thinkst.com.

Prerequisites

Migrating to v3

NB: The updated canarytokens-docker repo no longer has the Dockerfile for Canarytokens v2, so running that requires using the tagged image thinkst/canarytokens:v2_latest. We highly recommend moving to v3. Please contact us if you're battling with the migration.

Setup (in Ubuntu)

1) Please go through both your newly created configuration files, switchboard.env and frontend.env, and fill in the Required Settings section. The Optional Settings are not required to work and have sane defaults so don't change them if you don't need to.

2) Next decide on which email provider you want to use to send alerts. You will have to decide between mailgun, SMTP and sendgrid. The relevant required details can be found in the relevant .env file.

3) Generate a single unique WireGuard key seed to set as CANARY_WG_PRIVATE_KEY_SEED in both switchboard.env and frontend.env with the command:

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

These domains are only used for PDF tokens

CANARY_NXDOMAINS=example3.com

Requires a Google Cloud API key to generate an incident map on the history page with the Maps JavaScript API

CANARY_GOOGLE_API_KEY= LOG_FILE=frontend.log

  * switchboard.env (Example using Mailgun for email)

CANARY_PUBLIC_DOMAIN=mydomain.com LOG_FILE=switchboard.log CANARY_MAILGUN_DOMAIN_NAME=x.y CANARY_MAILGUN_API_KEY=zzzzzzzzzz CANARY_ALERT_EMAIL_FROM_ADDRESS=noreply@example.com CANARY_ALERT_EMAIL_FROM_DISPLAY="Example Canarytokens" CANARY_ALERT_EMAIL_SUBJECT="Canarytoken" CANARY_WG_PRIVATE_KEY_SEED=vk/GD+frlhve/hDTTSUvqpQ/WsQtioKAri0Rt5mg7dw=

* Finally, download and initiate the images:

$ docker compose up

* The front end and switchboard will now be running in the foreground. The front end is accessible at http://example1.com/generate. If you wish to run this in the background, you may use

$ docker compose up -d


NOTE: If you only own one domain, and would like to use pdf tokens, you can use subdomains for `CANARY_NXDOMAINS`. Using `example.com` as our domain, you can set `CANARY_NXDOMAINS` to `nx.example.com`. Then log into your DNS manager console (where you can edit your domain DNS records) and add an NS record of `nx.example.com` mapping to `example.com`.

## Persisting data

The tokens are saved in a Redis database file that exists outside of the Docker containers. Look for ```dump.rdb``` in the ```canarytokens-docker/data``` directory.

If you want to wipe all your tokens, delete dump.rdb.

## How to enable HTTPS

We have a separate docker-compose file that 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.

Specify a single domain name

MY_DOMAIN_NAME=example.com

or multiple domains names with this different key (comment out MY_DOMAIN_NAME above if you do):

MY_DOMAIN_NAMES=example.com anotherexample.net thirdexample.org

EMAIL_ADDRESS=jay@example.com

* Now when you want to bring up your server, you will use ```docker compose -f docker-compose-letsencrypt.yml up``` which 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 down``` to get to a clean slate, and then rerun ```docker compose -f docker-compose-letsencrypt.yml up -d``` with the added ```-d``` to 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 let's encrypt process (using cerbot) over [here](https://certbot.eff.org/lets-encrypt/ubuntuxenial-nginx). The process involves verifying that you are the owner of the domain you have specified and registering you with let's encrypt.

* THERE IS A RATE LIMIT. So don't keep bringing this server up and down otherwise you will quickly hit a let's encrypt certificate generation limit. To avoid this, for testing purposes you may add ```--staging``` to the ```./certbot-auto``` command in ```cerbot-nginx/start.sh``` which will test whether let's encrypt gives you the certificate.

## Enabling Basic Auth to your Canarytokens Site

You may follow these steps if you wish to have a public-facing canarytokens site but would like some basic auth to access it.

1. `git clone https://github.com/thinkst/canarytokens-docker.git`
2. Navigate to the nginx folder:
    - for HTTP:
    ```bash
    cd canarytokens-docker/nginx
- for HTTPS:
```bash
cd canarytokens-docker/certbot-nginx
```
  1. sudo htpasswd -c .htpasswd user where user can be any username you would like to use.
  2. sudo chown <user>:<user> .htpasswd where user is the local linux user
  3. edit the appropriate nginx.conf and 
    server {
  ...
  location ~* (/generate|/manage|/download|/history|/settings|/resources|/legal).* {
      auth_basic           "Basic Auth Restricted Canrytokens"; <---- ADD
      auth_basic_user_file /etc/nginx/.htpasswd;                 <---- ADD
  4. edit the appropriate Dockerfile and add below COPY nginx.conf ... 
    COPY .htpasswd /etc/nginx/.htpasswd
  5. rebuild the images using:
    • for HTTP: 
      docker compose build
    • for HTTPS: 
      docker compose -f docker-compose-letsencrypt.yml build

      restart your docker containers, and enjoy!

Thanks, @mamisano for catching a silly issue using the above 🙏

What's new?

We are going to track some new features/additions here so that it is quick and easy to see what has been recently added.

FAQ

We have a FAQ over here

Contributing

Please check out our Code of Conduct and Contributing documents before submitting a pull request.

We look forward to your valuable contributions.