Actions

These are a collection of endpoints that allow you to mint new, interact with, and view your existing Canarytokens.

Endpoints

GET /api/v1/canarytokens/list

GET /api/v1/canarytokens/paginate

POST /api/v1/apeeperfactory/delete

POST /api/v1/canarytoken/create

POST /api/v1/canarytoken/delete

POST /api/v1/canarytokens/delete

POST /api/v1/canarytoken/disable

GET /api/v1/canarytoken/download

POST /api/v1/canarytoken/enable

GET /api/v1/canarytoken/fetch

POST /api/v1/canarytoken/remove/s3

POST /api/v1/canarytoken/update

POST /api/v1/canarytoken/update/redirect_url

List Kinds of Canarytokens

TIP

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

GET /api/v1/canarytokens/list

Lists the available Canarytokens on your Canary Console.

Required Parameters

auth_token string

A valid auth token

Response

A JSON structure with result indicator and Canarytokens information.

Example

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

import requests

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

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN'
}

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

print(r.json())

Response

{
  "canarytokens": {
      "active-directory-login": "Active Directory Login",
      "autoreg-google-docs": "Google Doc",
      "autoreg-google-sheets": "Google Sheet",
      "aws-id": "AWS API Key",
      "aws-s3": "AWS S3 Bucket",
      "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",
      "gmail": "Gmail",
      "google-docs": "Google Doc",
      "google-sheets": "Google Sheet",
      "http": "Web Bug",
      "msexcel-macro": "MS Excel Macro Document",
      "msword-macro": "MS Word Macro Document",
      "mysql-dump": "MySQL Dump File",
      "office365mail": "Office 365 Mail Bug",
      "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",
      "web-image": "Custom Web Image",
      "windows-dir": "Windows Folder",
      "wireguard": "WireGuard VPN",
  },
    "result": "success"
}

Paginate Canarytokens

GET /api/v1/canarytokens/paginate

Fetch a page of all your Canarytokens with a specified limit per page, as well as cursors that allow you to iterate through the remaining pages.

Required Parameters

auth_token string

A valid auth token

Optional Parameters

flock_id string

A valid flock_id (for returning Canarytokens for a specific Flock)

limit string

Defaults to: 10

The size of the pages

cursor string

A valid page cursor retrieved from the cursor element returned along with a page while doing pagination

Response

A JSON structure with the current page of Canarytokens and cursors pointing to your next and previous pages.

Example

curl https://EXAMPLE.canary.tools/api/v1/canarytokens/paginate \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d limit=3
  -G

import requests

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

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'limit':'3'
}

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

print(r.json())

Response

{
  "canarytokens": [
    {
      "access_key_id": "<aws_access_key_id>",
      "canarytoken": "<token_code>",
      "created": "1586249510.069870",
      "created_printable": "2020-04-07 08:51:50 (UTC)",
      "enabled": true,
      "factory_auth": "<factory_auth_token>",
      "flock_id": "flock:default",
      "hostname": "<token_hostname>",
      "key": "<token_key>",
      "kind": "aws-id",
      "memo": "Example Memo",
      "node_id": "<node_id>",
      "renders": {
        "aws-id": "\n    [default]\n    aws_access_key_id = <aws_access_key_id>\n    aws_secret_access_key = <aws_secret_access_key>"
      },
      "secret_access_key": "<aws_secret_access_key>",
      "triggered_count": 0,
      "updated_id": 17,
      "url": "<token_url>",
      "username": "<user_name>"
    },
    {
      "access_key_id": "<aws_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": "<token_key>",
      "kind": "aws-id",
      "memo": "Example Memo",
      "node_id": "<node_id>",
      "renders": {
        "aws-id": "\n    [default]\n    aws_access_key_id = <aws_access_key_id>\n    aws_secret_access_key = <aws_secret_access_key>"
      },
      "secret_access_key": "<aws_secret_access_key>",
      "triggered_count": 4,
      "updated_id": 14,
      "url": "<token_url>",
      "username": "<user_name>"
    },
    {
      "canarytoken": "<token_code>",
      "cloned_web": "<cloned_domain>",
      "created": "1586183526.183108",
      "created_printable": "2020-04-06 14:32:06 (UTC)",
      "enabled": true,
      "flock_id": "flock:default",
      "hostname": "<token_hostname>",
      "key": "<token_key>",
      "kind": "cloned-web",
      "memo": "Cloned website detector on <cloned_domain>",
      "node_id": "<node_id>",
      "renders": {
        "cloned-web": "<script>\n    if (document.domain != \"<cloned_domain>\" && document.domain != \"<cloned_domain>\") {\n        var l = location.href;\n        var r = document.referrer;\n        var m = new Image();\n        m.src = \"<token_url>\" + encodeURI(l) + \"&r=\" + encodeURI(r);\n    }\n</script>"
      },
      "triggered_count": 0,
      "updated_id": 12,
      "url": "<token_url>"
    }
  ],
  "cursor": {
    "next": "MToxMjozOjQ6Mjo0",
    "next_link": "https://EXAMPLE.canary.tools/api/v1/canarytokens/paginate?cursor=MToxMjozOjQ6Mjo0&auth_token=EXAMPLE_AUTH_TOKEN",
    "prev": null,
    "prev_link": null
  },
  "page_num": 1,
  "page_total": 4,
  "result": "success"
}

