Canary API Docs

# 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
GET /api/v1/canarytoken/list_factories
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 \
  -G

  
        Copied!
1
2
3
Response
{
  "factory_canarytokens": {
    "active-directory-login": "Active Directory Login",
    "aws-id": "AWS API Key",
    "azure-id": "Azure Login Certificate and Config",
    "azure-entra-login": "Azure Entra Login",
    "cloned-css": "Cloned CSS",
    "cloned-web": "Cloned Website",
    "credit-card": "Credit Card",
    "dns": "DNS",
    "doc-msexcel": "MS Excel Document",
    "doc-msword": "MS Word Document",
    "fast-redirect": "Fast Redirect",
    "http": "Web Bug",
    "msexcel-macro": "MS Excel Macro Document",
    "msword-macro": "MS Word Macro Document",
    "mysql-dump": "MySQL Dump file",
    "pdf-acrobat-reader": "Acrobat PDF",
    "qr-code": "QR Code",
    "sensitive-cmd": "Sensitive Command",
    "signed-exe": "Custom Exe/Binary",
    "slack-api": "Slack API Key",
    "slow-redirect": "Slow Redirect",
    "web-image": "Custom Web Image",
    "windows-dir": "Windows Folder",
    "wireguard": "WireGuard VPN"
  },
  "result": "success"
}

  
        Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 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. Please check "List Factory Tokens" for available Canarytoken kind values.

Optional Parameters

flock_id string
Defaults to: flock_id of factory
A valid flock_id (defaults to the flock_id of the token factory)
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)
expected_referrer string
Expected domain to check against (required when creating cloned-css tokens)
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)
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)
expected_referrer string
The expected referrer to make a request when creating the Cloned CSS and Azure Entra Login Canarytokens.
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
process_name string
Name of the process you want to monitor (required when creating sensitive-cmd tokens)
pwa_app_name string
Name of the Fake App for the pwa Canarytoken
pwa_icon file
Icon used by your Fake App for the pwa Canarytoken
azure_id_cert_file_name string
Azure ID config will use this as the file path to the certificate (required when creating Azure ID tokens).
tokened_usernames string
A comma separated list of Active Directory usernames to token (required when creating active-directory-login tokens)

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

  
        Copied!
1
2
3
4
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"
}

  
        Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 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

  
        Copied!
1
2
3
4
Response
$ ls -l
-rw-r--r--  1 user  thinkst  5095 Apr  7 12:29 <filename>

  
        Copied!
1
2

# 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
flock_id string
A valid flock_id
memo string
A reminder that will be included in the alert to let you know where you placed this Canarytoken

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 flock_id=flock:default \
  -d memo='Example Memo'

  
        Copied!
1
2
3
Response
{
  "factory_auth": "<factory_auth_token>",
  "factory_url": "/api/v1/canarytoken/factory",
  "result": "success"
}

  
        Copied!
1
2
3
4
5

# 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

  
        Copied!
1
2
3
Response
{
  "msg": "TokenFactory auth string deleted",
  "result": "success"
}

  
        Copied!
1
2
3
4

# List Canarytoken Factory Auth Strings

GET /api/v1/canarytoken/list_factories

List all Factory auth strings for the Canarytoken Factory endpoint.

Required Parameters

auth_token string
A valid auth token

Response

A JSON structure with a list of factory auth strings.

Example

curl https://EXAMPLE.canary.tools/api/v1/canarytoken/list_factories \
  -d auth_token=EXAMPLE_AUTH_TOKEN -G

  
        Copied!
1
2
Response
{
  "factories": [
    {
      "factory_auth": "<Factory Auth String>",
      "flock_id": "flock:default",
      "memo": "Example Memo"
    },
    {
      "factory_auth": "<Factory Auth String 2>",
      "flock_id": "flock:default",
      "memo": "Example Memo 2"
    }
  ],
  "result": "success"
}

  
        Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

← Queries →