Thinkst Canary

By presenting itself as an apparently benign and legitimate service(s), the Canary draws the attention of unwanted activity. When someone trips one of the Canary's triggers, an alert is sent to notify the responsible parties so that action can be taken before valubale systems in your network are compromised.

Deception & Breach Simulation · Thinkst Canary

Details

ID	`Thinkst Canary`
Provider	Thinkst Canary
Category	Deception & Breach Simulation
From Version	5.0.0
Docker Image	`demisto/python3:3.12.13.10116658`
Supported Modules	Agentix XSIAM

README

By presenting itself as an apparently benign and legitimate service(s), the canary draws the attention of unwanted activity. When someone trips one of the Canary’s triggers, an alert is sent to notify the responsible parties so that action can be taken before valuable systems in your network are compromised.

Use Cases

Fetch alerts from CanaryTools as incidents in Cortex XSOAR and acknowledge them.
Get information about all registered Canaries.
Get information about Canary Tokens.
Add IP addresses to allow list.

Configure Thinkst Canary on Cortex XSOAR

For information about how to get your Authentication Token, see the Canary documentation.

Navigate to Settings > Integrations > Servers & Services.
Search for Thinkst Canary.
Click Add instance to create and configure a new integration instance.
- Name: A textual name for the integration instance.
- Fetch incidents: Should the instance fetch incidents or not
- Incident type: Choose a type for Canary Tools incidents
- Canary Server URL
- API auth token
- Trust any certificate (not secure)
- Use system proxy settings
Click Test to validate the URLs, token, and connection.

Commands

You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

List all registered Canaries: canarytools-list-canaries
List all Canary tokens: canarytools-list-tokens
Check if an IP address is whitelisted: canarytools-check-whitelist
Add an IP address to the allow list: canarytools-whitelist-ip
Edit an alert status: canarytools-edit-alert-status
Get a Canary Token file: canarytools-get-token

1. List all registered Canaries

Lists all registered Canaries.

Base Command

canarytools-list-canaries

Input

There are no input arguments for this command.

Context Output

Path	Type	Description
CanaryTools.Device.ID	string	Device ID
CanaryTools.Device.Name	string	Device name
CanaryTools.Device.Description	string	Device description
CanaryTools.Device.Address	string	Device IP address
CanaryTools.Device.Status	boolean	Device status - Live (True/False)
CanaryTools.Device.Location	string	Device location
CanaryTools.Device.Version	string	Device version
CanaryTools.Device.LastSeen	date	Device last seen time
CanaryTools.Device.LastUpdated	date	Device last updated time

Command Example

!canarytools-list-canaries

Context Example

{  
   "CanaryTools":{  
      "Device":{  
         "Status":true,
         "Description":"Lab",
         "LastUpdated":"2019-02-24 16:46:01 UTC+0000",
         "Version":"2.1.2",
         "Location":"Lab",
         "Address":"192.168.1.43",
         "Name":"VirtualCanary-1",
         "ID":"0002f07cb32d45b1",
         "LastSeen":"Sun Feb 24 2019 16:46:01 GMT+0000 (UTC)"
      }
   }
}

Human Readable Output

2. List all Canary tokens

Lists all Canary tokens.

Base Command

canarytools-list-tokens

Input

There are no input arguments for this command.

Context Output

Path	Type	Description
CanaryTools.Tokens.CanaryToken	string	Canary Token
CanaryTools.Tokens.CreatedTime	date	Token Created time
CanaryTools.Tokens.Status	boolean	Token status - Enabled (True / False)
CanaryTools.Tokens.Kind	string	Token Kind
CanaryTools.Tokens.Triggered	number	Token triggered count
CanaryTools.Tokens.DocName	string	Token document name (If the token is from type document)
CanaryTools.Tokens.TokenURL	string	Token URL (How the token is presented)

Command Example

!canarytools-list-tokens

Context Example

