QRadar SIEM integration (QUX)

Install and configure the Vectra Detect app for QRadar (QUX), supporting both Vectra SaaS API polling and Brain syslog ingestion.

As stated in the summary, this article only applies to customers using Vectra's Quadrant UX or the Vectra SaaS offering that was available prior to the release of the Respond UX. If you are using the Respond UX please see the QRadar Integration Guide for Vectra XDR (Respond UX) . If you are unsure of which UX you are using, please see Vectra Analyst User Experiences (Respond vs Quadrant).

Introduction

The Vectra Detect App for QRadar has been updated from 1.1.0 to 2.x and now supports the Vectra SaaS API as a data source in addition to syslog output from non Vectra SaaS installations of the Vectra Platform. The 1.1.0 version of the app only supported syslog. This new app allows for a single pane of glass for analysts who use QRadar and have both Vectra SaaS and non SaaS implementations of Vectra Detect.

Video Demo of Deployment

A demo video that is meant as a companion to this article is available here:

It walks through requirements, deployment of required components, and configuration of Account Scoring and Account Detection data sources from Vectra SaaS and also configuration of a Brain-based deployment of Vectra Detect using syslog output to QRadar.

Requirements

• QRadar 7.4.2 FP3+

  • The app requires a minimum version as listed above. If your version is not at least this, please install an update from IBM to get to the minimum version level.

• QRadar Log Source Management App

  • If this is not already installed, information is available here to assist from IBM: Installing the QRadar Log Source Management App.

• The Universal Cloud REST API Protocol from QRadar should be installed BEFORE installing the Vectra Detect QRadar app if you will be using a Vectra SaaS Data source.

  • This is available from IBM Fix Central here: Universal Cloud REST API Protocol.

  • If you do not install this protocol before the Vectra QRadar app, the protocol will not be available as a choice in the app and you will need to uninstall the app, install the protocol, and reinstall the app for the protocol to show up.

• Vectra QRadar App

  • Available here from IBM X-Force Exchange here: Vectra Detect App for QRadar - QRadar v7.4.2 FP3+

• For Vectra SaaS data sources

  • Hostname of your Vectra SaaS tenant.

    • This should be just the hostname without http, https, or trailing / from the URL of your tenant.

  • An API client will need to be created in your Vectra SaaS tenant for the QRadar app to use.

  • Workflow definition and parameter files for use when configuring the Universal Cloud REST API Protocol.

    • These files are available here from Github: Vectra Detect.

• For non-SaaS deployments of the Vectra Platform (Brain-based installations of Vectra Detect)

  • Serial number of your Brain to use as a log source identifier.

Installation Process

This is the overall process to follow for the installation. Links for required apps/packages are in the requirements section and details for the steps are included in below sections in this article.

1. Ensure you are updated to at least QRadar 7.4.2 FP3. Updating to this version is not covered in this guide. If you need assistance updating your QRadar installation, please work with your partner or IBM.

2. Ensure the QRadar Log Source Management App is installed. Link is in Requirements section above. Installation of this app is not covered in this guide but instructions are available from IBM at the referenced link.

3. If you will be using a Vectra SaaS log source, ensure the Universal Cloud REST API Protocol from IBM is installed. Full instructions are below or available at the link in the Requirements section above.

   1. Deploy the configuration in QRadar.

4. Install or upgrade the Vectra Detect QRadar App. The process is detailed below and the link for the package is available in the Requirements section above.

   1. Deploy the configuration in QRadar.

5. For Vectra SaaS data sources:

   1. Copy your hostname for you Vectra SaaS tenant for later use.

   2. Create an API client in your Vectra SaaS UI for later use.

   3. Download workflow files from Github for later use. Link is in the Requirements section above.

   4. Configure 2 Log Sources for QRadar

      1. Vectra Account Scoring

      2. Vectra Account Detections

   5. Deploy the configuration in QRadar.

