Vectra AI

Vectra Platform API Guide

REST API v3.4
Revision History
DATE COMMENT
November 2024
Add support for regex groups in the following endpoints:

o /v3.4/groups
o /v3.4/groups/<id>

October 2024
Adds query parameter “fields” and “exclude_fields” for the
/api/v3.4/entities endpoint.

September 2024
New endpoints for querying unique host counts and records by given
timespan:

o /v3.4/unique_host_count
o /v3.4/unique_host_count/audit

Rename of exisiting unique_host_count endpoints from V3.3 to new

names and urls:

o /v3.4/unique_host_count_monthly
o /v3.4/unique_host_count_monthly/audit

Adds support for downloading the curated ruleset for Vectra Match

o /api/v3.4/vectra-match/download-vectra-ruleset

New endpoint for monitoring health of detection models has been

added:

/api/v3.4/health/detection

July 2024
New endpoints for health monitoring of external connectors and
EDR’s have been added:

o /v3.4/health/external_connectors
o /v3.4/health/external_connectors/details
o /v3.4/health/edr
o /v3.4/health/edr/details
o /v3.4/health/network_brain/ping
DATE COMMENT
July 2024
Removal of the following endpoints:

/api/v3.4/events/account_scoring/
/api/v3.4/events/account_detection/

Removal of the following response fields and query parameters:

/api/v3.4/entities/<id>/notes/:
/api/v3.4/entities/<id>/notes/<id>/:
/api/v3.4/tagging/entity/<id>/:
/api/v3.4/tagging/entity/:
o ‘entity_type’ parameter
/api/v3.4/detections/:
/api/v3.4/detections/<id>/:
o ‘c_score’ parameter/field
o ‘t_score’ parameter/field
o ‘targets_key_asset’ parameter/field
o ‘category’ parameter/field
o ‘c_score_gte’ parameter
o ‘t_score_gte’ parameter
/api/v3.4/entities/:
/api/v3.4/entities/<id>/:
o ‘entity_type’ parameter/field
o ‘entity_importance’ field
/api/v3.4/events/entity_scoring/:
o ‘entity_type’ parameter/field
o ‘entity_importance’ field
o ‘last_detection_id’ field
o ‘last_detection_type’ field
o ‘last_detection_url’ field
/api/v3.4/events/detections/:
/api/v3.4/lockdown/:
o ‘entity_type’ parameter/field

June 2024
Adds support for uploading large rules files to Vectra Match:

/api/v3.4/vectra-match/rules/upload

© November 2024 Vectra AI, Inc. | 3

DATE COMMENT
April 2024
Initial Release

The following new endpoints have been added:

o /api/v3.4/users/
o /api/v3.4/users/<id>/
o /api/v3.4/users/roles/
Updates tagging to rename the ‘tag_id’ key to ‘entity_id’ in the
response object. The value of this key and the path for this endpoint
is unchanged.
Rename the ‘subaccounts’ response field to ‘associated_accounts’
for the following endpoints:
o /api/v3.4/accounts/
o /api/v3.4/accounts/<id>/

© November 2024 Vectra AI, Inc. | 4

API Version 3.4 Changelog
Accounts

• The ‘subaccounts’ field is deprecated in v3.4, replaced by the field ‘associated_accounts’.

Detections

• Deprecating the following params and fields for v3.4/detections/:

o ‘c_score’ parameter and field
o ‘t_score’ parameter and field
o ‘targets_key_asset’ parameter and field
o ‘category’ parameter and field
o ‘c_score_gte’ parameter
o ‘t_score_gte’ parameter

Entities

• Deprecating the following params and fields for v3.4/entities/:

o ‘entity_type’ parameter and field
o ‘entity_importance’ field

Events

• Deprecating the paths v3.4/events/account_scoring, and

v3.4/events/account_detection.
• Deprecating the following params and fields for v3.4/events/entity_scoring:
o ‘entity_type’ parameter and field
o ‘entity_importance’ field
o ‘last_detection_id’ field
o ‘last_detection_type’ field
o ‘last_detection_url’ field
• Deprecating the following params and fields for v3.4/events/detections:
o ‘entity_type’ parameter and field

Groups

• Regex groups support now available in paths v3.4/groups, and v3.4/groups/<id>.

Health

• Added ability to query health information for external connectors via the endpoint
v3.4/health/external_connectors
• Added ability to query detailed health information for external connectors via the endpoint
v3.4/health/external_connectors/details
• Added ability to query health information for EDR connections via the endpoint
v3.4/health/edr
• Added ability to query detailed health information for EDR connections via the endpoint
v3.4/health/edr/details

© November 2024 Vectra AI, Inc. | 5

 • Added ability to ping the network brain connection via the endpoint
v3.4/health/network_brain/ping
• Added ability to query detection model health via the endpoint v3.4/health/detection

Lockdown

• Deprecating the param and field ‘entity_type’.

Notes

• Deprecating the param ‘entity_type’.

Tagging

• ‘tag_id’ key renamed to ‘entity_id’ in the response. The value of this key and the path for this
endpoint is unchanged.
• Deprecating the param ‘entity_type’.

Users

• Updates /api/v3.4/users endpoint to remove ‘username’ and ‘last_login’ fields and to add
‘name’, ‘verified’, and ‘identities’ fields in the list Users response, adds ability to add Users.
• Adds ability to view, update, and delete single Users via the endpoint /api/v3.4/users/<id>
• Adds ability to list the available roles for user creation via the endpoint
/api/v3.4/users/roles

Vectra Match

• Adds /api/v3.4/vectra-match/download-vectra-ruleset endpoint

Unique Host Count

• Added /api/v3.4/unique_host_count endpoint to query the count of unique hosts seen in

a given timespan up to a year in the past.
• Added /api/v3.4/unique_host_count endpoint to query the unique hosts seen in a given
timespan up to a year in the past.
• Renamed previous unique_host_count endpoint to:
/api/v3.4/unique_host_count_monthly
• Renamed previous unique_host_count/audit endpoint to:
/api/v3.4/unique_host_count_monthly/audit

Overview
A REST API is available for administrators and developers to integrate Vectra’s breach detection data
into their applications. Vectra RESTful API provides access to security event data, platform
configuration, and health information via URI paths.

Vectra REST API is based on open standards. You can use any web development language to access
and retrieve information via the API. A common use-case would be to retrieve security event information

© November 2024 Vectra AI, Inc. | 6

generated by the Vectra platform and supply this information to a security operations dashboard or
incident response and ticketing systems.

The REST API can be accessed via HTTPS connection to the interface IP address of the Vectra brain.
The data in the response to the API query is in JSON format.

Examples of security event data that can be integrated into your application:

Security event type detected

Account information associated with the security event
Severity of the Account activities

The Vectra REST API is accessible using OAuth2 authentication.

Security Detection Data

The "Detections” and “Accounts” elements retrieve security events that can be inserted into external
applications. The REST API provides filtering options to extract data. Advanced parsing of the data can
be performed after data has been retrieved and saved into your target application. Order of the response
data returned is latest first.

Accessing REST API v3.4

The REST API v 3.4 is accessed via the URL https://<vectra_portal_url>/api/v3.4/<path>.
The <path> options for REST API queries are listed in the table below.

URL METHOD DATA TO QUERY

/detections GET, PATCH All detection events

/detections/<detection_id> GET Single detection event

details

/detections/<detection_id>/notes GET, POST, PATCH, DELETE Detection notes

/detections/<detection_id>/pcap GET Download PCAP data for

single detection
/accounts GET All accounts

/accounts/<account_id> GET Single account details

© November 2024 Vectra AI, Inc. | 7

URL METHOD DATA TO QUERY

/accounts/<account_id>/notes GET, POST, PATCH, DELETE Account notes

/rules GET, POST, PUT, DELETE Triage rule configuration

/tagging/detection/<detection_id> GET, PATCH Detection tags

/tagging/account/<account_id> GET, PATCH Account tags

/tagging/host/<host_id> GET, PATCH Host tags

/tagging/entity/<entity_id> GET, PATCH Entity tags

/assignments GET, POST Account assignments

/assignments/<id> GET,PUT,DELETE Single assignments

/assignment_outcomes GET, POST, PUT, DELETE Assignment outcomes

/assignment_outcomes/<id> GET,PUT,DELETE Single assignment outcome

/events/audits GET Audit log events

/entities GET All entities (Accounts,

Hosts)
/entities/<entity_id> GET Single entity details

/events/entity_scoring GET Entity scoring events

/groups GET, POST Groups

/groups/<group_id> GET, PATCH, DELETE Groups

/events/detections GET Detection events

/lockdown GET Entities lockdown status

/health GET Appliance health data

/health/external_connectors GET External connector health

data
/health/external_connectors/details GET External connector health
details
/health/edr GET EDR health data

/health/edr/details GET EDR health details

/health/network_brain/ping GET Network brain connection

status
/hosts GET All Hosts

/hosts/<host_id> GET Single Host details

/entities/<entity_id>/notes GET, POST All entity notes

/entities/<entity_id>/notes/<note_id> GET, PATCH, DELETE Single note details

© November 2024 Vectra AI, Inc. | 8

URL METHOD DATA TO QUERY

/users GET, POST Users

/users/<user_id> GET, PATCH, DELETE Single user

/users/roles GET User roles

/threatFeeds GET, POST Threat Feeds

/threatFeeds/<id> GET, POST, PATCH, DELETE Single Threat Feed

/threatFeeds/<id>/file GET, DELETE Single Threat Feed File

/vectra-match/download-vectra-ruleset GET Vectra Match Curated

Ruleset
/unique_hosts_observed_monthly GET Unique Host Counts

/unique_hosts_observed_monthly/audit GET Unique Host Audits

/unique_hosts_observed GET Unique Host Counts

/unique_hosts_observed/audit GET Unique Host Audits

API Clients
Getting access to the Vectra Platform API is done through the creation of an API Client. Creation of an
API Client will provide a set of OAuth 2.0 credentials that will be used to gain authorization to the Vectra
Platform API. Please note that management of API Clients is restricted to Detect users with the role of
“Super Admin”. To create an API client, log into your Detect portal and navigate to Manage > API
Clients.

Creating a new API Client

From the API Clients page, select ‘Add API Client’ to create a new client.

© November 2024 Vectra AI, Inc. | 9

Creating a new API Client has one required parameter:

• Role – the role maps the API Client to a set of permissions, similar to the way a Detect UI user
would be assigned a role. The role must be one of the following:
• Read-Only
• Restricted Admin
• Security Analyst
• Settings Admin
• Auditor

Creating a new API Client has two optional parameters:

• Name – a user-friendly name to identify the client (up to 256 characters)

• Description – a brief description to aid in identifying the client (up to 2048 characters)

Once you have entered the API Client information, select ‘Generate Credentials’ to obtain your client
credentials.

© November 2024 Vectra AI, Inc. | 10

Be sure to record your Client ID and Secret Key for safekeeping. You will need these two pieces of
information to obtain an access token from the Vectra Platform API. An access token is required to make
requests to all of the Vectra Platform API endpoints.

Authenticating as an API Client

Many REST API tools and libraries can programmatically manage access tokens for you once provided
the OAuth 2.0 parameters described below, or you can manually make requests to obtain them as
needed.

First you must authenticate using the Client ID and Secret Key you obtained when creating your API
Client.

Example Request:
POST https://<vectra_portal_url>/oauth2/token
Authorization: Basic <HTTPBasic(<client_id>:<secret_key>)>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Example Response:
{
"access_token": "Z0FBQUFB...",
"expires_in": 21600,
"refresh_expires_in": 86400,

© November 2024 Vectra AI, Inc. | 11

 "refresh_token": "eyJzdWIi...",
"token_type": "Bearer"
}

Notice that the response includes an access_token and refresh_token which will be used to make
subsequent API requests as a client, outlined in the next sections.

Also, be sure to note the differences in the expires_in and refresh_expires_in timers, which are
expressed in seconds. An access_token will expire in 6 hours, while a refresh_token will take 24 hours to
expire. Once your access_token has expired, you will need to reauthenticate your API client with your
client_id and secret_key in order to receive a new access_token. If your refresh_token has not expired,
you may use it to obtain a new access token using the previous authorization grant.

Manually Refreshing Token via API Client (e.g. Postman or Insomnia)

A refresh token will have the following syntax when returned as part of the /oauth2/token response:
“refresh_token”: “eyJzdWIi..."

As of March 2023, if you manually attempt to refresh your token via an API Client, copying and pasting
this value as is will be valid.

Refreshing Token via Script

There should be no formatting changes required for using the refresh token via script. For example, in
Python, accessing and saving the refresh token should look like this:

refresh_token = response.get(‘refresh_token’)

where response is the dictionary received from authenticating via /oauth2/token.

Auto-Refresh Token via Insomnia

If you are using Insomnia for API requests, we recommend the following setup for basic Authentication
and refresh token requests:

1. Create a new environment with your API client credentials. Select the “No Environment”
dropdown found on the top left corner of Insomnia, choose “Manage Environments”.

2. Use the example data below to create a new sub environment. Give the environment a unique
name.

© November 2024 Vectra AI, Inc. | 12

3. Repeat for any other desired tenants.
4. Select your desired environment to start making requests.
5. Create a new request for /oauth2/token & set up basic authentication. Reference the client_id
and secret from your environment file via Insomnia variables in the Basic auth tab (example
below).

Next, we’ll need to populate Form data for both types of requests: initial auth and refresh.

When authenticating initially for basic auth, form data should just include grant_type:
client_credentials (example below):

© November 2024 Vectra AI, Inc. | 13

When refreshing your token, use grant_type and refresh_token form data (example
below). refresh_token can be populated automatically via an Insomnia tag. To create a tag, enter
“Response => Body Attribute” in the refresh_token form data field and Insomnia will auto-
populate a configurable interface. Select the interface and input the following (Request should
be the /oauth2/token request):

© November 2024 Vectra AI, Inc. | 14

 Press “Done”, and your refresh form data should appear as the following:

Insomnia should now be configured to automatically grab and use the refresh_token field
returned.

Requests via Postman

If you prefer Postman, we have a public API collection you can import to your environment and use.

Example Request:
POST https://<vectra_portal_url>/oauth2/token
Authorization: Basic <HTTPBasic(client_id:secret_key)>
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
refresh_token=<refresh_token>

Example Response:
{
"access_token": "Z0FBQUFB...",
"expires_in": 21600,
"token_type": "Bearer"
}

Make API request as a client

Now that you have obtained an access_token, you will use that token to make API requests as an API
Client to all the Vectra Platform API endpoints. Here are a couple quick examples.

Example Request to accounts endpoint:

© November 2024 Vectra AI, Inc. | 15

GET /api/v3.4/accounts
Authorization: Bearer <access_token>

