We've reorganized our documentation navigation structure to align directly with your operational workflows. See the release notes and the walkthrough video for more information.

Collect Thinkst Canary logs

Supported in:

Google secops SIEM

This document explains how to collect Thinkst Canary logs by setting up a Google Security Operations feed using the Third Party API.

Thinkst Canary provides deception-based threat detection: hardware, virtual and cloud Canaries impersonate real assets, and Canarytokens act as tripwires in files, credentials and URLs. When an attacker touches a Canary or trips a token, the Canary Console records an incident. The feed retrieves those incidents from the Console API.

Before you begin

Make sure you have the following prerequisites:

A Google SecOps instance
Privileged access to the Thinkst Canary Console

Configure the REST API in Thinkst Canary

Sign in to your Thinkst Canary Console (https://<DOMAIN_HASH>.canary.tools).
Click the gear icon in the top right corner and select Global Settings.
In the menu, click API.
If the API is disabled, click Enable API.
Use the existing Default API Key, or click + Add new API key to create a dedicated one:
- API key type: Select Read-Only. This is sufficient for log collection.
- Note: Enter a name for the key (for example, Google SecOps Integration).
Note: The key type is fixed at creation and cannot be changed later.
Copy and save the following in a secure location:
- Domain Hash: The identifier of your Console. Your API hostname is <DOMAIN_HASH>.canary.tools.
- Auth Token: The API key used to authenticate requests.

Configure a feed in Google SecOps to ingest Thinkst Canary logs

Go to SIEM Settings > Feeds.
Click Add New Feed.
On the next page, click Configure a single feed.
In the Feed name field, enter a name for the feed (for example, Thinkst Canary Logs).
Select Third Party API as the Source type.
Select Thinkst Canary as the Log type.
Click Next.
Specify values for the following input parameters:
- Authentication HTTP header: The token generated earlier, in the auth_token:<TOKEN> format (for example, auth_token:AAAABBBBCCCC111122223333).
- API Hostname: The fully qualified domain name of your Thinkst Canary REST API endpoint, in the <DOMAIN_HASH>.canary.tools format (for example, myinstance.canary.tools).
- Asset namespace: The asset namespace
- Ingestion labels: The label to be applied to the events from this feed
Click Next.
Review your new feed configuration in the Finalize screen, and then click Submit.

After setup, the feed begins to retrieve logs from the Thinkst Canary instance in chronological order.

Incident updates and re-delivery

The Canary Console API returns an incident again whenever the incident is updated, not only when it is created. Canary bundles subsequent similar events from the same source into the existing incident. For example, each brute-force attack attempt becomes an event inside a single incident. Other incident modifications can also trigger re-delivery.

Expect the following behavior in Google SecOps:

Incidents that were already delivered reappear in the feed after they are updated.
A re-delivered incident can surface with an event timestamp considerably older than the moment it was re-delivered. This is because the parser derives event timestamps from the incident's original creation time and from the bundled events' own occurrence times, not from the update time.

The re-delivery itself is the documented behavior of the incident collection API (it filters on the incident's update counter), not data loss or a parser defect.

UDM mapping table

Log Field	UDM Mapping	Logic
`_canary_uptime_label`	`additional.fields`	Merged
`desc_events_n_func_code_label`	`additional.fields`	Merged
`desc_events_n_func_name_label`	`additional.fields`	Merged
`desc_events_n_sfunc_code_label`	`additional.fields`	Merged
`desc_events_n_sfunc_name_label`	`additional.fields`	Merged
`desc_events_n_timestamp_std_label`	`additional.fields`	Merged
`desc_events_n_unit_id_label`	`additional.fields`	Merged
`description_created_std_label`	`additional.fields`	Merged
`description_events_list_label`	`additional.fields`	Merged
`event_data_list`	`additional.fields`	Merged
`event_descrip_label`	`additional.fields`	Merged
`events_url_label`	`additional.fields`	Merged
`local_time_label`	`additional.fields`	Merged
`locale_label`	`additional.fields`	Merged
`lt_label`	`additional.fields`	Merged
`offline_text_label`	`additional.fields`	Merged
`updated_label`	`additional.fields`	Merged
`updated_std_label`	`additional.fields`	Merged
`_auth`	`extensions.auth`	Renamed/mapped
`_metadata`	`metadata`	Renamed/mapped
`_event_time`	`metadata.event_timestamp`	Parsed as `UNIX`
`_metadata_event_timestamp`	`metadata.event_timestamp`	Parsed as `UNIX`
`description.created_std`	`metadata.event_timestamp`	Parsed as `UNIX_MS`
`elem.timestamp_std`	`metadata.event_timestamp`	Parsed as `yyyy-MM-dd HH:mm:ss ZZZ+0000`
`updated`	`metadata.event_timestamp`	Parsed as `EEE, dd MMM yyyy HH:mm:ss ZZZ`
`updated_std`	`metadata.event_timestamp`	Parsed as `UNIX_MS`
`format`	`metadata.event_type`	Mapped: `grok` → `STATUS_UPDATE`, `grok` → `GENERIC_EVENT`
`has_principal_hostname`	`metadata.event_type`	Mapped: `true` → `STATUS_UPDATE`
`_network`	`network`	Renamed/mapped
`_observer`	`observer`	Renamed/mapped
`_principal`	`principal`	Renamed/mapped
`ThinkstCanary_Process`	`principal.application`	Directly mapped
`ThinkstCanary_Process`	`principal.asset.hostname`	Directly mapped
`ThinkstCanary_Hostname`	`principal.hostname`	Directly mapped
`_md_product_event_type`	`security_result`	Mapped values (10 total, e.g. `Shared File Opened` → `_security_result`, `Host Port Scan` → ...
`_security_result`	`security_result`	Merged
`format`	`security_result`	Mapped: `kv` → `_security_result`, `json` → `_security_result`
`_source`	`src`	Renamed/mapped
`_target`	`target`	Renamed/mapped
N/A	`metadata.event_type`	Constant: `STATUS_UPDATE`

Change Log

View the Change Log for this parser

Need more help? Get answers from Community members and Google SecOps professionals.