A honeytoken is data or a computing resource that exists solely to alert you when someone accesses it. This type of a honeypot could take many forms, including a user account that no one should use, a file that no one should access, and a link that no one should click. The open source application Canarytokens, created by Thinkst, makes it easy to start experimenting with this approach to detecting and tracking cyber-adversaries.
Here’s how you can generate your own Canarytokens and even set up your own dedicated Canarytokens environment.
What Are Canarytokens?
Thinkst sees honeytokens as a “quick, painless way to help defenders discover they’ve been breached (by having attackers announce themselves).” To accomplish this, you can use the open source Canarytokens web application to generate tokens such as:
- A URL an adversary might visit (a web bug)
- A hostname an adversary might resolve
- A PDF or Microsoft Word document an adversary might open
- An AWS key an adversary might try to use
When the intruder accesses or uses the honeytoken, Canarytokens will email you and share a few details about the event.
Quickly Generating Canarytokens
The easiest way to get a sense for Canarytokens’ capabilities is to use the version of the app that Thinkst hosts for free at canarytokens.org. The site lets you generate and monitor honeytokens without setting up your own infrastructure:
The downside of using the hosted Canarytokens version is that you give up control over the data the app generates. Also, you cannot customize the domain for tracking tokens’ activities (adversaries might know about canarytokens.org). For more control, you can deploy your own Canarytokens instance.
Deploying Your Own Canarytokens Server
If you’d like to retain full control over your honeytokens, set up your own Canarytokens server. This is a relatively straightforward process, though it does require registering a domain name in addition to installing Canarytokens software on an internet-accessible system.
Create a VM in a Public Cloud
You can host Canarytokens on an inexpensive Linux system in a public cloud. I like DigitalOcean (the link includes my referral code) for this in part because it offers a capable virtual machine for as little as $5 per month. You can start by deploying a DigitalOcean “droplet” running Ubuntu there in a few clicks:
Make a note of your new VM’s public IP address. Then boot up the VM and log into it.
Install Docker in the VM
After logging into your VM, execute the following commands to prepare for installing Docker there:
apt-get -y update apt-get -y upgrade apt-get -y install apt-transport-https \ ca-certificates curl gnupg-agent \ software-properties-common curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \ sudo apt-key add -
Now confirm that you have the right GPG key with the fingerprint 9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88. To do this, search the keyring on your VM for its last eight characters:
apt-key fingerprint 0EBFCD88
You should see the key that matches the fingerprint above. Continue installing Docker:
add-apt-repository \ "deb [arch=amd64] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable" apt-get -y update apt-get -y install docker-ce
Register and Set Up Your Domain for Canarytokens
Before proceeding, you’ll need to register a domain name that you’ll use exclusively for Canarytokens:
- Configure your domain’s DNS settings to create an “A” record for your domain to point to the public IP of your Canarytokens VM. (If you need to specify the resource name for the record, use “@”.)
- If you’re planning to use PDF honeytokens, create an “NS” record for some subdomain name and point it to the domain name you specified in the “A” record.
- If you’re planning to enable HTTPS on your Canarytokens server, also create a “www”.
For example, if using example.com as your Canarytokens domains and if your VM’s public IP is 220.127.116.11, you’d create the following DNS records:
In the example above, ns.example.com is the domain you’d use for PDF honeytokens. You could change the subdomain from “nx” to whatever you want. (Some Canarytokens types, such as Windows Folder, require that you configure your domain to use your Canarytokens system as the domain’s authoritative DNS server.)
Install and Configure Canarytokens
Once you’ve registered the domain name and designated your VM as its DNS server, proceed with installing Canarytokens:
apt-get -y install python-pip python-dev apache2-utils
pip install -U docker-compose
git clone https://github.com/thinkst/canarytokens-docker
Next, modify the Canarytokens configuration files frontenv.env and switchboard.env like this:
Edit the frontenv.env file. Specify the domain name you’ve set up for Canarytokens as the CANARY_DOMAINS parameter. If you’ve registered a subdomain for PDF tokens, specify it as the CANARY_NXDOMAINS parameter; otherwise, set CANARY_NXDOMAINS to the same value as CANARY_DOMAINS, but know that in this case you won’t be able to generate PDF honeytokens.
If you’d like Canarytokens to generate a geolocation map for your incidents, specify your Google Maps API key in the CANARY_GOOGLE_API_KEY parameter in frontenv.env and uncomment the corresponding line. To get this key you’ll need to enable billing in your Google Cloud account.
Edit the switchboard.env file. Specify the public IP address of your server as CANARY_PUBLIC_IP. Also, specify as CANARY_PUBLIC_DOMAIN the domain you used earlier for the CANARY_DOMAINS parameter and uncomment the corresponding line.
If you’d like to receive email alerts, set the parameters whose names start with CANARY_ALERT_EMAIL. You’ll also need to set up an account with Mailgun (free tier available), Mandrill, or SendGrid (free tier available). Specify the details as the corresponding parameters and uncomment the appropriate lines.
Start the Canarytokens App
You’re now ready to start the Canarytokens app. If you’d like to run the software in the foreground of your terminal, use the following command:
To run Canarytokens software in the background, use the following command instead:
docker-compose up -d
The first time you start the app, it’ll download the necessary code (in the form of Docker images). This can take 10 minutes or so. You’ll know it’s done when you see a message like: “Attaching to redis, frontend, switchboard, nginx.” The software will cache the Docker images, so the next time Canarytokens will starts quickly.
Once Canarytokens is running, use your web browser to visit the /generate URL on the server where you’ve activated Canarytokens (e.g., example.com/generate). You should see the Canarytokens interface for generating your very own honeytokens.
Running Your Canarytokens App
After connecting through your web browser to your Canarytokens instance, generate some honeytokens. Consider starting with a simple web bug / URL token, which will alert you when someone accesses the link.
When generating this token, provide the email address where you want Canarytokens to send the alert when the token is accessed. Also include the token’s description. Then click the Create my Canarytoken button.
The app will generate a unique URL for your token and present you with a page like this:
When someone accesses this URL, Canarytokens will email you an alert that will specify the IP address from which the token was accessed, along with other details like the browser’s User Agent string. The message will also include a link to your Canarytokens server where you’ll see the history of this token.
To terminate the Canarytokens app on your server, press Ctrl+C in the terminal where you’ve launched it, if you ran the app using the docker-compose up command. If you launched Canarytokens in the background using docker-compose up -d, run the command docker-compose down from the canarytokens-docker directory.
Canarytokens saves its data in the dump.rdb file in the canarytokens-docker/data directory. This way, it will remember your earlier tokens the next time you start the app. If you want to start with a clean slate, remove the file.
Enable HTTPS on Canarytokens
If you’d like to enable HTTPS on your Canarytokens server, terminate your Canarytokens app. Then edit the certbot.env file in the canarytokens-docker directory to specify the details the app will use when requesting a free TLS/SSL certificate from Let’s Encrypt.
Specify your Canarytokens domain name as the MY_DOMAIN_NAME parameter. Specify your email address as the EMAIL_ADDRESS parameter, which the app will provide to Let’s Encrypt when generating the certificate. (As noted above, make sure that you’ve registered the “www” alias for your Canarytokens domain before proceeding.)
Now, instead of using the command docker-compose up to start your Canarytokens app, use the following command from the canarytokens-docker directory:
docker-compose -f docker-compose-letsencrypt.yml up
Supply the “-d” parameter at the end if you’d like to run the app in the background. In this case, you’ll use the following command to terminate the app:
docker-compose -f docker-compose-letsencrypt.yml down
Note that every time you start up the HTTPS-enabled Canarytokens app, you’ll request a new certificate from Let’s Encrypt, which limits how many certs it will issue for a domain in a given period. If you frequently restart Canarytokens, you’ll reach your limit. If that happens, you’ll only be able to access your Canarytokens site using HTTP until you restart your app after waiting the appropriate time (probably about a week).
Password-Protect Canarytokens Management
By default, your Canarytokens pages for generating and managing tokens will be publicly accessible to anyone who comes across them. Take the following steps to password-protect them:
If you’ll be using HTTPS, go to the certbot-nginx directory from canarytokens-docker. If using HTTP only, go to the nginx directory instead.
Now, generate a username/password pair you’ll use for managing your Canarytokens, replacing admin with your desired username, and supplying your desired password at the prompt:
htpasswd -c htpasswd admin
Edit the nginx.conf file, adding the following two lines after the line that starts with the words location ~* (/generate
Next, edit the Dockerfile in the same directory, adding the following line after the one that starts with the words COPY nginx.conf
COPY htpasswd /etc/nginx/htpasswd
Now, rebuild your Canarytokens images. To do that, first go to the canarytokens-docker directory. If you’ll be using HTTPS, run the following command:
docker-compose -f docker-compose-letsencrypt.yml build
If you’ll be using HTTP only, run the following command instead:
You can now start your reconfigured Canarytokens app, as outlined earlier.
Experimenting with Honeytokens
Honeytokens can help you detect malicious attempts to interact with our data, infrastructure and applications. Since legitimate users should not be interacting with these honeypot resources, any activity associated with them is suspect, offering an intrusion detection and threat research method with a relatively low rate of false positives.
Canarytokens offers a convenient way of starting to experiment with honeytokens without too many difficulties and with an attractive value proposition. Give them a try—see what you learn.