Example Response:
{
"count": 16,
"next": "http://<vectra_portal_url>/api/v3.4/accounts?page=1",
"previous": null,
"results": [
...
}

Example Request to detections endpoint:

GET /api/v3.4/detections
Authorization: Bearer <access_token>

Example Response:
{
"count": 25,
"next": "http://<vectra_portal_url>/api/v3.4/detections?page=2",
"previous": null,
"results": [
...
}

Full sample output for accounts and detections endpoints can be found in Appendix A.

API Rate Limits

Rate limits define the frequency of requests that can be made to the v3.4 API. API rate limits apply on a
per-tenant basis.

The following rate limits are enforced across all v3.4 API endpoints and methods:

• Steady-state: 4 requests per second

• Burst: 10 requests per second

When request submissions exceed the steady-state request rate and burst limits, the v3.4 API will
throttle requests and return a 429 Too Many Requests error response.

© November 2024 Vectra AI, Inc. | 16

Detections
Detection objects contain all the information related to security events detected in the environment. The
URL to retrieve all detections is https://<vectra_portal_url>/api/v3.4/detections and
uses OAuth2 authentication.

Detections are grouped into one of the following categories:

DETECTION CATEGORY URL

Command & Control /detections?detection_category=command

Botnet /detections?detection_category=botnet

Reconnaissance /detections?detection_category=reconnaissance

Lateral Movement /detections?detection_category=lateral

Exfiltration /detections?detection_category=exfiltration

Info /detections?detection_category=info

The API query performs partial word match. For example, you can use /detections?
detection_category=recon to query all Reconnaissance category detections.

The following table lists the top-level fields and descriptions present in the response for a bulk GET
request to the v3.4 API for Detections

ELEMENT DESCRIPTION TYPE NOTES

count The number of object IDs retrieved in the integer

output

next URL to the next page of output string Useful when using a web-
based REST API browser.

previous URL link to the previous page of output string Useful when using a web-
based REST API browser.

results The list of Detections returned in the output List of

Objects

The following table lists the fields and descriptions present in a Detection. These Detections will be
contained inside the ‘results’ field, which is a top-level field described in the table above.

ELEMENT DESCRIPTION TYPE NOTES

id Object ID integer

© November 2024 Vectra AI, Inc. | 17

ELEMENT DESCRIPTION TYPE NOTES
detection The name of the string See Appendix B for the list of Detection
threat detected. names
detection_type The name of the string See Appendix B for the list of Detection
threat detected. names
detection_category The category of string See Appendix B for the list of categories.
the vname
attack detected.
src_ip The source IP string
address of the
host attributed
to the security
event.
state The state of the string If the detection has aged out the state will
detection. transition to “active” from “inactive”. If
marked as fixed in the UI, or via the V3.4
API, state will be “fixed”.
threat The threat score integer
attributed to the
detection.
certainty The certainty Integer
score attributed
to the detection.
first_timestamp The timestamp string Timestamp format:
when the event YYYY-MM-DD HH-MM-SS GMT
was first
detected
last_timestamp The timestamp string Timestamp format:
when the event YYYY-MM-DD HH-MM-SS GMT
was last
detected
created_timestamp The timestamp string Timestamp format:
when the YYYY-MM-DD HH-MM-SS GMT
detection was
created
description System string
generated
description of
the event.
url The URL that string
links directly to
this record.
The name of string
sensor_name sensor where
this flow was
detected from.

© November 2024 Vectra AI, Inc. | 18

ELEMENT DESCRIPTION TYPE NOTES
src_host A dictionary with JSON
fields that object
describe the
Host the
detection is from
url The URL that string
links directly to
the detection
record
summary The summary JSON See Appendix A for examples
information for object
the detection
grouped_details The detection JSON See Appendix A for examples
details for the object
detection
tags User defined List of
tags added to strings
the detection
campaign_summaries The summaries JSON The summaries of campaigns this detection
of campaigns of object. belongs to
which this
detection is part.
is_targeting_key_asset Indicates Boolean
whether the
detection targets
a key asset
note User defined string
note for this
detection.
note_modified_by Username who string
last modified
note
note_modifed_timestamp The timestamp string Timestamp format:
when note was YYYY-MM-DD HH-MM-SS GMT
last modified
notes An array of all array of Includes id, date_created, date_modified,
notes on the objects created_by, modified_by, and note contents
host.
assigned_to User named string
assigned to this
detection
assigned_date The timestamp string Timestamp format:
when user was YYYY-MM-DD HH-MM-SS GMT
assigned this
detection

© November 2024 Vectra AI, Inc. | 19

ELEMENT DESCRIPTION TYPE NOTES
src_account A dictionary with JSON
fields that object
describe the
Account the
detection is from
custom_detection Indicates string
category name
of the smart rule
used to filter
detection.
data_source A dictionary with JSON Includes type, connection_name,
fields describing object connection_id
the sensor.
detection_url URL of the string
detection

filtered_by_ai True/False boolean

whether the
detection was
filtered by AI
Triage
filtered_by_rule True/False boolean
whether the
detection was
filtered by a rule.
filtered_by_user True/False boolean
whether the
detection was
filtered by a
user.
groups Associated JSON Will only render matching domain and ip
groups Object groups

is_custom_model True/False boolean

whether
detection is a
custom model.
is_marked_custom True/False boolean
whether
detection has
custom filtering
applied.
sensor Sensor name string

triage_rule_id Triage rule ID integer

used for filtering

© November 2024 Vectra AI, Inc. | 20

You can also apply filters to the API response to query for specific elements.

The available options and filters for detection set is listed below.

QUERY PARAMETER DESCRIPTION

fields Filters results by fields provided. The available fields are

listed in the table above.
page Page number. Possible values are a positive integer or
last
page_size Page size. Possible values are a positive integer, up to
5000.
ordering 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.
min_id >= the id provided
max_id <= the id provided
state Filter by state: active, inactive, ignored, ignored for all
detection_category Filter by the detection category
detection_type Filter by the name of the threat detected.
src_ip Filter by source (ip address)
threat Filter by threat score
threat_gte Filter by threat score >= the score provided
certainty Filter by certainty score
certainty_gte Filter by certainty score >= the score provided
last_timestamp Filter by last timestamp
last_timestamp_gte Filter by last_timestamp >= the timestamp provided
last_timestamp_lte Filter by last_timestamp <= the timestamp provided
host_id Filter by id of the host object a detection is attributed to
entity_id Filter by id of the object a detection is attributed to
tags Filter by a tag or a comma-separated list of tags
is_targeting_key_asset Filter by is_targeting_key_asset: True or False
note_modified_timestamp_gte Filter by note_modified_timestamp >= the timestamp
provided: ‘2019-08-27T20:55:29Z’
src_account Filter by source account ID
src_account_id Filter by source account ID
id Filter by detection IDs (comma separated list of IDs)

© November 2024 Vectra AI, Inc. | 21

QUERY PARAMETER DESCRIPTION
created_timestamp_gte Filter by created_timestamp >= the timestamp provided
created_timestamp_lte Filter by created_timestamp <= the timestamp provided
canonicalize Boolean. Return response in Canonical JSON Format.
Note: This is a best effort, JSON makes no guarantees on
order and we cannot guarantee the response won’t be re-
ordered in transit. If there are any problems, we will return
the non-canonicalized response.

Examples of detection queries:

QUERY COMMENT

/api/v3.4/detections/?ordering=threat Retrieves all detections with threat score

sorted low to high (ascending).

/api/v3.4/detections/?ordering=-threat Retrieves all detections with threat score

sorted high to low (descending).

/api/v3.4/detections/?certainty_gte=60 Retrieves all detections with certainty score

greater than or equal to 60.

/api/v3.4/detections/?page=2 Retrieves page 2 of detections.

/api/v3.4/detections/?threat_gte=90&certainty_gte=90 Retrieves all detections with threat &certainty

score greater than or equal to 90

/api/v3.4/detections/?tags=RAT Retrieves all detections with tag value=RAT

/api/v3.4/detections/?tags=RAT,TOR Retrieves all detections with tag value=RAT,

and TOR
/api/v3.4/detections?canonicalize=True Alphabetically orders all detection objects.

Mark/Unmark Detections as Fixed

Marking a detection as Fixed indicates that some remedial action was taken based upon the detection.
Threat and Certainty scores will both be 0 once a detection has been marked as fixed.

Marking/unmarking a detection as fixed requires the following elements be present in the request body:

• detectionIdList
• mark_as_fixed

URL to mark/unmark a detection as fixed is

https://<vectra_portal_url>/api/v3.4/detections.

An example of using the PATCH method to mark or unmark a detection as fixed can be found in
Appendix A.

© November 2024 Vectra AI, Inc. | 22

Detection PCAP API

Version 3.4 of the API supports download of PCAP for a particular detection. Users can perform a GET
using the following URL format to download PCAP for any detection:

https://<vectra_portal_url>/api/v3.4/detections/<id>/pcap

The download of PCAP via API is subject to RBAC rules just like UI access. The api client role requires
the ‘view pcap’ permission (i.e. security analyst) in order to access PCAP data.

Accounts
Account objects contain information related to accounts observed in the environment. The URL to
retrieve all accounts is https://<vectra_portal_url>/api/v3.4/accounts and uses OAuth2
authentication.

The following table lists the top-level fields and descriptions present in the response for a bulk GET
request to the v3.4 API for Accounts

ELEMENT DESCRIPTION TYPE NOTES

count The number of object IDs integer
retrieved in the output
next URL to the next page of string Useful when using a web-based
output REST API browser.
previous URL to the previous string Useful when using a web-based
page of output REST API browser.
results A list of all Accounts list
(described in the table
below) being returned by
the query

The following table lists the fields and descriptions present in an Account. These Accounts will be
contained inside the ‘results’ field, which is a top-level field described in the table above.

ELEMENT DESCRIPTION TYPE NOTES

id The ID of the Account integer
url A v3.4 URL to the string Useful when using a web-based
Account REST API browser.
name The name associated string
with the Account
state The state of the Account string

© November 2024 Vectra AI, Inc. | 23

ELEMENT DESCRIPTION TYPE NOTES
threat The threat score integer
attributed to the account

certainty The certainty score Integer

attributed to the account
severity The severity of this string Either ‘Low’, ‘Medium’, ‘High’, or
Account ‘Critical’. This is calculated based
off of the threat and certainty of
the Account
account_type The method through List of Can be one or both of “kerberos”
which this account was strings or “o365”
discovered
tags User defined tags added List of
to the account strings
sensors Sensors associated with List of
the accounts detection strings
set
note User defined note added string
to the account
note_modified_by Username who last string
modified note
note_modified_timestamp The timestamp when string Timestamp format:
note was last modified YYYY-MM-DD HH-MM-SS GMT

notes An array of all notes on array of Includes id, date_created,

the host. objects date_modified, created_by,
modified_by, and note contents
privilege_level A number 1-10 to int
represent how privileged
this account is
privilege_category A string to represent how string Either ‘Low’, ‘Medium’, or ‘High’.
privileged this account it Privilege levels of 1 and 2 map to
‘Low’. Privilege levels of 3-7 map
to ‘Medium’. Privilege levels of 8-
10 map to ‘High’
last_detection_timestamp Last detection activity string Timestamp format:
from this Account YYYY-MM-DD HH-MM-SS GMT
detection_set List of Detections for string
Account
detection_summaries The summaries of List of
detections attached to Objects
this Account.

© November 2024 Vectra AI, Inc. | 24

ELEMENT DESCRIPTION TYPE NOTES
ldap Information about the JSON
LDAP server this object
Account came from (if
applicable)
data_source A dictionary with fields JSON Includes type, connection_name,
describing the sensor. object connection_id
probable_home Probable home host for string
account
assignment Current assignment JSON
object
past_assignments Past assignment set List of
objects
associated_accounts List of associated List of
accounts strings

The available options and filters for account set is listed below.

QUERY PARAMETER DESCRIPTION

fields Filters results by fields provided. The available fields are listed
in the table above.
page Page number. Possible values are a positive integer or last
page_size Page size. Possible values are a positive integer up to 5000.
ordering 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.
name filter by name
state filter by state: active or inactive
t_score filter by threat score
t_score_gte filter by threat score >= the score provided
c_score filter by certainty score
c_score_gte filter by certainty score >= the score provided
tags 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"
all No filter, return all host objects. Only available in version 2.0 API
min_id Filter hosts have id greater than or equal to min_id
max_id Filter hosts have id less than or equal to max_id
note_modified_timestamp_gte filter by note_modified_timestamp >= the timestamp provided:
‘2019-08-27T20:55:29Z’

© November 2024 Vectra AI, Inc. | 25

QUERY PARAMETER DESCRIPTION
privilege_level filter by exact privilege level of hosts. 1-10
privilege_level_gte filter hosts that have a privilege level greater than or equal to
the supplied number. 1-10
privilege_category filter hosts by privilege category. Options are ‘low’, ‘medium’
and ‘high’
id Filter by account IDs (comma separated list of IDs)

Tagging
The tagging API can be used to manage tags for accounts and detections.

To manage tags for an account, use the following URL:

https://<vectra_portal_url>/api/v3.4/tagging/account/<account_id>

To manage tags for a host, use the following URL:

https://<vectra_portal_url>/api/v3.4/tagging/host/<host_id>

To manage tags for a detection, use the following URL:

https://<vectra_portal_url>/api/v3.4/tagging/detection/<detection_id>

To manage tags for any of the above entities, use the following URL with the type of entity specified as a
query parameter:

https://<vectra_portal_url>/api/v3.4/tagging/entity/<entity_id>?type=type

The following table lists the fields and a description of the various elements for tagging operations.
Detailed examples of using GET and PATCH methods on tags is described in Appendix A.

ELEMENT DESCRIPTION TYPE NOTES

status Status of tagging string Valid values: ‘success’ or ‘failure’
request.
entity_id The id of the entity integer The id of the object being tagged.

tags List of tags for the host list of strings When doing a PATCH operation,
or detection object. the object will be updated to
match the list of tags provided.
To remove tags for a host or
detection set tags to an empty
list.
message Error message if string Only present when status is
operation was ‘failure’ of operation is a failure.
unsuccessful.

© November 2024 Vectra AI, Inc. | 26

ELEMENT DESCRIPTION TYPE NOTES
invalid_tags List of tags which are list of strings Only present when status is
invalid for the account or ‘failure’. This will only be returned
detection object. in the response for a PATCH
operation.

One of the following query parameter is required for the /tagging/entity/<entity_id> endpoint in order to
differentiate the object type:

QUERY PARAMETER DESCRIPTION

type Replaces “entity_type”

Triage
Version 3 of triage API supports GET, POST, PUT, and DELETE. The API endpoint for accessing triage
rules is https://<vectra_portal_url>/api/v3.4/rules

The following table lists the top-level fields and descriptions present in the response for a bulk GET
request to the v3 API for Triage rules.
ELEMENT DESCRIPTION TYPE NOTES
count The number of object integer
IDs retrieved in the
output
next URL to the next page of string Useful when using a web-based
output REST API browser.
previous URL link to the previous string Useful when using a web-based
page of output REST API browser.
results A list of all Triage rules list
(described in the table
below) being returned
by the query

The following table lists the fields and descriptions present in a Triage rule. These Triage rules will be
contained inside the ‘results’ field, which is a top-level field described in the table above.
ELEMENT DESCRIPTION TYPE NOTES
id The ID of the Triage rule integer
url A v3 URL to the Triage string Useful when using a web-based
rule REST API browser.
enabled Describes if the Triage Boolean
rule is enabled
created_timestamp Describes the time the string Timestamp format:
Triage rule was created YYYY-MM-DD HH-MM-SS GMT
last_timestamp The timestamp when string Timestamp format:
this Triage filter was YYYY-MM-DD HH-MM-SS GMT
triggered

© November 2024 Vectra AI, Inc. | 27

 is_whitelist This whitelists all Boolean True or False
detections for this
activity
priority Used in ordering integer
execution of Triage
filters
active_detections The total number of integer
active detections this
Triage rule applies to
total_detections The total number of integer
detections (active or
inactive) this Triage rule
applies to
template Specifies if this Triage Boolean True of False
rule was created based
off of a template
detection_category Original detection string
category
triage_category Custom Triage label string
used to categorize
specified detections
detection Original detection type string
source_conditions Specifies the entity this JSON source_conditions represents the
Triage rule applies to conditions that can be applied to
the source of a detection,
including host, account, IP, and
sensor.
For more information on the
format of source_conditions, see
below this table

additional_conditions Specifies additional JSON additional_conditions are other

matching criteria for this conditions that are different on a
Triage rule per-detection-type basis.
For more information on the
format of additional_conditions,
see below this table

Formatting source_conditions and additional_conditions

The format of version 2.2 Triage rules is based on AND/OR logic, making them more flexible and
customizable to your specific situation. Both ‘source_conditions’ and ‘additional_conditions’ are now
saved as JSON blobs which represents a tree-like structure. Each tree node is represented in the
following format:

{operator: operand}

© November 2024 Vectra AI, Inc. | 28

Where “operator” is any of the following:

For non-leaf nodes: ‘AND’ or ‘OR’

For leaf nodes: ‘ANY_OF’ or ‘NONE_OF’

And “operand” is any of the following:

For non-leaf nodes: A list of children tree nodes of the form [{operator: operand}, {operator:
operand}, …]
For leaf nodes: A dictionary of the form:
{
‘field’: <FIELD NAME>,
‘values’: [
{‘value’: [<VALUE>]}
],
‘group’: [
{‘value’: [<GROUP ID>]}
]
}

Stipulations on the format of the top-level tree structure as of 2.2 is that the top-level operator must be
an ‘OR’ node, with a single ‘AND’ node as the only child. The ‘AND’ node may have an arbitrary number
of leaf node children. All valid 2.2 Triage rules will look as follows:

{
‘OR’: [
{ ‘AND’: [
<LEAF NODE 1>,
<LEAF NODE 2>,
…
<LEAF NODE N>,
]}
]
}

source_conditions and additional_conditions have different fields that can be used in their leaf nodes.
For source_conditions, the following fields are valid: ip, host, account, sensor. The fields ‘ip’ and ‘host’
also support triaging on groups, meaning that an ip or a host leaf node can be given an IP Group or Host
Group ID, and the Triage rule will apply to every IP/host in the specified group.

For additional_conditions, the following fields are valid: remote1_ip, remote1_proto, remote1_port,
remote1_dns, remote2_ip, remote2_proto, remote2_port, remote2_dns, account, named_pipe, uuid,

© November 2024 Vectra AI, Inc. | 29

identity, share, extensions, rdp client name, rdp client token, keyboard name. The fields ‘remote1_ip’,
‘remote2_ip’, ‘remote1_dns’, ‘remote2_dns’ support triaging on groups.

Either source_conditions or additional_conditions may be null. Setting source_conditions to null implies

that this Triage rule with apply to All Hosts.

To see examples of complete valid source_conditions and additional_conditions, see Appendix A.

Assignments
Assignments are used to assign account objects to analysts for investigation. This information includes
but is not limited to:

• Assigned to user
• Assigned by user
• Date assigned
• Date resolved
• Events
• Outcome
• Account ID
• Triaged detections

URL to retrieve assignment information is

https://<vectra_portal_url>/api/v3.4/assignments

An example of using curl to retrieve all assignments using token authentication:

curl 'https://<vectra_portal_url>/api/v3.4/assignments/' \
-X 'GET' \
-H "Content-Type: application/json" \
--header "Authorization: Bearer <access_token>” \
--compressed \
--insecure

Assignment Resolution
Once completed, assignments can be resolved. Assignment resolutions provide a way to label and track
the outcomes of assignments. Outcomes get recorded in the assignment’s history.

Outcome choices may include one of the following built-in assignment outcomes:

• Benign True Positive

• Malicious True Positive
• False Positive

Alternatively, users can choose to define their own Custom outcomes for reporting purposes.

© November 2024 Vectra AI, Inc. | 30

URL to resolve an assignment is
https://<vectra_portal_url>/api/v3.4/assignments/<id>/resolve

An example of using curl to retrieve all assignments using token authentication:

curl 'https://<vectra_portal_url>/api/v3.4/assignments/9/resolve' \
-X 'GET' \
-H "Content-Type: application/json" \
--header "Authorization: Bearer <access_token> " \
--data '{"outcome": 2, "note": "some note", "triage_as": "my triage rule",
"detection_ids": [23, 73, 85, 88]}' \
--compressed \
--insecure

The following table lists fields and description of the various elements for assignments.
ELEMENT DESCRIPTION TYPE NOTES
count Number of object integer
IDs retrieved in the
output
next URL to the next string
page of output
previous URL link to the string
previous page of
output
results List of users list of objects
returned in the
output

The following table lists the fields and descriptions present in an assignment. These elements will be
contained inside the ‘results’ field, which is a top-level field described in the table above.

ELEMENT DESCRIPTION TYPE NOTES

id Object ID integer
assigned_by The user that made the list of objects
assignment
date_assigned Timestamp from when the datetime
assignment was assigned
date_resolved Timestamp from when the datetime
assignment was resolved
events Actions take on the assignment list of objects
outcome Outcome of the assignment list of objects
resolved_by The user that resolved the list of objects
assignment
triaged_detections The number of detections that integer
were triaged as a part of the
resolution of this assignment
account_id The ID of the account associated integer
with this assignment

© November 2024 Vectra AI, Inc. | 31

 assigned_to The user this assignment has been list of objects
assigned to

The available options and filters for assignments are listed below.

QUERY PARAMETER DESCRIPTION

accounts Filter by accounts
assignees Filter by assignees
resolution Filter by resolution (outcome)
resolved Filters by resolved status. True or False.
created_after Filter by created after timestamp.

Examples of assignments queries

QUERY COMMENT
https://<vectra_portal_url>/api/v3.4/assignme Retrieves all assignments on accounts
nts?accounts=1,2,3 1, 2 and 3
https://<vectra_portal_url>/api/v3.4/assignme Retrieves all assignments for users 1,
nts?assignees=1,2,3 2 and 3
https://<vectra_portal_url>/api/v3.4/assignme Retrieves all assignments with
nts?resolution=1,2,3 resolution 1, 2 or 3
https://<vectra_portal_url>/api/v3.4/assignme Retrieves all assignments that have
nts?resolved=true been resolved
https://<vectra_portal_url>/api/v3.4/assignme Retrieves all assignments that have
nts?created_after=2021-01-01T00:00:00Z been created since 2021-01-
01T00:00:00Z

Users
User objects contain information about users that have access to the Vectra system. These should be
used to create assignments via the Assignments endpoint. The URL to retrieve all user accounts is
https://<vectra_portal_url>/api/v3.4/users and uses OAuth2 authentication.

The following table lists the top-level fields and descriptions present in the response for a bulk GET
request to the v3.4 API for Users.

ELEMENT DESCRIPTION TYPE NOTES

count The number of object IDs integer
retrieved in the output
next URL to the next page of string Useful when using a web-based
output REST API browser.

© November 2024 Vectra AI, Inc. | 32

ELEMENT DESCRIPTION TYPE NOTES
previous URL to the previous string Useful when using a web-based
page of output REST API browser.
results A list of all Accounts list
(described in the table
below) being returned by
the query

The following table lists the fields and descriptions present in a User. These Users will be contained
inside the ‘results’ field, which is a top-level field described in the table above.

ELEMENT DESCRIPTION TYPE NOTES

id The ID of the User integer
email The email associated string
with the user
role The role associated with string
the user
last_login_timestamp Last login timestamp for string
the user

name The name of the user string

verified The user verification Boolean

status
identities The profiles associated List of
with a user objects

The available options and filters for account set is listed below.

QUERY PARAMETER DESCRIPTION

page Page number. Possible values are a positive integer or last
page_size Page size. Possible values are a positive integer up to 5000.
email email to search for.
role Filter for users with specified role.
last_login_gte Filter for users who have logged in at a time more recent than
specified date.

An example of using the GET, POST, PATCH, and DELETE methods for Users can be found in Appendix
A.

© November 2024 Vectra AI, Inc. | 33

Event-based endpoints
Event-based endpoints provide a mechanism for API clients to poll Detect for system events. These
endpoints provide a SaaS analog to syslog on the Detect appliance, where data is aggregated at an
external collector for storage and analysis, such as a SIEM.

Event-based endpoints include the following event types:

• Detection Events
• Audit Log Events
• Entity Scoring Events

These endpoints make use of a checkpoint value, which is used in subsequent requests to get new
events beginning from the last checkpoint.

Detection Events
Detection Events are generated upon initial detection and for each update of the detection.

The URL to retrieve accounts scoring events is

https://<vectra_portal_url>/api/v3.4/events/detections and uses OAuth2
authentication.

The following table lists the top-level fields and descriptions present in the response for a bulk GET
request to the v3.4 API for Detection Events.

ELEMENT DESCRIPTION TYPE NOTES

events A list of detection events list Event fields are described in the
table below
remaining_count The number of remaining integer
events
next_checkpoint The next checkpoint value integer Example: "next_checkpoint": 101
to use to retrieve any
remaining events Use with the ‘from’ query
parameter described below

The following table lists the fields and descriptions present in an Account Detection Event.

Element Description Type Notes

id The ID of the Account Detection integer

Event

© November 2024 Vectra AI, Inc. | 34

Element Description Type Notes

detection_id The ID of the detection integer

category The detection category string
threat The threat score attributed to the integer
detection
certainty The certainty score attributed to the integer
detection
d_type_vname The detection name string
triaged Indicates whether the detection has boolean
been triaged
certainty The certainty score attributed to the integer
account
event_timestamp Timestamp when the Account string
Detection Event occurred
detail The detection detail object Detail fields are specific to
detection type
severity The severity of the detection integer
detection_href Link to the detection string
detection_type Type of detection string
entity_id Id of the related entity integer
entity_uid UID of the related entity string
type Type of the related entity string Either Account or Host
url Corresponding URL of the string
detection event
mitre Type of Mitre Technique string

The available query parameters to filter for Account Detection Events are listed below.

QUERY PARAMETER TYPE DESCRIPTION

from integer Used to provide a checkpoint value for filtering
Account Detection Events
limit integer Used to specify the batch size returned by the
response from the /events/account_detection
endpoint. By default 500 events will be returned if a
limit is not specified. A maximum of 1,000 events will
be returned per request.
event_timestamp_gte string Detection events with a more recent timestamp than
ISO8601 the value provided.
event_timestamp_lte string Detection events with an older timestamp than the
ISO8601 value provided.

© November 2024 Vectra AI, Inc. | 35

QUERY PARAMETER TYPE DESCRIPTION
type string Type of the related entity (Account, Host).
include_info_category bool Whether to include Detection events with info
category.
include_triaged bool Whether to include Detection events that have been
triaged.
detection_id integer Filter by a specific Detection id.
ordering string Orders events by “event_timestamp”. The default
sorts event timestamps by ascending order. Events
can be sorted in descending order by prepending the
query with “minus” symbol.

The URL to retrieve accounts detection events from the last checkpoint is
https://<vectra_portal_url>/api/v3.4/events/account_detection?from=101

Audit Log Events

Audit Log Events are generated when a user action is performed on the system. Audit Log Event are
sequential and can be used to create an audit trail of user activity on your system.

The URL to retrieve audit log events is

https://<vectra_portal_url>/api/v3.4/events/audits and uses OAuth2 authentication.

The following table lists the top-level fields and descriptions present in the response for a bulk GET
request to the v3.4 API for Audit Log Events.

ELEMENT DESCRIPTION TYPE NOTES

events A list of audit log events list Event fields are described in the
table below
remaining_count The number of remaining integer
events
next_checkpoint The next checkpoint value integer Example: "next_checkpoint": 101
to use to retrieve any
remaining events Use with the ‘from’ query
parameter described below

The following table lists the fields and descriptions present in an Audit Log Event.

© November 2024 Vectra AI, Inc. | 36

Element Description Type Notes

id Autoincrementing ID bigint used for

checkpoints
user_id User ID of the user account associated with integer
the event.
username Username of the account associated with the string
event, at the time of the event
user_type User type, e.g. “LOCAL”, “SAML”, string / enum
“API_CLIENT”
api_client_id API client ID, if an event was caused by an string
API client interaction
role Role the user/API client had at the time of the string
event
version Vectra UI version at the time of the event string
source_ip IP address of the user/API client string
event_timestamp Event timestamp (UTC) in ISO-8601 format timestamp Example: 2022-
03-01T13:00:00Z
message Message describing the event. string
result_status "success" or "failure" string / enum
event_data JSON data specific to the event type string / JSON For example,
which tags were
added/removed
for a tagging
event
event_object The object type the audited action is being string / enum For example user,
performed on filter, or account
event_action What type of action is being audited string / enum For example,
creation or
deletion

The available query parameters to filter for Audit Log Events are listed below.

QUERY PARAMETER DESCRIPTION

event_timestamp_gte Start date/time for audit, inclusive, formatted in ISO-8601
event_timestamp_lte End date/time for audit, inclusive, formatted in ISO-8601
from Used to provide a checkpoint value for filtering Audit Events
user_id Audit events associated with a particular user_id
event_object Audit events on a particular object (e.g. account, user, host,
etc.)
event_action Audit events regarding a particular action (e.g. delete, create,
etc.)

© November 2024 Vectra AI, Inc. | 37

QUERY PARAMETER DESCRIPTION
limit Used to specify the batch size returned by the response from
the /events/audits endpoint. By default 500 events will be
returned if a limit is not specified. A maximum of 1,000 events
will be returned per request.
ordering Orders events by “event_timestamp”. The default sorts event
timestamps by ascending order. Events can be sorted in
descending order by prepending the query with “minus”
symbol.

The URL to retrieve accounts scoring events from the last checkpoint is
https://<vectra_portal_url>/api/v3.4/events/audits?from=101

Entity Scoring Events

Entity Scoring Events are generated when an entity score is changed, which occurs upon initial threat
detection, discovery of additional detections, and updates to any discovered detections. The entity
score is reduced over time if the underlying detection behavior subsides, either because of user
intervention or because the account has left the environment.

Host scoring events prior to May 2023 will have score_decrease enabled to false, so that all scoring
events will be returned. Host scoring events starting May 2023 will be able to be filtered by the
include_score_decreases query param.

NOTE: You must include the type query param in your request to specify if you would like ‘account’ or
‘host’ entity scoring events.

The URL to retrieve entity scoring events is

https://<vectra_portal_url>/api/v3.4/events/entity_scoring?type=<entity_type>
and uses OAuth2 authentication.

The following table lists the top-level fields and descriptions present in the response for a bulk GET
request to the v3.4 API for Entity Scoring Events.

ELEMENT DESCRIPTION TYPE NOTES

events A list of entity scoring list Event fields are described in the
events table below
remaining_count The number of remaining integer
events
next_checkpoint The next checkpoint value integer Example: "next_checkpoint": 101
to use to retrieve any
remaining events Use with the ‘from’ query
parameter described below

© November 2024 Vectra AI, Inc. | 38

The following table lists the fields and descriptions present in an Entity Scoring object.

Element Description Type Notes

entity_id Entity ID. integer

breadth_contrib Breadth contribution of the entity. integer
importance Importance score of the entity. integer
type Entity type, e.g. “Account”, “Host”. string
is_prioritized Whether or not the priority of this entity boolean
is above the configured priority
threshold.
severity Entity severity, e.g. “Low”, “Medium”, string
“High”.
urgency_reason Reason behind the urgency_score. string
urgency_score Priority or urgency of the entity. integer
velocity_contrib Velocity contribution of the entity. integer
event_timestamp Timestamp when the detection event string Timestamp format:
occurred. YYYY-MM-DD HH-
MM-SS GMT
name The name associated with the account, string
or the learned hostname.
active_detection_types A list of all active detection types on list
the entity.
category The event category string
(e.g. "ACCOUNT_SCORING").
last_detection The id, type and url of the last Object This will replace
detection. last_detection_id,
last_detection_type
and
last_detection_url
url The URL link directly to this entity. string

The available query parameters to filter for Entity Scoring events are listed below.

QUERY PARAMETER DESCRIPTION

type REQUIRED. Specifies the type of entity scoring events:
account or host.
include_score_decreases If it is set (present), events reflecting score decreases will be
included in event list.
from Used to provide a checkpoint value for filtering Entity Scoring
Events

© November 2024 Vectra AI, Inc. | 39

QUERY PARAMETER DESCRIPTION
limit Used to specify the batch size returned by the response from
the /events/entity_scoring endpoint. By default 500 events will
be returned if a limit is not specified. A maximum of 1,000
events will be returned per request.
event_timestamp_gte Start date/time for scoring event, inclusive, formatted in ISO-
8601
event_timestamp_lte End date/time for scoring event, inclusive, formatted in ISO-
8601
ordering Orders events by “event_timestamp”. The default sorts event
timestamps by ascending order. Events can be sorted in
descending order by prepending the query with “minus”
symbol.

Entities
Entities is an overarching term to cover various types of models, including Accounts and Hosts. Entities
are returned with an entity type, indicating what type of entity it is, along with urgency, importance, and
fields from the original model.

The URL to retrieve entities is https://<vectra_portal_url>/api/v3.4/entities and uses

OAuth2 authentication.

The following table lists the top-level fields and descriptions present in the response for a bulk GET
request to the v3.4 API for Entities.

ELEMENT DESCRIPTION TYPE NOTES

results A list of entity objects list Will return only Accounts
next URL to the next page of string
entity results
previous URL to the previous page string
of entity results
count Total number of entity integer
objects

The following table lists the fields and descriptions present in an Entities object.

Element Description Type Notes

id Autoincrementing ID. integer Entity ID

breadth_contrib Breadth contribution of the entity. integer

© November 2024 Vectra AI, Inc. | 40

Element Description Type Notes

type Entity type, e.g. “Account”, “Host”. string

is_prioritized Whether or not the priority of this entity boolean
is above the configured priority
threshold.
severity Entity severity, e.g. “Low”, “Medium”, string
“High”.
urgency_reason Reason behind the urgency_score. string
urgency_score Priority or urgency of the entity. integer
velocity_contrib Velocity contribution of the entity. integer
detection_set List of detections for this entity. list
last_detection_timestamp Last detection activity from this Entity. string Timestamp
format:
YYYY-MM-DD
HH-MM-SS GMT
last_modified_timestamp Last modification on this Entity. string Timestamp
format:
YYYY-MM-DD
HH-MM-SS GMT
name The name associated with the account, string
or the learned hostname.
notes A list of all notes on the entity. list
privilege_level An integer from 1-10 to represent how string
privileges this account is.
privilege_category A string to represent how privileged this string
account is, related to privilege level.
Either Low (1-2), Medium (3-7), or High
(8-10).
sensors Sensors related to the entity. list
state State of the entity, e.g. “active” or list
“inactive”.
tags User defined tags added to the entity. list
url The URL link directly to this entity. string
account_type The method through which this account list of strings
was discovered ("kerberos" or "o365").
host_type Generic, Non-attributable, normal, etc. list of strings
ip Last seen IP address of host for “host” string
entity types, or null for “account” types.

The available query parameters to filter for Entities are listed below.

© November 2024 Vectra AI, Inc. | 41

QUERY PARAMETER DESCRIPTION
is_prioritized If it is set (present), only entities whose priority score is above
the configured priority threshold will be included in the
response.
type Allows the caller to request only entities of the given type. Valid
values are "account" or "host". Multiple values can be provided
using commas to separate values (e.g. type=account,host ).
Required when querying single entity.
ordering Option to order the records by last timestamp,
last_modified_timestamp, and/or priority score. By default the
results are sorted by urgency score in descending order. Multi-
ordering is supported by sending a comma-separated list of
fields (e.g. ordering=urgency_score,-name )
fields Filters results to only return the fields provided. The available
fields are listed in the table above. The param can accept a
comma-separated list of fields (e.g. fields=id,name ).
exclude_fields Filters results to not return the fields provided. The available
fields are listed in the table above. The param can accept a
comma-separated list of fields (e.g. exclude_fields=id,name ).
last_detection_timestamp_gte Return only the entities which have a last detection timestamp
greater than or equal to, inclusive, formatted in ISO-8601
last_detection_timestamp_lte Return only the entities which have a last detection timestamp
less than or equal to, inclusive, formatted in ISO-8601
last_modified_timestamp_gte Return only the entities which have a last modified timestamp
equal to, inclusive, or greater than provided date, formatted in
ISO-8601
last_modified_timestamp_lte Return only the entities which have a last modified timestamp
equal to, inclusive, or less than provided date, formatted in
ISO-8601
name Filter by entity name.
note_modified_timestamp_gte Filter by note_modified_timestamp, inclusive, formatted in ISO-
8601
page Page number. Possible values are a positive integer or last
page_size Page size. Possible values are a positive integer up to 5000.
state Filter on entity activation state. Valid values are "active" or
"inactive" .
tags Filter by a tag or a comma-separated list of tags (returns
entities that contain any of the tags specified),
e.g. tags=baz or tags=foo,bar

Entity Notes
The Entity Notes API can retrieve a list of all notes associated with an entity (Account, Host).

© November 2024 Vectra AI, Inc. | 42

Version 3.4 of Entity Notes API supports GET, PATCH, POST, and DELETE to not only query the list of
notes, but also create, modify, or delete them.

The URL to retrieve Entity Notes is

https://<vectra_portal_url>/api/v3.4/entities/<entity_id>/notes and uses OAuth2
authentication.

The following table lists the top-level fields and descriptions present in the response for a bulk GET
request to the v3.4 API for Entity Notes.

ELEMENT DESCRIPTION TYPE NOTES

results A list of group objects. list
next URL to the next page of string
notes.
previous URL to the previous page string
of notes.
count The total number of notes integer
matching the query
parameters.

The following table lists the fields and descriptions present in a Group object.

Element Description Type Notes

id Auto-incrementing table id. integer

date_created Time when Note was initially string
created. ISO8601
date_modified Time Note was last modified. string
ISO8601
created_by User who created the Note. string
modified_by Last User to modify the Note. string
note Content of the Note. string

The available query parameters to filter for Entity Notes are listed below.

QUERY PARAMETER DESCRIPTION

type Allows the caller to request only entities of the given type.
Valid values are "account" or "host". Multiple values can be
provided using commas to separate values
(e.g. type=account,host ). Required when querying single
entity.

© November 2024 Vectra AI, Inc. | 43

An example of using the GET, POST,PATCH, and DELETE methods for Entity Notes can be found in
Appendix A.

Groups
The groups API can retrieve a listing of groups that are defined on the system.

Version 3.4 of groups API supports GET, PATCH, POST, and DELETE to not only query the list of
account/IP/host/domain groups, but also create, modify, or delete them.

The URL to retrieve account groups is https://<vectra_portal_url>/api/v3.4/groups and

uses OAuth2 authentication.

The following table lists the top-level fields and descriptions present in the response for a bulk GET
request to the v3.4 API for Groups.

Note that dynamic groups with large amounts of users may cause the endpoint to time out. To avoid
this, please set the “include_members” query param to False.

ELEMENT DESCRIPTION TYPE NOTES

results A list of group objects. list
next URL to the next page of string
groups.
previous URL to the previous page string
of groups.
count The total number of groups integer
matching the query
parameters.

The following table lists the fields and descriptions present in a Group object.

Element Description Type Notes

id Group ID. integer

name The group name. string
type The group type. string
cognito_managed Indication of whether group Boolean Only present when type is
is managed by Cognito “domain” or “ip”
description User defined description of string
the group.

© November 2024 Vectra AI, Inc. | 44

Element Description Type Notes

importance User defined group string One

importance. of "high", "medium", "low",
or "never_prioritize".
last_modified_timestamp Filter for all groups string Timestamp format:
modified on or after the YYYY-MM-DD HH-MM-SS
given timestamp (GTE). GMT
last_modified_by The last user that modified string
the group.
members List of member account list of
names. strings
rules List of triage rules that the list of The rules objects have the
group is attached to. objects following key names “id”,
“description”,
“triage_category” which all
have string values.
regex User defined regular string
expression used to match
and add members to
group.
membership_evaluation_ongoing True if background Boolean List of members will be
membership evaluation is empty until evaluation is
ongoing. complete.
member_count The amount of members integer
included in the group.
built_using Describes whether the
group was made with
“static_members” or
“regex’”

The available query parameters to filter for Groups are listed below.

QUERY PARAMETER DESCRIPTION

account_names Only valid when the type parameter is set to “account”. Provide
a comma-delimited (,) list of strings to filter groups associated
with accounts having one of the given names.
domains Only valid when the type parameter is set to “domain”. Provide
a comma-delimited (,) list of strings to filter groups associated
with domains having one of the given domains.
host_ids Only valid when the type parameter is set to “host”. Provide a
comma-delimited (,) list of integers to filter groups associated
with hosts having one of the given ids.
host_names Only valid when the type parameter is set to “host”. Provide a
comma-delimited (,) list of strings to filter groups associated
with hosts having one of the given names.

© November 2024 Vectra AI, Inc. | 45

QUERY PARAMETER DESCRIPTION
importance One of "high", "medium", "low", or "never_prioritize". Will
return an empty response otherwise.
ips Only valid when the type parameter is set to “ip”. Provide a
comma-delimited (,) list of strings to filter groups associated
with ips having one of the given ips.
description Filter by group description (case insensitive match).
last_modified_timestamp Filters for all groups modified on or after the given timestamp
(GTE), formatted in ISO-8601.
last_modified_by Filters groups by the user who made the most recent
modification.
name Filters by group name (case insensitive match).
type Filter by group type. Valid options: account, host, ip, domain
membership_action Exclusive parameter for PATCH requests. This will accept the
values “append”, “remove”, and “replace”. Members passed in
the request body will be used to perform the corresponding
membership update. Appendix A covers this in more detail.
is_regex Filters groups by presence of a regular expression statement.
Query will only include groups made with regex when True and
groups without regex when False.
is_membership_evaluation_ongoing Filters groups depending on if membership evaluation is
currently ongoing.
include_members Returns groups with a list of respective members if True,
returns groups with ‘members’ field as an empty list if False.
Dynamic groups may have hundreds or thousands of members
and can cause the endpoint to timeout if this query param is
not set to False.

An example of using the GET, POST, PATCH, and DELETE methods for Groups can be found in
Appendix A.

Lockdown
This is a new endpoint for to retrieve a list of entities (Accounts. Hosts) that are currently in “lockdown”
mode. API responses may vary depending on product subscriptions (Network, AWS, M365).

The URL to retrieve lockdown data is https://<vectra_portal_url>/api/v3.4/lockdown and

uses OAuth2 authentication.

The following table lists the top-level fields and descriptions present in the response for a bulk GET
request to the v3.4 API for Lockdown.

© November 2024 Vectra AI, Inc. | 46

ELEMENT DESCRIPTION TYPE NOTES
results A list of lockdown list
information
next URL to the next page of string
entity results
previous URL to the previous page string
of entity results
count Total number of entity integer
objects

The following table lists the fields and descriptions present in an lockdown result.

Element Description Type Notes

id Autoincrementing ID integer
lock_event_timestamp Time when the lockdown occurred. string
ISO8601
locked_by User who issued the lockdown. string
unlock_event_timestamp Time when the lockdown expires. string
ISO8601
entity_id ID of the related entity. integer
entity_name Name of the related entity. string
type Type of the related entity. string ‘Account’ or
‘Host’

The available query parameters to filter for lockdown.

QUERY PARAMETER DESCRIPTION

type Type of the related entity (Account, Host)

Hosts
API responses may vary depending on product subscriptions (Network, AWS, M365).

The URL to retrieve hosts is https://<vectra_portal_url>/api/v3.4/hosts and uses OAuth2

authentication.

© November 2024 Vectra AI, Inc. | 47

The following table lists the top-level fields and descriptions present in the response for a bulk GET
request to the v3.4 API for Hosts.

ELEMENT DESCRIPTION TYPE NOTES

results A list of entity objects list Will return only Accounts
next URL to the next page of string
entity results
previous URL to the previous page string
of entity results
count Total number of entity integer
objects

The following table lists the fields and descriptions present in an Entities object.

Element Description Type Notes

id Autoincrementing ID. integer Entity ID

name The name associated with the account, string
or the learned hostname.
state State of the entity, e.g. “active” or list
“inactive”.
has_active_traffic Whether a Host has active traffic. bool
active_traffic Same as ‘has_active_traffic’ bool
threat The calculated threat level of the Host. integer
t_score Same as ‘threat’.
severity Entity severity, e.g. “Low”, “Medium”, string
“High”.
certainty The calculated certainty of the Host. integer
c_score Same as ‘certainty’. integer
last_source Last source IP associated with Host. string
last_detection_timestamp Last detection activity from this Entity. string Timestamp
format:
YYYY-MM-DD
HH-MM-SS GMT
is_key_asset Whether Host is a key asset. bool
is_targeting_key_asset Whether Host is targeting a key asset. bool
probable_owner User associated with Host. string
tags User defined tags added to the entity. list
note Note attached to the Host. string

© November 2024 Vectra AI, Inc. | 48

Element Description Type Notes

note_modified_by Last user to modify note for Host. string

note_modified_timestamp Last time the note was modified. string
ISO8601
notes A list of all notes on the entity. List of Note
objects
host_artifact_set A list of associated artifacts. list
sensor Sensor associated with Host. string
sensor_name Name of the associated sensor. string
detection_set List of detections for this entity. list
url The URL link directly to this entity. string
Detection_summaries Associated detection summaries. list
Campaign_summaries Associated campaign summaries. list
Assigned_to Current user assigned to Host. string
Assigned_date Date when assignment was made. string
ISO8601
assignment Assignment object associated with object
Host.
past_assignments List of past assignments. list
privilege_level An integer from 1-10 to represent how string
privileges this account is.
privilege_category A string to represent how privileged this string
account is, related to privilege level.
Either Low (1-2), Medium (3-7), or High
(8-10).
host_luid Luid associated with Host. string
host_session_luids List of luids for corresponding Host list
sessions.
ip IP address for the Host. string
previous_ips Previously associated IP addresses. list
last_modified Time the Host was last modified. string
ISO8601
groups List of groups associated with the Host. list
has_custom_model Whether the Host has a custom model. bool
detection_profile Associated detection profile. string

The available query parameters to filter for Entities are listed below.

© November 2024 Vectra AI, Inc. | 49

QUERY PARAMETER TYPE DESCRIPTION
page integer Page number. Possible values are a positive
integer or last
page_size integer Page size. Possible values are a positive integer up
to 5000.
ordering string Option to order the records by last
timestamp and/or priority score. By default the
results are sorted by urgency score in descending
order. Multi-ordering is supported by sending a
comma-separated list of fields
(e.g. ordering=urgency_score,-name )
name string Filter by entity name.
state string Filter on entity activation state. Valid values are
"active" or "inactive" .
last_source string Filter by last source IP address.
threat integer Calculated threat level.
t_score integer Same as ‘t_score’.
t_score_gte integer Filter on ‘t_score’ over provided value.
certainty integer Calculated certainty level.
c_score integer Same as ‘c_score’.
c_score_gte integer Filter on ‘c_score’ over provided value.
last_detection_timestamp string Filter based on last detection timestamp.
ISO8601
tags string Filter by a tag or a comma-separated list of tags
(returns entities that contain any of the tags
specified), e.g. tags=baz or tags=foo,bar
key_asset bool Whether Host is or is targeting a key asset.
min_id integer Minimum ID for a Host.
max_id integer Maximum ID for a Host.
mac_address string MAC Address of the host.
note_modified_timestamp_gte string Filter by note_modified_timestamp, inclusive,
ISO8601 formatted in ISO-8601.
privilege_level integer Calculated privilege level (1-10).
privilege_level_gte integer Filter on privilege level over provided value.
privilege_category string One of ‘low’, ‘medium’, ‘high’

Health
API responses may vary depending on product subscriptions (Network, AWS, M365).

© November 2024 Vectra AI, Inc. | 50

The URL to retrieve health data is https://<vectra_portal_url>/api/v3.4/health and uses
OAuth2 authentication.
The following table lists the fields and descriptions present in a Health object.

Field Sub-Field Type Description

memory object System memory

usage_percent integer
free_bytes integer
used_bytes integer
total_bytes integer
updated_at string
ISO8601
trafficdrop object Sensor output is only shown if traffic has gone out of
baseline
sensors array
name string
ip_address string
luid string
error string
status string Status can be OK, WARNING, UNKNOWN, or SKIP
start string
end string
interfaces array
name string
baseline integer
cutoff integer
traffic integer
cpu object Processor information
user_percent integer % of CPU processing tasks
nice_percent integer % of CPU processing higher prioritized tasks
system_percent integer % of CPU processing system specific tasks
idle_percent integer % of CPU idle
updated_at string
ISO8601
hostid object

© November 2024 Vectra AI, Inc. | 51

Field Sub-Field Type Description

ip_always integer Number of IP addresses that are always covered by Host ID

when seen on the network
ip_sometimes integer Number of IP addresses that are sometimes covered by Host
ID when seen on the network
ip_never integer Number of IP addresses that are never covered by Host ID
when seen on the network
artifact_counts list of Calculated weekly
objects
updated_at string
ISO8601
network object Updates every 5 mins
interfaces list of Link speed shown in megabits per s
objects
traffic list of Link speed shown in megabits per s
objects
updated_at string
ISO8601
vlans integer
disk
disk_utilization object Includes free, used, total, and usage percentage of filesystem
in bytes
raid_disks_missing object Optional health status and errors, if any
degraded_raid_volume object Optional health status and errors, if any
disk_raid object Optional health status and errors, if any
updated_at string
ISO8601
power object Power supply information
status string
error string Optional power supply errors, if any
power_supplies list of List of power supplies and temperature information
objects
updated_at string
ISO8601
system object System Information
uptime string
serial_number string
version object Includes date of last update, version, mode, and model

© November 2024 Vectra AI, Inc. | 52

Field Sub-Field Type Description

updated_at string
ISO8601
connectivity object
sensors array
last_check string
affected_metadata_hours string Field not present if status is ‘OK’
error string
status string Status can be OK, WARNING, CRITICAL, or UNKNOWN
name string
serial_number string
luid string
ip_address string
sensors list of Sensor Information
objects
status string
name string
serial_number string
package_version string
last_seen string
ISO8601
ip_address string
luid string
location string
detection object Detection model health
updated_at string
ISO8601
check_results array One entry per failing detection model, or exactly one entry if
all detection models are healthy
name string
detection_type string
message string
status string Status can be OK or CRITICAL
event_timestamp string
ISO8601

The available query parameters to filter for Health are listed below.

© November 2024 Vectra AI, Inc. | 53

QUERY PARAMETER TYPE DESCRIPTION
cache bool True by default.
v_lans bool True by default.

Additionally, Health allows querying by field by appending the field to the end of the request url. For
example: https://<vectra_portal_url>/api/v3.4/health/memory will return only memory fields.

Health – External Connectors

The URL to retrieve health data is
https://<vectra_portal_url>/api/v3.4/health/external_connectors and uses OAuth2
authentication.

Health information is refreshed every 10 minutes. To get health information at the current time, use the
‘live’ query parameter. If refreshing health data takes more than 30 seconds, results will be stored and
can be accessed by calling the endpoint again without the ‘live’ parameter.

Field Sub-Field Type Description

external_connector object
connection_status string Current connection status. ‘enabled’ or ‘disabled’
auth_status object Authentication status. ‘authenticated’,
‘not_authenticated’, or ‘not_configured’
error_states object List of current error states. If a connection is in
error, the error message will be listed here.
lockdown_status string If lockdown can be enabled for a tenant, the
enabled status will be reflected. ‘enabled’ or
‘disabled’

Information can be queried for the following external connectors:

Field Description

active_directory Active Directory and Lockdown

azure_ad_lockdown Azure AD Lockdown
aws AWS
azure Azure
google_cloud Google Cloud
reverse_lookup_dns Reverse DNS Lookup
siem SIEM
vcenter vCenter

© November 2024 Vectra AI, Inc. | 54

Field Description

windows_event_log_ingestion Windows Event Log Ingestion

zscaler_private_access Zscaler Private Access (ZPA)

The available query parameters to filter for Health – External Connectors are listed below.

QUERY PARAMETER TYPE DESCRIPTION

data_type string Data types to be returned in the response.
Multiple values can be provided using commas to
separate values
(e.g. data_type=connection_status,auth_status ).
If no data types are given, all will be returned.
connector_type string Connector types to be returned in the response.
Multiple values can be provided using commas to
separate values (e.g. connector_type=aws,azure).
If no data types are given, all will be returned.
live bool False by default. Set to ‘true’ to refresh the data at
the current time.

Health – External Connector Details

The URL to retrieve health data is
https://<vectra_portal_url>/api/v3.4/health/external_connectors/details and
uses OAuth2 authentication.

Health information is refreshed every 10 minutes. To get health information at the current time, use the
‘live’ query parameter. If refreshing health data takes more than 30 seconds, results will be stored and
can be accessed by calling the endpoint again without the ‘live’ parameter.

Field Sub-Field Type Description

external_connector object
details object Dictionary containing detailed information for an
external connector. Detail information varies per
connector.

Detailed information can be queried for the following external connectors:

Connector Type Description

active_directory Active Directory and Lockdown

© November 2024 Vectra AI, Inc. | 55

Connector Type Description

azure_ad_lockdown Azure AD Lockdown

aws AWS
azure Azure
google_cloud Google Cloud
reverse_lookup_dns Reverse DNS Lookup
siem SIEM
vcenter vCenter
windows_event_log_ingestion Windows Event Log Ingestion
zscaler_private_access Zscaler Private Access (ZPA)

The available query parameters to filter for Health – External Connector Details are listed below.

QUERY PARAMETER TYPE DESCRIPTION

connector_type string Connector types to be returned in the response.
Multiple values can be provided using commas to
separate values (e.g. connector_type=aws,azure).
If no data types are given, all will be returned.
live bool False by default. Set to ‘true’ to refresh the data at
the current time.

Health – EDR
The URL to retrieve health data is https://<vectra_portal_url>/api/v3.4/health/edr and
uses OAuth2 authentication.

Health information is refreshed every 10 minutes. To get health information at the current time, use the
‘live’ query parameter. If refreshing health data takes more than 30 seconds, results will be stored and
can be accessed by calling the endpoint without the ‘live’ parameter.

Field Sub-Field Type Description

edr object
connection_status string Current connection status. ‘enabled’ or ‘disabled’
auth_status object Authentication status. ‘authenticated’,
‘not_authenticated’, or ‘not_configured’
error_states object List of current error states. If a connection is in error, the
error message will be listed here.
lockdown_status string If lockdown can be enabled for a tenant, the enabled
status will be reflected. ‘enabled’ or ‘disabled’

© November 2024 Vectra AI, Inc. | 56

Information can be queried for the following EDR connections:
EDR Description

host_lockdown Host Lockdown

windows_defender Microsoft Defender ATP
carbon_black Carbon Black Response
cb_cloud Carbon Black Cloud
fireeye FireEye Endpoint Security
sentinelone SentinelOne
cybereason Cybereason
crowdstrike CrowdStrike

The available query parameters to filter for Health – EDR are listed below.

QUERY PARAMETER TYPE DESCRIPTION

data_type string Data types to be returned in the response.
Multiple values can be provided using commas to
separate values
(e.g. data_type=connection_status,auth_status ).
If no data types are given, all will be returned.
edr_type string EDR types to be returned in the response.
Multiple values can be provided using commas to
separate values (e.g. edr_type=fireeye,cybereason).
If no data types are given, all will be returned.
live bool False by default. Set to ‘true’ to refresh the data at
the current time.

Health – EDR Details

The URL to retrieve health data is
https://<vectra_portal_url>/api/v3.4/health/edr/details and uses OAuth2
authentication.

Health information is refreshed every 10 minutes. To get health information at the current time, use the
‘live’ query parameter. If refreshing health data takes more than 30 seconds, results will be stored and
can be accessed by calling the endpoint again without the ‘live’ parameter.

Field Sub-Field Type Description

edr object
details object Dictionary containing detailed information for an EDR
connection. Detail information varies per connection.

© November 2024 Vectra AI, Inc. | 57

Detailed information can be queried for the following EDR connections:

EDR Description

host_lockdown Host Lockdown

windows_defender Microsoft Defender ATP
carbon_black Carbon Black Response
cb_cloud Carbon Black Cloud
fireeye FireEye Endpoint Security
sentinelone SentinelOne
cybereason Cybereason
crowdstrike CrowdStrike

The available query parameters to filter for Health – EDR Details are listed below.

QUERY PARAMETER TYPE DESCRIPTION

edr_type string EDR types to be returned in the response.
Multiple values can be provided using commas to
separate values (e.g. edr_type=fireeye,cybereason).
If no data types are given, all will be returned.
live bool False by default. Set to ‘true’ to refresh the data at
the current time.

Health – Network Brain Ping

The URL to retrieve health network brain data is
https://<vectra_portal_url>/api/v3.4/health/network_brain/ping and uses OAuth2
authentication.

Call this endpoint to receive confirmation that network brain is connected. Will also provide information
on time taken to reach the brain.

Field Sub-Field Type Description

results object
ping string Brain enabled status.
latency string Time taken to get brain status in milliseconds.

© November 2024 Vectra AI, Inc. | 58

Vectra Match Enablement
Version 3.4 of Vectra Match enablement API supports GET and POST. Changing the enablement state
on a given device using the POST endpoint requires a license for Vectra Match, and an audit log will be
emitted (NOTE: a valid Vectra Match license is not required to disable Match on a previously enabled
device if your license has expired). The API endpoint for accessing version 3.4 is
https://<vectra_management_ip>/api/v3.4/vectra-match/enablement.

The enablement GET endpoint requires a single query parameters, device_serial:

QUERY PARAMETER DESCRIPTION

device_serial Serial number of the paired device in question

The following table lists the top-level fields present in the response for a GET request to the v3.4 API for
Vectra Match enablement

ELEMENT DESCRIPTION TYPE NOTES

is_enabled Whether Vectra Match is bool
enabled on the
requested paired device
details Error output string Only returned with an
unsuccessful return code

The enablement POST endpoint requires a json body with two parameters, device_serial and
desired_state (WARNING: POSTing to the enablement endpoint causes a reboot if changing state):

JSON BODY PARAMETER DESCRIPTION

device_serial Serial number of the paired device in question
desired_state Boolean, true to enable, false to disable Vectra Match

The following table lists the top-level fields present in the response for a POST request to the v3.4 API
for Vectra Match enablement

ELEMENT DESCRIPTION TYPE NOTES

is_enabled Whether Vectra Match is bool
enabled on the
requested paired device
details Error output string Only present with an unsuccessful
return code

Examples of GET and POST methods on the vectra-match/enablement endpoint are shown in Appendix
A.

© November 2024 Vectra AI, Inc. | 59

Vectra Match Stats
Version 3.4 of Vectra Match stats API supports GET. Use of the stats endpoint for Vectra Match does
not require a valid license. The API endpoint for accessing version 3.4 is
https://<vectra_management_ip>/api/v3.4/vectra-match/stats

The stats GET endpoint allows for a single optional query parameter, device_serial. If device_serial is
not provided, information for all enabled and previously-enabled devices will be returned.

QUERY PARAMETER DESCRIPTION

device_serial Serial number of the paired device in question

The following table lists the top-level fields present in the response for a GET request to the v3.4 API for
Vectra Match stats

ELEMENT DESCRIPTION TYPE NOTES

stats List of json objects, each list object An example response can be
of which represents stats found in Appendix A
from a paired device with
Match enabled
details Error output string Only present with an unsuccessful
return code

Examples of the GET method on the vectra-match/stats endpoint is shown in Appendix A.

Vectra Match Status

Version 3.4 of Vectra Match status API supports GET. Use of the status endpoint for Vectra Match does
not require a valid license. The API endpoint for accessing version 3.4 is
https://<vectra_management_ip>/api/v3.4/vectra-match/status

The status GET endpoint allows for a single optional query parameter, device_serial. If device_serial is
not provided, information for all enabled and previously-enabled devices will be returned.

QUERY PARAMETER DESCRIPTION

device_serial Serial number of the paired device in question

The following table lists the top-level fields present in the response for a GET request to the v3.4 API for
Vectra Match status

© November 2024 Vectra AI, Inc. | 60

ELEMENT DESCRIPTION TYPE NOTES
status List of json objects, each list object An example response can be
of which represents found in Appendix A
status of a paired device
with Match enabled
details Error output string Only present with an unsuccessful
return code

Examples of the GET method on the vectra-match/status endpoint is shown in Appendix A.

Vectra Match Available Devices

Version 3.4 of Vectra Match available devices API supports GET. Use of the available devices endpoint
for Vectra Match does not require a valid license. The available devices endpoint will return information
about all currently paired sensors and, in the case of a mixed mode headend, information about the
headend itself. The API endpoint for accessing version 3.4 is
https://<vectra_management_ip>/api/v3.4/vectra-match/available-devices

The following table lists the top-level fields present in the response for a GET request to the v3.4 API for
Vectra Match available devices

ELEMENT DESCRIPTION TYPE NOTES

devices List of json objects, each list object An example response can be
of which represents found in Appendix A
information about a
paired device
details Error output string Only present with an unsuccessful
return code

Examples of the GET method on the vectra-match/available-devices endpoint is shown in Appendix A.

Vectra Match Rules

Version 3.4 of Vectra Match rules API supports GET and DELETE. Audit logs will be emitted for using
the DELETE endpoint. The API endpoint for accessing version 3.4 is
https://<vectra_management_ip>/api/v3.4/vectra-match/rules.

The rules GET endpoint requires a single query parameter, uuid:

QUERY PARAMETER DESCRIPTION

uuid UUID of desired rules file

The following table lists the top-level fields present in the response for a GET request to the v3.4 API for
Vectra Match rules

© November 2024 Vectra AI, Inc. | 61

ELEMENT DESCRIPTION TYPE NOTES
device_serials List of all device serials list If no assignments are present for
on which the ruleset is a rules file, device_serials will be
currently running an empty list.
hashsum sha256 sum of file string
name Display name of file string Rules cannot be referenced in API
operations by their display name,
UUID must be used
notes Notes about a file object Notes are added by the user
when uploading a new rules file
timestamp Timestamp of file upload string ISO-8601 format
time
uuid UUID of file string Use this UUID in later API calls to
reference this ruleset
details Error output string Only returned with an
unsuccessful return code

The rules DELETE endpoint requires a json body with a single parameter, uuid:

JSON BODY PARAMETER DESCRIPTION

uuid UUID of desired rules file

The following table lists the top-level fields present in the response for a DELETE request to the v3.4 API
for Vectra Match rules

ELEMENT DESCRIPTION TYPE NOTES

details Output string details will be ‘success’ if
successful, otherwise, will contain
information about the failure.

Examples of GET and DELETE methods on the vectra-match/rules endpoint are shown in Appendix A.

Vectra Match Rules Upload

Version 3.4 of Vectra Match rules upload API supports GET, POST, and PATCH. Uploading a rules file
requires a valid license for Vectra Match. Audit logs will be emitted for using the POST and PATCH
endpoints.

Once a rules file upload has been created, the API will return a uuid. This uuid will be used for managing
the ruleset upload from that point forward. The upload uuid is different to the rules file uuid.

The API endpoint for accessing version 3.4 is

https://<vectra_management_ip>/api/v3.4/vectra-match/rules/upload/.

© November 2024 Vectra AI, Inc. | 62

The process for performing a rules upload is:
1. Start a new rules file upload by POSTing a JSON body with the file_name and notes to
/api/v3.4/vectra-match/rules/upload/. This will return a UUID representing the upload
and a temporary upload URL.
2. Use the upload URL from step 1 to upload the file data
curl --request PUT --upload-file valid_rules.rules <URL>
3. Mark the upload as completed
PATCH /api/v3.4/vectra-match/rules/upload/<uuid>
The file will be sent to your appliance
4. Confirm the file has synced successfully to the appliance
GET /api/v3.4/vectra-match/rules/upload/<uuid>
5. On successful sync to the appliance, the file will appear in the rules_to_devices_map list of
Vectra Match rules
GET /api/v3.4/vectra-match/assignment

The rules POST endpoint takes the following JSON body parameters:

JSON BODY PARAMETER DESCRIPTION

file_name The name of the file to be uploaded. This will be show in the list
of rules.
notes Additional notes (optional)

Example of using POST endpoint with cURL:

curl --request POST \

--url https://<vectra_management_url>/api/v3.4/vectra-match/rules/uploads/ \
--header 'Authorization: Bearer <token>" \
--header 'Content-Type: application/json' \
--data '{"file_name": "<your-filename.rules>", "notes": "We can put some
notes here"}'

Example of using POST endpoint with Python Requests:

payload = {"file_name": "your-rules.rules", "notes": "additional notes here"}

resp = requests.post("https://<vectra_management_ip>/api/v3.4/vectra-
match/rules/upload/", headers={"Authorization":"Bearer <token>"},
verify=False, json=payload

The following table lists the top-level fields present in the response for a POST request to the v3.4 API
for Vectra Match rules upload

© November 2024 Vectra AI, Inc. | 63

ELEMENT DESCRIPTION TYPE NOTES
id UUID of file upload string Use this UUID in later API calls to
reference this upload
urls URL to upload the file List of This version of the API will only
data strings return one URL in the list.
The URL returned will expire after
2 minutes.

The PATCH endpoint requires a query parameter and json body parameters:

QUERY PARAMETER DESCRIPTION

UUID UUID of upload

JSON BODY PARAMETER DESCRIPTION

upload_status New upload status. Possible values: “completed”, “aborted”

The following table lists the top-level fields present in the response for a PATCH request to the v3.4 API
for Vectra Match rules

ELEMENT DESCRIPTION TYPE NOTES

upload_status Current upload status string Possible values: “completed”,
“aborted
The response confirms that you
have modified the upload status.

The following table lists the top-level fields and descriptions present in the response for a bulk GET
request to the v3.4 API for Vectra Match Rules Uploads.

ELEMENT DESCRIPTION TYPE NOTES

results A list of upload objects. list
next URL to the next page of string
notes.
previous URL to the previous page string
of notes.
count The total number of integer
uploads within the last day

The following table lists the fields and descriptions present in an Upload object.

© November 2024 Vectra AI, Inc. | 64

ELEMENT DESCRIPTION TYPE NOTES
id UUID of file upload string Use this UUID in later API calls to
reference this upload
upload_status Upload status string Possible values: “completed”,
“aborted”, “pending”
external_task_status Status of sync to string Possible values: “in_progress”,
appliance “not_started”, “success”, “failed”
external_task_updated_at Timestamp of when the string ISO-8601 format
status was last updated
external_task_error Error details string Ruleset validation errors start with
"Uploaded Vectra Match ruleset
failed validation, errors: "
external_task_error_code A numeric code for the integer 6001 More than 25 files are
error currently stored by Vectra
Match. Please delete any
unused files and try again
6002 Internal Server Error
6003 You are not licensed to
use Vectra Match, please
contact support to enable
this feature
6004 Failed to upload Vectra
Match ruleset, as a
ruleset with the same
hashsum already exists,
hashsum: {hashsum}
6005 Uploaded Vectra Match
ruleset failed validation,
errors: {}

The rules GET endpoint can take a single query parameter, uuid:

QUERY PARAMETER DESCRIPTION

uuid UUID for rules file upload

The GET endpoint will return a single upload object if it exists. See bulk get endpoint above for details of
the upload object.

Examples of GET, POST, and PATCH methods on the vectra-match/rules/upload endpoint are shown in
Appendix A.

© November 2024 Vectra AI, Inc. | 65

Vectra Match Assignment
Version 3.4 of Vectra Match assignment API supports GET, POST, and DELETE. Adding a new
assignment via POST requires a valid license for Vectra Match. Audit logs will be emitted for using the
POST and DELETE endpoints. The API endpoint for accessing version 3.4 is
https://<vectra_management_ip>/api/v3.4/vectra-match/assignment.

The following table lists the top-level fields present in the response for a GET request to the v3.4 API for
Vectra Match assignment

ELEMENT DESCRIPTION TYPE NOTES

device_to_rules_map List of objects, each of list of An example map can be found in
which represents a objects Appendix A
device, providing
information about which
ruleset is being run on
that device, who
updated it, and when it
was last updated
rules_to_devices_map List of objects, each of list of An example map can be found in
which represents a rules objects Appendix A
file, providing information
about which devices that
ruleset is being run on,
and other metadata
about the file
details Error output string Only returned with an
unsuccessful return code

The assignment POST endpoint requires a json body with two parameters, device_serials and uuid:

JSON BODY PARAMETER DESCRIPTION

device_serials List of serial numbers to assign the ruleset of <uuid> to
uuid UUID of ruleset to assign to specified device(s)

The following table lists the top-level fields present in the response for a POST request to the v3.4 API
for Vectra Match assignment

ELEMENT DESCRIPTION TYPE NOTES

details Output string details will be ‘success’ if
successful, otherwise, will contain
information about the failure.

The assignment DELETE endpoint requires a json body with two parameters, device_serial and uuid:

JSON BODY PARAMETER DESCRIPTION

device_serial Serial numbers to remove assignment from

© November 2024 Vectra AI, Inc. | 66

JSON BODY PARAMETER DESCRIPTION
uuid UUID of ruleset

The following table lists the top-level fields present in the response for a DELETE request to the v3.4 API
for Vectra Match assignment

ELEMENT DESCRIPTION TYPE NOTES

details Output string details will be ‘success’ if
successful, otherwise, will contain
information about the failure.

Examples of GET, POST, and DELETE methods on the vectra-match/assignment endpoint are shown in
Appendix A.

Vectra Match Alert Stats

Version 3.4 of Vectra Match alert stats API supports GET. Use of the alert stats endpoint for Vectra
Match does not require a valid license. The API endpoint for accessing version 3.4 is
https://<vectra_management_ip>/api/v3.4/vectra-match/alert-stats

The alert stats GET endpoint allows for a single optional query parameter, device_serial. If device_serial
is not provided, information for all enabled devices will be returned.

QUERY PARAMETER DESCRIPTION

device_serial Serial number of the paired device in question

The following table lists the top-level fields present in the response for a GET request to the v3.4 API for
Vectra Match alert stats

ELEMENT DESCRIPTION TYPE NOTES

alert_stats List of json objects, each list object An example response can be
of which represents alert found in Appendix A
stats from a paired
device with Match
enabled
details Error output string Only present with an unsuccessful
return code

Examples of the GET method on the vectra-match/alert-stats endpoint is shown in Appendix A.

Threat Feeds
API responses may vary depending on product subscriptions (Network, AWS, M365).

© November 2024 Vectra AI, Inc. | 67

The threat feeds API can be used to automate the upload of STIX files for threat intelligence matching.
The API endpoint can also be used to retrieve the current list of threat feed objects already configured in
the system.

To obtain the list of threat feeds (GET) or to create a new threat Feed (POST) use the following URL:
https://<vectra_management_ip>/api/v3.4/threatFeeds

To obtain details of any threat feed (GET), add a file to a threat feed (POST), update a threat feed
(PATCH), or delete a threat feed (DELETE) use the following URL:
https://<vectra_management_ip>/api/v3.4/threatFeeds/<id>

To download a threat feed file (GET) or delete a threat feed file (DELETE), use the following URL:
https://<vectra_management_ip>/api/v3.4/threatFeeds/<id>/file

where <id> is the id of the threat feed.

File Upload Specifications

There is a hard limit for file upload sizes of 5 MB at this time. If you receive a “413 Payload Too Large”
error while uploading a file via POST /api/v3.4/threatFeeds/<id>, the file you are attempting to
upload is too large. There is no limit on the amount of threatFeeds files you can upload, so we
recommend splitting apart your STIX file into smaller parts and uploading each as its own threat feed so
that each file is below the 5MB limit.

The following table lists the fields and a description of the various elements for the “threatFeeds”.
Detailed examples of using GET, POST on threatFeeds is described in Appendix A

ELEMENT DESCRIPTION TYPE NOTES

name The name of the threat string
feed
id The ID of the threat feed string

_rev The revision ID of the string

threat feed
lastUpdatedBy The user who updated string
the threat feed
version Version of the threat string
feed
uploadDate Timestamp the threat string
feed was created ISO8601
lastUpdated Timestamp the threat string
feed was last updated ISO8601
uploadResults Dictionary describing file object Includes indicatorType, expiration,
uploaded observableCount, certainty,
category

© November 2024 Vectra AI, Inc. | 68

ELEMENT DESCRIPTION TYPE NOTES
defaults Dictionary describing object Includes indicatorType, category,
threat feed default certainty, duration
values
type Threat Feed type string

The available query parameters to filter for Threat Feeds are listed below.

QUERY PARAMETER TYPE DESCRIPTION

category string
certainty string
expiration string
ISO8601
lastUpdated string
ISO8601
lastUpdatedBy string
name string
ordering string
page integer
page_size integer Limit number of threat feeds returned

Vectra Match Curated Ruleset Download

The Vectra Match Curated Ruleset can now be downloaded via the API via GET. This will provide a
download url which expires after 2 minutes

Users with a valid license can request a download link to the file via GET to
https://<vectra_management_ip>/api/v3.4/vectra-match/download-vectra-ruleset

Unique Hosts Observed Monthly

API responses may vary depending on product subscriptions (Network, AWS, M365).

The unique hosts observed API can be used to view the count of all distinct hosts seen during a
calendar month, for each month dating back one year. The endpoint is only available to Restricted
Admin clients.

To obtain the list of unique hosts observed (GET) use the following URL:
https://<vectra_management_ip>/api/v3.4/unique_hosts_observed_monthly/

The following table lists the fields and a description of the various elements for the month results.
Detailed examples of using GET on unique_hosts_observed_monthly is described in Appendix A

© November 2024 Vectra AI, Inc. | 69

ELEMENT DESCRIPTION TYPE NOTES
month_start First day of the month string

month_end Last day of the month string

unique_hosts_observed Count of unique hosts integer Includes hosts seen from 00:00
observed between UTC on first day of month through
month_start and 23:59 UTC on last day of month
month_end

The available query parameters to filter for Unique Hosts Observed Monthly are listed below.
Note if start and end are left blank, default start will be the beginning of the month of the previous year.
Default end will be the current day.

QUERY PARAMETER TYPE DESCRIPTION

start string Starting month of data list. Example: ‘2023-08’
ISO8601
end string Ending month of data list. Example: ‘2023-09’
ISO8601
last_month_only boolean Only return current month’s count.

Unique Hosts Observed Monthly – Audit

API responses may vary depending on product subscriptions (Network, AWS, M365).

The unique hosts observed API can be used to view of all the distinct hosts seen during a calendar
month, for each month dating back one year. The endpoint is only available to Restricted Admin clients.

To obtain the list of unique hosts (GET) use the following URL:
https://<vectra_management_ip>/api/v3.4/unique_hosts_observed_monthly/audit

The following table lists the fields and a description of the various elements for the month results.
Detailed examples of using GET on unique_hosts_observed_monthly/audit is described in Appendix A

ELEMENT DESCRIPTION TYPE NOTES

month Formatted as ‘YYYY-MM’ timestamp

host_id Related Host ID (if available) integer

host_luid Host LUID (if available) string

ip_address string

host_artifact_value Host Artifact Value (if available) string

host_artifact_type Host Artifact Type (if available) string

© November 2024 Vectra AI, Inc. | 70

ELEMENT DESCRIPTION TYPE NOTES
last_seen_start Last seen start timestamp The column is ‘last_seen’
because it gets updated at
new host sessions are
created. Host may have
been seen at more times
than what is recorded.
last_seen_end Last seen end timestamp The column is ‘last_seen’
because it gets updated at
new host sessions are
created. Host may have
been seen at more times
than what is recorded.

The available query parameters to filter for Unique Hosts Observed Monthly - Audit are listed below.

QUERY PARAMETER TYPE DESCRIPTION

month string Month of host records to be returned
ISO8601
start string Starting month of data list. Example: ‘2023-08’
ISO8601
end string Ending month of data list. Example: ‘2023-09’
ISO8601
page integer
page_size integer Limit number of host records returned

Unique Hosts Observed

API responses may vary depending on product subscriptions (Network, AWS, M365).

The unique hosts observed API can be used to view the count of all distinct hosts seen during a given
timespan dating back one year. The endpoint is only available to Restricted Admin clients.

To obtain the list of unique hosts observed (GET) use the following URL:
https://<vectra_management_ip>/api/v3.4/unique_hosts_observed/

The following table lists the fields and a description of the various elements for the month results.
Detailed examples of using GET on unique_hosts_observed is described in Appendix A

ELEMENT DESCRIPTION TYPE NOTES

start First day of timespan string

end Last day of timespan string

© November 2024 Vectra AI, Inc. | 71

ELEMENT DESCRIPTION TYPE NOTES
unique_hosts_observed Count of unique hosts integer Includes hosts seen from 00:00
observed between start UTC on start day through 23:59
and end UTC on end day of timespan

The available query parameters to filter for Unique Hosts Observed are listed below.

QUERY PARAMETER TYPE DESCRIPTION

start string Start date of data list. Example: ‘2023-08-15’
ISO8601
end string End date of data list. Example: ‘2023-09-31’
ISO8601
offset string Timezone offset to be used. Example: ‘+0700’
ISO8601

Unique Hosts Observed – Audit

API responses may vary depending on product subscriptions (Network, AWS, M365).

The unique hosts observed audit API can be used to view of all the distinct hosts seen during a given
timespan dating back one year. The endpoint is only available to Restricted Admin clients.

Note that counts between unique hosts observed count API and this API may differ. This is because
unique hosts may appear at varying times. This audit endpoint returns all relevant information about
unique hosts including their individual sessions.

To obtain the list of unique hosts (GET) use the following URL:
https://<vectra_management_ip>/api/v3.4/unique_hosts_observed/audit

The following table lists the fields and a description of the various elements for the month results.
Detailed examples of using GET on unique_hosts_observed/audit is described in Appendix A

ELEMENT DESCRIPTION TYPE NOTES

host_id Related Host ID (if available) integer

host_luid Host LUID (if available) string

ip_address string

host_artifact_value Host Artifact Value (if available) string

host_artifact_type Host Artifact Type (if available) string

last_seen_start Last seen start timestamp The column is ‘last_seen’

because it gets updated at
new host sessions are
created. Host may have
been seen at more times
than what is recorded.

© November 2024 Vectra AI, Inc. | 72

ELEMENT DESCRIPTION TYPE NOTES
last_seen_end Last seen end timestamp The column is ‘last_seen’
because it gets updated at
new host sessions are
created. Host may have
been seen at more times
than what is recorded.

The available query parameters to filter for Unique Hosts Observed - Audit are listed below.
Note if start and end are left blank, default start will be the beginning of the month of the previous year.
Default end will be the current day.

QUERY PARAMETER TYPE DESCRIPTION

start string Start date of data list. Example: ‘2023-08-15’
ISO8601
end string End date of data list. Example: ‘2023-09-31’
ISO8601
offset string Timezone offset to be used. Example: ‘+0700’
ISO8601
page integer
page_size integer Limit number of host records returned

Appendix A
This section will include examples of data retrieved from the REST API 3.4. Due to the amount of data
that can be retrieved from a single query, the output examples below show only a snippet of the actual
data that can be retrieved.

Note: The information in the following examples was generated in a lab environment. Any reference to IP
addresses similar to those used in your environment is purely coincidental.

Detections
GET

URL: https://<vectra_portal_url>/api/v3.4/detections/4

Headers:
"Authorization": "Bearer <access_token>"

Response:
{

© November 2024 Vectra AI, Inc. | 73

 "summary": {
"user_type": "Regular",
"azure_ad_privilege": {
"privilege": 2,
"privilegeCategory": "Low"
},
"num_events": 2,
"operations": [
"Consent to application.",
"Add delegated permission grant."
],
"src_ips": [],
"target_entities": [
"atlassian",
"microsoft graph"
],
"description": "This account was seen using an operation associated with a
high privilege admin activity that was anomalous for the user."
},
"threat": 0,
"note_modified_by": null,
"detection_category": "LATERAL MOVEMENT",
"is_marked_custom": false,
"detection_type": "Azure AD Privilege Operation Anomaly",
"note_modified_timestamp": null,
"assigned_to": null,
"detection": "Azure AD Privilege Operation Anomaly",
"note": null,
"groups": [],
"tags": [],
"assigned_date": null,
"src_ip": null,
"certainty": 0,
"last_timestamp": "2021-12-11T19:52:31Z",
"src_account": {
"id": 1,
"name": "O365:[email protected]",
"url": "http://123456789.uw2.portal.vectra.ai/api/v3.4/accounts/1",
"threat": 0,
"certainty": 0,
"privilege_level": null,
"privilege_category": null
},
"sensor": "tzlgmx99",
"detection_url": "http://123456789.uw2.portal.vectra.ai/api/v3.4/detections/4",
"first_timestamp": "2021-12-11T19:52:31Z",
"custom_detection": null,
"sensor_name": "Vectra X",

© November 2024 Vectra AI, Inc. | 74

 "is_custom_model": false,
"id": 4,
"state": "inactive",
"notes": [],
"is_targeting_key_asset": false,
"triage_rule_id": null,
"url": "http://123456789.uw2.portal.vectra.ai/api/v3.4/detections/4",
"description": null,
"grouped_details": [
{
"operation": "Consent to application.",
"target_entity": "atlassian",
"src_ips": [],
"user_type": "Regular",
"num_events": 1,
"azure_ad_privilege": {
"privilege": 2,
"privilegeCategory": "Low"
},
"operation_details": [
{
"display_name": "ConsentContext.IsAdminConsent",
"new_value": "False",
"old_value": null
},
{
"display_name": "ConsentContext.IsAppOnly",
"new_value": "False",
"old_value": null
},
{
"display_name": "ConsentContext.OnBehalfOfAll",
"new_value": "False",
"old_value": null
},
{
"display_name": "ConsentContext.Tags",
"new_value": "WindowsAzureActiveDirectoryIntegratedApp",
"old_value": null
},
{
"display_name": "ConsentAction.Permissions",
"new_value": "[] => [[Id:
kD4Wx1xB5kavt9rlFq0oJvsgHpNuEWpCvthhgPPoPIRqrXjJgw92RIqby2TABWol, ClientId: c7163e90-
415c-46e6-afb7-dae516ad2826, PrincipalId: c978ad6a-0f83-4476-8a9b-cb64c0056a25,
ResourceId: 931e20fb-116e-426a-bed8-6180f3e83c84, ConsentType: Principal, Scope:
openid profile email]]; ",
"old_value": null

© November 2024 Vectra AI, Inc. | 75

 },
{
"display_name": "TargetId.ServicePrincipalNames",
"new_value": "46cdaa3f-9339-4b60-bf04-4dd98cd903d7",
"old_value": null
}
],
"normal_operations": [
"UserLoggedIn"
],
"normal_account_objects": [
{
"id": 11,
"uid": "O365:[email protected]"
}
],
"last_timestamp": "2021-12-11T19:52:31Z"
},
{
"operation": "Add delegated permission grant.",
"target_entity": "microsoft graph",
"src_ips": [],
"user_type": "Regular",
"num_events": 1,
"azure_ad_privilege": {
"privilege": 2,
"privilegeCategory": "Low"
},
"operation_details": [
{
"display_name": "DelegatedPermissionGrant.Scope",
"new_value": " openid profile email",
"old_value": null
},
{
"display_name": "DelegatedPermissionGrant.ConsentType",
"new_value": "Principal",
"old_value": null
},
{
"display_name": "ServicePrincipal.ObjectID",
"new_value": "c7163e90-415c-46e6-afb7-dae516ad2826",
"old_value": null
},
{
"display_name": "ServicePrincipal.DisplayName",
"new_value": null,
"old_value": null

© November 2024 Vectra AI, Inc. | 76

 },
{
"display_name": "ServicePrincipal.AppId",
"new_value": null,
"old_value": null
},
{
"display_name": "ServicePrincipal.Name",
"new_value": null,
"old_value": null
},
{
"display_name": "TargetId.ServicePrincipalNames",
"new_value":
"https://canary.graph.microsoft.com/;https://graph.microsoft.us/;https://dod-
graph.microsoft.us/;https://dod-
graph.microsoft.us;https://graph.microsoft.com/;https://graph.microsoft.us;https://can
ary.graph.microsoft.com;https://graph.microsoft.com;https://ags.windows.net;00000003-
0000-0000-c000-000000000000/ags.windows.net;00000003-0000-0000-c000-000000000000",
"old_value": null
}
],
"normal_operations": [
"UserLoggedIn"
],
"normal_account_objects": [],
"last_timestamp": "2021-12-11T19:52:30Z"
}
],
"campaign_summaries": [],
"is_triaged": false
}

Detections (Notes)
GET

URL: https://<vectra_portal_url>/api/v3.4/detections/<detection_id>/notes

Headers:
"Authorization": "Bearer <access_token>"

Response:
[
{
"id": 1,
"date_created": "2021-01-11T13:42:43Z",

© November 2024 Vectra AI, Inc. | 77

 "date_modified": null,
"created_by": "vadmin",
"modified_by": null,
"note": "this is a detection note"
},
{
"id": 2,
… … …
}
]

POST

URL: https://<vectra_portal_url>/api/v3.4/detections/<detection_id>/notes

Headers:
"Authorization": "Bearer <access_token>",
"Content-Type": "application/json"

Body:
{"note":"this is a detection note"}
Response:
{
"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"
}

GET

URL: https://<vectra_portal_url>/api/v3.4/detections/<detection_id>/notes/<note_id>

Headers:
"Authorization": "Bearer <access_token>"

Response:
{
"id": 1,
"date_created": "2021-01-11T13:54:47.987918Z",
"date_modified": null,
"created_by": "vadmin",
"modified_by": null,
"note": " this is a detection note "
}

© November 2024 Vectra AI, Inc. | 78

PATCH

URL: https://<vectra_portal_url>/api/v3.4/detections/<detection_id>/notes/<note_id>

Headers:
"Authorization": "Bearer <access_token>",
"Content-Type": "application/json"

Body:
{
"note": “updated note”
}

Response:
{
"id": 1,
"date_created": "2021-01-11T13:47:42Z",
"date_modified": "2021-01-11T13:57:11Z",
"created_by": "vadmin",
"modified_by": "vadmin",
"note": "updated note"
}

DELETE

URL: https://<vectra_portal_url>/api/v3.4/detections/<detection_id>/notes/<note_id>

Headers:
"Authorization": "Bearer <access_token>"

Mark as Fixed
PATCH to mark/unmark a detection as fixed.

URL: https://<vectra_portal_url>/api/v3.4/detections

Headers:
"Authorization": "Bearer <access_token>",
"Content-Type": "application/json"

Body:
{
"detectionIdList": [128, 129],
"mark_as_fixed": "True"
}

© November 2024 Vectra AI, Inc. | 79

Response:
{
"_meta": {
"level": "Success",
"message": "Successfully marked detections"
}
}

Tagging
GET to list tags on an account or detection.

URL for accounts:

https://<vectra_portal_url>/api/v3.4/tagging/account/<account_id>
URL for detections:
https://<vectra_portal_url>/api/v3.4/tagging/detection/<detection_id>

URL for hosts:

https://<vectra_portal_url>/api/v3.4/tagging/host/<host_id>

URL for entities:

https://<vectra_portal_url>/api/v3.4/tagging/entity/<entity_id>?type=<entity_type>

Headers:
“Authorization”: “Bearer <access_token>”

Response:
{
"status": "success",
"tags": [
"newticket",
"under_investigation"
],
"entity_id": "1000"
}

PATCH to add “new_tag” for an account.

URL for accounts:

https://<vectra_portal_url>/api/v3.4/tagging/account/<account_id>

URL for detections:

https://<vectra_portal_url>/api/v3.4/tagging/detection/<detection_id>

© November 2024 Vectra AI, Inc. | 80

URL for hosts:
https://<vectra_portal_url>/api/v3.4/tagging/host/<host_id>

URL for entities:

https://<vectra_portal_url>/api/v3.4/tagging/entity/<entity_id>?type=<entity_type>

Headers:
“Authorization”: “Bearer <access_token>”,
“Content-Type”: “application/json”

Body:
{
"tags": [“newticket”, “under_investigation”]
}

Response:
{
"status": "success",
"tags": [
"newticket",
"under_investigation"
],
"entity_id": "1000"
}

PATCH to clear tags for a detection

URL for accounts:

https://<vectra_portal_url>/api/v3.4/tagging/account/<account_id>

URL for detections:

https://<vectra_portal_url>/api/v3.4/tagging/detection/<detection_id>

Headers:
“Authorization”: “Bearer <access_token>”,
“Content-Type”: “application/json”

Body:
{
"tags": []
}

Patch operation will alter the tags for the account or detection to match the “tags” list provided in the
PATCH.

© November 2024 Vectra AI, Inc. | 81

Accounts
GET

URL: https://<vectra_portal_url>/api/v3.4/accounts/1

Headers:
"Authorization": "Bearer <access_token>"

Response:
{
"id": 1,
"url": "http://123456789.uw2.portal.vectra.ai/api/v3.4/accounts/1",
"name": "O365:[email protected]",
"state": "inactive",
"threat": 0,
"certainty": 0,
"severity": "Low",
"account_type": [
"o365"
],
"tags": [],
"note": null,
"notes": [],
"note_modified_by": null,
"note_modified_timestamp": null,
"privilege_level": null,
"privilege_category": null,
"last_detection_timestamp": "2021-12-20T18:11:16Z",
"detection_set": [
"http://123456789.uw2.portal.vectra.ai/api/v3.4/detections/1",
"http://123456789.uw2.portal.vectra.ai/api/v3.4/detections/4"
],
"probable_home": null,
"assignment": null,
"past_assignments": [],
"sensors": [
"tzlgmx99"
],
"detection_summaries": [
{
"detection_id": 1,
"detection_url":
"http://123456789.uw2.portal.vectra.ai/api/v3.4/detections/1",
"detection_type": "O365 Internal Spearphishing",
"detection_category": "LATERAL MOVEMENT",

© November 2024 Vectra AI, Inc. | 82

 "is_targeting_key_asset": false,
"state": "inactive",
"threat": 0,
"certainty": 0,
"is_triaged": false,
"tags": [],
"summary": {
"subject": [
"Sandbox: Congratulations, you just won!"
],
"recipients": [
"[email protected]",
"[email protected]",
"[email protected]",
"[email protected]",
"[email protected]"
],
"recipients_count": 24,
"description": "This account sent emails containing malware,
suspicious links, or bad reputation."
},
"assigned_to": null,
"assigned_date": null
},
{
"detection_id": 4,
"detection_url":
"http://123456789.uw2.portal.vectra.ai/api/v3.4/detections/4",
"detection_type": "Azure AD Privilege Operation Anomaly",
"detection_category": "LATERAL MOVEMENT",
"is_targeting_key_asset": false,
"state": "inactive",
"threat": 0,
"certainty": 0,
"is_triaged": false,
"tags": [],
"summary": {
"user_type": "Regular",
"azure_ad_privilege": {
"privilege": 2,
"privilegeCategory": "Low"
},
"num_events": 2,
"operations": [
"Consent to application.",
"Add delegated permission grant."
],
"src_ips": [],

© November 2024 Vectra AI, Inc. | 83

 "target_entities": [
"atlassian",
"microsoft graph"
],
"description": "This account was seen using an operation associated
with a high privilege admin activity that was anomalous for the user."
},
"assigned_to": null,
"assigned_date": null
}
]
}

Account (Notes)
GET

URL: https://<vectra_portal_url>/api/v3.4/accounts/<account_id>/notes

Headers:
"Authorization": "Bearer <access_token>"

Response:
[
{
"id": 1,
"date_created": "2021-01-11T13:42:43Z",
"date_modified": null,
"created_by": "vadmin",
"modified_by": null,
"note": "this is an account note"
},
{
"id": 2,
… … …
}
]

POST

URL: https://<vectra_portal_url>/api/v3.4/accounts/<account_id>/notes

Headers:
"Authorization": "Bearer <access_token>",
“Content-Type”: “application/json”

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

© November 2024 Vectra AI, Inc. | 84

Response:
{
"id": 2,
"date_created": "2021-01-11T14:14:10.527603Z",
"date_modified": null,
"created_by": "vadmin",
"modified_by": null,
"note": "this is a note"
}

GET

URL: https://<vectra_portal_url>/api/v3.4/accounts/<account_id>/notes/<note_id>

Headers:
"Authorization": "Bearer <access_token>"

Response:
{
"id": 1,
"date_created": "2021-01-11T13:54:47.987918Z",
"date_modified": null,
"created_by": "vadmin",
"modified_by": null,
"note": " this is an account note "
}

PATCH

URL: https://<vectra_portal_url>/api/v3.4/accounts/<account_id>/notes/<note_id>

Headers:
"Authorization": "Bearer <access_token>",
“Content-Type”: “application/json”

Body:
{"note": "updated note"}

Response:
{
"id": 1,
"date_created": "2021-01-11T13:47:42Z",
"date_modified": "2021-01-11T13:57:11Z",
"created_by": "vadmin",
"modified_by": "vadmin",

© November 2024 Vectra AI, Inc. | 85

 "note": "updated note"
}

DELETE

URL: https://<vectra_portal_url>/api/v3.4/accounts/<account_id>/notes/<note_id>

Headers:
"Authorization": "Bearer <access_token>"

Triage Rules
GET

URL: https://<vectra_portal_url>/api/v3.4/rules/<id>

Headers:
"Authorization": "Bearer <access_token>"

Response:
{
"id": 68,
"url": "https://1.1.1.1/api/v3.4/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": [
{
"AND": [
{
"ANY_OF": {
"field": "remote1_port",
"values": [
{
"url": null,
"value": "135",
"label": "135"
}
],

© November 2024 Vectra AI, Inc. | 86

 "groups": [],
"label": "Port"
}
}
]
}
]
},
"source_conditions": {
"OR": [
{
"AND": [
{
"ANY_OF": {
"field": "host",
"values": [],
"groups": [
{
"url": "https://192.168.51.36/api/v3.4/groups/8",
"value": 8,
"label": "Cognito - IPAM"
}
],
"label": "Host"
}
}
]
}
]
},
"detection_category": "RECONNAISSANCE",
"triage_category": "Expected IPAM Behavior",
"detection": "Internal Darknet Scan"
}

