Thinkst Canary

Purpose

To integrate Thinkst Canary with AirMDR to retrieve Canary incidents, devices (Birds), and Canarytokens and perform supported incident-response actions.

Supported Versions

Component	Supported version
Thinkst Canary	Cloud-hosted Canary Console with API access enabled
Thinkst Canary API	REST API v1
AirMDR	Current production version of the Thinkst Canary integration
Network protocol	HTTPS with TLS 1.2 or later

The integration communicates with the Canary Console API and is therefore generally independent of the individual hardware, virtual, cloud, or container Canary version.Thinkst states that its Console API requires TLS 1.2 or later.

Authentication

Thinkst Canary authenticates API requests using an API key called an auth_token. AirMDR requires:

Base URL: The HTTPS URL of your Canary Console.
API Token: A dedicated Canary Global API key.

API roles:

API role	Access
Read-Only	Reads data across the Canary Console
Analyst	Reads Console data and can acknowledge, unacknowledge, and delete alerts
Admin	Provides full API access to the Console

The role assigned to a Canary API key cannot be changed after creation.
To change its role, create a replacement key, update AirMDR, test the connection, and then remove the previous key.

Pre-requisites

Users must have Administrator access and permission to access Global Settings in the Thinkst Canary Console.

The Canary Console domain hash must be available.

Setup Steps

Open your organization’s Thinkst Canary Console.
Enter your account credentials.
Complete multi-factor authentication if required.
A standard Console URL resembles: https://<domain-hash>.canary.tools

Open Global Settings and enable the Canary API

Navigate to Canary Console.
Select the gear icon.
Select Global Settings.
From the settings menu, select API.
Check whether the API is enabled.
If it is disabled, select Enable API.
Confirm the action if prompted.
If the Console API is disabled, it must initially be enabled through the Canary Console UI.

Create an API key for AirMDR

In the API section, select the option to add or create an API key.
In the name or note field, enter a descriptive value such as: AirMDR Integration
Select required role (Admin or Analyst) as the API key role.
Create the API key.
- Record the generated Key ID for auditing and future rotation.
- Select the eye or reveal icon next to the key, if required.
Copy the displayed Auth Token.
Copy the token when it is created and store it securely. Thinkst notes that viewing an existing token after creation should be considered deprecated and may not remain available in future versions.

Obtain the Base URL

In the same API settings area, locate the Domain Hash displayed in the API section.
Navigation Path: Canary Console → Gear icon → Global Settings → API
Construct the Base URL using the following format: https://<domain-hash>.canary.tools
Example: https://abc123def456.canary.tools
Enter the Console URL only. Do not append /api/v1, /settings, /nest/settings, or another API endpoint.

You can also verify the value by checking your Canary Console browser address. Copy only the URL origin, for example: https://abc123def456.canary.tools

Thinkst Canary Credential Reference Table

AirMDR field	What to enter	Where to obtain it
Base URL	Complete HTTPS URL of the Canary Console, such as `https://abc123def456.canary.tools`	Canary Console → Global Settings → API → Domain Hash
API Token	Auth Token generated for the dedicated Analyst API key	Canary Console → Global Settings → API → select/reveal the AirMDR API key

Validate Connectivity

Use Thinkst Canary’s ping endpoint to validate the Base URL and API Token:

Sample Request

curl --request GET \
  "https://<domain-hash>.canary.tools/api/v1/ping" \
  --header "X-Canary-Auth-Token: <api-token>"

Sample Response

Sample Successful Response:

{
  "result": "success"
}

Sample Invalid Response:

{
  "message": "Unauthorized",
  "result": "error"
}

Using the X-Canary-Auth-Token header helps prevent the token from appearing in URLs and query-string logs.

Configure Thinkst Canary in AirMDR Integrations Dashboard

Navigate to AirMDR, provide the credentials and click Login
Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select ADMIN → Integrations.
Use the search option, enter the keyword “Thinkst Canary”, select the Connections tab, and click + New Connection button.

Use the following values in the AirMDR integration configuration screen:

AirMDR Field	Description	Example
Instance	Unique name for the Thinkst Canary connection	`Thinkst-Canary-Production`
Organization	Organization associated with the connection	`AirMDR Organization`
Description	Purpose of the connection	`Thinkst Canary production integration`
Base URL	Complete HTTPS URL of the Thinkst Canary Console	`https://abc123def456.canary.tools`
API Token	Auth Token generated for the dedicated Thinkst Canary API key	`<THINKST_CANARY_API_TOKEN>`

Expand Advanced Configuration if required.

In Remote Agent, select an AirMDR Remote Agent only when the Thinkst Canary Console must be reached through an approved network route or direct outbound access from AirMDR is restricted.
In Expiry, select the date on which AirMDR should treat the stored connection credentials as expired, according to your organization’s credential-rotation policy.

