Thinkst Canary

Thinkst Canary is a deception technology platform that helps organizations detect intrusions by deploying honeypots and Canarytokens.

Thinkst Canary is a leading deception technology platform designed to detect intrusions and unauthorized access by deploying decoy systems and tokens. The Thinkst Canary connector for Swimlane Turbine enables seamless integration for automated incident management, allowing users to acknowledge, delete, and fetch incidents and Canarytokens efficiently. This integration enhances threat detection and response capabilities, providing Swimlane Turbine users with real-time insights and automated workflows to manage security incidents effectively.

Limitations

None to date.

Supported Versions

This Thinkst Canary connector uses the v1 API.

Additional Documents

Documentation Thinkst Canary

Configuration

Prerequisites

Before you can use the Thinkst Canary connector for Turbine, you'll need access to the Thinkst Canary API. This requires the following:

Authentication using an Authentication Token:

URL: The endpoint URL for accessing the Thinkst Canary API.

Auth Token: A valid authentication token to authorize API requests.

Authentication Methods

URL: The endpoint URL for accessing the Thinkst Canary API.

Auth Token: A token used to authenticate API requests securely.

Capabilities

This Thinkst Canary connector provides the following capabilities:

Acknowledge Incident

All Incidents

Create Canarytoken

Delete Canarytoken

Delete Incident

Fetch Tokens

Acknowledge Incident

Acknowledge a specified incident Click Here.

All Incidents

Returns all incidents Click Here.

Create Canarytoken

Create a new Canarytoken Click Here.

Delete Canarytoken

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

Delete Incident

Deletes a specified incident Click Here.

Fetch Tokens

Fetch all created Canarytokens Click Here.

Configurations

Thinkst Canary Asset

Authenticates using Authentication Token.

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
auth_token	Auth token.	string	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Acknowledge Incident

Acknowledge a specified incident in Thinkst Canary using the provided data body.

Endpoint

URL: api/v1/incident/acknowledge

Method: POST

Input

Argument Name	Type	Required	Description
data_body	object	Required	Response data
data_body.incident	string	Required	A valid incident key.

Input Example

{"data_body":{"incident":"example_incident"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
action	string	Output field: action
key	string	Output field: key
result	string	Result of the operation

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"action":"acknowledged","key":"<incident_key>","result":"success"}}

All Incidents

Returns a comprehensive list of all incidents recorded in Thinkst Canary.

Endpoint

URL: api/v1/incidents/all

Method: GET

Input

Argument Name	Type	Required	Description
parameters.node_id	string	Optional	Get all incidents associated with a specific Canary or Canarytoken node_id.
parameters.flock_id	string	Optional	Get all incidents for a specific flock_id.
parameters.incidents_since	number	Optional	Only return incidents whose updated_id is greater than this integer. The returned feed includes a max_updated_id field if the incident list has entries.
parameters.newer_than	string	Optional	Timestamp used to filter returned incidents in the format "yyyy-mm-dd-hh:mm:ss". All incidents created strictly after this timestamp will be returned. Incidents may be missed when using this for polling, and it is advised to use incidents_since for that purpose instead.
parameters.older_than	string	Optional	Timestamp used to filter returned incidents in the format yyyy-mm-dd-hh:mm:ss. All incidents created strictly before this timestamp will be returned.
parameters.event_limit	number	Optional	Specify the maximum number of event logs to be returned with the incident.
parameters.limit	number	Optional	Parameter used to initiate cursor pagination. The limit is used to specify the page sizes returned when iterating through the pages representing all incidents.
parameters.cursor	string	Optional	The cursor string retrieved from the cursor element returned along with a page while doing pagination.
parameters.shrink	boolean	Optional	A 'true' value will remove duplicated entries (some older Consoles will have this defaulted to false, but you'd already know about it if you're on one of those consoles).
parameters.tz	string	Optional	Timezone for standardised timestamps (fields that end in "_std").

Input Example