POST

URL: https://<vectra_portal_url>/api/v3.4/rules

Headers:
"Authorization": "Bearer <access_token>",
"Content-Type": "application/json"

Body:
{

© November 2024 Vectra AI, Inc. | 87

"description": "Peer to peer triage rule",
"detection_category": "COMMAND & CONTROL",
"triage_category": "Miscategorization",
"detection": "Peer-to-Peer",
"is_whitelist": false,
"additional_conditions": {
"OR": [
{
"AND": [
{
"ANY_OF": {
"field": "remote1_ip",
"values": [],
"groups": [
{
"value": 2
}
]
}
},
{
"ANY_OF": {
"field": "remote1_dns",
"values": [
{
"value": "test.server.com"
}
],
"groups": [
{
"value": 11
}
]
}
}
]
}
]
},
"source_conditions": {
"OR": [
{
"AND": [
{
"ANY_OF": {
"field": "host",
"values": [
{

© November 2024 Vectra AI, Inc. | 88

 "value": 1
}
],
"groups": [
{
"value": 8
}
]
}
}
]
}
]
}
}

The following fields are mandatory:

“detection_category”: Must be set to the category of the detection – LATERAL MOVEMENT,

RECONNAISSANCE, COMMAND & CONTROL, EXFILTRATION, BOTNET, INFO

