Mass Canarytokens deployment

Canarytokens can be created manually and automatically. The process for manually creating a token can be found here. The purpose of this article is to demonstrate how to automate the process using the simple scripts and the API.

Note: A Canarytoken Factory Auth String is an API key with a limited scope that should be used when deploying tokens at scale. If the key were ever exposed, it can't be used to meddle in your Console.

Canarytokens are unlimited and provide an interesting mechanism to extend detection capabilities onto existing endpoints. In order to scale this, some sample scripts are provided.

Canarytoken scripts

API calls related to Token management are documented here and a variety of scripts have been uploaded to Github.

The docs provide both curl and python code snippets for each API call. For example, https://docs.canary.tools/canarytokens/actions.html#create-canarytoken provides the following snippets:

curl https://EXAMPLE.canary.tools/api/v1/canarytoken/create \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d memo='Example Memo' \
  -d kind=EXAMPLE_KIND

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/canarytoken/create'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'memo': 'Example Memo',
  'kind': 'EXAMPLE_TOKEN_KIND'
}

r = requests.post(url, data=payload)

print(r.json())

To perform a successful API call, replace the "EXAMPLE" url with your Console endpoint and enter your API key into the "auth_token" field.

Using a combination of API calls, you can automate the deployment of Tokens using a scripting language of your choice.  Below are examples of automated deployments using Bash and Powershell:

Bash

Download canarygen_awscreds_auto_v0.2.sh from Github and modify the variables similarly to what was mentioned above.

wget https://raw.githubusercontent.com/thinkst/canary-utils/master/bash/canarygen_awscreds_auto_v0.2.sh

Replace the console and token variables with your applicable values.

sed -i 's/ab1234ef/xxxxyyyy/g' canarygen_awscreds_auto_v0.2.sh
sed -i 's/deadbeef02082f1ad8bbc9cdfbfffeef/aaaaaaaaaaaaaaabbbbbbbbbbbbbbbbb/g' canarygen_awscreds_auto_v0.2.sh

Modify the filename of the token to something enticing.

sed -i 's/awscreds_$filedate.txt/credentials.txt/g' canarygen_awscreds_auto_v0.2.sh

Execute the script and confirm that it's been placed into the correct directory.

PowerShell

Download Invoke-CreateCanarytokens.ps1 from Github and modify the variables similarly to what was mentioned above.

wget https://raw.githubusercontent.com/thinkst/canary-utils/master/Invoke-CreateCanarytokens.ps1 -o Invoke-CreateCanarytokens.ps1

Replace the empty 'Domain' and 'FactoryAuth' variables with your applicable values.

(Get-Content .\Invoke-CreateCanarytokens.ps1) | %{ $_ -replace "Domain = ''", "Domain = 'xxxxyyyy.canary.tools'"} | Set-Content .\Invoke-CreateCanarytokens.ps1
(Get-Content .\Invoke-CreateCanarytokens.ps1) | %{ $_ -replace "FactoryAuth = ''", "FactoryAuth = 'aaaaaaaaaaaaaaabbbbbbbbbbbbbbbbb'"} | Set-Content .\Invoke-CreateCanarytokens.ps1

You can also set the 'TargetDirectory', 'TokenType' and TokenFilename variables using the syntax above.

(Get-Content .\Invoke-CreateCanarytokens.ps1) | %{ $_ -replace 'TargetDirectory = "c:\\Backup"', "TargetDirectory = 'c:\admin'"} | Set-Content .\Invoke-CreateCanarytokens.ps1
(Get-Content .\Invoke-CreateCanarytokens.ps1) | %{ $_ -replace "TokenType = 'doc-msword'", "TokenType = 'pdf-acrobat-reader'"} | Set-Content .\Invoke-CreateCanarytokens.ps1
(Get-Content .\Invoke-CreateCanarytokens.ps1) | %{ $_ -replace 'TokenFilename = "credentials.docx"', "TokenFilename = 'network-diagram.pdf'"} | Set-Content .\Invoke-CreateCanarytokens.ps1

Execute the script and confirm that it's been placed into the correct directory.

Configuration management integration

Scripting token deployment certainly saves time, but has some limitations when scaling to a larger set of endpoints (Think 1000, or 10 000 endpoints...). Using a configuration management system makes it possible to deploy thousands of Tokens to relevant sets of endpoint groups.

We've gone ahead and integrated these scripts into Microsoft Endpoint Manager, as well as Jamf Pro. These guides provides detailed steps related to the specific applications, but the scripts above could be integrated into other configuration management systems too.