Use canary tokens for intrusion detection [Tutorial]

Kennedy Muthii

Ethical hacking

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 | 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] 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

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




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.




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.



On an Ubuntu system, port 53 is used to support our own DNS hence an error occurs when we try to run our server which uses the port. To accommodate this, we can make changes to the server configuration by editing the resolv.conf file.
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.

Use canary tokens for intrusion detection [Tutorial]


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

Use canary tokens for intrusion detection [Tutorial]


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.

Use canary tokens for intrusion detection [Tutorial]



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.

Use canary tokens for intrusion detection [Tutorial]

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.


Views: 75

Kennedy Muthii

He is an accomplished professional proficient in Python, ethical hacking, Linux, cybersecurity, and OSINT. With a track record including winning a national cybersecurity contest, launching a startup in Kenya, and holding a degree in information science, he is currently engaged in cutting-edge research in ethical hacking. You can connect with him on LinkedIn.

Can't find what you're searching for? Let us assist you.

Enter your query below, and we'll provide instant results tailored to your needs.

If my articles on GoLinuxCloud has helped you, kindly consider buying me a coffee as a token of appreciation.

Buy GoLinuxCloud a Coffee

For any other feedbacks or questions you can send mail to

Thank You for your support!!

Leave a Comment

GoLinuxCloud Logo

We try to offer easy-to-follow guides and tips on various topics such as Linux, Cloud Computing, Programming Languages, Ethical Hacking and much more.

Programming Languages