{"parameters":{"node_id":"example_node_id","flock_id":"example_flock_id","incidents_since":1,"newer_than":"example_newer_than","older_than":"example_older_than","event_limit":100,"limit":100,"cursor":"example_cursor","shrink":true,"tz":"example_tz"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
cursor	object	Output field: cursor
cursor.next	string	Output field: cursor.next
cursor.next_link	string	Output field: cursor.next_link
cursor.prev	object	Output field: cursor.prev
cursor.prev_link	object	Output field: cursor.prev_link
feed	string	Output field: feed
incidents	array	Unique identifier
incidents.description	object	Unique identifier
incidents.description.acknowledged	string	Unique identifier
incidents.description.created	string	Unique identifier
incidents.description.created_std	string	Unique identifier
incidents.description.description	string	Unique identifier
incidents.description.dst_host	string	Unique identifier
incidents.description.dst_port	string	Unique identifier
incidents.description.events	array	Unique identifier
incidents.description.events.canarytoken	string	Unique identifier
incidents.description.events.dst_port	number	Unique identifier
incidents.description.events.event_name	string	Unique identifier
incidents.description.events.headers	object	HTTP headers for the request
incidents.description.events.headers.Accept	string	HTTP headers for the request
incidents.description.events.headers.Accept-Encoding	string	HTTP headers for the request
incidents.description.events.headers.Connection	string	HTTP headers for the request
incidents.description.events.headers.User-Agent	string	HTTP headers for the request

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"cursor":{"next":"MTE6MTA6MTQ0OjE6MjowOjI6NQ==","next_link":"https://EXAMPLE.canary.tools/api/v1/incidents/all?cursor=MTE6MTA6MTQ0OjE6MjowOjI...","prev":null,"prev_link":null},"feed":"All Incidents","incidents":[{}],"max_updated_id":10,"result":"success","updated":"Tue, 07 Apr 2020 08:53:43 GMT","updated_std":"2020-04-07 08:53:43 UTC+0000","updated_timestamp":1586249623}}

Create Canarytoken

Create a new Canarytoken in Thinkst Canary using the provided data body.

Endpoint

URL: /api/v1/canarytoken/create

Method: POST

Input

Argument Name	Type	Required	Description
data_body	object	Required	Response data
data_body.kind	string	Required	Specifies the type of Canarytoken.
data_body.memo	string	Required	A reminder that will be included in the alert to let you know where you placed this Canarytoken, limited to 10000 characters.
data_body.aws_access_key	string	Optional	AWS Access Key ID (required if automating creation of AWS S3 token).
data_body.aws_secret_key	string	Optional	AWS Secret Access Key (required if automating creation of AWS S3 token).
data_body.aws_session_token	string	Optional	AWS Session Token (required if automating creation of AWS S3 token, using temporary credentials).
data_body.aws_region	string	Optional	AWS Region (required if automating creation of AWS S3 token).
data_body.azure_id_cert_file_name	string	Optional	Azure ID config will use this as the file path to the certificate (required when creating Azure ID tokens).
data_body.browser_redirect_url	string	Optional	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).
data_body.browser_scanner_enabled	boolean	Optional	Enables a Javascript scanner to retrieve more information (only valid with 'http' Canarytokens).
data_body.cloned_web	string	Optional	Domain to check against (required when creating cloned-web tokens).
data_body.custom_domain	string	Optional	Specifies the custom Canarytoken domain to use (that's already been linked to the Console) when creating a Canarytoken.
data_body.expiry	string	Optional	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).
data_body.expected_referrer	string	Optional	The expected referrer to make a request when creating the Cloned CSS and Azure Entra Login Canarytokens.
data_body.flock_id	string	Optional	A valid flock_id (defaults to the Default Flock or flock id of auth_token if using Canarytoken Deploy Flock API key type).
data_body.idp_app_type	string	Optional	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.
data_body.process_name	string	Optional	Name of the process you want to monitor (required when creating sensitive-cmd tokens).
data_body.pwa_app_name	string	Optional	Name of the Fake App for the pwa Canarytoken.
data_body.pwa_icon	string	Optional	Name of the icon used by your Fake App for the pwa Canarytoken.
data_body.s3_log_bucket	string	Optional	S3 bucket where logs will be stored (required when creating aws-s3 tokens).
data_body.s3_source_bucket	string	Optional	S3 bucket to monitor for access (required when creating aws-s3 tokens).
data_body.tokened_usernames	string	Optional	A comma separated list of Active Directory usernames to token (required when creating active-directory-login tokens).
form_data	object	Optional	Response data
form_data.doc	object	Optional	Upload MS Word Document to canarytoken; optionally used with MS Word Document (doc-msword) token.
form_data.doc.file_name	string	Required	Response data

Input Example

