Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

API Deployment

Match API overview and deployment examples for RUX (OAuth) and QUX (token), including ruleset upload and assignment.

About the Vectra Match APIs

Vectra provides different APIs for use with Respond UX or Quadrant UX deployments. Please see the below resources to get started with either API.

Respond UX (API v3.3 or higher)

vectra-match_v3.3.yaml
79KB
Open

Quadrant UX (API v2.5 or higher)

vectra-match_v2.5.yaml
75KB
Open

The deployment examples included below contain basic steps to get up and running. It is recommended to read the API guide (specific to your deployment type) to see additional examples and definitions for included datapoints.

The v3.3 API (RUX) uses OAuth 2.0 to authenticate access. Please see the links above for the quickstart tutorial and API guide for full details on authentication and how to manage token refreshes while accessing the API.

Example Request:

Example Response:

The v2.5 API (QUX) uses token authentication. Every user created on the Vectra platform has access to manage API tokens under the My Profile page. Example of using token authentication with cURL is shown below.

Overall Match API Capabilities

  • Match Enablement - /vectra-match/enablement

    • GET or POST to get enablement state or set enablement state per device.

  • Match Stats - /vectra-match/stats

    • GET returns detailed stats per device or for all devices that were ever enabled.

  • Match Status - /vectra-match/status

    • GET returns health status per device or for all devices that were ever enabled.

  • Match Available Devices - /vectra-match/available-devices

    • GET returns available (paired) devices that can be enabled for Match.

  • Match Rules - /vectra-match/rules

    • GET, POST, or DELETE to retrieve information about, upload (v2.5 only), or delete a ruleset file.

  • Match Rules Upload - /vectra-match/rules/upload/ (v3.3 only)

    • POST, PATCH, and GET to start a ruleset upload, mark the upload complete, and retrieve status.

  • Match Assignments - /vectra-match/assignment

    • GET, POST, or DELETE to retrieve, assign, or delete a ruleset assignment to a device.

  • Match Alert Stats - /vectra-match/alert-stats

    • GET to retrieve top 10 list of most frequently fired rules per device.

API Deployment Examples

In the below deployment examples, please keep in mind the following:

  • The examples below were created when Match was originally released and are specific to Quadrant UX authentication (token vs OAuth).

    • For use with RUX (v3.3 API or later), the example requests would need to be modified to use OAuth authentication as per the v3.3 API guide.

    • The endpoints and calls to them are the same as for the v2.5 API with the exception of ruleset upload, which had to be different because of the architecture difference between QUX and RUX deployments.

      • API calls are made against the Brain in QUX deployments, while they are made against Vectra’s cloud in RUX deployments.

      • For RUX deployments, rulesets are uploaded to a temporary URL that allows upload to an AWS S3 bucket. The Vectra cloud then transfers the file to the Brain so that it can be assigned to Sensors just like in QUX deployments.

      • Any example of doing ruleset upload for both RUX and QUX deployments will be included below. Be sure to follow the correct example depending on which deployment type you have.

  • These examples are specific to our sample environment, depending on how you access the API, you will need to adjust for the tooling you use (Postman, cURL, etc). Examples will contain variables that you need to replace with values for your environment such as:

    • {{baseURL}} – replace with IP or hostname of your Brain or Vectra tenant and then add a / and the the api version you are using.

      • For example - https://brain_hostname_or_ip/v2.5

      • For example - https://vectra_tenant/v3.3

    • <token> – replace with your API token.

      • As per the above, the token is only used for v2.5 API, for v3.3 OAuth must be used.

    • <Device Serial> – replace with your Sensor serial number.

Retrieve list of available devices

Devices must be paired to be available for Match enablement (mixed mode devices are supported).

To enable a device (Network Data Source or Sensor), you will need to know its serial number. This can be retrieved from the UI at Configuration → COVERAGE → Data Sources → Network → Sensor but using the API makes programmatic retrieval of all devices simple. Our sample deployment contains a single Sensor for simplicity. Making a GET request to the available-devices endpoint to list available devices (to be available for enabling, a device must be paired to your Brain).