Create Canarytoken

POST /api/v1/canarytoken/create

Create a new Canarytoken.

Required Parameters

auth_token string

A valid auth token

kind string

Specifies the type of Canarytoken. Please check "List Canarytokens" for available Canarytoken kind values.

memo string

A reminder that will be included in the alert to let you know where you placed this Canarytoken, limited to 10000 characters.

Optional Parameters

aws_access_key string

AWS Access Key ID (required if automating creation of AWS S3 token)

aws_secret_key string

AWS Secret Access Key (required if automating creation of AWS S3 token)

aws_session_token string

AWS Session Token (required if automating creation of AWS S3 token, using temporary credentials)

aws_region string

AWS region (required if automating creation of AWS S3 token)

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).

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)

browser_scanner_enabled boolean

Defaults to: true

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

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

expiry string

Specifies the expiry when creating a Canarytoken. String format using y, mo, w, d, h are supported. E.g. 12h, 6mo (Only AWS API Key token)

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'

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.

flock_id string

Defaults to: 'flock:default' or flock_id of auth_token

A valid flock_id (defaults to the Default Flock or flock id of auth_token if using Canarytoken Deploy Flock API key type)

idp_app_type string

Type of the Fake App for the IdP App Canarytoken. Valid options are: aws, azure, bitwarden, dropbox, duo, elasticsearch, freshbooks, gcloud, gdrive, github, gitlab, gmail, intune, jamf, jira, kibana, lastpass, ms365, msteams, onedrive, onepassword, outlook, pagerduty, sage, salesforce, sap, slack, virtru, zendesk, zoho, zoom.

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 string

Name of the icon used by your Fake App for the pwa Canarytoken

s3_log_bucket string

S3 bucket where logs will be stored (required when creating aws-s3 tokens)

s3_source_bucket string

S3 bucket to monitor for access (required when creating aws-s3 tokens)

tokened_usernames string

A comma separated list of Active Directory usernames to token (required when creating active-directory-login tokens)

web_image file

Upload an Image file (jpeg or png) that will be displayed on the Canarytokens URL (required when creating web-image tokens) With curl use the following flag: -F 'web_image=@upload-me.png; type=image/png' for png files -F 'web_image=@upload-me.jpg; type=image/jpeg' for jpeg files

Response

A JSON structure with the created Canarytoken information.

Example

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

import requests

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

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

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

print(r.json())

Response

{
  "canarytoken": {
    "browser_scanner_enabled": true,
    "canarytoken": "<token_code>",
    "created": "1586161315.087693",
    "created_printable": "2020-04-06 08:21:55 (UTC)",
    "enabled": true,
    "flock_id": "flock:default",
    "hostname": "<token_hostname>",
    "key": "<token_key>",
    "kind": "http",
    "memo": "Example Memo",
    "triggered_count": 0,
    "updated_id": 7,
    "url": "<token_url>"
  },
  "result": "success"
}

Delete Apeeper Canarytoken Factory

POST /api/v1/apeeperfactory/delete

Delete an Apeeper Canarytoken factory.

Required Parameters

auth_token string

A valid auth token

hash string

A valid ApeeperFactory hash

Response

A JSON structure with result indicator.

Delete Canarytoken

POST /api/v1/canarytoken/delete

Delete a Canarytoken. You'll need to delete all incidents on a token before you can delete the token itself. If there are still incidents attached to the token, you can specify `clear_incidents=true` to delete them all.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken

Optional Parameters

clear_incidents boolean

Delete associated incidents

Response

A JSON structure with result indicator.

Example

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

import requests

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

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'canarytoken': 'EXAMPLE_CANARYTOKEN'
}

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

print(r.json())

Response

{
  "result": "success"
}

Bulk Delete Canarytokens

POST /api/v1/canarytokens/delete

Bulk delete Canarytokens that match the specified criterion. If clear_incidents is specified, all incidents on all tokens to be deleted will also be deleted. If clear_incidents is not specified or false and any incidents exist on matching tokens, no tokens will be deleted and an error returned.

Required Parameters

auth_token string

A valid auth token

domains string

A comma separated list of custom domains from which all tokens should be deleted.

Optional Parameters

clear_incidents boolean

If true, delete all incidents on all matching tokens before deleting matching tokens

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/canarytokens/delete \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d domains="EXAMPLE_DOMAIN1,EXAMPLE_DOMAIN2"

import requests

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

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'domains': 'EXAMPLE_DOMAIN1,EXAMPLE_DOMAIN2'
}

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

