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.

Endpoints

GET /api/v1/canarytokens/factory/list

POST /api/v1/canarytoken/create_factory

DELETE /api/v1/canarytoken/delete_factory

POST /api/v1/canarytoken/factory/create

GET /api/v1/canarytoken/factory/download

List Canarytokens available via Canarytoken Factory

TIP

The values returned by this Canarytokens Factory API correspond to the kind parameter used to create Canarytokens via the Canarytokens Factory. As an example, if you wanted to create a Cloned Web Canarytoken, you would check the response to this Canarytoken Factory API and use cloned-web to define the Canarytoken type you wish to create via the Canarytoken Factory.

GET /api/v1/canarytokens/factory/list

Lists the Canarytokens available via your Canarytokens Factory.

Required Parameters

auth_token string

A valid auth token

Response

A JSON structure with result indicator and Canarytokens Factory information.

Example

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

import requests

url = 'https://EXAMPLE.canary.tools/api/v1/canarytokens/factory/list'

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN'
}

r = requests.get(url, params=payload)

print(r.json())

Response

{
  "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"
}

Create Canarytokens Using Factory

POST /api/v1/canarytoken/factory/create

Create Canarytokens using a Canarytokens Factory auth string

Required Parameters

factory_auth string

A valid factory_auth string

memo string

A reminder that will be included in the alert to let you know where you placed this Canarytoken

kind string

Specifies the type of Canarytoken. Supported classes include http, dns, cloned-web, doc-msword, web-image, windows-dir, pdf-acrobat-reader, msword-macro, msexcel-macro, aws-id, qr-code, fast-redirect, slow-redirect, slack-api

Optional Parameters

flock_id string

Defaults to: 'flock:default'

A valid flock_id (defaults to the Default Flock)

web_image string

An image file for use with web-image tokens (request must be multipart/form-data encoded if parameter is present, required when using web-image)

cloned_web string

Domain to check against (required when creating cloned-web tokens)

browser_scanner_enabled boolean

Defaults to: true

Enables a Javascript scanner to retrieve more information (only valid with 'http' Canarytokens)

aws_id_username string

AWS ID Username is optional if you want to create an AWS API key linked to certain Name otherwise it is randomly generated.

browser_redirect_url string

Browser redirect URL is the URL you want your Canarytoken server to redirect attackers to after they have triggered your Canarytoken token (required when creating fast-redirect and slow-redirect tokens)

exe string

The Windows executable that you would like tokened (required when creating signed-exe tokens)

web_image string

Image file (jpeg or png) that will be displayed on the Canarytokens URL (required when creating web-image tokens)

doc file

Upload MS Word Document to canarytoken; optionally used with MS Word Document (doc-msword) token. With curl use the following flag -F 'doc=@upload-me.docx; type=application/vnd.openxmlformats-officedocument.wordprocessingml.document'

pdf file

Upload PDF file to canarytoken; optionally used with Adobe PDF canarytoken (pdf-acrobat-reader). With curl use the following flag -F pdf=@upload-me.pdf; type=application/pdf

Response

A JSON structure with the generated Canarytoken.

Example

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

import requests

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

payload = {
  'factory_auth': 'EXAMPLE_FACTORY_AUTH_TOKEN',
  'memo': 'Example Memo',
  'kind': 'EXAMPLE_KIND'
}

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

print(r.json())

Response

{
  "canarytoken": {
    "access_key_id": "<access_key_id>",
    "canarytoken": "<token_code>",
    "created": "1586246956.323499",
    "created_printable": "2020-04-07 08:09:16 (UTC)",
    "enabled": true,
    "factory_auth": "<factory_auth_token>",
    "flock_id": "flock:default",
    "hostname": "<token_hostname>",
    "key": "canarydrop:<key>",
    "kind": "aws-id",
    "memo": "Example Memo",
    "renders": {
      "aws-id": "\n    [default]\n    aws_access_key_id = <aws_access_key>\n    aws_secret_access_key = <aws_secret_access_key>"
    },
    "secret_access_key": "<aws_secret_access_key>",
    "triggered_count": 0,
    "updated_id": 14,
    "url": "<token_url>",
    "username": "<token_user_name>"
  },
  "result": "success"
}

Download Canarytoken using Factory Auth String

GET /api/v1/canarytoken/factory/download

Download the generated file (if one exists) for the supplied Canarytoken using the Factory auth string

Required Parameters

factory_auth string

A valid Canarytoken factory auth string

canarytoken string

An identifier for a Canarytoken that supports downloadable files

Response

A file if the Canarytoken supports file generation, otherwise an error.

Example

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

import requests
import re


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

payload = {
  'factory_auth': 'EXAMPLE_FACTORY_AUTH',
  'canarytoken': 'EXAMPLE_CANARYTOKEN'
}

r = requests.get(url, allow_redirects=True, params=payload)
filename = re.findall("filename=(.+)", r.headers["Content-Disposition"])[0]
with open(filename, 'wb') as f:
    f.write(r.content)

Response

$ ls -l
-rw-r--r--  1 user  thinkst  5095 Apr  7 12:29 <filename>

Create Canarytoken Factory Auth String

POST /api/v1/canarytoken/create_factory

Create an auth string for the Canarytoken Factory endpoint.

Required Parameters

auth_token string

A valid auth token

memo string

A reminder that will be included in the alert to let you know where you placed this Canarytoken

Optional Parameters

flock_id string

Defaults to: 'flock:default'

A valid flock_id (defaults to the Default Flock)

Response

A JSON structure with auth string and Canarytoken factory endpoint.

Example

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

import requests

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

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

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

print(r.json())

Response

{
  "factory_auth": "<factory_auth_token>",
  "factory_url": "/api/v1/canarytoken/factory",
  "result": "success"
}

Delete Canarytoken Factory Auth String

DELETE /api/v1/canarytoken/delete_factory

Delete an auth string for the Canarytoken Factory endpoint.

Required Parameters

auth_token string

A valid auth token

factory_auth string

An existing factory auth string

Response

A JSON structure with result indicator.

Example

curl -X DELETE https://EXAMPLE.canary.tools/api/v1/canarytoken/delete_factory \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d factory_auth=EXAMPLE_FACTORY_AUTH_TOKEN

import requests

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

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'factory_auth': 'EXAMPLE_FACTORY_AUTH_TOKEN'
}

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

print(r.json())

Response

{
  "msg": "TokenFactory auth string deleted",
  "result": "success"
}