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

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 gives you a limited use key that is able to create other tokens. You can leave this key on a host knowing that even if an attacker were able to grab it, he'd be able to create new tokens but not remove (or alter) anything else.

The Canarytoken factory's limited use key also allows you to download Canarytoken files (such as a MS Word document Canarytoken or a Windows Explorer Canarytoken). 

It is as easy as making a GET request to https://xxxxxxxx.canary.tools/api/v1/canarytoken/factory/download using your Canarytokens factory limited use key as the parameter "factory_auth" and the canarytoken identifier  as the parameter "canarytoken".

Below are two full examples of downloading a Canarytoken using the Canarytoken Factory endpoints. For these examples, we have assumed that you have already created a Canarytoken Factory auth string. If you haven't, heres how we can get 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"
}

Please note that the above response is in the order of "canarytoken-kind":"canarytoken-kind-description". When creating a Canarytoken through the Canarytoken Factory endpoint, you must supply the kind (not the description). As an example, you would supply the "qr-code" as the Canarytoken kind when wanting to create a QR code Canarytoken.