SIEM connector (syslog intermediary)

How to configure a syslog intermediary server to poll the RUX API and then send data via syslog to a downstream collector.

Introduction

As per the article summary, when using the Respond UX (RUX) to access the Vectra AI Platform, syslog is not natively supported and event retrieval is supported via API. If syslog output of Vectra events is required, the SIEM Connector installed in the customer environment can provide syslog output. It provides organizations with a turnkey solution to connect any log management solution or SIEM that supports syslog to the Vectra AI Platform (RUX).

This connector allows:

• Pulling data from the Vectra Respond UX API at regular intervals.

• Storing and sending events to any syslog-aware solution.

• Support of TCP, UDP or TLS for syslog transport.

The events that are being pulled by the SIEM Connector are:

• Entity scoring events

• Detections events

• Audit events

All events are in JSON format. Only syslog headers are being added to the payload before being sent out.

Native SIEM/SOAR Integrations

It is highly recommended to use a native integration that works with the RUX API when possible. Only use the SIEM connector when a API-based integration is not possible. Several integrations using the API have already been published such as:

• Crowdstrike Falcon Next-Gen SIEM (credentials for Crowstrike Falcon required to access Crowdstrike docs at link)

• Splunk Integration Guide for Vectra XDR (Respond UX) ​​​​​​

• QRadar Integration Guide for Vectra XDR (Respond UX) ​​​​​​

• Azure Sentinel Integration Guide for Vectra XDR (Respond UX) ​​​​​​

• Splunk SOAR Integration Guide for Vectra XDR

• Palo Alto XSOAR Integration Guide for Vectra XDR

• ServiceNow SIR Integration Guide for Vectra XDR

• ServiceNow ITSM Integration Guide for Vectra XDR

• Google SecOps Integration Guide for Vectra XDR (Respond UX)

Solution Overview

Pre-requisites

Below are the prerequisites for setting up the Vectra SIEM connector.

• Users must have a Linux based server to provide as a host for the Docker container.

• Users must have access to a Vectra Respond UX tenant with client_id and client_secret for API authentication using the role Auditor.

  • Additional information about the API is available here: Vectra SaaS API Guide v3.4

• Users must configure a syslog destination server to receive data over UDP, TCP or TLS.

• Docker (version 24.0.5 minimum)

  • Refer to https://docs.docker.com/engine/install/#server for installation instructions.

  • ​​​​​​$ docker version - Will show the version to allow you to validate it.

• Docker compose (version 2.20.2 minimum)

  • Refer to https://docs.docker.com/compose/install/linux/ for installation instructions.

  • $ docker compose version - Will show the version to allow you to validate it.

Minimum System Requirements

To run the connector, the following are the minimum requirements where you will run the connector:

• 4 GB of RAM

• 20 GB of free storage

Compatibility Matrix

Compatibility Point	Version Supported
Vectra AI Platform (SaaS) API	v3.3 and higher
Operating System	Windows, Linux (Ubuntu)

Download and Initial Setup

The connector is available in the "vectranetworks" GitHub: Click here Clone the repo to get started:

git clone https://github.com/vectranetworks/siem-connector.git

Configuration

Vectra API Configuration

The information relative to the API are being passed to the container through the docker-compose file. Below is the relevant part for this configuration:

environment:
    BASE_URL: <VECTRA-TENANT-BASE-URL>
    CLIENT_ID: <VECTRA_CLIENT_ID>
    CLIENT_SECRET: <VECTRA_CLIENT_SECRET>

Optional Configuration - No Triage

The default image retrieves all detection details including those that have been triaged. To prevent triaged detections from being ingested, modify line 19 of docker-compose.yml as follows and save before launching.

image: tmevectra/vectra-saas-siem-connector:no_triage

Target Configuration

Then, provide destination server details and cron schedules for each APIs in the config.json file:

{
  "configuration": {
      "server": [
          {
              "name": "<server-name>",
              "server_protocol": "<server-protocol>",
              "server_host": "<destination-server-ip-or-host>",
              "server_port": <destination-server-port>
          }
      ],
      "scheduler": {
          "audit": "<cron-expression-for-audit>",
          "detections": "<cron-expression-for-detections>",
          "entity_scoring": "<cron-expression-for-entity-scoring>"
      },
      "retry_count": <retry-count>
  }
}

Description of each field:

Field	Description	Possible Values
Server Details
name	Destination server name	alphabets, number, _ , -(Minimum 1 character)
server_protocol	Protocol supported by destination server	TCP, UDP, TLS, tcp, udp, tls
server_host	Destination server host or IP address	Valid IP or hostname
server_port	Destination server port which is able to receive data on configured protocol	Min: 1Max: 65535
Scheduler Details
audit, detections, entity_scoring	API will fetch events on provided respective cron intervals	Valid cron expression
retry_count	Number of times the connector will retry before exiting in case the server is not reachable (If a negative value is given, the connector will continue retrying until server is reachable). It is not recommended to use a negative value.	Positive or negative integer