{"data_body":{"kind":"example_token_kind","memo":"example_memo","aws_access_key":"example_aws_access_key","aws_secret_key":"example_aws_secret_key","aws_session_token":"example_aws_session_token","aws_region":"example_aws_region","azure_id_cert_file_name":"example_azure_id_cert_file_name","browser_redirect_url":"example_browser_redirect_url","browser_scanner_enabled":true,"cloned_web":"example_cloned_web_url","custom_domain":"example_custom_domain","expiry_date":"example_expiry_date","expected_referrer":"example_expected_referrer","flock_id":"flock:default","idp_app_type":"aws","process_name":"example_process_name","pwa_app_name":"example_pwa_app_name","pwa_icon":"example_pwa_icon","s3_log_bucket":"example_s3_log_bucket","s3_source_bucket":"example_s3_source_bucket","tokened_usernames":"example_tokened_usernames"},"form_data":{"doc":{"file_name":"example_file_name","file":"2"},"exe":{"file_name":"example_file_name","file":"4"},"pdf":{"file_name":"example_file_name","file":"3"},"web_image":[{"file_name":"example_file_name","file":"1"}]}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
canarytoken	object	Output field: canarytoken
canarytoken.browser_scanner_enabled	boolean	Output field: canarytoken.browser_scanner_enabled
canarytoken.canarytoken	string	Output field: canarytoken.canarytoken
canarytoken.created	string	Output field: canarytoken.created
canarytoken.created_printable	string	Output field: canarytoken.created_printable
canarytoken.enabled	boolean	Output field: canarytoken.enabled
canarytoken.flock_id	string	Unique identifier
canarytoken.hostname	string	Name of the resource
canarytoken.key	string	Output field: canarytoken.key
canarytoken.kind	string	Output field: canarytoken.kind
canarytoken.memo	string	Output field: canarytoken.memo
canarytoken.triggered_count	number	Count value
canarytoken.updated_id	number	Unique identifier
canarytoken.url	string	URL endpoint for the request
result	string	Result of the operation

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"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 Canarytoken

Delete a Canarytoken in Thinkst Canary after clearing all associated incidents. Use clear_incidents=true to remove incidents automatically.

Endpoint

URL: api/v1/canarytoken/delete

Method: POST

Input

Argument Name	Type	Required	Description
data_body	object	Required	Response data
data_body.canarytoken	string	Required	A valid Canarytoken.
data_body.clear_incidents	boolean	Optional	Delete associated incidents.

Input Example

{"data_body":{"canarytoken":"example_canarytoken","clear_incidents":true}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
result	string	Result of the operation

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"result":"success"}}

Delete Incident

Delete a specified incident in Thinkst Canary using the provided data body.

Endpoint

URL: api/v1/incident/delete

Method: DELETE

Input

Argument Name	Type	Required	Description
data_body	object	Required	Response data
data_body.incident	string	Required	A valid incident key.

Input Example

{"data_body":{"incident":"example_incident"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
action	string	Output field: action
key	string	Output field: key
result	string	Result of the operation

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"action":"deleted","key":"<incident_key>","result":"success"}}

Fetch Tokens

Fetch all created Canarytokens from Thinkst Canary for monitoring and analysis.

Endpoint

URL: api/v1/canarytokens/fetch

Method: GET

Input

Argument Name	Type	Required	Description
parameters.flock_id	string	Optional	A valid flock_id (for returning Canarytokens for a specific Flock).
parameters.include_endpoints	string	Optional	Include factory endpoints (such as ApeeperFactory).

Input Example

{"parameters":{"flock_id":"example_flock_id","include_endpoints":"ApeeperFactory"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
result	string	Result of the operation
tokens	array	Output field: tokens
tokens.browser_scanner_enabled	boolean	Output field: tokens.browser_scanner_enabled
tokens.canarytoken	string	Output field: tokens.canarytoken
tokens.created	string	Output field: tokens.created
tokens.created_printable	string	Output field: tokens.created_printable
tokens.enabled	boolean	Output field: tokens.enabled
tokens.flock_id	string	Unique identifier
tokens.hostname	string	Name of the resource
tokens.key	string	Output field: tokens.key
tokens.kind	string	Output field: tokens.kind
tokens.memo	string	Output field: tokens.memo
tokens.node_id	string	Unique identifier
tokens.triggered_count	number	Count value
tokens.updated_id	number	Unique identifier
tokens.url	string	URL endpoint for the request

Output Example

{"status_code":200,"response_headers":{},"reason":"OK","json_body":{"result":"success","tokens":[{}]}}

Response Headers

Header	Description	Example
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 GMT