The AirMDR Expiry setting is a connection-management control. It does not automatically expire or rotate the API token in Thinkst Canary.

Click Save.

Skills provided by this Integration

Investigation and Enrichment Skills

These skills retrieve information without changing data in the Thinkst Canary Console. A Read-Only or higher API key can be used.

Skill ID	Purpose
List Thinkst Canary Incidents	Lists Canary incidents by acknowledgement state and time window. Use this as the starting point for incident triage and to obtain the incident keys required by other incident-related skills. An incident indicates that a Canary device or Canarytoken was accessed and requires investigation.
Get Thinkst Canary Incident	Retrieves the complete details of a specific incident using either its incident key or incident hash. Use it to review bundled events such as attempted credentials, scanned ports, source activity, or the user agent that accessed a Canarytoken. Provide either the Incident ID or Hash ID, but not both.
List Thinkst Canary Birds	Lists the Canary Birds registered with the Console. Use it to review deployed deception coverage, resolve a Bird name to its node ID, or identify Birds that have stopped reporting. The Filter String and State filters can be combined to search across Bird states.
Get Thinkst Canary Bird Info	Retrieves detailed information about one Canary Bird using its node ID. Use it to identify the decoy associated with an incident, including the device personality it emulates, its location, configuration, and reporting status.
Get Thinkst Canary Device IPs	Lists the IP addresses assigned to Canary Birds. Use the results to distinguish decoy-related activity from activity involving production assets. For large deployments, provide a Flock ID to limit the results; if omitted, the Console returns Birds across all accessible Flocks.
List Thinkst Canary Tokens	Lists Canarytokens deployed through the Console, including their type, memo, and status. Use it to review token-based deception coverage, find tokens by memo or type, and identify disabled tokens that are no longer generating alerts.

Incident Response Skills

These skills change incident data in the Thinkst Canary Console and require an Analyst or Admin API key.

Skill ID	Purpose
Acknowledge Thinkst Canary Incident	Marks a specific incident as handled and removes it from the unacknowledged queue. The action changes the incident state in the Canary Console and affects only the incident identified by its key. It can be reversed using the Unacknowledge Thinkst Canary Incident skill.
Unacknowledge Thinkst Canary Incident	Returns an acknowledged incident to the unacknowledged queue so that it appears as requiring triage again. Use it to reopen an incident that was acknowledged too early or requires further investigation based on new evidence.
Delete Thinkst Canary Incident	Permanently removes a specific incident and its associated alert history from the Canary Console. Deletion cannot be undone; use acknowledgement for normal triage and reserve deletion for intentional housekeeping or approved data-removal activities.

To view the details of Input Parameters and Output for the respective skills

Go to AirMDR → Thinkst Canary Integration page.
Select the Skills tab and click on the required listed skills.

Additional Information

🧰 Error Handling

Error or symptom	Likely cause	Recovery
`Invalid auth_token` or `Unauthorized`	Incorrect, deleted, or malformed API Token	Copy the correct token again or create a replacement API key
Connection timeout	DNS, firewall, proxy, or Remote Agent connectivity issue	Allow outbound TCP 443 to the Canary Console and verify DNS resolution
Hostname or certificate error	Incorrect Base URL or TLS interception problem	Confirm the Console domain and validate the TLS certificate chain
API endpoint not found	`/api/v1` was incorrectly included in the Base URL or URL is malformed	Enter only the Console Base URL
Incident retrieval succeeds but update fails	A Read-Only API key is configured	Replace it with a dedicated Analyst API key
API unavailable	Canary API is disabled	Enable it under Global Settings → API
Connection works manually but fails in AirMDR	Different network route or Remote Agent configuration	Test connectivity from the selected Remote Agent
Some incidents are not returned	Filtering, pagination, or synchronization checkpoint	Review integration execution details and rerun the affected skill
Key role is incorrect	Roles cannot be edited after key creation	Create a new key with the correct role and rotate the integration

🔄 Monitoring & Logs

AirMDR monitoring

Monitor the integration from the AirMDR interface for:

Connection status.
Authentication failures.
Skill execution history.
API timeouts.
Incident retrieval or update failures.
Remote Agent availability, when applicable.

Thinkst Canary monitoring

Thinkst Canary generates Audit Trail records when actions are performed on the Console. The API key’s Key ID can help identify which credential performed an API operation.Review the Console Audit Trail for:

API actions initiated by AirMDR.
Incident-state changes.
API key creation or removal.
Unexpected or unauthorized actions.

Thinkst provides an Audit Trail endpoint at: GET /api/v1/audit_trail/fetchIllustrative AirMDR log entries

INFO  Thinkst Canary connection validated successfully.
INFO  Retrieved 12 incidents from the Canary Console.
WARN  Thinkst Canary API request was rate-limited or temporarily unavailable.
ERROR Thinkst Canary authentication failed: invalid or expired API token.
ERROR Unable to connect to the configured Canary Console Base URL.