print(r.json())

Response

{
  "result": "success",
  "deleted_count": 1
}

Disable Canarytoken

POST /api/v1/canarytoken/disable

Disable a Canarytoken.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken

Response

A JSON structure with result indicator.

Example

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

import requests

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

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'canarytoken': 'EXAMPLE_CANARYTOKEN'
}

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

print(r.json())

Response

{
  "result": "success"
}

Download Canarytoken

GET /api/v1/canarytoken/download

Download the generated file (if one exists) for the supplied Canarytoken.

Required Parameters

auth_token string

A valid auth token

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/download \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d canarytoken=EXAMPLE_CANARYTOKEN \
  -G -L -O -J

import requests
import re


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

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  '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>

Enable Canarytoken

POST /api/v1/canarytoken/enable

Enable a disabled Canarytoken.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken

Response

A JSON structure with result indicator.

Example

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

import requests

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

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'canarytoken': 'EXAMPLE_CANARYTOKEN'
}

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

print(r.json())

Response

{
  "result": "success"
}

Fetch a Canarytoken

GET /api/v1/canarytoken/fetch

Fetch information about a specific Canarytoken.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken

Response

A JSON structure with the Canarytoken.

Example

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

import requests

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

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'canarytoken': 'EXAMPLE_CANARYTOKEN'
}

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

print(r.json())

Response

{
  "result": "success",
  "token": {
    "canarytoken": "<token_code>",
    "created": "1585947523.255526",
    "created_printable": "2020-04-03 20:58:43 (UTC)",
    "enabled": true,
    "flock_id": "flock:default",
    "hostname": "<token_hostname>",
    "key": "<token_key>",
    "kind": "dns",
    "memo": "Example Memo",
    "triggered_count": 0,
    "updated_id": 4,
    "url": "<token_url>"
  }
}

Remove AWS S3 Canarytoken

POST /api/v1/canarytoken/remove/s3

Remove an AWS S3 Canarytoken from your Amazon console.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken

aws_access_key string

AWS Access Key ID (this is not stored on the Console and is only used for the duration of the operation)

aws_secret_key string

AWS Secret Access Key (this is not stored on the Console and is only used for the duration of the operation)

aws_region string

AWS Region where the token is located

Optional Parameters

aws_session_token string

AWS Session Token. Required when using temporary AWS authentication (this is not stored on the Console and is only used for the duration of the operation)

delete_buckets boolean

Defaults to: false

Boolean indicating if buckets must be deleted

s3_source_bucket string

Name of the S3 bucket which was being monitored (required if delete_buckets is true)

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/canarytoken/remove/s3 \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d canarytoken=EXAMPLE_CANARYTOKEN \
  -d aws_access_key=EXAMPLE_AWS_ACCESS_KEY \
  -d aws_secret_key=EXAMPLE_AWS_SECRET_KEY \
  -d aws_region=EXAMPLE_AWS_REGION

import requests

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

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'canarytoken': 'EXAMPLE_CANARYTOKEN',
  'aws_access_key': 'EXAMPLE_AWS_ACCESS_KEY',
  'aws_secret_key': 'EXAMPLE_AWS_SECRET_KEY',
  'aws_region': 'EXAMPLE_AWS_REGION'
}

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

print(r.json())

Response

{
  "result": "success"
}

Update Canarytoken Memo

POST /api/v1/canarytoken/update

Update the memo of a Canarytoken.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken

memo string

A reminder that will be included in the alert to let you know where you placed this Canarytoken, limited to 10000 characters.

Response

A JSON structure with result indicator.

Example

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

import requests

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

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

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

print(r.json())

Response

{
  "result": "success",
  "token": {
    "canarytoken": "<token_code>",
    "created": "1585947523.255526",
    "created_printable": "2020-04-03 20:58:43 (UTC)",
    "enabled": true,
    "flock_id": "flock:default",
    "hostname": "<token_hostname>",
    "key": "<token_key>",
    "kind": "dns",
    "memo": "Updated Example Memo",
    "triggered_count": 0,
    "updated_id": 4,
    "url": "<token_url>"
  }
}

Update Canarytoken Redirect URL

POST /api/v1/canarytoken/update/redirect_url

Update the redirect URL of a Canarytoken that supports redirects.

Required Parameters

auth_token string

A valid auth token

canarytoken string

A valid Canarytoken that support redirects (e.g. slow redirect token or QR code token)

redirect_url string

A valid url that the user should be redirected to after opening the Canarytoken

Response

A JSON structure with result indicator.

Example

curl https://EXAMPLE.canary.tools/api/v1/canarytoken/update/redirect_url \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d canarytoken=EXAMPLE_CANARYTOKEN \
  -d redirect_url='https://example.com'

import requests

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

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN',
  'canarytoken': 'EXAMPLE_CANARYTOKEN',
  'redirect_url': 'https://example.com'
}

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

print(r.json())

Response

{
  "result": "success",
}