> ## Documentation Index > Fetch the complete documentation index at: https://docs.airmdr.com/llms.txt > Use this file to discover all available pages before exploring further. # Thinkst Canary > The Thinkst Canary integration enables AirMDR to retrieve and enrich security alerts generated by Canary devices and Canarytokens. When configured with an Analyst API key, AirMDR can also update supported incident states during investigation and response. ## 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 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 1. Open your organization’s Thinkst Canary Console. 2. Enter your account credentials. 3. Complete multi-factor authentication if required.
A standard Console URL resembles: `https://.canary.tools` 1. Navigate to Canary Console. 2. Select the **gear** icon. 3. Select **Global Settings**. 4. From the settings menu, select **API**. 5. Check whether the API is enabled. 6. If it is disabled, select **Enable API**. 7. Confirm the action if prompted. If the Console API is disabled, it must initially be enabled through the Canary Console UI. 1. In the **API** section, select the option to add or create an API key. 2. In the name or note field, enter a descriptive value such as: `AirMDR Integration` 3. Select required role (**Admin** or **Analyst**) as the API key role. 4. 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. 5. 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. 1. In the same API settings area, locate the **Domain Hash** displayed in the API section. **Navigation Path: Canary Console → Gear icon → Global Settings → API** 2. Construct the Base URL using the following format: `https://.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: ```json theme={null} curl --request GET \ "https://.canary.tools/api/v1/ping" \ --header "X-Canary-Auth-Token: " ``` **Sample Successful Response:** ```text theme={null} { "result": "success" } ``` **Sample Invalid Response:** ```text theme={null} { "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 1. Navigate to [AirMDR](https://app.airmdr.com/auth/login), provide the credentials and click **Login** 2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select **ADMIN → Integrations**. 3. Use the search option, enter the keyword "**Thinkst Canary**", select the **Connections** tab, and click **+ New Connection** button. 4. 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 | `` | * 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. 5. Click **Save**. ### Skills provided by this Integration 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. | 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](https://dev-darryl.airmdr.com/integrationsv2/6b39bd71-a837-4f7f-9e2d-a8a7f5cd71c2/skills?search=thinks) Integration page. * Select the **Skills** tab and click on the required listed skills. ## Additional Information | 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 | ### 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/fetch` **Illustrative AirMDR log entries** ```text theme={null} 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. ### ✅ 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. * 📧 Contact [**AirMDR Support**](mailto:support@airmdr.com) 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 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://.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.