Vectra Cognito V2

Vectra Cognito v2 is a network detection and response platform that uses AI to detect and respond to cyber threats.

Vectra Cognito v2 is a leading network detection and response platform that uses AI to detect and respond to cyber threats in real-time. This connector enables seamless integration with Swimlane Turbine, allowing users to automate security operations by retrieving detailed host and detection information, adding notes and tags, and managing detections efficiently. By leveraging this integration, security teams can enhance their threat management capabilities, streamline workflows, and improve response times to potential security incidents.

Prerequisites

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

an API key authentication using the following parameters:

URL: The endpoint URL for accessing the Vectra API.

API Token: A token used to authenticate API requests.

and OAuth2 authorization using the following parameters:

URL: The endpoint URL for accessing the Vectra API.

Client ID: The client identifier for OAuth2 authentication.

Secret Key: The secret key associated with the client ID.

Token URL: The URL to obtain the OAuth2 token.

Capabilities

The Vectra Cognito connector provides the following capabilities:

Add Detection Notes

Add Host Notes

Add Tags

Get Host by ID

Get Hosts

Get Triage Rule by ID

Retrieve Detections

Update Detection

Configurations

Vectra Cognito Version 2 API Key Authentication

Authenticates using an API Token.

Configuration Parameters

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

Vectra Cognito OAuth2 Client Credentials

Authenticates using OAuth2 client credentials grant with HTTP Basic Auth against the Vectra API v2.5 token endpoint.

Configuration Parameters

