Overview

In this blog post we will be looking into Canary Tokens what they exactly are and how they work. We will also look into how we can utilize Intune to deploy the tokens on Windows, MacOS and Linux Clients.

At its core, a Canary Token is a digital tripwire designed to alert you when your data is accessed unexpectedly. They are small files or web URLs that can be placed virtually anywhere in your system or network – documents, emails, databases, or even embedded into your web pages. They are designed to look like regular parts of your system, blending into the background so as not to arouse suspicion. They can be anything from a seemingly innocent file on your server, a URL, a DNS name, a database entry, or even a piece of code embedded in your website. When an intruder interacts with these tokens, it triggers an alert that provides you with immediate notification of the unauthorized access. When a Canary Token is triggered – i.e., when an attacker accesses the token – it sends an alert to the owner. This alert typically includes information about the attacker, such as their IP address, the time of the access, and in some cases, even the location.

For example, consider a scenario where you have a document labeled “Employee Salaries 2023” stored in your company’s private database. Naturally, this document is sensitive and should only be accessed by authorized personnel. To protect this document, you could create a Canary Token and embed it within the document.

The Canary Token allows you to detect this unauthorized activity early on, helping you react quickly to the potential threat. This might include strengthening your security measures, investigating the incident further, or taking legal action if necessary. In this way, Canary Tokens serve as a potent tool in your cybersecurity toolkit, providing an additional layer of defense against potential threats.

Problem: How can I mass deploy tokens programatically and automate it with Intune?

Solution: Using the official API from Canary we will create a Remediation Script that automatically deploys this on our Windows devices. For MacOS and Linux we will create a Bash Script.

Windows

How does the PowerShell script work?

The deployment with Intune consist of two PowerShell Scripts. The first one will be the script to detect if a token is already deployed and the second script will deploy a token if it is not aleady present.

Here are both scripts to download:

1. Detection Script: GitHub
2. Remediation Script: GitHub

First of all we will need the API Access to the Canary Console. Follow this guide to enable API: https://help.canary.tools/hc/en-gb/articles/360012727537-How-does-the-API-work-

We also need the following informations:

1. Canary Factory
2. Factory Auth Key
3. FlockID

Copy and past the Keys and the domain in the Parameter section of the remediation Script:

You can run the Remediation Script on your device to test if everything works and change the target directory for the tokens. I recommend to clean up the tokens in your Canary Console after testing to have a clean and consistent overview of all deployed tokens.

Detection Script

Let´s look into how the detection Script works.

1. List of Token Types to check if they are already present on this device.
2. The target directory where to look for. This directory is important and has to match with the folder from the remediation script or else it will not be able to find the token and eventually rerun infinitely depending on the settings in Intune.
3. If the token is not present It will exit with a Status code of 1 to tell Intune that the remediation Script should run next. If there is a token already present it will exit with 0 meaning that the remediation Script must not be run.

The status of the detection script will be written in the output which you can check in the Intune portal to verify deployments and check errors.

Remediation Script

Let´s look into how the remediation Script works.

1. List of required parameters to authenticate with the Canary API.
   • There are two ways of deploying the Tokens:
     • Pre-Define a specific Token that should be deployed on all Devices, e.g. AWS Certificate or
     • Randomize the Token from a given list, e.g. AWS Cert, Azure Cert, PDF File and more
2. You will have to define the Target Directories on the devices of the Tokens so they match your wishes. The target folder will be created by this script if it does not exist. This has to match the $TokenOptions of the detection Script or it will infinitely run cause it can not find the token in the folder.
3. We will force TLS 1.2 to match the requirements of the API and to securely connect to it.
4. The script will now generate the tokens in the Canary Factory. Every Token will have a Token Memo and the Devicename in it. This way you will be able to distinguish that Tokens and search for the Devicename in case of a offboarding scenario.
5. Lastly it will download the token and place it in the target directory.

The status of the remediation script will be written in the output which you can check in the Intune portal to verify deployments and check errors.

I have implemented error handling and a retry method because API Calls can fail sometimes, therefore we will try again if the connectioned failed upto 3 times.

Step-by-Step deployment with Intune

After reading and understand the idea behind Canary Tokens and also the PowerShell Scripts for the mass deployment we can now deploy them with Intune.

1. Go to the Intune portal at: intune.microsoft.com
2. Go to Devices -> Remediations

3. Select + Create script package

4. Give it a Name to your liking and click on Next

5. Now upload the detection and remediation script:

6. Select or Skip Scope tags and Assign it to a Azure AD Group.

7. Profit 🙂