These entries illustrate the information that should be recorded; the exact AirMDR log format may differ.

Recommended log levels

INFO: Successful connection tests, synchronization, and skill execution.
WARN: Temporary API failures, retries, incomplete results, or response delays.
ERROR: Authentication failures, unreachable endpoints, or failed incident actions.
DEBUG: Enable temporarily during troubleshooting and disable afterward to avoid excessive logging.

Never record the complete API Token in logs.

🛑 Security & Access Best Practices

✅ Do

Create a dedicated API key for AirMDR.
Use the required role (Admin or Analyst) role when incident-response actions are required.
Store the API Token in the AirMDR secret field.
Use HTTPS and retain TLS certificate validation.
Identify the key with a clear name such as AirMDR Integration.
Record its Key ID for auditing and rotation.
Rotate credentials periodically and after suspected exposure.
Enable sensitive-data masking in Canary when appropriate.

❌ Avoid

Do not use an Admin API key for the standard integration.
Do not reuse a personal or shared API key.
Do not include the API Token in screenshots or documentation.
Do not place the token directly in URLs when a secure header can be used.
Do not store credentials in scripts, source control, or plaintext files.
Do not disable TLS certificate verification.
Do not delete the previous key until the replacement connection has been tested.

👉 Support & Maintenance

📧 Contact AirMDR Support through your designated support channel.
🔁 Rotate credentials regularly. Recommended cadence: Every 90 days or as per internal security policy
🔄 Reconnect in AirMDR immediately when secrets are changed.

🛑 Data Flow & Security

Data exchanged

Depending on the enabled AirMDR skills and API role, AirMDR may retrieve:

Canary incidents and alert details.
Incident timestamps and current status.
Source IP addresses and activity details.
Canary device or Bird information.
Flock information.
Canarytoken metadata.
Supporting information required for investigation and enrichment.

With an Analyst key, AirMDR may send supported incident-state actions back to Thinkst Canary, including:

Acknowledge an incident.
Unacknowledge or reopen an incident.
Delete an incident when the corresponding AirMDR skill is used.

Encryption

AirMDR-to-Canary Console API traffic uses HTTPS.
Thinkst requires TLS 1.2 or later for Console API communication.
Keep TLS certificate verification enabled.
Do not transmit the API Token through email, tickets, chat messages, or documentation.

The public API documentation verifies encryption in transit but does not specify the Console’s at-rest encryption algorithm. Refer to the applicable Thinkst and AirMDR security documentation for contractual at-rest encryption controls.

Ports and endpoints

Direction	Protocol and port	Destination or endpoint	Purpose
AirMDR/Remote Agent → Canary Console	HTTPS/TCP 443	`https://<domain-hash>.canary.tools`	API authentication and data exchange
AirMDR/Remote Agent → Canary Console	HTTPS/TCP 443	`/api/v1/ping`	Connection validation
AirMDR/Remote Agent → Canary Console	HTTPS/TCP 443	`/api/v1/incidents/*`	Retrieve or manage incidents
Canary device → DNS resolver	DNS/UDP or TCP 53	Organization’s configured DNS resolver	Canary device-to-Console management communication

DNS port 53 is used by Canary devices for their normal Console communication. It is not the protocol used by AirMDR to call the Canary API.

Getting Started

AirMDR Detections

Integrations

API Reference

AirMDR Product Suite

Thinkst Canary

Purpose

Supported Versions

Authentication

Pre-requisites

Setup Steps

Thinkst Canary Credential Reference Table

Validate Connectivity

Configure Thinkst Canary in AirMDR Integrations Dashboard

Skills provided by this Integration

Additional Information

AirMDR monitoring

Thinkst Canary monitoring

Recommended log levels

✅ Do

❌ Avoid

Data exchanged

Encryption

Ports and endpoints

​Purpose

​Supported Versions

​Authentication

​Pre-requisites

​Setup Steps

​Thinkst Canary Credential Reference Table

​Validate Connectivity

​Configure Thinkst Canary in AirMDR Integrations Dashboard

​Skills provided by this Integration

​Additional Information

​AirMDR monitoring

​Thinkst Canary monitoring

​Recommended log levels

​✅ Do

​**❌ **Avoid

​Data exchanged

​Encryption

​Ports and endpoints

Purpose

Supported Versions

Authentication

Pre-requisites

Setup Steps

Thinkst Canary Credential Reference Table

Validate Connectivity

Configure Thinkst Canary in AirMDR Integrations Dashboard

Skills provided by this Integration

Additional Information

AirMDR monitoring

Thinkst Canary monitoring

Recommended log levels

✅ Do

❌ Avoid

Data exchanged

Encryption

Ports and endpoints