{  
   "CanaryTools":{  
      "Tokens":[  
         {  
            "Status":true,
            "Kind":"doc-msword",
            "Triggered":16,
            "TokenURL":"http://e71ed0532685.o3n.io/cdn/ows8bhzvpx9ro3nz32r5vb3pa/logo.gif",
            "DocName":"token.docx",
            "CanaryToken":"ows8bhzvpx9ro3nz32t5vb3pa",
            "CreatedTime":"2019-01-23 15:51:31 (UTC)"
         }
      ]
   }
}

Human Readable Output

3. Check if an IP address is on allow list

Checks whether a given IP address and port are on allow list.

Base Command

canarytools-check-whitelist

Input

Argument Name	Description	Required
ip	IP address	Required
port	Destination port	Optional

Context Output

Path	Type	Description
CanaryTools.IP.Address	string	IP address
CanaryTools.IP.Port	string	Destination port for the IP allow list
CanaryTools.IP.Whitelisted	boolean	Is the IP address on allow list (true/false)

Command Example

!canarytools-check-whitelist ip=1.1.1.1 port=45

Context Example

{  
   "CanaryTools":{  
      "IP":{  
         "Whitelisted":"True",
         "Port":"45",
         "Address":"1.1.1.1"
      }
   }
}

Human Readable Output

4. Add an IP address to the allow list

Adds an IP address to the allow list in Canary.

Base Command

canarytools-whitelist-ip

Input

Argument Name	Description	Required
ip	IP address to allow list	Required
port	Destination port to allow list	Optional

Context Output

Path	Type	Description
CanaryTools.IP.Address	string	IP address
CanaryTools.IP.Port	string	Destination port for the IP allow list
CanaryTools.IP.Whitelisted	boolean	Is the IP address on allow list (True/False)

Command Example

!canarytools-whitelist-ip ip=2.2.2.2 port=21

Context Example

{  
   "CanaryTools":{  
      "IP":{  
         "Whitelisted":"True",
         "Port":"21",
         "Address":"2.2.2.2"
      }
   }
}

Human Readable Output

5. Edit an alert status

Edits the status for an alert in Canary Tools.

Base Command

canarytools-edit-alert-status

Input

Argument Name	Description	Required
alertID	Alert ID (e.g., incident:canarytoken:d6fe0ae4dfd36cc3cc6d9d4f::1548593719)	Required
status	Required status for the alert (Acknowledge, Unacknowledge)	Required

Context Output

Path	Type	Description
CanaryTools.Alert.ID	string	Alert ID
CanaryTools.Alert.Status	string	Alert status

Command Example

!canarytools-edit-alert-status alertID=incident:canarytoken:d6fe0ae4dfd36cc3cc6d9d4f::1548593719 status=Acknowledge

Context Example

{  
   "CanaryTools":{  
      "Alert":{  
         "Status":"Acknowledge",
         "ID":"incident:canarytoken:d6fe0ae4dfd36cc3cc6d9d4f::1548593719"
      }
   }
}

Human Readable Output

6. Get a Canary Token file

Fetches a Canary Token file from the Canary Tools server.

Base Command

canarytools-get-token

Input

Argument Name	Description	Required
token	Canary Token	Required

Context Output

Path	Type	Description
CanaryTools.Tokens.CanaryToken	string	Canary Token
File.Size	string	File Size
File.SHA1	string	File SHA-1
File.SHA256	string	File SHA-256
File.Name	string	File name
File.SSDeep	string	File SSDeep
File.EntryID	string	File EntryID
File.Info	string	File info
File.Type	string	File type
File.MD5	string	File MD5
File.Extension	string	File extension

Command Example

!canarytools-get-token token=wpdkr30rx9naixdsijxdbd5ab

Context Example

