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/fetch

POST /api/v1/apeeperfactory/delete

POST /api/v1/canarytoken/create

POST /api/v1/canarytoken/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

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": {
    "apeeper": "EC2 Meta-data Service", 
    "autoreg-google-docs": "Google Doc", 
    "autoreg-google-sheets": "Google Sheet", 
    "aws-id": "AWS API Key", 
    "aws-s3": "AWS S3 Bucket", 
    "cloned-web": "Cloned Website", 
    "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", 
    "googledocs_factorydoc": "Document Factory", 
    "googlesheets_factorydoc": "Document Factory", 
    "http": "Web Bug", 
    "msexcel-macro": "MS Excel Macro Document", 
    "msword-macro": "MS Word Macro Document", 
    "office365mail": "Office 365 Mail Bug", 
    "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"
}

Fetch all Canarytokens

GET /api/v1/canarytokens/fetch

Fetches all 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/fetch \
  -d auth_token=EXAMPLE_AUTH_TOKEN -G

import requests

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

payload = {
  'auth_token': 'EXAMPLE_AUTH_TOKEN'
}

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

print(r.json())

Response

{
  "tokens": {
      {
        "browser_scanner_enabled": "True",
        "canarytoken": "<token_code>",
        "created": "1685958255.606980'",
        "created_printable": "2023-06-05 09:44:15 (UTC)'",
        "enabled": "True",
        "flock_id": "flock:default'",
        "hostname": "<token_hostname>",
        "key": "<token_key>",
        "kind": "http'",
        "memo": "desktop",
        "node_id": "<token_node_id>", 
        "triggered_count": "0",
        "updated_id": "1",
        "url": "<token_url>"
      },
      {
        "canarytoken": "<token_code>",
        "created": "1688122821.384507",
        "created_printable": "2023-06-30 11:00:21 (UTC)",
        "enabled": "True",
        "flock_id": "flock:default",
        "hostname": "<token_hostname>",
        "key": "<token_key>",
        "kind": "dns",
        "memo": "mail inbox",
        "node_id": "<token_node_id>",
        "triggered_count": "0",
        "updated_id": "2",
        "url": "<token_url>"
      }
  }, 
  "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 Secret Access Key (required if automating creation of AWS S3 token)

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)

exe string

The Windows executable that you would like tokened (required when creating signed-exe 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'

flock_id string

Defaults to: 'flock:default'

A valid flock_id (defaults to the Default Flock)

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)

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)

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

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

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.

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