# Actions

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

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

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

1
2

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"
}
 
        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
33
34
35
36
37

# 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
Python

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

1
2
3
4

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"
}
 
        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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

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

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'

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)

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)

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

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 created Canarytoken information.

Example

cURL
Python

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

1
2
3
4

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 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
Python

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

1
2
3

Response

{
  "result": "success"
}
 
        Copied!

1
2
3

# Bulk Delete Canarytokens

POST /api/v1/canarytokens/delete

Bulk delete Canarytokens that match the specified criterion. You'll need to delete all incidents on the matching tokens before you can delete the tokens, otherwise 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.

Response

A JSON structure with result indicator.

Example

cURL
Python

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

1
2
3

Response

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

1
2
3
4

# 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
Python

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

1
2
3

Response

{
  "result": "success"
}
 
        Copied!

1
2
3

# 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
Python

curl https://EXAMPLE.canary.tools/api/v1/canarytoken/download \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -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

# 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
Python

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

1
2
3

Response

{
  "result": "success"
}
 
        Copied!

1
2
3

# 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
Python

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

1
2
3
4

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 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
Python

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
 
        Copied!

1
2
3
4
5
6

Response

{
  "result": "success"
}
 
        Copied!

1
2
3

# 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
Python

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

1
2
3
4

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 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
Python

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'
 
        Copied!

1
2
3
4

Response

{
  "result": "success",
}
 
        Copied!

1
2
3

← Mass Deployment Cloned Web Ignore List →