6. For non-SaaS deployments of the Vectra Platform (Brain-based installations of Vectra Detect)

   1. Copy the serial number of your Brain for later use as a log source identifier.

   2. Configure syslog output from your Vectra Brain to QRadar.

   3. Configure the Vectra syslog log source in QRadar.

   4. Deploy the configuration in QRadar.

Installation of Universal Cloud REST API Protocol

• If you have not previously installed the Universal Cloud REST API Protocol from IBM, it must be installed prior to installing the Vectra Detect App for QRadar.

  • This protocol is required when configuring a Vectra SaaS log source.

• To check for the Universal Cloud REST API Protocol follow these steps:

  • Navigate to Admin > Apps > Log Source Management.

  • Select "Log Sources".

  • Click "+ New Log Source".

  • Select "Single Log Source".

  • Search for "Universal DSM", select it and then click "Step 2: Select Protocol Type".

  • Search for "Universal Cloud REST API" and if not in the protocol list, it must be installed with the below instructions.

  • Close the window.

• Download the RPM package file of the "Universal Cloud REST API" protocol from here f you have not already downloaded it from the link in the requirement section above.

• Log into your QRadar command line via SSH as the root user.

• Copy the downloaded package to a temp folder in your QRadar appliance and then navigate to that folder in your SSH session.

• Type the following command to install the RPM:

rpm -i <downloaded_package_name.rpm>

• Deploy full configuration through the QRadar UI after the installation has succeeded.

• To validate the installation of the protocol, perform the steps above where it was instructed how to check for the presence of the Universal Cloud REST Protocol.

Installation of the Vectra Detect App for QRadar

Upgrades From Prior Versions of the Vectra Detect App

• Users will be able to upgrade from v1.1.0 to v2.x only if the older app is install on QRadar v 7.4.2 FP3+ (app framework v2)

• The same installation steps below should be followed for upgrades or new installations

Installation

• Login to your QRadar console.

• Go to Admin > Extension Management.

• Click on "Add" to add a new extension

• QRadar will prompt with a list of changes being made by the app.

• Click on "Install".

• QRadar will then show a window that the app has been install successfully along with lists of different components of the app.

• To validate that the installation was successful, navigate to Extensions Management again and see the "Installed" status against "Vectra Detect App for QRadar - QRadar v7.4.2 FP3+"

For Vectra SaaS Data Sources Follow These Steps

Copy Hostname of your Vectra SaaS Tenant

The hostname of your Vectra SaaS tenant will be needed later when you modify the workflow parameters file that will be uploaded to QRadar. This hostname needs to be just the hostname and not the URL. Do NOT include http, https, or a trailing /. It should appear similar this (obfuscated for security) screenshot below in your browser bar. Keep in mind that when copying from your browser bar, you may end up with a URL that needs to be edited.

API Client Creation in Vectra SaaS

To create an API client, log in to your Vectra SaaS tenant with “Super Admin” role. If you are do not have super admin privileges for your tenant, please work with a member of your team who does in order to create the API client. Documentation of Vectra SaaS API - https://support.vectra.ai/s/article/KB-VS-1571

• Go to Manage > API Clients and click "Add API Client".

• Give your API Client a name (up to 256 characters).

• The "Description" field is optional (up to 2048 characters).

• Select a role for the client. It must be one of the following:

  • Read-Only

  • Restricted Admin

  • Security Analyst

  • Settings Admin

• After adding all the above information click on "Generate Credentials" to obtain your client credentials.

• From the API client created dialog, copy the Client ID and Secret Key to a local file or secret manager for later use.

  • Note: The Secret Key is only shown once. If you loose the credentials, a new client will need to be created to get a new Secret Key.

• Click Done.

Additional information regarding the Vectra SaaS API is available in the following Vectra Support articles:

• Vectra SaaS API Quickstart Tutorial

• Vectra SaaS API Guide

Download / Modify Workflow Definition and Parameter Files