MacOS

How does the Shell Script work?

First of all we will need API Access to the Canary Console. Follow this guide to enable API: https://help.canary.tools/hc/en-gb/articles/360012727537-How-does-the-API-work-

We also need the following informations:

1. Canary Factory
2. Factory Auth Key
3. FlockID

Copy and past the Keys inside the script.

The script does the following:

1. Initialization: Defines constants for the domain, factory authentication, and flock ID.
   • You have to provide this necessary informations before deploying this script on any device. Just add them to the specific lines inside the script.
2. Dependency Check & Installation:
   • Checks if curl is installed; if not, it tries to install it using brew.
   • Checks if jq (a command-line JSON processor) is installed; if not, it installs it similarly.
3. Token Selection:
   • It randomly selects a token type from aws, azure, wireguard, msword-macro, or pdf-acrobat-reader.
   • Depending on the token type, it sets various parameters (like target directory, token type, and filename).
4. Parameters & Directory Check:
   • Ensures that essential parameters (FACTORY_AUTH, TOKEN_TYPE, and FLOCK_ID) aren’t empty.
   • If the required directory does not exist, it’s created.
5. Token Creation:
   • It forms the data to be sent as POST to create a canary token.
   • Sends a POST request to create the token and checks for success.
6. Token Download:
   • Downloads the token.
   • Writes the token to the designated location.
7. Result: Outputs the location of the token if the creation and download are successful.

You can download the script from here: GitHub

We can deploy shell scripts on MacOS Devices with Intune. Here is a guide how to do it:

Step-by-step deployment with Intune

1. Go to the Intune portal at: intune.microsoft.com
2. Go to Devices -> macOS -> Shell Scripts

3. Add a new Script, give it a name and upload the script:

Note: Add your own domain, Factory_Auth and Flock_ID to the script before uploading it to Intune.

4. Click on next and Assign this script to a AAD Group where you want the script to run. The last step is to click on Add:

5. Done 🙂

Linux

Since its possible now to also run scripts with Intune on managed Linux clients we will use it to automate the deployment of canary tokens.

How does the Shell Script work?

First of all we will need API Access to the Canary Console. Follow this guide to enable API: https://help.canary.tools/hc/en-gb/articles/360012727537-How-does-the-API-work-

We also need the following informations:

1. Canary Factory
2. Factory Auth Key
3. FlockID

Copy and past the Keys inside the script.

The script does the following:

1. Initialization: Defines constants for domain, factory authentication, and flock ID.
   • You have to provide this necessary informations before deploying this script on any device. Just add them to the specific lines inside the script.
2. Dependency Check & Installation:
   • Checks if jq is installed; if not, installs it using apt-get.
   • Does the same for curl.
3. Token Selection:
   • Randomly selects a token type from the predefined array.
4. Token Options Definition:
   • Uses an associative array to map token options (directory, type, and filename) for each token type.
5. Parameter Checks:
   • Validates that the essential parameters are set.
6. Directory Creation:
   • Checks if the target directory exists; if not, creates it.
7. File Existence Check:
   • Checks if the token file already exists, and if so, it exits.
8. Token Creation on Console:
   • Forms the data for the POST request.
   • If the token is of type “azure”, adds specific azure related data to the request.
   • Sends a POST request in a loop, retrying up to 3 times with increasing sleep intervals if the creation fails.
9. Token Download:
   • If the token creation is successful, it downloads the token.
10. Output:
    • Announces the location where the token was written.

In essence, this script ensures curl and jq are available, randomly selects a token type, and then creates and downloads the token, placing it in the /opt directory. The script also includes error handling, such as checking if a token file already exists and retrying the token creation if it initially fails.

You can download the script from here: GitHub

We can deploy shell scripts on Linux Devices with Intune. Here is a guide how to do it:

Step-by-step deployment with Intune

1. Go to the Intune portal at: intune.microsoft.com
2. Go to Devices -> Linux -> Configuration Scripts

3. Add a new Script, give it a name and upload the script:

Note: Add your own domain, Factory_Auth and Flock_ID to the script before uploading it to Intune.

4. Click on next and Assign this script to a AAD Group where you want the script to run. The last step is to click on Create:

5. Done 🙂

Links

How do I download a Canarytoken file using the Canarytoken Factory?

Disabling Protected View for MS Word and Excel tokens

As always: Test and verify before mass deploying the Tokens. You should also think about what happens if you need to offboard devices and what happenes to the Tokens that are in the Canary Console.

Any suggestions or questions? Please message me on Twitter: UgurKocDe