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

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

Create Canarytoken

POST /api/v1/canarytoken/create

Create a new Canarytoken.

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

kind string

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

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)

s3_source_bucket string

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

s3_log_bucket string

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

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)

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 the client wants to create an AWS API key linked to certain NameError otherwise its randomly generated (optional when creating aws-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)

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

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

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