“detection”: The detection that must be triaged. Use the detection name as seen in the UI or the
“Understanding Vectra Detections” guide.

“triage_category”: The name that will be used for the triaged detection. Only applies if “is_whitelist” is
set to 0.

“description”: User defined description for the rule.

“is_whitelist”: A Boolean flag indicating whether to create a “whitelist” or a “track without scores” rule
source_conditions: conditions that can be applied to the source of a detection. Can be NULL.

additional_conditions: other conditions that are different on a per-detection-type basis. Can be NULL.

Response:

Success
The response contains the id of the triage rule if successful:

{
"_meta": {
"message": "Successfully created triage filter",
"level": "success"
},
"id": 11

© November 2024 Vectra AI, Inc. | 89

}

Failure
Failure will result in an error message along with an indication of what was incorrect

{
"_meta": {
"message": "Invalid field(s) found",
"level": "error"
},
"host": [
"Invalid host: 5 does not map to a real host"
]
}

PUT

URL: https://<vectra_portal_url>/api/v3.4/rules/<id>

Headers:
"Authorization": "Bearer <access_token>",
"Content-Type": "application/json"

Body:
{
"detection_category": "LATERAL MOVEMENT",
"triage_category": "Susp Rmt Exec - Test",
"detection": "Suspicious Remote Execution",
"is_whitelist": 0,
"description": "put test",
"additional_conditions": {
"OR": [
{
"AND": [
{
"ANY_OF": {
"field": "remote1_ip",
"values": [
{
"value": "1.1.1.1"
}
],
"groups": [],
}
}
]
}

© November 2024 Vectra AI, Inc. | 90

 ]
},
"source_conditions": {
"OR": [
{
"AND": [
{
"ANY_OF": {
"field": "ip",
"values": [
{"value": "1.1.1.1"},
{"value": "1.2.1.1"},
{"value": "1.1.3.1"}
],
"groups": []
}
}
]
}
]
}

DELETE

URL: https://<vectra_portal_url>/api/v3.4/rules/<id>

Headers:
"Authorization": "Bearer <access_token>",
"Content-Type": "application/json"

Body:
{
"detectionIdLIst": [<detection_id1>, <detection_id2>, …]
}

Users
GET

URL: https://<vectra_portal_url>/api/v3.4/users

Headers:
"Authorization": "Bearer <access_token>"

© November 2024 Vectra AI, Inc. | 91

Response:
{
"count": 4,
"next": null,
"previous": null,
"results": [
{
"id": 24,
"email": "[email protected]",
"role": "Super Admin",
"last_login_timestamp": "2023-05-03T14:49:09Z",
"verified ": true
“identities”: [
{“type”: “local”},
{“type”: “SAML”, “saml_profile_id”: 1}
]
},
{
"id": 27,
"email": "[email protected]",
"role": "Super Admin",
"last_login_timestamp": "2023-05-03T14:47:33Z",
"verified ": true
“identities”: [
{“type”: “local”},
{“type”: “SAML”, “saml_profile_id”: 1}
]

},
]
}

POST

URL: https://<vectra_portal_url>/api/v3.4/users

To create users with a local profile (non SAML profile) use this endpoint.

The endpoint cannot create local user profiles for user emails that have logged in with an existing SAML
profile. Input your desired user role using the corresponding snake-case standardized name. Refer to the
/users/role endpoint to list available roles and their standardized names.

The following request body and all its fields are required to use this endpoint.

Headers:
"Authorization": "Bearer <access_token>",

© November 2024 Vectra AI, Inc. | 92

"Content-Type": "application/json"

Body:
{
"name": “firstname lastname”,
“role”: “auditor”,
“email”: “[email protected]”
}

Response:
{
"id": 4,
“role”: “Auditor”,
“email”: “[email protected]”,
“name”: “firstname lastname”
“identities”:[
{“type”: “local”}
],
"last_login_timestamp": null,
"verified ": false
}

GET

URL: https://<vectra_portal_url>/api/v3.4/users/<user_id>

Headers:
"Authorization": "Bearer <access_token>"

Response:
{
"id": 4,
“email”: “[email protected]”,
“name”: “newfirstname newlastname”
“role”: “super_admins”,
"last_login_timestamp": null,
"verified ": false
}

PATCH

URL: https://<vectra_portal_url>/api/v3.4/users/<user_id>

To modify users, use this endpoint. The endpoint will not update roles for users that only have a SAML
account. Input your desired user role using the corresponding snake-case standardized name. Refer to
the /users/role endpoint to list available roles and their standardized names.

© November 2024 Vectra AI, Inc. | 93

The following request body is used and none of the fields shown are required.

Headers:
"Authorization": "Bearer <access_token>",
"Content-Type": "application/json"

Body:
{
"name": “newfirstname newlastname”,
“role”: “super_admins”
}

Response:
{
"id": 4,
“role”: “super_admins”,
“email”: “[email protected]”,
“name”: “newfirstname newlastname”
“identities”:[
{“type”: “local”}
],
"last_login_timestamp": null,
"verified ": false
}

DELETE

URL: https://<vectra_portal_url>/api/v3.4/users/<user_id>

To delete users, use this endpoint. This will deactivate a user’s local and SAML profiles; SAML profiles
can be reactivated by logging in again via the external provider. Note that the last verified super admin
user cannot be deleted using this endpoint.

Headers:
"Authorization": "Bearer <access_token>",
"Content-Type": "application/json"

GET

URL: https://<vectra_portal_url>/api/v3.4/users/roles

Headers:
"Authorization": "Bearer <access_token>"

Response:

© November 2024 Vectra AI, Inc. | 94

[
{
"id": 2,
"name": "Admin",
"standardized_name": "admins",

},
{
"id": 1,
"name": "Super Admin",
"standardized_name": "super_admins",
}
]

Assignments
GET used to retrieve assignments

URL: https://<vectra_portal_url>/api/v3.4/assignments

Headers:
“Authorization”: “Bearer <access_token>”,
“Content-Type”: “application/json"

Response:
{
"count": 3,
"next": null,
"previous": null,
"results": [
{
"id": 4,
"assigned_by": {
"id": 1,
"username": "josem"
},
"date_assigned": "2021-05-18T04:34:48Z",
"date_resolved": null,
"events": [
{
"assignment_id": 4,
"actor": 1,
"event_type": "created",
"datetime": "2021-05-18T04:34:48Z",
"context": {
"to": 20

© November 2024 Vectra AI, Inc. | 95

 }
}
],
"outcome": null,
"resolved_by": null,
"triaged_detections": {},
"host_id": null,
"account_id": 1,
"assigned_to": {
"id": 20,
"username": "admin"
}
},
{
"id": 2,
"assigned_by": {
"id": 1,
"username": "josem"
},
"date_assigned": "2021-05-18T03:51:38Z",
"date_resolved": "2021-05-18T03:51:53Z",
"events": [
{
"assignment_id": 2,
"actor": 1,
"event_type": "resolved",
"datetime": "2021-05-18T03:51:53Z",
"context": {
"triage_as": "Miscategorization",
"detection_ids": [
1
],
"created_rule_ids": [
27
]
}
},
{
"assignment_id": 2,
"actor": 1,
"event_type": "created",
"datetime": "2021-05-18T03:51:38Z",
"context": {
"to": 20
}
}
],
"outcome": {

© November 2024 Vectra AI, Inc. | 96

 "id": 3,
"builtin": true,
"user_selectable": true,
"title": "False Positive",
"category": "false_positive"
},
"resolved_by": {
"id": 1,
"username": "josem"
},
"triaged_detections": [
1
],
"host_id": null,
"account_id": 1,
"assigned_to": {
"id": 20,
"username": "admin"
}
},
{
"id": 1,
"assigned_by": {
"id": 1,
"username": "josem"
},
"date_assigned": "2021-05-17T23:21:52Z",
"date_resolved": "2021-05-17T23:23:53Z",
"events": [
{
"assignment_id": 1,
"actor": 1,
"event_type": "resolved",
"datetime": "2021-05-17T23:23:53Z",
"context": {
"triage_as": null,
"detection_ids": [],
"created_rule_ids": null
}
},
{
"assignment_id": 1,
"actor": 1,
"event_type": "created",
"datetime": "2021-05-17T23:21:52Z",
"context": {
"to": 20
}

© November 2024 Vectra AI, Inc. | 97

 }
],
"outcome": {
"id": 1,
"builtin": true,
"user_selectable": true,
"title": "Benign True Positive",
"category": "benign_true_positive"
},
"resolved_by": {
"id": 1,
"username": "josem"
},
"triaged_detections": {},
"host_id": null,
"account_id": 1,
"assigned_to": {
"id": 20,
"username": "admin"
}
}
]
}

POST used to assign an entity to a user.

URL: https://<vectra_portal_url>/api/v3.4/assignments

Headers:
“Authorization”: “Bearer <access_token>”,
“Content-Type”: “application/json"

Body:
{
"assign_account_id": "27",
"assign_to_user_id": "30"
}

Response:
{
"assignment": {
"id": 25,
"assigned_by": {
"id": 45,
"username": "api_client_df405cc568734d4a8b7ebec1753ee647"
},

© November 2024 Vectra AI, Inc. | 98

 "date_assigned": "2022-03-31T19:07:24.841453Z",
"date_resolved": null,
"events": [
{
"assignment_id": 25,
"actor": 45,
"event_type": "created",
"datetime": "2022-03-31T19:07:24Z",
"context": {
"to": 30,
"entity_t_score": 68,
"entity_c_score": 48
}
}
],
"outcome": null,
"resolved_by": null,
"triaged_detections": null,
"host_id": null,
"account_id": 27,
"assigned_to": {
"id": 30,
"username": "[email protected]"
}
}
}

PUT used to modify/reassign assignments.

URL: https://<vectra_portal_url>/api/v3.4/assignments/<id>

Headers:
“Authorization”: “Bearer <access_token>”,
“Content-Type”: “application/json"

Body:
{
"assign_account_id": "27",
"assign_to_user_id": "23"
}

Response:
{
"assignment": {
"id": 25,
"assigned_by": {

© November 2024 Vectra AI, Inc. | 99

 "id": 45,
"username": "api_client_df405cc568734d4a8b7ebec1753ee647"
},
"date_assigned": "2022-03-31T19:07:24Z",
"date_resolved": null,
"events": [
{
"assignment_id": 25,
"actor": 45,
"event_type": "reassigned",
"datetime": "2022-03-31T19:13:02Z",
"context": {
"from": 30,
"to": 23,
"entity_t_score": 68,
"entity_c_score": 48
}
},
{
"assignment_id": 25,
"actor": 45,
"event_type": "created",
"datetime": "2022-03-31T19:07:24Z",
"context": {
"to": 30,
"entity_t_score": 68,
"entity_c_score": 48
}
}
],
"outcome": null,
"resolved_by": null,
"triaged_detections": {},
"host_id": null,
"account_id": 27,
"assigned_to": {
"id": 23,
"username": "[email protected]"
}
}
}

DELETE used to delete assignments.

URL: https://<vectra_portal_url>/api/v3.4/assignments/<id>

© November 2024 Vectra AI, Inc. | 100

Headers:
“Authorization”: “Bearer <access_token>”

PUT used to resolve assignments.

URL: https://<vectra_portal_url>/api/v3.4/assignments/<id>/resolve

Headers:
“Authorization”: “Bearer <access_token>”,
“Content-Type”: “application/json"

Body:
{
"outcome": "1",
"note": "Resolved by JoseM",
"triage_as": "My triage rule",
"detection_ids": [128,120]
}

Response:
{
"assignment": {
"id": 26,
"assigned_by": {
"id": 45,
"username": "api_client_df405cc568734d4a8b7ebec1753ee647"
},
"date_assigned": "2022-03-31T19:16:37Z",
"date_resolved": "2022-03-31T19:20:06Z",
"events": [
{
"assignment_id": 26,
"actor": 45,
"event_type": "resolved",
"datetime": "2022-03-31T19:20:06Z",
"context": {
"entity_t_score": 68,
"entity_c_score": 48,
"triage_as": "My triage rule",
"triaged_detection_ids": [
128,
120
],
"fixed_detection_ids": null,
"created_rule_ids": [
14,

© November 2024 Vectra AI, Inc. | 101

 15
]
}
},
{
"assignment_id": 26,
"actor": 45,
"event_type": "created",
"datetime": "2022-03-31T19:16:37Z",
"context": {
"to": 30,
"entity_t_score": 68,
"entity_c_score": 48
}
}
],
"outcome": {
"id": 1,
"builtin": true,
"user_selectable": true,
"title": "Benign True Positive",
"category": "benign_true_positive"
},
"resolved_by": {
"id": 45,
"username": "api_client_df405cc568734d4a8b7ebec1753ee647"
},
"triaged_detections": [
128,
120
],
"host_id": null,
"account_id": 27,
"assigned_to": {
"id": 30,
"username": "[email protected]"
}
}
}

Assignment Outcomes
GET used to list assignment outcomes.

URL: https://<vectra_portal_url>/api/v3.4/assignment_outcomes

Headers:

© November 2024 Vectra AI, Inc. | 102

“Authorization”: “Bearer <access_token>”

Response:
{
"count": 3,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"builtin": true,
"user_selectable": true,
"title": "Benign True Positive",
"category": "benign_true_positive"
},
{
"id": 2,
"builtin": true,
"user_selectable": true,
"title": "Malicious True Positive",
"category": "malicious_true_positive"
},
{
"id": 3,
"builtin": true,
"user_selectable": true,
"title": "False Positive",
"category": "false_positive"
}
]
}