• Download the 3 highlighted files below from the IBM Github site for the Vectra Detect App :

• The AccountDetection and AccountScoring workflow files should be left unmodified and are used to define how the Universal Cloud REST API will communicate with the Vectra SaaS API. These files will reference values that are defined in the Workflow-Parameter file which will need to be modified for your Vectra SaaS tenant.

• Using the text editor of your choice, modify the "VectraDetect-Workflow-Parameter-Values.xml" file to add your Vectra SaaS tenant hostname, Client ID, Secret Key, and true/false value for historical data.

  • Special note regarding the "historical" flag:

    • This flag will be considered only in the first run of the workflow, so that you can configure whether to pull all the historical data in the first pull. If set true it will pull all the historical data.

Example of blank parameter file:

<?xml version="1.0" ?>
<WorkflowParameterValues xmlns="http://qradar.ibm.com/UniversalCloudRESTAPI/WorkflowParameterValues/V2">

    <!-- Do not add http or https in the below value of Vectra SaaS Hostname-->
    <Value name="vectraSaaSHostName" value=""/>
    <Value name="clientId" value=""/>
    <Value name="secretKey" value=""/>
    <Value name="historical" value="false"/>
</WorkflowParameterValues>

Example of modified parameter file:

<?xml version="1.0" ?>
<WorkflowParameterValues xmlns="http://qradar.ibm.com/UniversalCloudRESTAPI/WorkflowParameterValues/V2">

    <!-- Do not add http or https in the below value of Vectra SaaS Hostname-->
    <Value name="vectraSaaSHostName" value="109numbers71.uw2.portal.vectra.ai"/>
    <Value name="clientId" value="092a140bobfuscatedbda10a212f60c8"/>
    <Value name="secretKey" value="Ukk3NzobfuscatedobfuscatedobfuscatedobfuscatedBYSkw1T1BOTExXQUwhMCwzRWsxaV5tNz9JVWU"/>
    <Value name="historical" value="true"/>
</WorkflowParameterValues>

Configure Vectra SaaS Log Source in QRadar

• Navigate to Admin > Apps > Log Source Management.

• Select "Log Sources", click "+ New Log Source", and then click "Single Log Source":

• On the "Select a Log Source Type" screen, search for "Vectra Detect", select it and click "Step 2: Select Protocol Type":

• Search for "Universal Cloud REST API", select it, and click "Step 3: Configure Log Source Parameters:

• On the "Configure Log Source Parameters screen you must fill in the following 3 items. Other selections on this screen are optional.

  • Name - Choose a name for the log source such as "Vectra_Account_Scoring_<your tenant ID>" or "Vectra_Detection <your tenant ID>" depending on which log source you are adding.

    • You will be repeating this process to add both Account Scoring and Account Detection log sources for Vectra SaaS.

  • Extension - Choose the "VectraDetectCustom_ext" for post processing of events after parsing.

  • Coalescing Events - Make sure to uncheck this to avoid grouping the events on the basis of Source and Destination IP.

• On the "Configure Protocol Parameters page some values are mandatory and others are optional. Selections not discussed below are optional.

  • Log Source Identifier - Choose a name for the log source identifier such as "Vectra_Account_Scoring_<your tenant ID>" or "Vectra_Detection <your tenant ID>" depending on which log source you are adding.

    • Keep in mind that the log source identifier must be unique within the same protocol (both of these are using the Universal REST API protocol so they must be unique).

  • Workflow - Here you will paste in the contents of your unmodified "VectraDetect-AccountScoring-Workflow.xml" or "VectraDetect-AccountDetection-Workflow.xml" file depending on which log source you are configuring.

  • Workflow Parameter Values - Here you will paste in the contents of your modified "VectraDetect-Workflow-Parameter-Values.xml" file.

  • Use Proxy - If a proxy is required in your environment to reach Vectra SaaS, check this box and enter your proxy information.

  • Recurrence - This value controls how often the workflow runs to retrieve data from Vectra SaaS. This can also be modified after the configuration has been saved. The default of 10 min should be sufficient for most customers but this can be modified as required.

