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

How to download a Canarytoken file using the Canarytoken Factory by providing the required authentication and token identifier, enabling automated token distribution across your systems.

Sometimes you want to automate the creation of Canarytokens across your fleet. Perhaps you want every EC2 instance to reach out and fetch a token on creation (or startup). The Canary Console API allows for the automation, but it seems a bad idea to use your API key on every host.
 

The Canarytoken Factory provides a limited-use key that can create other tokens. You can safely leave this key on a host, because even if an attacker obtains it, they can only create new tokens and cannot remove or alter existing ones.

This key also allows you to download Canarytoken files, such as MS Word or Windows Explorer tokens. To do this, make a GET request to:

https://xxxxxxxx.canary.tools/api/v1/canarytoken/factory/download

Use the following parameters:

• factory_auth → your Canarytoken Factory limited-use key

• canarytoken → the identifier of the Canarytoken you want to download

Below are two examples of downloading a Canarytoken using the Factory endpoints. These examples assume you already have a Canarytoken Factory auth string. If you don't, here's how to obtain one.

Creating a Canarytoken Factory auth string

1. Create Canarytoken Factory: Create a Canarytoken Factory which will provide us with a Canarytoken Factory auth string. You can retrieve one using:

   curl https://EXAMPLE.canary.tools/api/v1/canarytoken/create_factory \
   -d auth_token=CANARY_CONSOLE_API_KEY \
   -d memo='Example Canarytoken Factory Memo'

   The response you will receive will contain your Canarytoken Factory auth string. It will look like this:

   {
     "factory_auth": "EXAMPLE_FACTORY_AUTH_STRING",
     "result": "success"
   }

   We will use the `factory_auth` value going forward for authenticating to your Canarytoken Factory endpoints.

Grabbing the MS-Word tokened document using the Canarytoken Factory

This is going to take two steps: First we will create the token, and then we will download it.

1. Create the token: Use the Canarytoken Factory endpoint to create the token by passing it the "kind" parameter. (A full list of "kinds" can be found by following the steps at the end of this article)

   curl https://EXAMPLE.canary.tools/api/v1/canarytoken/factory/create \
   -d factory_auth=EXAMPLE_FACTORY_AUTH_STRING \
   -d memo='Example MS Word Canarytoken' \
   -d kind=doc-msword

   The response you will receive will contain your Canarytoken identifier.

   {
     "canarytoken": {
       "canarytoken": "tbangcyykk87m8v1skalzfdr8",
       "enabled": true,
       "factory_auth": "EXAMPLE_FACTORY_AUTH_STRING",
       "flock_id": "flock:default",
       "hostname": "<token_hostname>",
       "key": "canarydrop:<key>",
       "kind": "doc-msword",
       "memo": "Example MS Word Canarytoken",
       "triggered_count": 0,
       "url": "<token_url>",
     },
     "result": "success"
   }

   You have now created your MS Word document Canarytoken

2. Downloading the token: Download the MS Word document Canarytoken using the factory_auth string and the Canarytoken identifier.

   curl https://EXAMPLE.canary.tools/api/v1/canarytoken/factory/download \
   -d factory_auth=EXAMPLE_FACTORY_AUTH_STRING \
   -d canarytoken=tbangcyykk87m8v1skalzfdr8
   -G -L -O -J

Grabbing the AWS API Key Canarytoken credentials file using the Canarytoken Factory

This is going to take two steps: First we will create the token, and then we will download it.

1. Create the token: Use the Canarytoken Factory endpoint to create the token by passing it the "kind" parameter. (A full list of "kinds" can be found by following the steps at the end of this article)

   curl https://EXAMPLE.canary.tools/api/v1/canarytoken/factory/create \
   -d factory_auth=EXAMPLE_FACTORY_AUTH_STRING \
   -d memo='Example AWS API Key Canarytoken' \
   -d kind=aws-id

   The response you will receive will contain your Canarytoken identifier.

   {
     "canarytoken": {
       "canarytoken": "tbangcyykk87m8v1skalzfdr8",
       "enabled": true,
       "factory_auth": "EXAMPLE_FACTORY_AUTH_STRING",
       "flock_id": "flock:default",
       "hostname": "<token_hostname>",
       "key": "canarydrop:<key>",
       "kind": "aws-id",
       "memo": "Example AWS API Key Canarytoken",
       "triggered_count": 0,
       "url": "<token_url>",
     },
     "result": "success"
   }

   You have now created your AWS API Key Canarytoken

2. Downloading the token: Download the AWS API Key Canarytoken credentials file using the factory_auth string and the Canarytoken identifier.

   curl https://EXAMPLE.canary.tools/api/v1/canarytoken/factory/download \
   -d factory_auth=EXAMPLE_FACTORY_AUTH_STRING \
   -d canarytoken=tbangcyykk87m8v1skalzfdr8
   -G -L -O -J

Grabbing the list of Canarytoken kinds that the Canarytoken Factory supports

This requires your Canarytoken API Key to retrieve a list of support Canarytokens that you can create via the Canarytoken Factory endpoint.

curl https://EXAMPLE.canary.tools/api/v1/canarytokens/factory/list \
-d auth_token=EXAMPLE_AUTH_TOKEN

The response will be the currently supported Canarytoken kinds.

{
  "factory_canarytokens":{
    "aws-id":"Amazon API Key",
    "cloned-web":"Cloned Website",
    "dns":"DNS",
    "doc-msword":"MS Word .docx Document",
    "fast-redirect":"Fast HTTP Redirect",
    "http":"Web",
    "msexcel-macro":"MS Excel .xlsm Document",
    "msword-macro":"MS Word .docm Document",
    "pdf-acrobat-reader":"Acrobat Reader PDF Document",
    "qr-code":"QR Code",
    "signed-exe":"Signed Exe",
    "slack-api":"Slack API Key",
    "slow-redirect":"Slow HTTP Redirect",
    "web-image":"Remote Web Image",
    "windows-dir":"Windows Directory Browsing"
  },
  "result":"success"
}

When creating a Canarytoken through the Canarytoken Factory endpoint, you must supply the kind (not the description).

Example: To create a QR code Canarytoken, supply "qr-code" as the Canarytoken kind.