POST used to create assignment outcomes.

URL: https://<vectra_portal_url>/api/v3.4/assignment_outcomes

Headers:
“Authorization”: “Bearer <access_token>”,
“Content-Type”: “application/json"

Body:
{
"title": "Custom outcome",
"category": "benign_true_positive"
}

Response:

© November 2024 Vectra AI, Inc. | 103

{
"id": 6,
"builtin": false,
"user_selectable": true,
"title": "Custom outcome",
"category": "benign_true_positive"
}

PUT used to modify an assignment outcome. The title can always be modified, but category can only be
modified if the assignment outcome has not been used as an outcome for an assignment.

URL: https://<vectra_portal_url>/api/v3.4/assignment_outcomes/<id>

Headers:
“Authorization”: “Bearer <access_token>”,
“Content-Type”: “application/json"

Body:
{
"title": "My New Outcome Title",
"category": "false_positive"
}

Response:
{
"id": 6,
"builtin": false,
"user_selectable": true,
"title": "My New Outcome Title",
"category": "false_positive"
}

DELETE used to delete an assignment outcome.

URL: https://<vectra_portal_url>/api/v3.4/assignment_outcomes/<id>

Headers:
“Authorization”: “Bearer <access_token>”

Detection Events
GET

URL: https://<vectra_portal_url>/api/v3.4/events/detections?from=222