• Click "Step 5: Test Protocol Parameters" to test these parameters.

• When you see success in the test, click "Finish" and close the Log Source Management app.

• Make sure that you deploy your changes in QRadar after adding the log source.

• Repeat these steps to add the other log source depending on which one you added first. When done you should have two log sources configured for Vectra SaaS:

For non-SaaS Deployments of the Vectra Platform, Follow These Steps

Find and Copy the Log Source Identifier

• In your Vectra Brain UI, navigate to *Settings > General * and copy your serial number for later use as the Log Source Identifier for your QRadar syslog configuration.

Configure Syslog Output from your Vectra Brain

• In your Vectra Brain UI, navigate to Settings > Notifications > Syslog and click on the pencil icon or "Edit" link to edit your Syslog settings.

• Add the IP and Port of your QRadar server/listener.

• Choose TCP and JSON for the Protocol and Format.

• Include all the Log Types.

• The other options can be selected as needed:

  • Include filtered - you can choose if you'd like to include detections that have been triaged by AI or any other rules that you've create, with this option.

  • Include detections in info - some customers may choose to not forward info category detections with this option

  • Include host/account score decreases - this option determines whether or not Vectra will forward host and account scoring decreases

• Finally, the enhanced detail checkbox should be checked.

  • The ability to turn off enhanced detail is primarily meant for use by customers who are working with a downstream tool that isn't configured to handle the additional detail these logs provide.

• Once you've completed your configuration, save it and open your QRadar console.

• In the above example, we are using port 5141 but it should be noted that the default port for the QRadar syslog listener is 514. Modify this port as required for your environment.

Configure the Vectra Detect Syslog Log Source in QRadar

• Navigate in your QRadar console to Admin > Apps > Log Source Management.

• Select "Log Sources", click "+ New Log Source", and then click "Single Log Source":

• On the "Select a Log Source Type" screen, search for "Vectra Detect", select it and click "Step 2: Select Protocol Type":

• Choose "Syslog" for the protocol and click "Step 3: Configure Log Source Parameters".

• On the "Configure the Log Source parameters" page some values are mandatory and others are optional. Selections not discussed below are optional.

  • Name - Choose a name for the log source such as "Vectra Brain".

  • Extension - Choose the "VectraDetectCustom_ext" for post processing of events after parsing.

  • Coalescing Events - Make sure to uncheck this to avoid grouping the events on the basis of Source and Destination IP.

• Select "Step 4: Configure Protocol Parameters".

• On the "Configure the Protocol parameters" screen, for the log source identifier, paste in the serial number of your Vectra Brain appliance that you copied earlier.

• Click "Finish" and then deploy your changes.

• Once that is done, you have completed the Non SaaS Vectra Detect QRadar integration.

Supplemental Information

QRadar Deployment Guidance

The above instructions assume that users are familiar with doing deployments of configuration changes in QRadar. If you are unfamiliar with that process, here are the steps:

• Navigate to the "Admin" panel.

• Clcik on "Deploy Changes".

  • We recommend users "Deploy Full Configuration" by clicking on the "Advanced" dropdown.

Uninstalling the Application

To uninstall the application, the user needs to perform the following steps:

1. Navigate to the "Admin" panel.

2. Open "Extension Management".

3. Select the "Vectra Detect App for QRadar - QRadar v7.4.2 FP3+" application.

4. Click on Uninstall.

Steps to Check Application Logs

User can check the logs for data collection by running the following command in the root after logging in via ssh.

tail -f /var/log/qradar.log /var/log/qradar.error | grep Vectra_Detect_App_for_QRadar

Users can go inside the application docker container to check logs for the dashboard. In docker, the container user can see logs.

