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

NOTE

We recommend that you use the Canarytoken Deploy Flock API Key type, instead of Factory Auth Tokens.

The Canarytoken Deploy Flock API type is specifically designed to only be able to create and download (deploy) Canarytokens within a specific flock, and can be viewed/managed from the Console UI Flock API settings (opens new window) in the same way as your other Flock API keys.

Existing Canarytoken Factory Endpoints and factory auth strings continue to work as before to support existing deployments. They are now simpler to manage in the Console UI as they're transparently converted to Canarytoken Deploy Flock API keys.

# 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-entra-login": "Azure Entra Login",
      "azure-id": "Azure Login Certificate and Config",
      "cloned-css": "CSS cloned site",
      "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",
      "pwa": "Fake App",
      "qr-code": "QR Code",
      "sensitive-cmd": "Sensitive Command",
      "signed-exe": "Custom Exe/Binary",
      "slack-api": "Slack API Key",
      "slow-redirect": "Slow Redirect",
      "sql": "SQL Server",
      "svn": "SVN Repo",
      "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
30
31
32

# 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 file
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)
custom_domain string
Specifies the custom Canarytoken domain to use (that's already been linked to the Console) when creating a Canarytoken
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 file
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.
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
idp_app_type string
Type of the Fake App for the IdP App Canarytoken
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 string
Name of the 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 →