© November 2024 Vectra AI, Inc. | 104

Headers:
"Authorization": "Bearer <access_token>"

Response:
{
"events": [
{
"id": 28538,
"category": "command_and_control",
"threat": 50,
"certainty": 50,
"triaged": false,
"detection_type": "Azure AD Redundant Access Creation",
"d_type_vname": "Azure AD Redundant Access Creation",
"detection_id": 959,
"detection_href":
"https://207031206993.uw2.devportal.vectra.ai/detections/959?detail_id=94341",
"entity_id": 1,
"type": "account",
"entity_href": "https://207031206993.uw2.devportal.vectra.ai/accounts/1",
"entity_uid": "O365:ServicePrincipal_3fb87dda-882a-49e1-88b9-
67d2499b2fd4",
"src_entity": "O365:ServicePrincipal_3fb87dda-882a-49e1-88b9-
67d2499b2fd4",
"event_timestamp": "2022-09-12T16:31:35Z",
"detail": {
"operation": "Add member to role.",
"target": "[email protected]",
"change": "Application Administrator",
"results": "Success",
"last_timestamp": "2022-09-09T08:13:58Z"
},
"severity": 5
}
],
"next_checkpoint": 28539,
"remaining_count": 9797
}

Audit Log Events

GET

URL: https://<vectra_portal_url>/api/v3.4/events/audits?from=16&limit=2

Headers:
"Authorization": "Bearer <access_token>"

© November 2024 Vectra AI, Inc. | 105

Response:
{
"events": [
{
"id": 16,
"user_id": 24,
"username": "[email protected]",
"user_type": "JWT",
"api_client_id": null,
"user_role": "Admin",
"version": "2022.0.0",
"source_ip": "10.100.219.11",
"event_timestamp": "2022-05-21T06:24:52Z",
"message": "Tag josetag100 has been added to linked_accounts with ids
[45]",
"result_status": "success",
"event_data": {
"tag": {
"tag_name": "josetag100",
"entity": "linked_account",
"entity_ids": [
45
]
}
},
"event_object": "account_tag",
"event_action": "created"
},
{
"id": 17,
"user_id": 24,
"username": "[email protected]",
"user_type": "JWT",
"api_client_id": null,
"user_role": "Admin",
"version": "2022.0.0",
"source_ip": "10.100.114.24",
"event_timestamp": "2022-05-21T07:15:58Z",
"message": "note for detection@172 created This has b...",
"result_status": "success",
"event_data": {
"detection_note": {
"text": "This has been fixed downstream and is being monitored for
additional activity.",
"note_id": 16,
"detection_id": "172"
}

© November 2024 Vectra AI, Inc. | 106

 },
"event_object": "detection_note",
"event_action": "created"
}
],
"next_checkpoint": 18,
"remaining_count": 0
}

Entities
GET

URL: https://<vectra_portal_url>/api/v3.4/entities/<entity_id>?type=account

Headers:
"Authorization": "Bearer <access_token>"

Response:
{
"id": 1,
"breadth_contrib": 0,
"importance": 0,
"is_prioritized": false,
"severity": "High",
"urgency_reason": “Ransomware: This entity was prioritized because it was
implicated in an active ransomware detection”,
"urgency_score": 0,
"velocity_contrib": 0,
"detection_set": [
"http://202079170575.uw2.devportal.vectra.ai/api/v3/detections/1",
"http://202079170575.uw2.devportal.vectra.ai/api/v3/detections/408",
"http://202079170575.uw2.devportal.vectra.ai/api/v3/detections/549",
"http://202079170575.uw2.devportal.vectra.ai/api/v3/detections/699"
],
"last_detection_timestamp": "2022-10-06T17:34:23Z",
"name": "SAML:[email protected]",
"notes": [
{
"id": 3,
"date_created": "2022-05-24T14:55:01Z",
"date_modified": null,
"created_by": "api_client_b58f8e28a46f40b59a77bf04d068af61",
"modified_by": null,
"note": "# IMPORTANT - PLEASE READ!! Account under **active
investigation**."
}
],

© November 2024 Vectra AI, Inc. | 107

 "privilege_level": 2,
"privilege_category": “Low”,
"sensors": [
"abx1pcad"
],
"state": "active",
"tags": [
"high_priority"
],
"url": "https://202079170575.uw2.devportal.vectra.ai/accounts/1",
"account_type": [
"aws"
],
"type": "account",
“ip” null
}

Entity Scoring Events

GET

URL:
https://<vectra_portal_url>/api/v3.4/events/entity_scoring?type=account&from=100&limit
=2

Headers:
"Authorization": "Bearer <access_token>"

Response:
{
"events": [
{
"entity_id": 100,
"name": "AWS:None/us-1-east/config:AWSConfig-Describe",
"importance": 0,
"type": "account",
"is_prioritized": false,
"severity": "Low",
"urgency_reason": “Ransomware: This entity was prioritized because it was
implicated in an active ransomware detection”,
"urgency_score": 0,
"url": "https://200888808432.uw2.devportal.vectra.ai/accounts/8",
"category": "ACCOUNT SCORING",
"last_detection": {
"id": 103,
"type": " AWS S3 Enumeration",
"url": " https://200888808432.uw2.devportal.vectra.ai/detections/103"
},

© November 2024 Vectra AI, Inc. | 108

 "active_detection_types": [
"AWS S3 Enumeration"
],
"event_timestamp": "2022-08-07T00:14:31Z",
"breadth_contrib": 0,
"velocity_contrib": 0
},
{
"entity_id": 101,
"name": "AWS:884414556547/solus-cgid-domryder-ucw",
"importance": 0,
"type": "account",
"is_prioritized": false,
"severity": "Low",
"urgency_reason": “Ransomware: This entity was prioritized because it was
implicated in an active ransomware detection”,,
"urgency_score": 0,
"url": "https://200888808432.uw2.devportal.vectra.ai/accounts/2",
"category": "ACCOUNT SCORING",
"last_detection": {
"id": 80,
"type": " AWS attack Tools",
"url": " https://200888808432.uw2.devportal.vectra.ai/detections/80"
},
"active_detection_types": [
"AWS Attack Tools"
],
"event_timestamp": "2022-08-07T06:15:04Z",
"breadth_contrib": 0,
"velocity_contrib": 0
}
],
"next_checkpoint": 102,
"remaining_count": 659
}

Entity (Notes)
GET

URL: https://<vectra_portal_url>/api/v3.4/entities/<entity_id>/notes?type=account,host

Headers:
"Authorization": "Bearer <access_token>"