• Run the below at the command line

  • /opt/qradar/support/recon ps

• The above command will list all the applications installed in QRadar, then find the app with the name “Vectra Detect App For QRadar” and copy the App-ID of that.

• Now run the below command using the App-ID that you copied from the above step:

  • /opt/qradar/support/recon connect App-ID

• Now the user is in the docker container.

  • cd /opt/app-root/store/log

    • This navigates to the log directory.

  • ls

    • Lists log files you may want to examine.

    • app.log contains logs of the Dashboard

Visualizations

All the dashboards consist of individual panels which plot specific metrics related to the events received from Vectra Detect. The data in all dashboards are populated from two log source types: Vectra Detect and Vectra SaaS. All the dashboards allow the user to filter events by time.

Overview Dashboard

This dashboard is built to provide overall visibility into Host Scoring and Detection events received from Vectra Detect. It consists of Critical, High, Medium, and Low single value panels (populated with Last 30 Days time range irrespective of Time Range filter), two table panels are Worst Offenders and Key Assets, and two bar chart panels are Top 10 Detections by Type and Top 10 Detections by Category.

On clicking any of the single value panels (Critical, High, Medium, and Low), the user is redirected to the Entities dashboard. On clicking any row of the table panel (Worst Offenders and Key Assets), the user will be redirected to the Detections dashboard. On clicking any bar of bar chart panels (Top 10 Detections by Type and Top 10 Detections Category), the user will be redirected to the Detections dashboard.

Entities Dashboard

This dashboard consists of a scatter chart named Entity Severity Quadrant, which is plotted according to the Threat and Certainty for unique Entities. It also consists of a table panel Entities list that shows the top 1000 logs for unique Entities, Accounts list, Accounts Currently Locked (30 days history) and Accounts locked during the selected time range. The table panel Accounts Currently Locked (30 days history) independent of the Time Range filter and shows events of the last 30 days.

Filters for this dashboard are Time Range, Entity Type, Search Filter, and Severity (which is specific to table panel).

Detections Dashboard

This dashboard consists of an area chart named Detection Type Activity over Time. It also consists of a table panel Detections list.

Filters for this dashboard are Time Range, Detection Categories, Behavior, Type, and Search Filter. The Detection Categories filter is dynamically populated based on Time Range.

The behavior dropdown is populated based on the option selected in the Detection of Categories dropdown and Time Range.

Campaigns Dashboard

This dashboard consists of a bar chart named Top 10 Campaign Activity. It also consists of a table panel Last Campaign events.

Filters for this dashboard are Time Range, Campaign Name, and Type. Campaign Name and Type are dynamically populated based on the Time Range.

Health Dashboard

This dashboard consists of a table panel Last Health logs. Filters for this dashboard are Time Range, Result, and Search filter.

Audit Dashboard

This dashboard consists of a table panel Last Audit logs. Filters for this dashboard are Time Range, Result, User, and Search filter.

Notes for all Dashboards

• “Search Filter” is a case-sensitive filter in all the dashboards.

  • It will search the entered value in the raw payload.

• There is a limit of 1000 records in all the table panels and an information icon ( ) is provided for the same with the “Results are limited to 1000 entries.” message (except for Worst Offenders and Key Assets table panels whose limit is 10 records and message is “Results are limited to 10 entries.”) which is displayed when hovered over the icon.

Saved Searches

The Vectra Detect App for QRadar also provides a number of saved searches that can be executed. To run a saved search, follow these steps:

• Go to the "Log Activity" tab in QRadar.

• Click on the Search dropdown and select "New Search".

• Click on the "Group" dropdown and select "Vectra Detect".

• Select a search from the list of Available Saved Searches and click on Load. To run the search in the Log Activity tab, click on the Search button situated at the bottom right corner.

• The following saved searches are provided in the app and have a default Time Range of the last 30 days.