Parameter	Description	Type	Required
url	Base URL of the Vectra portal (e.g., https://<vectra_portal_url>).	string	Required
token_url	Full URL to the OAuth2 token endpoint (e.g., https://<vectra_portal_url>/api/v2.5/oauth2/token).	string	Required
client_id	The Client ID obtained when creating your API Client (used as Basic Auth username).	string	Required
client_secret	The Secret Key obtained when creating your API Client (used as Basic Auth password).	string	Required
verify_ssl	Verify SSL certificate.	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Add Detection Notes

Append notes to a specific detection identified by its detection_id in Vectra Cognito v2.

Endpoint

URL: /api/v2.5/detections/{{detection_id}}/notes

Method: POST

Input

Argument Name	Type	Required	Description
path_parameters.detection_id	string	Required	Parameters for the Add Detection Notes action
note	string	Optional	Parameter for Add Detection Notes

Input Example

{"json_body":{"note":"this is a detection note"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	number	Unique identifier
date_created	string	Output field: date_created
date_modified	object	Output field: date_modified
created_by	string	Output field: created_by
modified_by	object	Output field: modified_by
note	string	Output field: note

Output Example

{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 15 Apr 2024 20:37:23 GMT"},"reason":"OK","json_body":{"id":2,"date_created":"2021-01-11T14:14:10.527603Z","date_modified":null,"created_by":"vadmin","modified_by":null,"note":"this is a detection note"}}

Add Host Notes

Append notes to a specified host within Vectra Cognito v2 using the host's unique identifier, requiring path parameters and JSON body.

Endpoint

URL: /api/v2.5/hosts/{{host_id}}/notes

Method: POST

Input

Argument Name	Type	Required	Description
path_parameters.host_id	string	Required	Parameters for the Add Host Notes action
note	string	Optional	Parameter for Add Host Notes

Input Example

{"json_body":{"note":"this is a note"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	number	Unique identifier
date_created	string	Output field: date_created
date_modified	object	Output field: date_modified
created_by	string	Output field: created_by
modified_by	object	Output field: modified_by
note	string	Output field: note

Output Example

{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 15 Apr 2024 20:37:23 GMT"},"reason":"OK","json_body":{"id":2,"date_created":"2021-01-11T13:54:47.987918Z","date_modified":null,"created_by":"vadmin","modified_by":null,"note":"this is a note"}}

Add Tags

Add a new tag to a specified host in Vectra Cognito v2 using the host's unique identifier.

Endpoint

URL: /api/v2.5/tagging/host/{{host_id}}

Method: PATCH

Input

Argument Name	Type	Required	Description
path_parameters.host_id	string	Required	Parameters for the Add Tags action
tags	array	Optional	Parameter for Add Tags

Input Example

{"json_body":{"tags":["test","new_tag","this is a tag","We need to follow up on this host."]}}

Output

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

Output Example

{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 15 Apr 2024 20:37:23 GMT"},"reason":"OK","json_body":{}}

Get Host by ID

Retrieve detailed information for a specific host in Vectra Cognito v2 using the unique host ID.

Endpoint

URL: /api/v2.5/hosts/{{id}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.id	string	Required	Parameters for the Get Host by ID action

Input Example

{"path_parameters":{"id":1}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	number	Unique identifier
name	string	Name of the resource
active_traffic	boolean	Output field: active_traffic
t_score	number	Score value
c_score	number	Score value
last_source	string	Output field: last_source
previous_ips	array	Output field: previous_ips
last_detection_timestamp	string	Output field: last_detection_timestamp
key_asset	boolean	Output field: key_asset
state	string	Output field: state
targets_key_asset	boolean	Output field: targets_key_asset
probable_owner	string	Output field: probable_owner
detection_set	array	Output field: detection_set
host_artifact_set	array	Output field: host_artifact_set
host_artifact_set.type	string	Type of the resource
host_artifact_set.value	string	Value for the parameter
sensor	object	Output field: sensor
tags	array	Output field: tags
note	string	Output field: note
note_modified_by	string	Output field: note_modified_by
note_modified_timestamp	string	Output field: note_modified_timestamp
notes	array	Output field: notes
notes.id	number	Unique identifier

Output Example

{"status_code":200,"response_headers":{"Content-Type":"application/x-www-form-urlencoded","Date":"Wed, 21 Jun 2023 20:37:23 GMT"},"reason":"OK","json_body":{"id":1029,"name":"insightws07","active_traffic":true,"t_score":90,"c_score":99,"last_source":"10.16.6.6","previous_ips":["10.16.12.1","10.16.0.1"],"last_detection_timestamp":"2019-08-28T19:05:12Z","key_asset":false,"state":"active","targets_key_asset":true,"probable_owner":"dkelle","detection_set":["https://10.1.6.10/api/v2.5/detections/1354...

Get Hosts

Retrieve comprehensive information on all hosts from Vectra Cognito v2.

Endpoint

URL: /api/v2.5/hosts

Method: GET

Input

Argument Name	Type	Required	Description
parameters.fields	string	Optional	Filters objects listed.
parameters.page	number	Optional	Page number. Possible values are a positive integer or last.
parameters.page_size	number	Optional	Page size. Possible values are a positive integer up to 5000.
parameters.ordering	string	Optional	Orders records by last timestamp, threat score and certainty score. The default out sorts threat and certainty score in ascending order. Scores can be sorted in descending order by prepending the query with “minus” symbol.
parameters.name	string	Optional	Filter by name.
parameters.state	string	Optional	Filter by state active or inactive.
parameters.last_source	string	Optional	Filter by last_source (IP address).
parameters.t_score	number	Optional	Filter by threat score.
parameters.t_score_gte	number	Optional	Filter by threat score >= the score provided.
parameters.c_score	number	Optional	Filter by certainty score.
parameters.c_score_gte	number	Optional	Filter by certainty score >= the score provided.
parameters.last_detection_timestamp	string	Optional	Filter by last_detection_timestamp.
parameters.last_detection_timestamp_gte	string	Optional	Filter by last_detection_timestamp >= timestamp provided.
parameters.last_detection_timestamp_lte	string	Optional	Filter by last_detection_timestamp <= timestamp provided.
parameters.tags	string	Optional	Filter by a tag or a comma-separated list of tags (returns hosts that contain any of the tags specified), e.g.tags=baz	tags=foo,bar".
parameters.key_asset	boolean	Optional	Filter by key asset True, False.
parameters.min_id	number	Optional	Filter hosts have ID greater than or equal to min_id.
parameters.max_id	number	Optional	Filter hosts have ID less than or equal to max_id.
parameters.mac_address	string	Optional	Filter by mac address.
parameters.note_modified_timestamp_gte	string	Optional	Filter by note_modified_timestamp >= the timestamp provided.
parameters.privilege_level	number	Optional	Filter by exact privilege level of hosts. 1-10.
parameters.privilege_level_gte	number	Optional	Filter hosts that have a privilege level greater than or equal to the supplied number. 1-10.
parameters.privilege_category	string	Optional	Filter hosts by privilege category. Options are ‘low’, ‘medium’ and ‘high’.

Input Example

{"parameters":{"fields":"string","page":123,"page_size":123,"ordering":"string","name":"Example Name","state":"string","last_source":"string","t_score":123,"t_score_gte":123,"c_score":123,"c_score_gte":123,"last_detection_timestamp":"string","last_detection_timestamp_gte":"string","last_detection_timestamp_lte":"string","tags":"string","key_asset":true,"min_id":123,"max_id":123,"mac_address":"string","note_modified_timestamp_gte":"string","privilege_level":123,"privilege_level_gte":123,"privilege_category":"string"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	number	Unique identifier
name	string	Name of the resource
active_traffic	boolean	Output field: active_traffic
t_score	number	Score value
c_score	number	Score value
last_source	string	Output field: last_source
previous_ips	array	Output field: previous_ips
last_detection_timestamp	string	Output field: last_detection_timestamp
key_asset	boolean	Output field: key_asset
state	string	Output field: state
targets_key_asset	boolean	Output field: targets_key_asset
probable_owner	string	Output field: probable_owner
detection_set	array	Output field: detection_set
host_artifact_set	array	Output field: host_artifact_set
host_artifact_set.type	string	Type of the resource
host_artifact_set.value	string	Value for the parameter
sensor	object	Output field: sensor
tags	array	Output field: tags
note	string	Output field: note
note_modified_by	string	Output field: note_modified_by
note_modified_timestamp	string	Output field: note_modified_timestamp
notes	array	Output field: notes
notes.id	number	Unique identifier

Output Example

Get Triage Rule by ID

Retrieve a specific triage rule from Vectra Cognito v2 using the unique identifier provided in the path parameters.

Endpoint

URL: /api/v2.5/rules/{{id}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.id	string	Required	Parameters for the Get Triage Rule by ID action

Input Example

{"path_parameters":{"id":"12345678-1234-1234-1234-123456789abc"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	number	Unique identifier
url	string	URL endpoint for the request
description	string	Output field: description
enabled	boolean	Output field: enabled
created_timestamp	string	Output field: created_timestamp
last_timestamp	object	Output field: last_timestamp
is_whitelist	boolean	Output field: is_whitelist
priority	object	Output field: priority
active_detections	number	Output field: active_detections
total_detections	number	Output field: total_detections
template	boolean	Output field: template
additional_conditions	object	Output field: additional_conditions
additional_conditions.OR	array	Output field: additional_conditions.OR
additional_conditions.OR.AND	array	Output field: additional_conditions.OR.AND
additional_conditions.OR.AND.ANY_OF	object	Output field: additional_conditions.OR.AND.ANY_OF
additional_conditions.OR.AND.ANY_OF.field	string	Output field: additional_conditions.OR.AND.ANY_OF.field
additional_conditions.OR.AND.ANY_OF.values	array	Value for the parameter
additional_conditions.OR.AND.ANY_OF.groups	array	Output field: additional_conditions.OR.AND.ANY_OF.groups
additional_conditions.OR.AND.ANY_OF.label	string	Output field: additional_conditions.OR.AND.ANY_OF.label
source_conditions	object	Output field: source_conditions
source_conditions.OR	array	Output field: source_conditions.OR
source_conditions.OR.AND	array	Output field: source_conditions.OR.AND
source_conditions.OR.AND.ANY_OF	object	Output field: source_conditions.OR.AND.ANY_OF

Output Example

{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 15 Apr 2024 20:37:23 GMT"},"reason":"OK","json_body":{"id":68,"url":"https://1.1.1.1/api/v2.5/rules/68","description":"Expected behavior from these devices","enabled":true,"created_timestamp":"2019-08-27T20:55:29Z","last_timestamp":null,"is_whitelist":false,"priority":null,"active_detections":2,"total_detections":3,"template":true,"additional_conditions":{"OR":[]},"source_conditions":{"OR...

Retrieve Detections

Gather all detection data from Vectra Cognito v2, providing a comprehensive overview of potential security threats.

Endpoint

URL: /api/v2.5/detections

Method: GET

Input

Argument Name	Type	Required	Description
parameters.fields	string	Optional	Filters objects listed.
parameters.page	number	Optional	Page number. Possible values are a positive integer or last.
parameters.page_size	number	Optional	Page size. Possible values are a positive integer, up to 5000.
parameters.ordering	string	Optional	Orders records by last timestamp, threat score and certainty score. The default sorts threat and certainty score in ascending order. Scores can be sorted in descending order by prepending the query with “minus” symbol.
parameters.min_id	number	Optional	Greater than or equal to(>=) the id provided.
parameters.max_id	number	Optional	Less than or equal to(<=) the id provided.
parameters.state	string	Optional	Filter by state active, inactive, ignored, ignored for all.
parameters.category	string	Optional	Filter by the detection category. This performs partial word match. For example, you can use recon to query all Reconnaissance category detections.
parameters.detection_type	string	Optional	Filter by the name of the threat detected.
parameters.detection_category	string	Optional	Filter by the detection category.
parameters.src_ip	string	Optional	Filter by source (IP address).
parameters.t_score	number	Optional	Filter by threat score.
parameters.t_score_gte	number	Optional	Filter by threat score >= the score provided.
parameters.threat_score	number	Optional	Filter by threat score.
parameters.threat_gte	number	Optional	Filter by threat score >= the score provided.
parameters.c_score	number	Optional	Filter by certainty score.
parameters.c_score_gte	number	Optional	Filter by certainty score >= the score provided.
parameters.certainty	number	Optional	Filter by certainty score.
parameters.certainty_gte	number	Optional	Filter by certainty score >= the score provided.
parameters.last_timestamp_gte	string	Optional	Filter by last_timestamp >= the date provided.
parameters.last_timestamp	string	Optional	Filter by last timestamp.
parameters.host_id	number	Optional	Filter by ID of the host object a detection is attributed to.
parameters.tags	string	Optional	Filter by a tag or a comma-separated list of tags.
parameters.destination	string	Optional	Filter by destination in the detection detail set.
parameters.proto	string	Optional	Filter by the protocol in the detection detail set.

Input Example

{"parameters":{"fields":"string","page":123,"page_size":123,"ordering":"string","min_id":123,"max_id":123,"state":"string","category":"string","detection_type":"string","detection_category":"string","src_ip":"string","t_score":123,"t_score_gte":123,"threat_score":123,"threat_gte":123,"c_score":123,"c_score_gte":123,"certainty":123,"certainty_gte":123,"last_timestamp_gte":"string","last_timestamp":"string","host_id":123,"tags":"string","destination":"string","proto":"string","is_targeting_key_asset":true,"note_modified_timestamp_gte":"string","return_as_turbine_schema":true,"alert_organization":"string","ioc_types":["string"],"domains_ignore_list":"string","ip_cidr_ignore_list":"string","regex_ignore":"string","ioc_ignore_paths":["string"]}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
last_timestamp	string	Output field: last_timestamp
grouped_details	array	Output field: grouped_details
grouped_details.num_sessions	number	Output field: grouped_details.num_sessions
grouped_details.protocol	string	Output field: grouped_details.protocol
grouped_details.last_timestamp	string	Output field: grouped_details.last_timestamp
grouped_details.host_detection	number	Output field: grouped_details.host_detection
grouped_details.accounts	array	Output field: grouped_details.accounts
grouped_details.is_host_detail	boolean	Output field: grouped_details.is_host_detail
grouped_details.bytes_received	number	Output field: grouped_details.bytes_received
grouped_details.dst_geo	object	Output field: grouped_details.dst_geo
grouped_details.src_ip	string	Output field: grouped_details.src_ip
grouped_details.dst_ips	array	Output field: grouped_details.dst_ips
grouped_details.grouping_field	string	Output field: grouped_details.grouping_field
grouped_details.description	object	Output field: grouped_details.description
grouped_details.is_account_detail	boolean	Output field: grouped_details.is_account_detail
grouped_details.dst_ports	array	Output field: grouped_details.dst_ports
grouped_details.account_detection	object	Output field: grouped_details.account_detection
grouped_details.first_timestamp	string	Output field: grouped_details.first_timestamp
grouped_details.dst_geo_lat	object	Output field: grouped_details.dst_geo_lat
grouped_details.dst_geo_lon	object	Output field: grouped_details.dst_geo_lon
grouped_details.bytes_sent	number	Output field: grouped_details.bytes_sent
grouped_details.target_domains	array	Output field: grouped_details.target_domains
grouped_details.account_uid	object	Unique identifier

Output Example

{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 15 Apr 2024 20:37:23 GMT"},"reason":"OK","json_body":{"last_timestamp":"2019-08-27T20:13:08Z","grouped_details":[{}],"custom_detection":null,"is_custom_model":false,"detection":"Hidden HTTP Tunnel","detection_type":"Hidden HTTP Tunnel","is_targeting_key_asset":false,"note_modified_timestamp":"2021-12-15T17:26:41Z","c_score":59,"t_score":10,"id":36,"category":"COMMAND & CONTROL","src_ip":"...

Search Detections

Search detections using Vectra's Lucene-style query language against the v2.5 search endpoint, supporting pagination and optional normalization to Turbine Schema alerts.

Endpoint

URL: /api/v2.5/search/detections

Method: GET

Input

Argument Name	Type	Required	Description
parameters.query_string	string	Required	Lucene-style search query for detections. Examples: 'detection.is_triaged:false and detection.grouped_details.dst_ports:445', 'detection.grouped_details.target_domains:snakeoil.biz', 'detection.last_timestamp:[now-1d to now] and (detection.is_triaged:false)'.
parameters.page_size	number	Optional	Number of results returned per page. Default is 50. Maximum is 5000.
parameters.return_as_turbine_schema	boolean	Optional	If true, returns results as normalized Turbine Schema alerts instead of raw API response.
parameters.alert_organization	string	Optional	Optional organization name to include in the Turbine Schema alert. Used only when return_as_turbine_schema is true.
parameters.ioc_types	array	Optional	List of observable types to extract. Supported: ipv4_public, ipv4_private, ipv6_public, ipv6_private, domain, url, email, sha1, sha256, md5. If omitted or empty, all types are extracted.
parameters.domains_ignore_list	string	Optional	Comma-separated domain values to exclude from observable extraction.
parameters.ip_cidr_ignore_list	string	Optional	Comma-separated CIDR ranges to exclude from observable extraction.
parameters.regex_ignore	string	Optional	Regex pattern — any observable value matching this pattern is excluded.
parameters.ioc_ignore_paths	array	Optional	Array of slash-separated field paths to strip from each alert before extracting observables. Supports wildcards () and nested paths. Example: ["processCommandLine", "context//ipAddress"].

Input Example

{"parameters":{"query_string":"string","page_size":50,"return_as_turbine_schema":true,"alert_organization":"string","ioc_types":["string"],"domains_ignore_list":"string","ip_cidr_ignore_list":"string","regex_ignore":"string","ioc_ignore_paths":["string"]}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
count	number	Total number of matching detections.
next	string	URL of the next results page, or null if on the last page.
previous	string	URL of the previous results page, or null if on the first page.
results	array	Array of raw detection objects returned by the search.
results.last_timestamp	string	Result of the operation
results.grouped_details	array	Result of the operation
results.grouped_details.num_sessions	number	Result of the operation
results.grouped_details.protocol	string	Result of the operation
results.grouped_details.last_timestamp	string	Result of the operation
results.grouped_details.host_detection	number	Result of the operation
results.grouped_details.accounts	array	Result of the operation
results.grouped_details.is_host_detail	boolean	Result of the operation
results.grouped_details.bytes_received	number	Result of the operation
results.grouped_details.dst_geo	object	Result of the operation
results.grouped_details.src_ip	string	Result of the operation
results.grouped_details.dst_ips	array	Result of the operation
results.grouped_details.grouping_field	string	Result of the operation
results.grouped_details.description	object	Result of the operation
results.grouped_details.is_account_detail	boolean	Result of the operation
results.grouped_details.dst_ports	array	Result of the operation
results.grouped_details.account_detection	object	Result of the operation
results.grouped_details.first_timestamp	string	Result of the operation
results.grouped_details.dst_geo_lat	object	Result of the operation

Output Example

{"status_code":200,"response_headers":{"content-type":"application/json"},"reason":"OK","json_body":{"count":1,"next":null,"previous":null,"results":[{}]}}

Update Detection

Mark or unmark multiple detections as fixed in Vectra Cognito v2 using the provided JSON body.

Endpoint

URL: /api/v2.5/detections

Method: PATCH

Input

Argument Name	Type	Required	Description
detectionIdList	array	Optional	Unique identifier
mark_as_fixed	string	Optional	Parameter for Update Detection

Input Example

{"detectionIdList":[123],"mark_as_fixed":"string"}

Output

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

Output Example

{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 15 Apr 2024 20:37:23 GMT"},"reason":"OK","json_body":{}}

Response Headers

Header	Description	Example
content-length	The length of the response body in bytes	140
content-type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Mon, 15 Apr 2024 20:37:23 GMT