# Actions
These are a collection of endpoints that allow you to mint new, interact with, and view your existing Canarytokens.
Endpoints
# 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
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",
"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"
}
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
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
# 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
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"
}
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
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 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'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/pdfprocess_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 filestokened_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
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"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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
Response
{
"result": "success"
}
1
2
3
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
Response
{
"result": "success",
"deleted_count": 1
}
1
2
3
4
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
Response
{
"result": "success"
}
1
2
3
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
Response
$ ls -l
-rw-r--r-- 1 user thinkst 5095 Apr 7 12:29 <filename>
1
2
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
Response
{
"result": "success"
}
1
2
3
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
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>"
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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
Response
{
"result": "success"
}
1
2
3
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
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>"
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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
Response
{
"result": "success",
}
1
2
3
2
3