{  
   "CanaryTools":{  
      "Tokens":"wpdkr30rx9naixdsijxwbd5ab"
   },
   "File":{  
      "Info":"image/jpeg",
      "SHA1":"9719f38b13a9ab79469987a1ba495939c8577c54",
      "Name":"affinity-photo-161120170952.jpg",
      "Extension":"jpg",
      "Size":240804,
      "EntryID":"163@f7519b11-9105-4dd4-8036-fe2790f28ca6",
      "SSDeep":"6144:IIgHoF7QKgKBiWlCdA1xQe5S55nXxlQIqwUAlP:InIFHriAGALT2Xd5P",
      "SHA256":"cacf61ee474920578bd0e6f000b65fa40b313b912a8611b930414a7b9ae1d49b",
      "Type":"ASCII text, with very long lines, with no line terminators\n",
      "MD5":"c499c7f42eae921c974a4e71cb4a4cc5"
   }
}

Human Readable Output

Configuration parameters

server — Canary Server URL (e.g., https://***.canary.tools) (required)
auth_token — API Authentication Token
authentication_token —
insecure — Trust any certificate (not secure)
proxy — Use system proxy settings
isFetch — Fetch incidents
fetchDelta — First fetch time (<number> <time unit>, e.g., 12 hours, 7 days, 3 months, 1 year)
incidentType — Incident type
incidentFetchInterval — Incidents Fetch Interval

Commands (6)

canarytools-check-whitelist
Checks whether a given IP address and port are on allow list.
canarytools-edit-alert-status
Edits the status for an alert in Canary Tools.
canarytools-get-token
Fetches a Canary Token file from the Canary Tools server.
canarytools-list-canaries
Lists all registered Canaries.
canarytools-list-tokens
Lists all Canary tokens.
canarytools-whitelist-ip
Adds an IP address to the allow list in Canary.

Source

ThinkstCanary.py ThinkstCanary_test.py ThinkstCanary.yml ThinkstCanary_description.md

Download History Raw

commonfields:
  id: Thinkst Canary
  version: -1
sectionorder:
- Connect
- Collect
name: Thinkst Canary
display: Thinkst Canary
category: Deception & Breach Simulation
provider: Thinkst Canary
description: By presenting itself as an apparently benign and legitimate service(s), the Canary draws the attention of unwanted activity. When someone trips one of the Canary's triggers, an alert is sent to notify the responsible parties so that action can be taken before valubale systems in your network are compromised.
configuration:
- display: Canary Server URL (e.g., https://***.canary.tools)
  name: server
  defaultvalue: ""
  type: 0
  required: true
  section: Connect
- display: API Authentication Token
  name: auth_token
  defaultvalue: ""
  type: 4
  section: Connect
  hidden: true
  required: false
- name: authentication_token
  type: 9
  displaypassword: API Authentication Token
  hiddenusername: true
  required: false
  section: Connect
- display: Trust any certificate (not secure)
  name: insecure
  type: 8
  section: Connect
  advanced: true
  required: false
- display: Use system proxy settings
  name: proxy
  type: 8
  section: Connect
  advanced: true
  required: false
- display: Fetch incidents
  name: isFetch
  type: 8
  section: Collect
  required: false
- display: First fetch time (<number> <time unit>, e.g., 12 hours, 7 days, 3 months, 1 year)
  name: fetchDelta
  defaultvalue: "24 hours"
  type: 0
  section: Collect
  required: false
- display: Incident type
  name: incidentType
  type: 13
  section: Connect
  required: false
- display: Incidents Fetch Interval
  name: incidentFetchInterval
  defaultvalue: '1'
  required: false
  type: 19
  section: Collect
  advanced: true
script:
  script: ''
  type: python
  subtype: python3
  dockerimage: demisto/python3:3.12.13.10116658
  commands:
  - name: canarytools-list-canaries
    arguments: []
    outputs:
    - contextPath: CanaryTools.Device.ID
      description: Device ID.
      type: string
    - contextPath: CanaryTools.Device.Name
      description: Device name.
      type: string
    - contextPath: CanaryTools.Device.Description
      description: Device description.
      type: string
    - contextPath: CanaryTools.Device.Address
      description: Device IP address.
      type: string
    - contextPath: CanaryTools.Device.Status
      description: Device status - Live (True/False).
      type: boolean
    - contextPath: CanaryTools.Device.Location
      description: Device location.
      type: string
    - contextPath: CanaryTools.Device.Version
      description: Device version.
      type: string
    - contextPath: CanaryTools.Device.LastSeen
      description: Device last seen time.
      type: date
    - contextPath: CanaryTools.Device.LastUpdated
      description: Device last updated time.
      type: date
    description: Lists all registered Canaries.
  - name: canarytools-list-tokens
    arguments: []
    outputs:
    - contextPath: CanaryTools.Token.CanaryToken
      description: Canary Token.
      type: string
    - contextPath: CanaryTools.Token.CreatedTime
      description: Token Created time.
      type: date
    - contextPath: CanaryTools.token.Enabled
      description: Token status - Enabled (True / False).
      type: boolean
    - contextPath: CanaryTools.Token.Kind
      description: Token Kind.
      type: string
    - contextPath: CanaryTools.Token.Triggered
      description: Token triggered count.
      type: number
    - contextPath: CanaryTools.Token.DocName
      description: Token document name (If the token is from type document).
      type: string
    - contextPath: CanaryTools.Token.TokenURL
      description: Token URL (How the token is presented).
      type: string
    description: Lists all Canary tokens.
  - name: canarytools-check-whitelist
    arguments:
    - name: ip
      required: true
      description: IP address.
    - name: port
      description: Destination port.
    outputs:
    - contextPath: CanaryTools.IP.Address
      description: IP address.
      type: string
    - contextPath: CanaryTools.IP.Port
      description: Destination port for the IP allow list.
      type: string
    - contextPath: CanaryTools.IP.Whitelisted
      description: Is the IP address on allow list (true/false).
      type: boolean
    description: Checks whether a given IP address and port are on allow list.
  - name: canarytools-whitelist-ip
    arguments:
    - name: ip
      required: true
      description: IP address to add to allow list.
    - name: port
      description: Destination port to add to allow list.
    outputs:
    - contextPath: CanaryTools.IP.Address
      description: IP address.
      type: string
    - contextPath: CanaryTools.IP.Port
      description: Destination port for the IP allow list.
      type: string
    - contextPath: CanaryTools.IP.Whitelisted
      description: Is the IP address on allow list (True/False).
      type: boolean
    description: Adds an IP address to the allow list in Canary.
  - name: canarytools-edit-alert-status
    arguments:
    - name: alert_id
      required: true
      description: 'Alert ID (e.g., incident:canarytoken:d6fe0ae4dfd36cc3cc6d9d4f::1548593719, Can be retrieved through fetch incidents).'
    - name: status
      required: true
      auto: PREDEFINED
      predefined:
      - Acknowledge
      - Unacknowledge
      description: Required status for the alert (Acknowledge, Unacknowledge).
    outputs:
    - contextPath: CanaryTools.Alert.ID
      description: Alert ID.
      type: string
    - contextPath: CanaryTools.Alert.Status
      description: Alert status.
      type: string
    description: Edits the status for an alert in Canary Tools.
  - name: canarytools-get-token
    arguments:
    - name: token
      required: true
      description: Canary Token, Can be retrieved through list-tokens command.
    outputs:
    - contextPath: CanaryTools.Token.CanaryToken
      description: Canary Token.
      type: string
    - contextPath: File.Size
      description: File Size.
      type: string
    - contextPath: File.SHA1
      description: File SHA-1.
      type: string
    - contextPath: File.SHA256
      description: File SHA-256.
      type: string
    - contextPath: File.Name
      description: File name.
      type: string
    - contextPath: File.SSDeep
      description: File SSDeep.
      type: string
    - contextPath: File.EntryID
      description: File EntryID.
      type: string
    - contextPath: File.Info
      description: File info.
      type: string
    - contextPath: File.Type
      description: File type.
      type: string
    - contextPath: File.MD5
      description: File MD5.
      type: string
    - contextPath: File.Extension
      description: File extension.
      type: string
    description: Fetches a Canary Token file from the Canary Tools server.
  isfetch: true
tests:
- CanaryTools Test
fromversion: 5.0.0