Use canary tokens for intrusion detection [Tutorial]

Introduction to Canary tokens

Canary tokens are a free and easy way of protecting assets such as emails, websites, and documents from unauthorized access. Canary tokens are just like web bugs (The transparent images added on an email to enable a user to know when the email is opened for example, when running a phishing campaign and we need to know who opened the email and who clicked on the link). Canary tokens can be used on production systems and unlike setting up honeypots, they do not require much resources to set up. Whenever an asset protected by a canary token is accessed, an email notification is sent back to the email provided.

Some of the assets that can be protected using canary tokens include:

HTTP GET requests, Adobe PDF, Ms. Word, QR code, Ms. Excel documents, Custom EXE, Windows Directories e.t.c.

In this guide, we will install and run an instance of canary tokens server that can be used to protect assets for an organization.

Using canary tokens for intrusion detection

Install Docker

To run our own server instance, there are several components we need to make sure they are installed. Since the server runs on docker, our first step is to install docker on our machine. To install docker on a debian-based server, we will first add the Docker PGP key.

curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor | sudo tee /usr/share/keyrings/docker-archive-keyring.gpg > /dev/null

Next step we configure the docker APT repository.

echo ‘deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian buster stable’ | sudo tee /etc/apt/sources.list.d/docker.list

We then run

sudo apt-get update

and finally, run the command to download and install docker on our machine.

sudo apt-get install -y docker-ce

After the docker installation is complete, we can now install canary tokens dockerized server

Install and configure canarytokens server

To run an instance of canarytokens on our server, we first download the docker version from the official GitHub repository.

git clone https://github.com/thinkst/canarytokens-docker

After the download is complete we navigate to the folder having our files.

cd canarytokens-docker

There are two configuration files we need to create (frontend.env and switchboard.env). The files will contain the configurations required for the canarytokens server to run. To create the files we copy their contents from samples we downloaded.

cp switchboard.env.dist switchboard.env

cp frontend.env.dist frontend.env

switchboard.env

On the switchboard.env file, the first thing we need to specify is our IP address. We will define the address under CANARY_PUBLIC_IP as shown in the image below. Next, we add the email to be used under CANARY_ALERT_EMAIL, and finally, we add our domain under CANARY_PUBLIC_DOMAIN.

frontend.env

On the frontend.env, we just need to add the domain name under CANARY_DOMAINS. If we want to receive the geolocation from where the canarytoken was initialized, we can add Google Maps API Key under CANARY_GOOGLE_API_KEY.

Adding password protection to the canarytokens app

When we install canarytokens, it has no password protection hence anyone having the app's domain address can access the app. We can protect the app by adding password authentication before the user can access the app and generate tokens.

Since we are using HTTP we navigate into the /canarytokens-docker/nginx folder and run the below command.

htpasswd -c htpasswd yourusername

Replace “yourusername” with your desired username. When the command runs, you will be prompted to provide the password to be used as shown in the image below.

Within the nginx.conf file, we add the below lines after the line location ~* (/generate|/manage|/download|/history|/settings|/resources|/legal)

And finally, we edit the Dockerfile within the same folder to include the below line.

COPY htpasswd /etc/nginx/htpasswd

 After we are through with editing the configuration files, we are now ready to start the canarytokens server. Since we are using docker, we run the command.

docker-compose up

While running the app for the first time, it can take longer before it starts since the app will download other required dependencies. When the installation is complete we can now navigate to the application using our favorite web browser. Ensure you use the top-level URL while accessing the server you have installed canarytokens on.

cd /etc/systemd

nano resolv.conf

On this file, we are looking to edit #DNSStubListener=no and change it to #DNSStubListener=yes and finally remove the similar file as shown below.

cd /etc

rm resolv.conf

ln -s /run/systemd/resolve/resolv.conf .

service systemd-resolved restart

After the restart is complete you can now try accessing our server.

Generating an HTTP token

To generate a canarytoken for use we just specify the kind of token we want to generate and create the token.

We are provided with a link that will trigger an alert whenever someone accesses it as shown in the image below.

Within the email notification sent to you, we can be able to view the IP address, Geo-location (only if the Google Maps API is configured), and the browser User Agent string.

Conclusion

We were able to run canary tokens app on our server. Canary tokens, as described above, are easier to run and require fewer resources compared to honeypots. Using canary tokens, we can be able to secure various assets from unauthorized access. The tokens can also be used to set up email honeypots to notify the owners when the email has been hacked.

To set up such kind of a honeypot, we send an email from a trusted source i.e. CEO, HR. The content of the email includes a username, a password, and a link as shown in the image below. Whenever an attacker gains access to your email and tries to log in to the provided link, an email alert will be sent to the specified email.

Although canarytokens provide a quick solution, bad actors may also abuse these tokens to their advantage. For example, in a phishing campaign, the attackers are able to know how many victims have opened the email and how many victims have clicked on the links leading to the phishing pages. The tokens can also be added to malware to notify the bad actor whenever someone runs the malware.