Canarytoken deployment using Ansible

Use an Ansible playbook to deploy Azure Login Certificate Canarytokens on Linux endpoints to detect unauthorized access. The playbook automates token creation, stores certificates and configs accessibly, and adjusts permissions for visibility. Learn to set variables, create a Factory Auth String, and customise reminders for efficient token deployment and management.

In this article, we'll drop Canarytokens on Linux endpoints using an Ansible playbook.

Azure is a major player in Cloud infrastructure, and many organisations rely on it for their operations. Attackers are aware of this and routinely hunt for Azure credentials. The Azure Login Certificate Canarytoken is designed to turn this behaviour to your advantage. When attackers attempt to use the Token, you get an immediate notification, giving you crucial insight into a potential compromise.

The Ansible playbook is available on our GitHub repo; it will create and download an Azure Login Certificate Token to a pre-defined location on each host and set system-wide read permissions on the Canarytoken and associated config file.

The Ansible Playbook

The basic pseudo-code logic for the Ansible Playbook would be:

1. Generate Azure Login Certificate Canarytoken with the reminder set as the hostname of the target system.
2. Download the ZIP File (azure-config.zip) containing both the client config and Azure Certificate.
3. Create a folder with appropriate read permissions at /etc/azure-config
4. Unzip the contents of the ZIP file to /etc/azure-config
   1. /etc/azure-config/azure-prod (certificate file)
   2. /etc/azure-config/config (config file)
5. Set system-wide read permission on the certificate and config file
6. Remove the downloaded ZIP file

We'll leverage the Canarytoken factory for authenticating to the Console during automated deployment. This will give you a limited-use key that can only create other Tokens. The factory auth string cannot perform other actions on your Console and is limited to generating Canarytokens in its associated Flock.

A Factory Auth String can be generated by querying the API endpoint documented here.

We'll cover two quick examples of generating an auth string below:

Curl — Create Factory Auth

curl -X POST https://CONSOLE.canary.tools/api/v1/canarytoken/create_factory \
-d auth_token=YourConsoleAPIKeyHere \
-d memo "ansible-azure-cert-dropper" \
-d flock_id=flock:default

PowerShell — Create Factory Auth

$uri = "https://CONSOLE.canary.tools/api/v1/canarytoken/create_factory
$body = @{
    auth_token = "YourConsoleAPIKeyHere"
    memo = "awscreds-multi-user-dropper"
    flock_id = "flock:default"
}
Invoke-RestMethod -Uri $uri -Method Post -Body $body

The azure-token-dropper.yaml playbook contains a few variables that need to be set according to your deployment requirements. In this example, we will deploy the Azure Login Certificate and Config file into a specific directory (/etc/azure-config/) and change file permissions associated with the Canarytoken to increase its visibility on the system.

In our YAML file, add your Console Hash on line 5 (the unique characters before .canary.tools on the URL used to access your Console). On line 6, specify your Factory Auth string, which can be created using the curl example request shown earlier in this article.

The playbook has several variables defined in the Deploy Azure Token task. These can be modified to customise the deployment.

If the target_directory variable does not already exist, it will be created, and permissions will be set so that it can be read by other users on the system. The token_filename does not need to be modified it is a temporary zip file; after extracting the file (containing the Azure Login Certificate token and config file), it will be deleted.

The azure_id_cert_file_name can be changed. This will be the name of the certificate file and will be referenced in the associated config file.

Each Azure Login Certificate Canarytoken will have a unique reminder specified when creating the token. The reminder field in this playbook contains the following information:

• Hostname
• Directory where Canarytoken was placed
• Name of the Azure Login Certificate file
• DateTime of creation

The attributes have been specified using a delimiter, making it easier to work with if you export and manage Canarytokens outside your Console. You can modify these details in the reminder and add other attributes or remove those you deem unnecessary.

Finally, the script will ensure that other system users can read the Canarytoken certificate and associated config files.

This script must be executed with elevated privileges to create the /etc/azure-config directory and has been done with the --ask-become-pass argument in the example below.

After deployment, we can review the changes that have been made. Two files were created on each of the target systems:

• /etc/azure-config/azure-prod
• /etc/config

An example of what each of these files would contain has been provided below.

Using a configuration management system makes it possible to deploy thousands of Tokens to relevant sets of endpoint groups. We also have a multi-token dropper Ansible playbook that provides examples for deploying different Canarytokens with Ansible.