BODY: None

Request cURL Example:

Response Example:

Get current enablement state for a given device

First, we will check the enablement state of the device we now see as available above by making GET request to the enablement endpoint.

Example request:

Request cURL Example:

Response example:

We see that the device is not currently enabled for Match.

Set enablement state for a given device

To enable this device, we now make POST request to the same enablement endpoint and include the device serial number and desired state (true/false) in the BODY of the request.

BODY Syntax:

Example BODY:

Request cURL Example:

Response Example:

Get current status for a device (or all devices)

After enabling Match on a device, activation can take 5–10 minutes due to several back-end changes being required.

  • Include device_serial to check a single device.

  • Omit device_serial to retrieve status for all devices.

Example Request (single device):

cURL Request Example (single device):

Example Response:

After Match has successfully activated:

Upload and validate a new ruleset (v3.3 RUX deployments only)

While waiting for device activation, we can upload a ruleset to the Vectra cloud for later assignment to the device. After the ruleset is uploaded to the Vectra cloud, it will automatically be transferred to the Brain where it can then be assigned. The general process to do the ruleset upload for RUX deployments is as follows:

  1. POST to {{baseUrl}}/vectra-match/rules/upload/ a JSON body with a desired filename for the upload along with any desired notes.

    • This will return an ID (used only to track the ruleset upload) and a temporary URL (valid only for 2 minutes).

    • If you do not start uploading within 2 minutes, you must start over with a new POST.

Please Note:

  • This is not the same as the UUID that will be used to track the rules file on the Brain/Sensors.

  • This ID only tracks the ruleset upload. The filename that was uploaded must be used later to find the ruleset UUID used for device assignment.

  • It is recommended to use a unique filename and the optional notes field within the request to describe rulesets so that rulesets are more easily distinguishable from one another.

  1. Use a PUT to the URL that was returned in the 1st step with a form data body consisting of the ruleset file to upload the file to Vectra’s cloud.

  2. PATCH to {{baseUrl}}/vectra-match/rules/upload/{{ID}} with a JSON body stating {"upload_status": "completed"} to mark the ruleset upload as complete.

    • The ruleset will then automatically be synced to the Brain appliance.

  3. GET to {{baseUrl}}/vectra-match/rules/upload/{{ID}} to confirm the file has successfully been synced to the Brain appliance.

  4. To find the UUID (used for ruleset assignment):

    • Use the /assignment endpoint to list the ruleset assignments.

    • Find the filename you just uploaded and use the corresponding UUID for ruleset management and assignment. The timestamp may also be useful when searching for the correct UUID.

Please Note:

After a successful upload and sync to the Brain, the ruleset UUID will be used from this point on to reference this file when interacting with the Match API. During the upload process, the ruleset will be validated. If the ruleset fails validation, a 422 error with details will be returned.

Please Note:

A ruleset is accepted when one or more rules within the ruleset are valid. A ruleset is only rejected if there are zero valid rules, it is too large, doesn’t have a .rules extension, or the contents match exactly with an existing ruleset.

Please Note:

Per the Supported Limits, a Brain can support a maximum of 25 unique rulesets. A multipart form object, rotate, is available to make it easier to stay under this limit. Setting rotate to true will allow the Brain to delete the oldest unassigned ruleset when a 26th ruleset is attempted to be uploaded. If all rulesets are assigned to sensors or the rotate option is not used, when a 26th ruleset is attempted to be uploaded to the Brain, a 507 error stating More than 25 files are currently stored by Vectra Match. Please delete any unused files and try again will be returned.

Starting Ruleset Upload

Headers:

BODY: Form data body with optional notes

Request cURL Example:

Request Python Requests Example:

Response Example:

Uploading the Ruleset

Request cURL Example:

Request Python Requests Example:

Response:

Mark Ruleset Upload as Complete

Use the ID that was returned from the earlier POST

Headers:

Required Request JSON Body:

Response:

Confirm Sync of Ruleset to Brain Appliance

Headers:

Response:

Find the UUID of the Ruleset

Use the ID that was returned from the earlier POST

Headers:

Search the output for your filename (using the timestamp may help) and when you find it, the uuid that corresponds to the ruleset (now that it is on the Brain appliance) should be used moving forward. Below you will see a portion of the full output of the GET to the /assignment endpoint and the uuid (on 3rd line) that should be used.

Upload and validate a new ruleset (v2.5 QUX deployments only)

While waiting for device activation, we can upload a ruleset to the Brain for later assignment to the device.

To upload a new ruleset, make a POST request to the rules endpoint. Examples using cURL and Python Requests are shown below. Using Postman (collection available at Vectra Postman collection) or another similar tool allows a GUI selection of the file to supply the form data body. It is recommended to use the optional notes field within the request to describe rulesets so that rulesets are more easily distinguishable.

Please Note:

After a successful upload, the ruleset is given a unique UUID that is shown on the last line of the response example. The UUID will be used from this point on to reference this file when interacting with the Match API. During the upload process, the ruleset will be validated. If the ruleset fails validation, a 422 error with details will be returned.

Please Note:

A ruleset is accepted when one or more rules within the ruleset are valid. A ruleset is only rejected if there are zero valid rules, it is too large, doesn’t have a .rules extension, or the contents match exactly with an existing ruleset.

Please Note:

Per the Supported Limits, a Brain can support a maximum of 25 unique rulesets. A multipart form object, rotate, is available to make it easier to stay under this limit. Setting rotate to true will allow the Brain to delete the oldest unassigned ruleset when a 26th ruleset is attempted to be uploaded. If all rulesets are assigned to sensors or the rotate option is not used, when a 26th ruleset is attempted to be uploaded to the Brain, a 507 error stating More than 25 files are currently stored by Vectra Match. Please delete any unused files and try again will be returned.

BODY: Form data body with optional notes

Request cURL Example:

Request Python Requests Example:

Response Example:

As you can see in the first line of the response example, the ruleset has not been assigned to any devices yet.

Add a ruleset assignment to various devices

Now that we have a valid ruleset, we can assign this ruleset to our device by making a POST request to the assignment endpoint. Please note that this operation supports assigning a ruleset to any number of devices with one API call. The first example below is for our example deployment with one device, the second example shows how this would work for multiple device assignment in a single API call. The assignment process will copy the ruleset to the device and Match will begin processing rules against observed traffic after a short delay for automated service restarts.

cURL Request Example:

BODY:

BODY Example from OpenAPI document showing multiple device assignment:

Response Example:

Retrieve all existing mappings between rulesets and devices

To see all ruleset assignments, simply make a GET request to the assignment endpoint.

cURL Request Example:

Response Example:

Delete a ruleset

To delete a ruleset, make a DELETE request to the rules endpoint with the ruleset uuid in the body of the request. Please note that when deleting a ruleset, any corresponding assignments are also removed.

cURL Request Example:

Body Example:

Example Response:

Delete a ruleset assignment

To delete a ruleset assignment, make a DELETE request to the assignment endpoint with the uuid and device_serial in the body of the request:

cURL Request Example:

Body Example:

Example Response:

Download the Vectra Match Curated Ruleset (v3.3 RUX only)

To download the Vectra Match Curated Ruleset, make a GET request to the download-vectra-ruleset endpoint.

  • This will return a URL that is valid for 2 minutes that can be used to download the curated ruleset.

Example Response:

To Download the File:

  • Another GET could be used to stream the contents of the curated.rules file

  • Or a simple cURL or WGET could be used.

cURL example below:

Download the Vectra Match Curated Ruleset (v2.5 QUX only)

To download the Vectra Match Curated Ruleset, make a GET request to the download-vectra-ruleset endpoint.

When using Postman, you can just use the Send and Download option instead of the normal Send button.

cURL Request Example:

Response:

You will receive a Status Code: 200 and the call will stream the contents of curated.rules file

PreviousDeployment (UI and general guidance)NextOutputting Matches to downstream receivers

Last updated

Was this helpful?