Response:
[

© November 2024 Vectra AI, Inc. | 109

 {
"id": 154,
"date_created": "2023-03-15T18:58:48Z",
"date_modified": null,
"created_by": "api_client_8971fa9ddc89461daedebf451cd6e0c8",
"modified_by": null,
"note": "# IMPORTANT - PLEASE READ!! \n\n Account under **active
investigation**. \n\n For more information see MITRE technique [T-
1571](https://attack.mitre.org/techniques/T1571)"
}
]

POST

URL: https://<vectra_portal_url>/api/v3.4/entities/<entity_id>/notes?type=account

Headers:
"Authorization": "Bearer <access_token>",
"Content-Type": "application/json"

Body:
{"note":"this is an account note"}
Response:
{
"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"
}

GET

URL:
https://<vectra_portal_url>/api/v3.4/entities/<entity_id>/notes/<note_id>?type=account

Headers:
"Authorization": "Bearer <access_token>"

Response:
{
"id": 1,
"date_created": "2023-03-15T18:58:48Z",
"date_modified": null,
"created_by": "api_client_8971fa9ddc89461daedebf451cd6e0c8",
"modified_by": null,

© November 2024 Vectra AI, Inc. | 110

 "note": "# IMPORTANT - PLEASE READ!! \n\n Account under **active investigation**.
\n\n For more information see MITRE technique [T-
1571](https://attack.mitre.org/techniques/T1571)"
}

PATCH

URL:
https://<vectra_portal_url>/api/v3.4/entities/<entity_id>/notes/<note_id>?type=account

Headers:
"Authorization": "Bearer <access_token>",
"Content-Type": "application/json"

Body:
{
"note": “updated note”
}

Response:
{
"id": 1,
"date_created": "2021-01-11T13:47:42Z",
"date_modified": "2021-01-11T13:57:11Z",
"created_by": "vadmin",
"modified_by": "vadmin",
"note": "updated note"
}

DELETE

URL:
https://<vectra_portal_url>/api/v3.4/entities/<entity_id>/notes/<note_id>?type=account

Headers:
"Authorization": "Bearer <access_token>"

Groups
GET

URL: https://<vectra_portal_url>/api/v3.4/groups/<group_id>

Headers:
"Authorization": "Bearer <access_token>"

© November 2024 Vectra AI, Inc. | 111

Response:
{
"id": 5,
"name": "test_group",
"description": "a test group",
"last_modified": "2022-11-18T18:21:34Z",
"last_modified_by": "API Client c628cdee",
"type": "account",
"members": [
{
"uid": “name_1”
},
{
"uid": “name_2”
}
],
"rules": [],
"importance": "high",
"regex": "name_(\\w\\d)*",
"membership_evaluation_ongoing": false,
"member_count": 2,
“built_using”: “regex”
}

POST

URL: https://<vectra_portal_url>/api/v3.4/groups

Headers:
"Authorization": "Bearer <access_token>",
"Content-Type": "application/json"

Members:
Members are added to the “members” list in the body. The member value added depends on the group type.
- Account Members: Added by uuid
- Host Members: Added by name, ID, or url
- IP Members: Added by IP address
- Domain Members: Added by domain

Body:
{

"name": "test_group",

"type": "account",

"members":[

"name_1","name_2"

© November 2024 Vectra AI, Inc. | 112

 ],

"description": "a test group",

"importance": "high"

Response:
{
"group": {
"id": 5
}
}

Regex Group POST:

Regex groups can be added but members cannot be included in the request; this will result in error. Regex groups
can only be of type ‘host’ and ‘account’.

Body:
{

"name": "test_regex_group",

"type": "host",

"description": "a test regex host group",

"regex": "(\\w\\d)*@vectra.ai"

Response:
{
"group": {
"id": 6
}
}

PATCH
PATCH method can be used to modify existing groups. A PATCH is a partial override, so the format can include one
or more fields from the POST.

When using the default PATCH functionality to modify the members, a complete new list must be included. For
example, if a group already contains accounts “[email protected]”, and “[email protected]”, and the group should be
modified to include account “[email protected]”, then “[email protected]” should be added to the list, the members
field of the PATCH request should be “[email protected]”,“[email protected]”,“[email protected]”.

Alternatively, the “membership_action” query parameter can be passed in with a value of “replace”, “append”, or
“remove”. The “append” and “remove” values will only affect members listed in the request body; if a user wants to
add or remove account “[email protected]” for a group, then the user can pass the members field of

© November 2024 Vectra AI, Inc. | 113

“[email protected]” in the request body with the appropriate value of “membership_action”. The “replace” value will
perform the default PATCH behavior.

Regex groups may be patched but members cannot be manually changed.

URL: https://<vectra_portal_url>/api/v3.4/groups/<group_id>

Headers:

"Authorization": "Bearer <access_token>",

"Content-Type": "application/json"

Body:
{
"name": "test_group new name"
}

Response:
{
"id": 5,
"name": "test_group new name",
"description": "a test group",
"last_modified": "2022-11-18T18:28:11Z",
"last_modified_by": "API Client c628cdee",
"type": "account",
"members": [
{
"uid": “name_1”
},
{
"uid": “name_2”
}
],
"rules": [],
"importance": "high"
"regex": "",
"membership_evaluation_ongoing": false,
"member_count": 2,
“built_using”: “static_members”
}

DELETE

URL: https://<vectra_portal_url>/api/v3.4/groups/<group_id>

Headers:
"Authorization": "Bearer <access_token>"

© November 2024 Vectra AI, Inc. | 114

Lockdown
GET

URL: https://<vectra_portal_url>/api/v3.4/lockdown

Headers:
"Authorization": "Bearer <access_token>"

Response:

[
{
"id": 1,
"type": "account",
"entity_id": 2,
"entity_name": "O365:[email protected]",
"lock_event_timestamp": "2023-03-06T22:30:06Z",
"locked_by": "vadmin",
"certainty": 0,
"unlock_event_timestamp": "2023-03-07T22:30:06Z"
}
]

Hosts
GET (multiple)

URL: https://<vectra_portal_url>/api/v3.4/hosts

Headers:
"Authorization": "Bearer <access_token>"

Response:
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"name": "bar.mbpro",
"has_active_traffic": false,
"threat": 60,
"certainty": 96,
"t_score" : 60,
"c_score": 96,
"severity": "critical",
"last_source": "9.0.0.1",

© November 2024 Vectra AI, Inc. | 115

 "ip": "9.0.0.1",
"previous_ips": [],
"last_detection_timestamp": "2023-03-06T22:30:06Z",
"is_key_asset": false,
"state": "active",
"is_targeting_key_asset": false,
"detection_set": [
"https://202079170575.uw2.devportal.vectra.ai/api/v3.4/detections/1",
"https://202079170575.uw2.devportal.vectra.ai/api/v3.4/detections/44"
],
"host_artifact_set": [],
"sensor": null,
"sensor_name": null,
"tags": [],
"note": null,
"notes": [],
"note_modified_by": null,
"note_modified_timestamp": null,
"url": ""https://202079170575.uw2.devportal.vectra.ai/api/v3.4/hosts/1",
"last_modified": "2023-03-06T21:44:23Z",
"assigned_to": null,
"assigned_date": null,
"groups": [],
"has_custom_model": false,
"privilege_level": null,
"privilege_category": null,
"probable_owner": null,
"detection_profile": "Botnet",
"assignment": null,
"past_assignments": [],
"host_session_luids": [
"5CIdU065"
],
"host_luid": null
}
]
}

GET (single)

URL: https://<vectra_portal_url>/api/v3.4/hosts/1

Headers:
"Authorization": "Bearer <access_token>"
Response:
{
"id": 1,
"name": "bar.mbpro",
"has_active_traffic": false,

© November 2024 Vectra AI, Inc. | 116

 "threat": 60,
"certainty": 96,
"t_score" : 60,
"c_score": 96,
"severity": "critical",
"last_source": "9.0.0.1",
"ip": "9.0.0.1",
"previous_ips": [],
"last_detection_timestamp": "2023-03-06T22:30:06Z",
"is_key_asset": false,
"state": "active",
"is_targeting_key_asset": false,
"detection_set": [
"https://202079170575.uw2.devportal.vectra.ai/api/v3.4/detections/1",
"https://202079170575.uw2.devportal.vectra.ai/api/v3.4/detections/44"
],
"host_artifact_set": [],
"sensor": null,
"sensor_name": null,
"tags": [],
"note": null,
"notes": [],
"note_modified_by": null,
"note_modified_timestamp": null,
"url": ""https://202079170575.uw2.devportal.vectra.ai/api/v3.4/hosts/1",
"last_modified": "2023-03-06T21:44:23Z",
"assigned_to": null,
"assigned_date": null,
"groups": [],
"has_custom_model": false,
"privilege_level": null,
"privilege_category": null,
"probable_owner": null,
"detection_profile": "Botnet",
"assignment": null,
"past_assignments": [],
"host_session_luids": [
"5CIdU065"
],
"host_luid": null
}

Health – External Connectors

GET

© November 2024 Vectra AI, Inc. | 117

URL: https://<vectra_portal_url>/api/v3.4/health/external_connectors

Headers:
"Authorization": "Bearer <access_token>"

Response:
{
"results": {
"active_directory": {
"connection_status": "enabled",
"auth_status": {
"3a27a16e": "authenticated"
},
"error_states": {},
"lockdown_status": "enabled"
},
"azure_ad_lockdown": {
"connection_status": "enabled",
"auth_status": {
"status": "authenticated"
},
"lockdown_status": "enabled"
},
"aws": {
"connection_status": "disabled"
},
"azure": {
"connection_status": "disabled"
},
"google_cloud": {
"connection_status": "disabled"
},
"reverse_lookup_dns": {
"connection_status": "disabled"
},
"siem": {
"connection_status": "disabled"
},
"vcenter": {
"connection_status": "enabled",
"auth_status": {
"status": "not_configured"
},
"error_states": {
"status": "An error occurred during vCenter connection check, please
try again later"
}
},

© November 2024 Vectra AI, Inc. | 118

 "windows_event_log_ingestion": {
"connection_status": "enabled",
"auth_status": {
"status": "not_configured"
},
"error_states": {
"status": "Not connected"
}
},
"zscaler_private_access": {
"connection_status": "disabled"
}
},
"updated_at": "2024-07-24T21:51:41Z"
}

Health – External Connectors Details

GET

URL: https://<vectra_portal_url>/api/v3.4/health/external_connectors/details

Headers:
"Authorization": "Bearer <access_token>"

Response:
{
"results": {
"active_directory": {
"connection_status": "enabled",
"details": {
"profiles": {
"3a27a16e": {
"uriConnectionStatus": {
"192.168.49.204": {
"message": "Connected",
"severity": "misc-yep"
}
},
"metrics": {
"numADAccountsFound": 87,
"numADMetricOverlap": 0
},
"connectionStatus": {
"message": "Connected",
"severity": "misc-yep"
}
}
},

© November 2024 Vectra AI, Inc. | 119

 "metrics": {
"numKerberosLast30Days": 10,
"numADMetricOverlap": "0"
},
"numAdServersConnected": 1,
"numAdServersDisconnected": 0,
"numAdServersDisabled": 0,
"numUrisDisconnected": 0
}
},
"azure_ad_lockdown": {
"connection_status": "enabled",
"details": {
"lockdownManualEnabled": true,
"lockdownAutoEnabled": false,
"lockdownEnabled": true,
"lockdownAutoType": "lock",
"lockdownAutoUrgency": 100,
"consentState": "CONSENT_AWAITING"
}
},
"aws": {
"connection_status": "disabled"
},
"azure": {
"connection_status": "disabled"
},
"google_cloud": {
"connection_status": "disabled"
},
"reverse_lookup_dns": {
"connection_status": "disabled"
},
"siem": {
"connection_status": "disabled"
},
"vcenter": {
"connection_status": "enabled"
},
"windows_event_log_ingestion": {
"connection_status": "enabled",
"details": {
"status": "Not connected",
"severity": "misc-alert"
}
},
"zscaler_private_access": {
"connection_status": "disabled"

© November 2024 Vectra AI, Inc. | 120

 }
},
"updated_at": "2024-07-24T21:56:41Z"
}

Health – EDR

GET

URL: https://<vectra_portal_url>/api/v3.4/health/edr

Headers:
"Authorization": "Bearer <access_token>"

Response:
{
"results": {
"carbon_black": {
"connection_status": "enabled",
"auth_status": {
"cbdemo.demo.vectra.io:443": "authenticated"
},
"error_states": {},
"lockdown_status": "enabled"
},
"cb_cloud": {
"connection_status": "enabled",
"auth_status": {
"status": "authenticated"
},
"error_states": {},
"lockdown_status": "enabled"
},
"crowdstrike": {
"connection_status": "disabled"
},
"cybereason": {
"connection_status": "disabled"
},
"fireeye": {
"connection_status": "disabled"
},
"host_lockdown": {
"connection_status": "enabled",
"auth_status": {
"status": "authenticated"
},
"lockdown_status": "enabled"

© November 2024 Vectra AI, Inc. | 121

 },
"sentinelone": {
"connection_status": "disabled"
},
"windows_defender": {
"connection_status": "enabled",
"auth_status": {
"status": "authenticated"
},
"error_states": {},
"lockdown_status": "enabled"
}
},
"updated_at": "2024-07-24T22:07:11Z"
}

Health – EDR Details

GET

URL: https://<vectra_portal_url>/api/v3.4/health/edr/details

Headers:
"Authorization": "Bearer <access_token>"

Response:
{
"results": {
"host_lockdown": {
"connection_status": "enabled",
"details": {
"activeIntegrations": [
"Microsoft Defender ATP",
"Carbon Black",
"Carbon Black Cloud"
],
"lockdownAutoEnabled": true
}
},
"windows_defender": {
"connection_status": "enabled",
"details": {
"status": "Connected",
"severity": "misc-yep",
"hostLockdown": {
"enabled": true
}
}

© November 2024 Vectra AI, Inc. | 122

 },
"carbon_black": {
"connection_status": "enabled",
"details": {
"carbon_blacks": {
"cbdemo.demo.vectra.io:443": {
"status": "Connected",
"severity": "misc-yep"
}
},
"hostLockdown": {
"enabled": true
}
}
},
"cb_cloud": {
"connection_status": "enabled",
"details": [
{
"statusType": "success",
"text": "Carbon Black Cloud connected"
},
{
"statusType": "success",
"text": "Host Lockdown"
}
]
},
"fireeye": {
"connection_status": "disabled"
},
"sentinelone": {
"connection_status": "disabled"
},
"cybereason": {
"connection_status": "disabled"
},
"crowdstrike": {
"connection_status": "disabled"
}
},
"updated_at": "2024-07-24T22:07:11Z"
}

Health – Network Brain Ping

GET

© November 2024 Vectra AI, Inc. | 123

URL: https://<vectra_portal_url>/api/v3.4/health/network_brain/ping

Headers:
"Authorization": "Bearer <access_token>"

Response:
{
"results": {
"ping": "Brain enabled",
"latency": "311.43ms"
}
}

Vectra Match Enablement

GET

Used to retrieve whether Vectra Match is enabled on a given device

URL: https://<vectra_management_ip>/api/v3.4/vectra-match/enablement

Headers:
“Authorization”: “Token <api-key>”

Query Params:
{“device_serial”:”<device_serial>”}

Response:
Status Code: 200
{
"is_enabled": true
}

POST

Used to enable or disable Vectra Match on a given device (WARNING: POSTing to the enablement endpoint causes
a reboot if changing state). A valid Vectra Match license is required to enable this feature on a given paired device,
but is not required to disable Match.

URL: https://<vectra_management_ip>/api/v3.4/vectra-match/enablement

Headers:
“Authorization”: “Token <api-key>”

Required Request JSON Body:

© November 2024 Vectra AI, Inc. | 124

{“device_serial”:”<device_serial”, “desired_state”: true}

Response:
Status code: 200
{
"is_enabled": true
}

Vectra Match Stats

GET

Used to retrieve Vectra Match stats. Returned fields include:

eve_stats: statistics directly pulled from the Vectra Match (suricata) engine
interface_stats: statistics about each network interface and its processing/drop rate
ft_stats: statistics about each flow thread and its processing/drop rate
forwarder_stats: statistics about how many syslog messages Vectra Match is producing
device_serial: serial of the device for which the stats are given
timestamp: timestamp of when the information was gathered

URL: https://<vectra_management_ip>/api/v3.4/vectra-match/stats

Headers:
“Authorization”: “Token <api-key>”

Optional Query Params:

{“device_serial”:”<device_serial>”}

Response:
Status Code: 200
{
"stats": [
{
"eve_stats": {
"timestamp": "2023-02-01T01:05:45.123456+00:00",
"event_type": "stats",
"stats": {
"uptime": 177,
"capture": {
"packets": 1361,
"rx_errors": 0,
"tx_errors": 0,
"dpdk": {
"imissed": 0,
"no_mbufs": 0,
"ierrors": 0
}

© November 2024 Vectra AI, Inc. | 125

},
"decoder": {
"pkts": 1361,
"bytes": 2335792,
"invalid": 0,
"ipv4": 0,
"ipv6": 0,
"ethernet": 1361,
"chdlc": 0,
"raw": 0,
"null": 0,
"sll": 0,
"tcp": 0,
"udp": 0,
"sctp": 0,
"esp": 0,
"icmpv4": 0,
"icmpv6": 0,
"ppp": 0,
"pppoe": 0,
"geneve": 0,
"gre": 0,
"vlan": 0,
"vlan_qinq": 0,
"vxlan": 0,
"vntag": 0,
"ieee8021ah": 0,
"teredo": 0,
"ipv4_in_ipv6": 0,
"ipv6_in_ipv6": 0,
"mpls": 0,
"avg_pkt_size": 1716,
"max_pkt_size": 2048,
"max_mac_addrs_src": 0,
"max_mac_addrs_dst": 0,
"erspan": 0,
"nsh": 0,
"event": {
"ipv4": {
"pkt_too_small": 0,
"hlen_too_small": 0,
"iplen_smaller_than_hlen": 0,
"trunc_pkt": 0,
"opt_invalid": 0,
"opt_invalid_len": 0,
"opt_malformed": 0,
"opt_pad_required": 0,
"opt_eol_required": 0,

© November 2024 Vectra AI, Inc. | 126

 "opt_duplicate": 0,
"opt_unknown": 0,
"wrong_ip_version": 0,
"icmpv6": 0,
"frag_pkt_too_large": 0,
"frag_overlap": 0,
"frag_ignored": 0
},
"icmpv4": {
"pkt_too_small": 0,
"unknown_type": 0,
"unknown_code": 0,
"ipv4_trunc_pkt": 0,
"ipv4_unknown_ver": 0
},
"icmpv6": {
"unknown_type": 0,
"unknown_code": 0,
"pkt_too_small": 0,
"ipv6_unknown_version": 0,
"ipv6_trunc_pkt": 0,
"mld_message_with_invalid_hl": 0,
"unassigned_type": 0,
"experimentation_type": 0
},
"ipv6": {
"pkt_too_small": 0,
"trunc_pkt": 0,
"trunc_exthdr": 0,
"exthdr_dupl_fh": 0,
"exthdr_useless_fh": 0,
"exthdr_dupl_rh": 0,
"exthdr_dupl_hh": 0,
"exthdr_dupl_dh": 0,
"exthdr_dupl_ah": 0,
"exthdr_dupl_eh": 0,
"exthdr_invalid_optlen": 0,
"wrong_ip_version": 0,
"exthdr_ah_res_not_null": 0,
"hopopts_unknown_opt": 0,
"hopopts_only_padding": 0,
"dstopts_unknown_opt": 0,
"dstopts_only_padding": 0,
"rh_type_0": 0,
"zero_len_padn": 0,
"fh_non_zero_reserved_field": 0,
"data_after_none_header": 0,
"unknown_next_header": 0,

© November 2024 Vectra AI, Inc. | 127

 "icmpv4": 0,
"frag_pkt_too_large": 0,
"frag_overlap": 0,
"frag_invalid_length": 0,
"frag_ignored": 0,
"ipv4_in_ipv6_too_small": 0,
"ipv4_in_ipv6_wrong_version": 0,
"ipv6_in_ipv6_too_small": 0,
"ipv6_in_ipv6_wrong_version": 0
},
"tcp": {
"pkt_too_small": 0,
"hlen_too_small": 0,
"invalid_optlen": 0,
"opt_invalid_len": 0,
"opt_duplicate": 0
},
"udp": {
"pkt_too_small": 0,
"hlen_too_small": 0,
"hlen_invalid": 0
},
"sll": {
"pkt_too_small": 0
},
"ethernet": {
"pkt_too_small": 0
},
"ppp": {
"pkt_too_small": 0,
"vju_pkt_too_small": 0,
"ip4_pkt_too_small": 0,
"ip6_pkt_too_small": 0,
"wrong_type": 0,
"unsup_proto": 0
},
"pppoe": {
"pkt_too_small": 0,
"wrong_code": 0,
"malformed_tags": 0
},
"gre": {
"pkt_too_small": 0,
"wrong_version": 0,
"version0_recur": 0,
"version0_flags": 0,
"version0_hdr_too_big": 0,
"version0_malformed_sre_hdr": 0,

© November 2024 Vectra AI, Inc. | 128

 "version1_chksum": 0,
"version1_route": 0,
"version1_ssr": 0,
"version1_recur": 0,
"version1_flags": 0,
"version1_no_key": 0,
"version1_wrong_protocol": 0,
"version1_malformed_sre_hdr": 0,
"version1_hdr_too_big": 0
},
"vlan": {
"header_too_small": 0,
"unknown_type": 0,
"too_many_layers": 0
},
"ieee8021ah": {
"header_too_small": 0
},
"vntag": {
"header_too_small": 0,
"unknown_type": 0
},
"ipraw": {
"invalid_ip_version": 0
},
"ltnull": {
"pkt_too_small": 0,
"unsupported_type": 0
},
"sctp": {
"pkt_too_small": 0
},
"esp": {
"pkt_too_small": 0
},
"mpls": {
"header_too_small": 0,
"pkt_too_small": 0,
"bad_label_router_alert": 0,
"bad_label_implicit_null": 0,
"bad_label_reserved": 0,
"unknown_payload_type": 0
},
"vxlan": {
"unknown_payload_type": 0
},
"geneve": {
"unknown_payload_type": 0

© November 2024 Vectra AI, Inc. | 129

 },
"erspan": {
"header_too_small": 0,
"unsupported_version": 0,
"too_many_vlan_layers": 0
},
"dce": {
"pkt_too_small": 0
},
"chdlc": {
"pkt_too_small": 0
},
"nsh": {
"header_too_small": 0,
"unsupported_version": 0,
"bad_header_length": 0,
"reserved_type": 0,
"unsupported_type": 0,
"unknown_payload": 0
}
},
"too_many_layers": 0
},
"flow": {
"memcap": 0,
"total": 0,
"active": 0,
"tcp": 0,
"udp": 0,
"icmpv4": 0,
"icmpv6": 0,
"tcp_reuse": 0,
"get_used": 0,
"get_used_eval": 0,
"get_used_eval_reject": 0,
"get_used_eval_busy": 0,
"get_used_failed": 0,
"wrk": {
"spare_sync_avg": 0,
"spare_sync": 0,
"spare_sync_incomplete": 0,
"spare_sync_empty": 0,
"flows_evicted_needs_work": 0,
"flows_evicted_pkt_inject": 0,
"flows_evicted": 0,
"flows_injected": 0,
"flows_injected_max": 0
},

© November 2024 Vectra AI, Inc. | 130

 "end": {
"state": {
"new": 0,
"established": 0,
"closed": 0,
"local_bypassed": 0
},
"tcp_state": {
"none": 0,
"syn_sent": 0,
"syn_recv": 0,
"established": 0,
"fin_wait1": 0,
"fin_wait2": 0,
"time_wait": 0,
"last_ack": 0,
"close_wait": 0,
"closing": 0,
"closed": 0
},
"tcp_liberal": 0
},
"mgr": {
"full_hash_pass": 15,
"rows_per_sec": 6553,
"rows_maxlen": 0,
"flows_checked": 0,
"flows_notimeout": 0,
"flows_timeout": 0,
"flows_timeout_inuse": 0,
"flows_evicted": 0,
"flows_evicted_needs_work": 0
},
"spare": 10000,
"emerg_mode_entered": 0,
"emerg_mode_over": 0,
"recycler": {
"recycled": 0,
"queue_avg": 0,
"queue_max": 0
},
"memuse": 7394304
},
"tcp": {
"active_sessions": 0,
"sessions": 0,
"ssn_memcap_drop": 0,
"ssn_from_cache": 0,

© November 2024 Vectra AI, Inc. | 131

 "ssn_from_pool": 0,
"pseudo": 0,
"pseudo_failed": 0,
"invalid_checksum": 0,
"no_flow": 0,
"syn": 0,
"synack": 0,
"rst": 0,
"midstream_pickups": 0,
"pkt_on_wrong_thread": 0,
"segment_memcap_drop": 0,
"segment_from_cache": 0,
"segment_from_pool": 0,
"stream_depth_reached": 0,
"reassembly_gap": 0,
"overlap": 0,
"overlap_diff_data": 0,
"insert_data_normal_fail": 0,
"insert_data_overlap_fail": 0,
"memuse": 7274496,
"reassembly_memuse": 1376256
},
"defrag": {
"ipv4": {
"fragments": 0,
"reassembled": 0,
"timeouts": 0
},
"ipv6": {
"fragments": 0,
"reassembled": 0,
"timeouts": 0
},
"max_frag_hits": 0
},
"flow_bypassed": {
"local_pkts": 0,
"local_bytes": 0,
"local_capture_pkts": 0,
"local_capture_bytes": 0,
"closed": 0,
"pkts": 0,
"bytes": 0
},
"detect": {
"engines": [
{
"id": 0,

© November 2024 Vectra AI, Inc. | 132

 "last_reload": "2023-02-01T01:00:45.123456+00:00",
"rules_loaded": 21944,
"rules_failed": 2
}
],
"alert": 0,
"alert_queue_overflow": 0,
"alerts_suppressed": 0
},
"app_layer": {
"flow": {
"http": 0,
"ftp": 0,
"smtp": 0,
"tls": 0,
"ssh": 0,
"imap": 0,
"smb": 0,
"dcerpc_tcp": 0,
"dns_tcp": 0,
"nfs_tcp": 0,
"ntp": 0,
"ftp-data": 0,
"tftp": 0,
"ike": 0,
"krb5_tcp": 0,
"quic": 0,
"dhcp": 0,
"snmp": 0,
"sip": 0,
"rfb": 0,
"mqtt": 0,
"telnet": 0,
"rdp": 0,
"http2": 0,
"failed_tcp": 0,
"dcerpc_udp": 0,
"dns_udp": 0,
"nfs_udp": 0,
"krb5_udp": 0,
"failed_udp": 0
},
"tx": {
"http": 0,
"ftp": 0,
"smtp": 0,
"tls": 0,
"ssh": 0,

© November 2024 Vectra AI, Inc. | 133

 "imap": 0,
"smb": 0,
"dcerpc_tcp": 0,
"dns_tcp": 0,
"nfs_tcp": 0,
"ntp": 0,
"ftp-data": 0,
"tftp": 0,
"ike": 0,
"krb5_tcp": 0,
"quic": 0,
"dhcp": 0,
"snmp": 0,
"sip": 0,
"rfb": 0,
"mqtt": 0,
"telnet": 0,
"rdp": 0,
"http2": 0,
"dcerpc_udp": 0,
"dns_udp": 0,
"nfs_udp": 0,
"krb5_udp": 0
},
"error": {
"http": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"ftp": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"smtp": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"tls": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0

© November 2024 Vectra AI, Inc. | 134

},
"ssh": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"imap": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"smb": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"dcerpc_tcp": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"dns_tcp": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"nfs_tcp": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"ntp": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"ftp-data": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0

© November 2024 Vectra AI, Inc. | 135

},
"tftp": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"ike": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"krb5_tcp": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"quic": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"dhcp": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"snmp": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"sip": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"rfb": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0

© November 2024 Vectra AI, Inc. | 136

},
"mqtt": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"telnet": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"rdp": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"http2": {
"gap": 0,
"alloc": 0,
"parser": 0,
"internal": 0
},
"failed_tcp": {
"gap": 0
},
"dcerpc_udp": {
"alloc": 0,
"parser": 0,
"internal": 0
},
"dns_udp": {
"alloc": 0,
"parser": 0,
"internal": 0
},
"nfs_udp": {
"alloc": 0,
"parser": 0,
"internal": 0
},
"krb5_udp": {
"alloc": 0,
"parser": 0,
"internal": 0
}

© November 2024 Vectra AI, Inc. | 137

 },
"expectations": 0
},
"http": {
"memuse": 0,
"memcap": 0
},
"ftp": {
"memuse": 0,
"memcap": 0
},
"file_store": {
"open_files": 0
}
}
},
"ft_stats": {
"memif_bytes_dropped": 5990,
"memif_bytes_sent": 21282,
"memif_packets_dropped": 30,
"memif_packets_sent": 246,
"packets_received": 276,
"bytes_received": 27272
},
"interface_stats": {
"interfaces": [
{
"byte_dropped": 0,
"byte_received": 0,
"byte_received_perf": 0,
"ierrors": 0,
"imissed": 0,
"ipackets": 0,
"mbuf_9k_alloc_failed": 0,
"mbuf_9k_alloc_ok": 0,
"mbuf_9k_populate_failed": 0,
"name": "eth0",
"no_packet": 0,
"packet_dropped": 0,
"packet_received": 0,
"packet_received_perf": 0,
"rx_loop": 0,
"rx_nombuf": 0,
"speed": 0,
"status": "down",
"tx_attempt": 0,
"tx_loop": 0,
"tx_packet_dropped": 0,

© November 2024 Vectra AI, Inc. | 138

 "type": "ixgbe"
},
{
"byte_dropped": 0,
"byte_received": 0,
"byte_received_perf": 0,
"ierrors": 0,
"imissed": 0,
"ipackets": 0,
"mbuf_9k_alloc_failed": 0,
"mbuf_9k_alloc_ok": 0,
"mbuf_9k_populate_failed": 0,
"name": "eth1",
"no_packet": 0,
"packet_dropped": 0,
"packet_received": 0,
"packet_received_perf": 0,
"rx_loop": 0,
"rx_nombuf": 0,
"speed": 0,
"status": "down",
"tx_attempt": 0,
"tx_loop": 0,
"tx_packet_dropped": 0,
"type": "ixgbe"
},
{
"byte_dropped": 0,
"byte_received": 27272,
"byte_received_perf": 0,
"ierrors": 0,
"imissed": 0,
"ipackets": 276,
"mbuf_9k_alloc_failed": 0,
"mbuf_9k_alloc_ok": 0,
"mbuf_9k_populate_failed": 0,
"name": "eth2",
"no_packet": 9129055228,
"packet_dropped": 0,
"packet_received": 276,
"packet_received_perf": 0,
"rx_loop": 9129055499,
"rx_nombuf": 0,
"speed": 1000,
"status": "up",
"tx_attempt": 0,
"tx_loop": 0,
"tx_packet_dropped": 0,

© November 2024 Vectra AI, Inc. | 139

 "type": "dpdk"
},
{
"byte_dropped": 0,
"byte_received": 0,
"byte_received_perf": 0,
"ierrors": 0,
"imissed": 0,
"ipackets": 0,
"mbuf_9k_alloc_failed": 0,
"mbuf_9k_alloc_ok": 0,
"mbuf_9k_populate_failed": 0,
"name": "eth3",
"no_packet": 0,
"packet_dropped": 0,
"packet_received": 0,
"packet_received_perf": 0,
"rx_loop": 0,
"rx_nombuf": 0,
"speed": 0,
"status": "down",
"tx_attempt": 0,
"tx_loop": 0,
"tx_packet_dropped": 0,
"type": "dpdk"
}
]
},
"forwarder_stats": {
"events_processed": 0,
"events_sent": 0,
"alerts_dropped_for_rate_limit": 0,
"alerts_dropped_for_rate_limit_this_hour": 0
},
"device_serial": "U12312300000123",
"timestamp": "2023-02-01T01:23:45.123456+00:00"
}
]
}

Vectra Match Status

GET

Used to retrieve Vectra Match status. Returned fields include:

device_serial: serial of the device for which the information is valid

is_enabled: boolean of whether Vectra Match is enabled on given device

© November 2024 Vectra AI, Inc. | 140

process_health: returns “healthy” if process is healthy, else gives description of current process health
timestamp: timestamp of when the information was gathered
process_error_detail: returns empty string when healthy, otherwise gives more information about cause
of health degredation

URL: https://<vectra_management_ip>/api/v3.4/vectra-match/status

Headers:
“Authorization”: “Token <api-key>”

Optional Query Params:

{“device_serial”:”<device_serial>”}

Response:
Status Code: 200
{
"status": [
{
"device_serial": "U12312300000123",
"is_enabled": true,
"process_health": "healthy",
"timestamp": "2023-02-01T01:23:45.123456+00:00"
},
{
"device_serial": "U12312300000456",
"is_enabled": true,
"process_health": "healthy",
"timestamp": "2023-02-01T01:23:46.234567+00:00"
},
{
"device_serial": "U12312300000789",
"is_enabled": true,
"process_health": "healthy",
"timestamp": "2023-02-01T01:23:47.345678+00:00"
}
]
}