Worst Offenders	Worst Offenders - 7.4.3+
Key Assets	Key Assets - 7.4.3+
Hosts list	Hosts list - 7.4.3+
Accounts list	Accounts list - 7.4.3+
Accounts Currently Locked (30 days history)	Accounts Currently Locked (30 days history) - 7.4.3+
Accounts locked during the selected time range	Accounts locked during the selected time range - 7.4.3+
Detections list	Detections list - 7.4.3+
Last Campaign events	Last Campaign events - 7.4.3+
Last Health logs	Last Health logs - 7.4.3+
Last Audit logs	Last Audit logs - 7.4.3+

• The saved searched ending with “-7.4.3+” should be used when using a QRadar instance with version high than 7.4.3.

Troubleshooting

This section describes the common issues that might happen during the deployment or the running of the app and the steps to resolve the issues.

Case #1 - Vectra events are shown up as “Vectra Detect Message”

Problem:

Vectra Detect events will show up as Vectra Detect Message rather than getting identified as the right QRadar category. This will be seen in the “Log Activity” tab in QRadar when a user might be searching for an event of Vectra Detect log source type.

Troubleshooting Steps:

This issue is caused when the required field is not present in the raw event or the event payload size is more than 4096 bytes which leads to the breaking of the event payload. If the payload is getting truncated, users can increase the maximum payload size. 4096 is the default size configured in the QRadar platform. Follow the below steps to increase max payload size in QRadar:

• Navigate to System settings by going to the Admin panel.

• Click on the button under Switch To → Advanced.

• There are two options: Max TCP Syslog Payload Length and Max UDP Syslog Payload Length. Below is a screenshot for quick reference:

• Increase the value of these fields according to need (Recommended: 32000).

• Click on Deploy Changes.

Case #2 - UI related issues in the app

Problem:

Any dashboard panel shows errors or unintended behavior.

Troubleshooting Steps:

• Clear the browser cache and reload the webpage.

• Try reducing the time range of the filter and retry. It has been seen that QRadar queries expire if too much data is being matched in the query.

• If the issue is not resolved, please contact support by following the troubleshooting steps given in the last Case.

Case #3 - Dashboard is not populating after upgrading the app

Problem:

Vectra app dashboard is not populating even though data is present in the log activity after upgrading the app from 1.1.0 to 2.0.0

Troubleshooting Steps:

• Go to Admin Panel.

• Click on Advance > Deploy Full Configuration.

Case #4 - Data is not getting ingested after configuring log source

Problem:

Log Source is properly configured and deployed but still data is not getting ingested in the log activity.

Troubleshooting Steps:

• Go to the Log Source management App.

• Open the Log Source that you created.

• If the status of the log source is showing an error with a message related to Name or service not known then it means the user has entered either the hostname with https:// or the hostname is not correct, enter the correct hostname in the workflow parameter.

Case #5 - Getting error of protocol type not found while creating/updating log source

Problem:

The user might be trying to configure the Universal protocol without properly installing the universal protocol.

Troubleshooting Steps:

• When a user clicks on start test, an error pop-up comes with the message Protocol type 92 was not found.

• It means that either the protocol is not installed correctly or it is not present.

• Try uninstalling the existing protocol and install the new protocol with the earlier instructions from this document.

Case #6 - All other issues which are not part of the document

Problem:

If the problem is not listed in the document, please follow the below steps.

Troubleshooting Steps:

• Click on System and License Management in the Admin Panel.

• Select the host on which Vectra Detect App For QRadar is installed.

• Click on Actions in the top panel and select the option to Collect Log Files.

• A pop-up named Log File Collection will open.

• Click on Advanced Options.

• Select the checkbox to Include Debug Logs, Application Extension Logs, and Setup Logs(Current Version).

• Click on Collect Log Files Button after selecting 2 days as data input.

• Click on "Click here to download files".

• This will download all the log files in a single zip on your local machine.

• Please contact support and attach this log file.