The recommended configuration for cron is to pull every minute and set a retry_count to 2:

"scheduler": {
    "audit": "* * * * *",
    "detections": "* * * * *",
    "entity_scoring": "* * * * *"
},
"retry_count": 2

If desired, some guidance around setting cron expressions is available here: https://crontab.guru/

In case of TLS servers, provide a TLS configured server certificate.pem file in the cert folder.

Please Note:

Certificate file name should be the same as the server name provided in config.json.

Connector Management

Start the Connector

The docker-compose configuration defines the two containers that are required for this solution:

• rabbitmq RabbitMQ as a queue mechanism which handles tasks and data preservation.

• vectra-saas Contains a Vectra Syslog Connector (python application) which will fetch data from Vectra API and push data to the configured syslog server.

Both images are being pulled from Docker Hub. There is no need to build the image for vectra-saas locally. To start the connector, run:

docker compose up -d

Stop the Connector

In case you need to stop the connector, run:

docker compose stop

This would be required for example if the config file is modified.

Terminate the Connector

In case you need to terminate the connector (this removes containers):

docker compose down

Restart Policy

In case of any failure or restart of the server, the containers would be automatically restarted. This is controlled by docker-compose with the restart policy.

Output's log format

It follows RFC 5234 specifications. The Syslog message that is sent out has the following format:

<PRI> <TMESTAMP> <HOSTNAME>: <MSG>

Description:

• PRI: Facility and Severity. It is set to <14> (Facility=user-level and Severity=info)

• TIMESTAMP: Formalized timestamp

• HOSTNAME: The HOSTNAME is static and set to VECTRA-SYSLOG-CONNECTOR.

• MSG: JSON payload pulled from Vectra's AI Platform API

Example of a detection event:

<14>2023-11-02T00:18:01Z VECTRA-SYSLOG-CONNECTOR: {"id": 1098, "category": "reconnaissance", "threat": 40, "certainty": 40, "triaged": false, "detection_type": "AWS Suspect Escalation Reconnaissance", "d_type_vname": "AWS Suspect Escalation Reconnaissance", "detection_href": "https://<REDACTED>.cc1.portal.vectra.ai/detections/128?detail_id=1098", "entity_id": 31, "entity_type": "account", "type": "account", "url": "https://<REDACTED>.cc1.portal.vectra.ai/accounts/31", "severity": 4, "event_timestamp": "2023-09-14T16:56:07Z", "detection_id": 128, "entity_uid": "AWS:<REDACTED>", "detail": {"event_name": "ListAttachedRolePolicies", "event_id": "7e905780-ed55-40b1-bb79-ae82e4287a47", "account_id": "<REDACTED>", "src_external_host": {"ip": "74.201.86.232", "name": null}, "assumed_role": "SecurityAuditExtended", "access_key_id": "<REDACTED>", "aws_region": "us-east-1", "request_parameters": "{\"roleName\":\"AWSServiceRoleForApplicationAutoScaling_ECSService\"}", "response_elements": null, "error_code": null, "error_message": null, "role_sequence": ["AWS:<REDACTED>", "SecurityAuditExtended"], "user_agent": "aws-sdk-go-v2/1.20.1 os/linux lang/go#1.20.7 md/GOOS#linux md/GOARCH#amd64 api/iam#1.22.2", "identity_type": "AWS External Account", "last_timestamp": "2023-09-14T16:33:22Z"}}

Logs and Common Error Messages

When using docker compose, it automatically maps a volume to access logs from the host (in same directory). They will be located in the logs folder and a new file will be created every day. This contains all the application logs and will be required to troubleshoot any issues that occurr. Some common errors are described below:

Connection Refused Error

Summary: When syslog server is not reachable then connector will give the error of connector refused.

Vectra API Down Error Message

Summary: If the credentials are incorrect or the vectra APIs are offline, the connector will display the Vectra API server is down error.

Validation Errors

Case 1: If the provided IP of the syslog server is invalid then it will give the IP validation error. Case 2: If provided cron expressions are invalid then it will give the cron expression validation error.

Too Many Requests Error

Summary: The connection will display the Too Many Requests warning if the Vectra API is too busy to authenticate. After 30 seconds, the connector will retry three times in the Too many Requests scenario.

No Such File or Directory

Summary: The connector will fail with the No such file or directory error if the server name and certificate name are different in TLS protocol.

Alternate Setup

Depending on your preferences and architecture, you could setup this connector without using docker compose. Vectra provides the source code to allow anyone to fork it and customize it the way they need. In addition to that, we provide the Dockerfile in the vectra-connector folder to either:

• Create the image locally without relying on Docker Hub

• Customize the image for your need.

Resources

• Github project: https://github.com/vectranetworks/siem-connector/tree/main