Vectra Match Available Devices

GET

Used to retrieve devices on which Vectra Match can be enabled. Returned fields include:

device_serial: serial of the device

ip_address: IP address of the device
is_virtual: boolean, returns True if the device is virtual
last_seen: ISO-8601 timestamp of the time this device was last seen by the headend

© November 2024 Vectra AI, Inc. | 141

location: string, user-provided location
product_name: string, name of the product platform of the device
version: string, version of Vectra software that the device is currently running
alias: string, user-provided name for the device
headend_uri: string, if the device is a sensor, this is the URI of the headend to which it is paired
mode: string, ‘sensor’ if the device is a sensor, ‘mixed’ if the device is a headend in mixed mode

URL: https://<vectra_management_ip>/api/v3.4/vectra-match/available-devices

Headers:
“Authorization”: “Token <api-key>”

Response:
Status Code: 200
{
"devices": [
{
"device_serial": "U12312300000123",
"ip_address": "192.168.0.10",
"is_virtual": false,
"product_name": "X29v2",
"version": "7.5.0-1-9036",
“mode”: “mixed”,
},
{
"alias": "Sensor-Office",
"device_serial": "U12312300000456",
"headend_uri": "x29v2-5-10.example.local",
"ip_address": "192.168.1.10",
"is_virtual": false,
"last_seen": "2023-02-01T12:34:56Z",
"location": "Main Office",
"product_name": "S101",
"version": "7.5.0-1-9036",
“mode”: “sensor”,
},
{
"alias": "Sensor-DC",
"device_serial": "U12312300000789",
"headend_uri": "x29v2-5-10.example.local",
"ip_address": "192.168.2.10",
"is_virtual": false,
"last_seen": "2023-02-01T01:23:45Z",
"location": "New Office",
"product_name": "S11",
"version": "7.5.0-1-9036",
“mode”: “sensor”,

© November 2024 Vectra AI, Inc. | 142

 }
]
}

Vectra Match Rules

GET

Used to retrieve information about a Vectra Match ruleset, given its UUID

URL: https://<vectra_management_ip>/api/v3.4/vectra-match/rules

Headers:
“Authorization”: “Token <api-key>”

Query Params:
{“uuid”:”<uuid>”}

Response:
Status Code: 200
{
"device_serials": [],
"hashsum": "e5227116937f484e3044ba1f28d6053edb33fc565581d0fda73b587d6a2bfed9",
"name": "valid_rules.rules",
"notes": {
"creator": "vectra",
"description": "test note"
},
"timestamp": "2023-02-01T01:23:45.123456+00:00",
"uuid": "6aea451c-4156-4ac6-bbeb-c9e0b16b1da5"
}

DELETE

Used to delete a Vectra Match ruleset

URL: https://<vectra_management_ip>/api/v3.4/vectra-match/rules

Headers:
“Authorization”: “Token <api-key>”

Required Request JSON Body:

{“uuid”:”<uuid>”}

Response:
Status code: 200
{

© November 2024 Vectra AI, Inc. | 143

 "details": "success"
}

Vectra Match Rules Upload

POST

Used to upload a new Vectra Match ruleset. A valid Vectra Match license is required to use this endpoint.

URL: https://<vectra_management_ip>/api/v3.4/vectra-match/rules/upload/

Headers:
“Authorization”: “Bearer <api-key>”

Required Request JSON Body:

{“file_name”:”<filename>”, "notes": "<notes>"}

Request cURL Example:

curl --request POST \

--url https://<vectra_management_ip>/api/v3.4/vectra-match/rules/uploads/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{"file_name": "<your-filename.rules>", "notes": "We can put some notes
here"}'

Request Python Requests Example:

payload = {"file_name": "your-rules.rules", "notes": "additional notes here"}

resp = requests.post("https://<vectra_management_ip>/api/v3.4/vectra-
match/rules/upload/", headers={"Authorization":"Bearer <token>"}, verify=False,
json=payload

Response:

Status code: 200

{
"urls": [
"<temporary-upload-url-valid-for-2-mins>"
],
"id": "b68f41be-1312-4275-8c36-4ba0f738cf8a"
}

PUT

Upload the file to Vectra.

© November 2024 Vectra AI, Inc. | 144

Request cURL Example:

curl --request PUT \

--url ‘<upload-url-from-post>' \
--upload-file valid_rules.rules

Request Python Requests Example:

payload = open('./your-file.rules', 'rb')

resp = requests.request("PUT", upload-url-from-post, data=payload)

Response:

Status code: 200

PATCH

Mark the upload as completed.

URL: https://<vectra_management_ip>/api/v3.4/vectra-match/rules/upload/<upload-uuid>

Headers:
“Authorization”: “Bearer <api-key>”

Required Request JSON Body:

{“upload_status": "completed”}

Response:
Status code: 200
{
"upload_status": "completed"

GET

Get the details of the upload.

URL: https://<vectra_management_ip>/api/v3.4/vectra-match/rules/upload/<upload-uuid>

Headers:
“Authorization”: “Bearer <api-key>”

Response:
Status code: 200
{
“id": "b68f41be-1312-4275-8c36-4ba0f738cf8a",
"upload_status": "completed",
"external_task_status": "not_started",
"external_task_updated_at": "2024-02-29T09:58:28Z"
}

Failed external task Response:

© November 2024 Vectra AI, Inc. | 145

{
“id": "b68f41be-1312-4275-8c36-4ba0f738cf8a",
"upload_status": "completed",
"external_task_status": "not_started",
"external_task_error": ""Uploaded Vectra Match ruleset failed validation, errors:
22/5/2024 -- 16:03:54 - <Error> - [ERRCODE: SC_ERR_INVALID_ACTION(142)]….. - <Error> -
[ERRCODE: SC_ERR_NO_RULES_LOADED(43)] - Loading signatures failed.",
"external_task updated_at": "2024-02-29T09:58:28Z",
“external_task_error_code”: 6005
}

GET LIST

Get the list of the users uploads from the last 24 hours.

URL: https://<vectra_management_ip>/api/v3.4/vectra-match/rules/upload/

Headers:
“Authorization”: “Bearer <api-key>”

Response:
Status code: 200
[
{
“id": "b68f41be-1312-4275-8c36-4ba0f738cf8a",
"upload_status": "completed",
"external_task_status": "not_started",
"external_task_updated_at": "2024-02-29T09:58:28Z"
}
]

Vectra Match Assignment

GET

Used to retrieve information about current Vectra Match ruleset assignments.

URL: https://<vectra_management_ip>/api/v3.4/vectra-match/assignment

Headers:
“Authorization”: “Token <api-key>”

Response:
Status Code: 200
{
"device_to_rules_map": [
{
"device_serial": "U12312300000123",
"rules": [
"6aea451c-4156-4ac6-bbeb-c9e0b16b1da5"

© November 2024 Vectra AI, Inc. | 146

 ],
"timestamp": "2023-02-01T01:23:45.123456+00:00",
"updated_by": "vadmin"
},
{
"device_serial": "U12312300000456",
"rules": [
"6aea451c-4156-4ac6-bbeb-c9e0b16b1da5"
],
"timestamp": "2023-02-01T01:23:45.123456+00:00",
"updated_by": "vadmin"
},
{
"device_serial": "U12312300000789",
"rules": [
"6aea451c-4156-4ac6-bbeb-c9e0b16b1da5"
],
"timestamp": "2023-02-01T01:23:45.123456+00:00",
"updated_by": "vadmin"
}
],
"rules_to_devices_map": [
{
"device_serials": [
"U12312300000123",
"U12312300000456",
"U12312300000789"
],
"hashsum": "e5227116937f484e3044ba1f28d6053edb33fc565581d0fda73b587d6a2bfed9",
"name": "valid_rules.rules",
"notes": {
"creator": "vectra",
"description": "test note"
},
"timestamp": "2023-02-01T01:23:45.123456+00:00",
"uuid": "6aea451c-4156-4ac6-bbeb-c9e0b16b1da5"
}
]
}

POST

Used to assign a Vectra Match ruleset to one or more devices. A valid Vectra Match license is required to use this
endpoint.

URL: https://<vectra_management_ip>/api/v3.4/vectra-match/assignment

© November 2024 Vectra AI, Inc. | 147

Headers:
“Authorization”: “Token <api-key>”

Required Request JSON Body:

{“uuid”:”<uuid>”, “device_serials”:[“<serial1>”, “<serial2>”,…]}

Response:
Status code: 200
{
"details": "success"
}

DELETE

Used to remove a rules file from a given device

URL: https://<vectra_management_ip>/api/v3.4/vectra-match/assignment

Headers:
“Authorization”: “Token <api-key>”

Required Request JSON Body:

{“uuid”:”<uuid>”, “device_serial”:”<device_serial>”}

Response:
Status code: 200
{
"details": "success"
}

Vectra Match Alert Stats

GET

Used to retrieve Vectra Match alert stats. Returned fields include:

top_alert_counts: statistics directly pulled from the Vectra Match (suricata) engine about the top 10 alerts
that have been processed since the last rotation of the suricata’s eve.json event log
eve_log_rotated_time: ISO-8601 timestamp of the last time the eve.json log was rotated, which helps to
indicate the time window the alert counts were collected over (from this timestamp until the current time)
device_serial: serial of the device for which the stats are given
URL: https://<vectra_management_ip>/api/v3.4/vectra-match/alert-stats

Headers:
“Authorization”: “Token <api-key>”

Optional Query Params:

{“device_serial”:”<device_serial>”}

© November 2024 Vectra AI, Inc. | 148

Response:
Status Code: 200
{
"alert_stats": [
{
"top_alert_counts": [
{"count": 1032, "signature_id": 2100498, "signature": "GPL
ATTACK_RESPONSE id check returned root"},
{
"count": 101,
"signature_id": 2006380,
"signature": "ET POLICY Outgoing Basic Auth Base64 HTTP Password
detected unencrypted",
},
{"count": 78, "signature_id": 2028807, "signature": "ET JA3 Hash -
[Abuse.ch] Possible Tofsee"},
{"count": 60, "signature_id": 2034636, "signature": "ET INFO Python
SimpleHTTP ServerBanner"},
{
"count": 34,
"signature_id": 2001580,
"signature": "ET SCAN Behavioral Unusual Port 137 traffic
Potential Scan or Infection",
},
{"count": 27, "signature_id": 2028763, "signature": "ET JA3 Hash -
[Abuse.ch] Possible Adwind"},
{"count": 12, "signature_id": 2017398, "signature": "ET POLICY IP
Check Domain (icanhazip. com in HTTP Host)"},
{"count": 10, "signature_id": 2027390, "signature": "ET USER_AGENTS
Microsoft Device Metadata Retrieval Client User-Agent"},
{"count": 8, "signature_id": 2035466, "signature": "ET INFO Observed
Discord Domain in DNS Lookup (discordapp .com)"},
{"count": 7, "signature_id": 2016922, "signature": "ET MALWARE
Backdoor family PCRat/Gh0st CnC traffic"},
],
"device_serial": "A21010000000002",
"eve_log_rotated_time": "2023-03-23T18:00:00",
}
]
}

Threat
GET

- Used to retrieve a download url for the Vectra Match Curated Ruleset file
- Download url expires after 2 minutes

© November 2024 Vectra AI, Inc. | 149

URL: https://<vectra_management_ip>/api/v3.4/vectra-match/download-vectra-ruleset
{
"download_url": "https://sample-download-url"
}

Threat Feeds
GET
URL: https://<vectra_management_ip>/api/v3.4/threatFeeds/

Headers:
“Authorization”: “Token <api-key>”

Response:
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "40822ff3a8098b4073851996b5735185",
"_rev": "2-563284353939596519e8b8a9f058193f",
"name": "test-feed-2",
"lastUpdatedBy": "api_client_78d7360065524aa9919dd127d56c1d81",
"version": "7.8-336-g1de329dc878",
"uploadDate": "2023-08-23T15:22:22.563534+00:00",
"lastUpdated": "2023-08-31T15:35:23.837079+00:00",
"defaults": {
"indicatorType": "Anonymization",
"certainty": "Low",
"duration": 7,
"category": "cnc"
},
"uploadResults": "{
'indicatorType': 'Malware Artifacts',
'observableCount': 2,
'certainty': 'Low',
'expiration': '2023-09-07T15:35:23.727684+00:00',
'category': 'cnc'
}",
"type": "STIX"
},
]
}

© November 2024 Vectra AI, Inc. | 150

POST to create a threatFeed

URL: https://<vectra_management_ip>/api/v3.4/threatFeeds/

Headers:
“Authorization”: “Token <api-key>”

Body:
{
"threatFeed": {
"name":"test-feed",
"defaults": {
"certainty":"High",
"duration":7,
"indicatorType":"Anonymization",
"category":"cnc"
}
}
}

All the fields shown above are mandatory. See the section on threatFeeds for possible values each label can take.

PATCH to update a threatFeed

URL: https://<vectra_management_ip>/api/v3.4/threatFeeds/<id>

Headers:
“Authorization”: “Token <api-key>”

Body:
{
"threatFeed": {
"name":"test-feed",
"defaults": {
"certainty":"High",
"duration":7,
"indicatorType":"Anonymization",
"category":"cnc"
},
“upload”: {
“replace_filename”: “test_stix_file.xml”,
“filename”: “existing_stix_file.xml”
}
}
}
Note: The replace_filename must be an already uploaded STIX file. This action will delete the former Threat Feed File
and link the current Threat Feed object to the replacement file.

© November 2024 Vectra AI, Inc. | 151

POST to add or replace STIX file to an existing threatFeed

URL: https://<vectra_management_ip>/api/v3.4/threatFeeds/<id>/

Headers:
“Authorization”: “Token <api-key>”

Body: Send the STIX file as a multi part form data

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="stix_test_url_anon.xml"
Content-Type: text/xml

------WebKitFormBoundary7MA4YWxkTrZu0gW—

Response Success:

{
"threatFeed": {
"uploadResults": {
"category": "cnc",
"certainty": "High",
"expiration": "2019-08-27T20:55:29.27Z ",
"indicatorType": "Anonymization",
"observableCount": 4
}
}
}

If you are using a tool like postman, perform the POST with the body of the POST as “form-data” with Key as “file”
and value as the selected file from the file system. Do not add a content type header explicitly for postman, since
the tool does it automatically.

Unique Hosts Observed Monthly

GET used to list unique hosts observed.

URL: https://<vectra_portal_url>/api/v3.4/unique_hosts_observed_monthly

Headers:
“Authorization”: “Bearer <access_token>”

Response:

© November 2024 Vectra AI, Inc. | 152

[
{
"month_start": "2022-10-01",
"month_end": "2022-10-31",
"unique_hosts_observed": 0
},
{
"month_start": "2022-11-01",
"month_end": "2022-11-30",
"unique_hosts_observed": 0
},
{
"month_start": "2022-12-01",
"month_end": "2022-12-31",
"unique_hosts_observed": 0
},
{
"month_start": "2023-01-01",
"month_end": "2023-01-31",
"unique_hosts_observed": 0
},
{
"month_start": "2023-02-01",
"month_end": "2023-02-28",
"unique_hosts_observed": 0
},
{
"month_start": "2023-03-01",
"month_end": "2023-03-31",
"unique_hosts_observed": 0
},
{
"month_start": "2023-04-01",
"month_end": "2023-04-30",
"unique_hosts_observed": 0
},
{
"month_start": "2023-05-01",
"month_end": "2023-05-31",
"unique_hosts_observed": 0
},
{
"month_start": "2023-06-01",
"month_end": "2023-06-30",
"unique_hosts_observed": 0
},
{
"month_start": "2023-07-01",

© November 2024 Vectra AI, Inc. | 153

 "month_end": "2023-07-31",
"unique_hosts_observed": 0
},
{
"month_start": "2023-08-01",
"month_end": "2023-08-31",
"unique_hosts_observed": 0
},
{
"month_start": "2023-09-01",
"month_end": "2023-09-30",
"unique_hosts_observed": 10
},
{
"month_start": "2023-10-01",
"month_end": "2023-10-31",
"unique_hosts_observed": 15
}
]

Unique Hosts Observed Monthly - Audit

GET used to list information on unique hosts observed.

URL: https://<vectra_portal_url>/api/v3.4/unique_hosts_observed_monthly/audit

Headers:
“Authorization”: “Bearer <access_token>”

Response:
"count": 21,
"next":
"https://208328399689.uw2.devportal.vectra.ai/api/v3.4/unique_hosts_observed_monthly/a
udit?page=2&page_size=10",
"previous": null,
"results": [
{
"month": "2023-09",
"host_id": 1,
"host_luid": "test1",
"ip_address": "1.2.3.4",
"host_artifact_value": "test",
"host_artifact_type": "generic",
"last_seen_start": "2023-09-12T16:00:00Z",
"last_seen_end": "2023-09-29T19:18:03Z"
},
{
"month": "2023-09",

© November 2024 Vectra AI, Inc. | 154

 "host_id": 2,
"host_luid": null,
"ip_address": "4.8.8.8",
"host_artifact_value": "test_2",
"host_artifact_type": "kerberos",
"last_seen_start": "2023-09-25T16:00:00Z",
"last_seen_end": null
},
{
"month": "2023-09",
"host_id": 1,
"host_luid": "ex_luid",
"ip_address": "3.8.8.8",
"host_artifact_value": "test",
"host_artifact_type": "generic",
"last_seen_start": "2023-09-24T16:00:00Z",
"last_seen_end": null
},
{
"month": "2023-09",
"host_id": 12,
"host_luid": null,
"ip_address": "3.7.8.8",
"host_artifact_value": null,
"host_artifact_type": null,
"last_seen_start": "2023-09-24T16:00:00Z",
"last_seen_end": null
},
{
"month": "2023-09",
"host_id": 12,
"host_luid": null,
"ip_address": "3.7.8.5",
"host_artifact_value": null,
"host_artifact_type": null,
"last_seen_start": "2023-09-24T16:00:00Z",
"last_seen_end": null
},
{
"month": "2023-09",
"host_id": 12,
"host_luid": "test22",
"ip_address": "1.7.8.5",
"host_artifact_value": null,
"host_artifact_type": null,
"last_seen_start": "2023-09-14T16:00:00Z",
"last_seen_end": null
},

© November 2024 Vectra AI, Inc. | 155

 {
"month": "2023-09",
"host_id": 11,
"host_luid": "test21",
"ip_address": "1.7.3.5",
"host_artifact_value": null,
"host_artifact_type": null,
"last_seen_start": "2023-09-14T16:00:00Z",
"last_seen_end": null
},
]

Unique Hosts Observed

GET used to list unique hosts observed in a given timespan

URL: https://<vectra_portal_url>/api/v3.4/unique_hosts_observed

Headers:
“Authorization”: “Bearer <access_token>”

Response:
[
{
"month_start": "2023-06-01",
"month_end": "2023-10-15",
"unique_hosts_observed": 230
}
]

Unique Hosts Observed - Audit

GET used to list information on unique hosts observed.

URL: https://<vectra_portal_url>/api/v3.4/unique_hosts_observed/audit

Headers:
“Authorization”: “Bearer <access_token>”

Response:
"count": 21,
"next":
"https://<vectra_portal_url>.uw2.devportal.vectra.ai/api/v3.4/unique_hosts_observed/au
dit?page=3&page_size=6",
"previous": null,
"results": [
{
"host_id": 1,

© November 2024 Vectra AI, Inc. | 156

 "host_luid": "test1",
"ip_address": "1.2.3.4",
"host_artifact_value": "test",
"host_artifact_type": "generic",
"last_seen_start": "2023-06-12T16:00:00Z",
"last_seen_end": "2023-06-29T19:18:03Z"
},
{
"host_id": 1,
"host_luid": "test1",
"ip_address": "1.2.3.4",
"host_artifact_value": "test",
"host_artifact_type": "generic",
"last_seen_start": "2023-07-12T16:00:00Z",
"last_seen_end": "2023-07-29T19:18:03Z"
},
{
"host_id": 2,
"host_luid": null,
"ip_address": "4.8.8.8",
"host_artifact_value": "test_2",
"host_artifact_type": "kerberos",
"last_seen_start": "2023-08-25T16:00:00Z",
"last_seen_end": null
},
{
"host_id": 1,
"host_luid": "ex_luid",
"ip_address": "3.8.8.8",
"host_artifact_value": "test",
"host_artifact_type": "generic",
"last_seen_start": "2023-09-24T16:00:00Z",
"last_seen_end": null
},
{
"host_id": 22,
"host_luid": null,
"ip_address": "3.7.8.8",
"host_artifact_value": null,
"host_artifact_type": null,
"last_seen_start": "2023-09-24T16:00:00Z",
"last_seen_end": null
},
{
"host_id": 13,
"host_luid": "test22",
"ip_address": "1.7.8.5",
"host_artifact_value": null,

© November 2024 Vectra AI, Inc. | 157

 "host_artifact_type": null,
"last_seen_start": "2023-10-14T16:00:00Z",
"last_seen_end": null
},
]

Appendix B
Detections
Predefined categories and vnames

CATEGORY VNAME
Command and Control
Azure AD Admin Account Creation
Azure AD MFA-Failed Suspicious Sign-On
O365 Power Automate HTTP Flow Creation
Azure AD Redundant Access Creation
Azure AD Suspicious OAuth Application
O365 Suspicious Power Automate Flow Creation
Azure AD Suspicious Sign-On
Azure AD TOR Activity
AWS Root Credential Usage
AWS Suspicious Credential Usage
AWS TOR Activity
Botnet
AWS Cryptomining
Reconnaissance
O365 Suspicious Compliance Search
O365 Unusual eDiscovery Search
O365 Suspect eDiscovery Usage
AWS EC2 Enumeration
AWS Organization Discovery
AWS S3 Enumeration
AWS Suspect Credential Access from EC2
AWS Suspect Credential Access from ECS
AWS Suspect Credential Access from SSM
AWS Suspect Escalation Reconnaissance

© November 2024 Vectra AI, Inc. | 158

CATEGORY VNAME
AWS User Permission Enumeration
Lateral Movement
Azure AD Successful Brute-Force
O365 Suspicious Mailbox Manipulation
O365 Attacker Tool: Ruler
Azure AD Change to Trusted IP Configuration
O365 Disabling of Security Tools
O365 DLL Hijacking Activity
O365 External Teams Access
O365 Internal Spearphising
O365 Log Disabling Attempt
O365 Malware Stage: Upload
Azure AD MFA Disabled
Azure AD Newly Created Admin Account
O365 Ransomware
O365 Risky Exchange Operation
Azure AD Privilege Operation Anomaly
O365 Suspicious Sharepoint Operation
O365 Suspicious Teams Application
Azure AD Unusual Scripting Engine Usage
AWS ECR Hijacking
AWS Lambda Hijacking
AWS Logging Disabled
AWS Ransomware S3 Activity
AWS Security Tools Disabled
AWS Suspect Admin Privilege Granting
AWS Suspect Console Pivot
AWS Suspect Login Profile Manipulation
AWS Suspect Privilege Escalation
AWS User Hijacking
Exfiltration
O365 eDiscovery Exfil
O365 Exfiltration Before Termination
O365 Suspicious Download Activity

© November 2024 Vectra AI, Inc. | 159

CATEGORY VNAME
O365 Suspicious Exchange Transport Rule
O365 Suspicious Mail Forwarding
O365 Suspect Power Automate Activity
O365 Suspicious Sharing Activity
AWS Suspect External Access Granting
AWS Suspect Public EBS Change
AWS Suspect Public EC2 Change
AWS Suspect Public S3 Change

© November 2024 Vectra AI, Inc. | 160