Palo Alto XSOAR-XSIAM Integration (RUX)
Deploy the Palo Alto Cortex XSOAR/XSIAM integration for RUX, including incident mirroring, lifecycle sync, commands, and operational guidance.
Events Detection Integration for Cortex XSOAR
Integration Guide
API v3.5 | Pack Version 1.0.0 | May 2026
Quick Start
The Vectra RUX Events Detection integration creates one Cortex XSOAR incident per Vectra detection, providing detection-level visibility while preserving the full context of the affected entity.
Deployment Checklist
Create a Vectra API Client with the Security Analyst role.
Install the Vectra RUX Events Detection content pack from the Marketplace.
Add a new integration instance in Cortex XSOAR.
Configure the Server URL, Client ID, and Client Secret Key.
Enable Fetch Incidents.
Configure mirroring as required.
Click Test and verify an
okresponse.Save the integration instance.
Result
Each qualifying Vectra detection creates a dedicated XSOAR incident:
This model enables independent investigation, assignment, status tracking, ticket linkage, and lifecycle management for every detection.
Overview & Methodology
Background
This guide covers the Vectra RUX Events Detection integration for Cortex XSOAR — a detection-centric approach that unlocks richer, more targeted automation compared to previous-generation integrations.
By structuring response workflows around individual detections rather than entities, analysts gain the ability to investigate and automate response actions against specific threat behaviors while retaining the full entity context that makes Vectra's attack signal intelligence valuable.
Detection-level incidents enable:
Precise playbook targeting
Independent lifecycle management
Detection-level ticket linkage
Fine-grained status tracking
Better operational metrics
More flexible automation workflows
Organizations migrating from entity-centric workflows typically find that many automation use cases become significantly easier to implement and maintain.
Architecture Overview
The integration consumes detection events from the Vectra Events API and creates one XSOAR incident per detection. Mirroring keeps data synchronized between XSOAR and Vectra throughout the detection lifecycle.
The Entity-Centric Model (Previous Approach)
The previous Vectra integration created a single XSOAR incident per entity — a host or account — consolidating all detections associated with that entity into one record.
While this aligned closely with the Vectra platform's AI prioritization model, it introduced several operational challenges:
A single incident could contain a large and growing collection of detections.
Detections of different types and severities were grouped together.
High-priority behaviors could become buried within lower-priority activity.
Closing or updating the incident affected all associated detections.
The incident lifecycle was tied to entity state rather than individual detection outcomes.
Note
The previous entity-centric integration (Vectra XDR) remains available in the Cortex XSOAR Marketplace and is currently in sustaining mode. It continues to receive maintenance updates and bug fixes but is no longer the primary focus for new feature development.
The Detection-Centric Hybrid Model (This Release)
This release (Vectra RUX) adopts a detection-centric model in which every Vectra detection generates its own XSOAR incident.
The objective is to provide detection-level visibility and control while preserving the broader entity context needed for effective investigations.
One Incident Per Detection
Every Vectra detection maps to exactly one XSOAR incident.
Each incident is scoped to a single observed threat behavior, allowing analysts and playbooks to operate on detections independently.
Entity Context Is Preserved
Every incident includes context about the source entity, including:
Entity ID
Entity Name
Entity Type
Importance
Urgency Score
Priority Status
Assignment Information
Analysts never lose visibility into the affected asset.
Event-Driven Updates
Detections generate multiple events over their lifecycle.
The integration continuously updates incidents using the latest event data so that detection state, metadata, tags, and investigation status remain current.
Cross-Detection Correlation
Incidents can be linked through:
Shared Entity ID
Shared External Reference ID
This enables rapid navigation between related detections and investigations.
XSIAM Compatibility
The detection-centric model aligns naturally with XSIAM correlation workflows.
Multiple detections from Vectra and other security technologies can be correlated into a single XSIAM case while preserving the integrity of the original detection records.
Tip
Although more individual incidents are created under this model, investigations become significantly easier to manage. The previous entity-centric approach often resulted in a single incident containing many unrelated threat behaviors. The detection-centric approach allows each threat behavior to be tracked independently while preserving entity context.
Why "Hybrid"?
The model is described as hybrid because it combines detection-level granularity with entity-level context. Analysts gain the precision to investigate individual detections while retaining visibility into the overall risk posture of the affected entity.
The Vectra Events API and change_type
change_typeAll incidents originate from the Vectra Events Detection API endpoint:
The endpoint produces a continuous stream of events that describe state changes for individual detections.
Every event includes a change_type value.
change_type = new
newA new detection has been created.
All detection fields are populated for the first time.
change_type = append
appendA new observation has been added to an existing detection.
Summary fields are updated with cumulative activity while event details reflect the new observation.
change_type = adjust
adjustA non-observation change has occurred.
Examples include:
Urgency score changes
Priority changes
Tag modifications
Group updates
change_type = investigation_status
investigation_statusThe investigation status has changed.
Examples include:
Open
Acknowledged
Escalated
Paused
Closed
Expired
change_type = state
stateThe detection has been closed or reopened.
This event ensures detection state remains synchronized between Vectra and XSOAR.
change_type = triage
triageThe triage state of the detection has changed.
Triage-related fields and investigation metadata are updated.
Event Merging Logic
During each mirror cycle, the integration performs two API lookups:
Latest activity event (
neworappend)Latest state event (
adjust,state, triage, orinvestigation_status)
When both events are present:
The most recent event takes precedence for overlapping fields.
String collections such as tags are merged and de-duplicated.
A single consolidated view is written into the incident.
When only one event exists, that event alone is used.
The resulting data is applied through the Incoming Mapper, and the incident's change_type field reflects the most recent processed event.
Incident Creation and the Fetch Cycle
The fetch-incidents process continuously polls the Events Detection API.
Each unique detection_id creates a new XSOAR incident if that detection has not previously been fetched.
Organizations can control which detections generate incidents:
All Detections
Leave both filtering options disabled.
All qualifying detections are imported.
Prioritized Detections Only
Enable:
Create Incidents for Prioritized Detections
Only detections associated with prioritized entities are imported.
Escalated Detections Only
Enable:
Create Incidents for Escalated Detections
Only detections whose investigation status is set to Escalated are imported.
Prioritized OR Escalated
Enable both options.
Incidents are created whenever either condition is true.
Warning
The Prioritized and Escalated filters operate as OR logic, not AND logic.
If both options are enabled, detections matching either condition are imported.
Incident Naming Convention
Incidents are created using the following format:
This naming convention provides immediate visibility into the detection category, behavior type, and affected asset.
Implementation
This section covers the initial configuration of the integration instance. It assumes the Vectra RUX content pack has already been installed in Cortex XSOAR.
Prerequisites
Before configuring the integration, ensure the following requirements are met:
Cortex XSOAR 6.10 or later.
A reachable Vectra platform accessible via HTTPS.
A Vectra API Client configured with the Security Analyst role.
The API Client's Client ID and Client Secret Key.
Network connectivity from the XSOAR server to the Vectra platform.
Firewall rules permitting outbound HTTPS connections.
Creating an API Client
API credentials are created within the Vectra platform:
Create a new API Client and assign the Security Analyst role.
Record the generated:
Client ID
Client Secret Key
These values will be required during integration configuration.
Creating the Integration Instance
Navigate to:
Search for Vectra RUX - Network Detection & Response (Partner Contribution) and click Add Instance.
The integration settings are grouped below by function, not by the order presented in the user interface.
Recommended Configuration
Most deployments should begin with the following settings:
Fetch Incidents
Enabled
Max Fetch
50
Entity Types
Host and Account
Mirroring Direction
Incoming and Outgoing
Open Detection on Incident Reopen
Enabled
Close Detection on Incident Closure
Enabled
Detection Status for Incident Reopen
Escalated
Detection Close Reason for Incident Closure
Remediated
These values provide full bidirectional synchronization while limiting fetch volume to a manageable level.
Connection Settings
These settings control authentication and connectivity to the Vectra platform.
Server URL
Yes
Base URL of the Vectra platform (for example: https://tenant.portal.vectra.ai). Do not include a trailing slash.
Client ID
Yes
OAuth2 Client ID associated with a Security Analyst API Client.
Client Secret Key
Yes
OAuth2 Client Secret Key associated with the Client ID.
Trust Any Certificate
No
Disables SSL certificate validation. Recommended only for lab or troubleshooting purposes.
Use System Proxy Settings
No
Routes API requests through the XSOAR system proxy if configured.
Fetch Settings
These settings control incident creation behavior.
Fetch Incidents
Enables incident creation from Vectra detection events.
Max Fetch
Maximum number of events retrieved per fetch cycle. Valid range: 1–200.
First Fetch Time
Determines how far back to look during the initial fetch. Accepts relative values such as 1 hour or 2 days.
Entity Types
Controls which entity types generate incidents. Host, Account, or both.
Create Incidents for Prioritized Detections
Restricts incident creation to detections associated with prioritized entities.
Create Incidents for Escalated Detections
Restricts incident creation to detections whose investigation status is Escalated.
Warning
If both Create Incidents for Prioritized Detections and Create Incidents for Escalated Detections are enabled, the filters operate as OR logic, not AND logic.
Incidents will be created for detections that are:
Prioritized
Escalated
Both Prioritized and Escalated
Mirroring Settings
These settings control synchronization between Cortex XSOAR and Vectra.
Mirroring Direction
Controls whether changes flow from Vectra to XSOAR, XSOAR to Vectra, or both directions.
Mirror Tag for Notes
War Room entries containing this tag are synchronized back to Vectra as detection notes. Default: note.
Incoming Mirroring
Use Incoming Mirroring when Vectra is the authoritative source of truth.
Changes made in Vectra are synchronized into XSOAR, including:
Detection metadata
Investigation status
Tags
Entity context
Detection notes
Event summaries
Changes made in XSOAR are not written back to Vectra.
Outgoing Mirroring
Use Outgoing Mirroring when XSOAR is responsible for driving detection workflow actions.
Changes made in XSOAR are synchronized into Vectra, including:
Investigation status updates
Tag updates
Detection notes
External reference IDs
Detection closure
Detection reopening
Changes made in Vectra are not automatically reflected in XSOAR.
Incoming and Outgoing Mirroring (Recommended)
This mode enables full bidirectional synchronization.
Changes are synchronized in both directions and is the recommended production configuration.
Note
Mirroring settings only apply to incidents created after the integration configuration is saved.
Existing incidents are not automatically enrolled in mirroring.
Incident Lifecycle Settings
These settings control how incident state changes affect Vectra detections.
Open Detection on Incident Reopen
Automatically reopens the Vectra detection when the XSOAR incident is reopened.
Detection Status for Incident Reopen
Investigation status assigned to reopened detections. Options: Open or Escalated.
Close Detection on Incident Closure
Automatically closes the Vectra detection when the XSOAR incident is closed.
Detection Close Reason for Incident Closure
Close reason sent to Vectra. Options: Benign or Remediated.
Reopening Incidents
When an XSOAR incident is reopened and outbound mirroring is enabled:
The corresponding Vectra detection is reopened.
The configured Investigation Status is applied.
Subsequent mirroring resumes normally.
Closing Incidents
When an XSOAR incident is closed and outbound mirroring is enabled:
The corresponding Vectra detection is closed.
The configured close reason is applied.
Closing notes are synchronized to Vectra.
The incident and detection lifecycle remain aligned.
Incident Configuration
These settings control how incidents are created and mapped.
Incident Type
Vectra RUX Events Detection
Classifier
Leave blank
Mapper (Incoming)
Vectra RUX - Incoming Mapper
Incident Type
All incidents generated by this integration should use:
Classifier
No classifier is required.
The integration assigns the incident type directly during incident creation.
Leave this field blank unless a custom deployment requires a specialized classifier.
Mapper (Incoming)
The integration ships with a built-in mapper:
This mapper is responsible for:
Initial incident population
Incoming mirroring
Field synchronization
Most deployments should use the default mapper without modification.
Custom Mappers
If field customization is required:
Duplicate the default mapper.
Modify the duplicate.
Reference the duplicate in the integration settings.
Custom mappers must preserve the following fields or mirroring will not function correctly:
dbotMirrorDirection
dbotMirrorId
dbotMirrorInstance
dbotMirrorTags
Testing the Connection
After completing the configuration:
Click Test.
Wait for the validation to complete.
A successful connection returns:
Common Test Failures
Invalid Credentials
Symptoms:
Authentication errors
HTTP 401 responses
Resolution:
Verify the Client ID.
Verify the Client Secret Key.
Confirm the API Client has the Security Analyst role.
Connectivity Issues
Symptoms:
Timeouts
Connection failures
Resolution:
Verify the Server URL.
Verify network connectivity.
Verify firewall rules.
SSL Certificate Errors
Symptoms:
Certificate validation failures
Resolution:
Verify the certificate chain on the Vectra platform.
Temporarily enable Trust Any Certificate to isolate SSL-related issues.
Do not leave this setting enabled in production environments.
Deployment Validation Checklist
Before enabling the integration in production, verify:
Test returns
ok.Fetch Incidents is enabled.
Correct Entity Types are selected.
Mirroring direction matches operational requirements.
Incident Type is set correctly.
Incoming Mapper is configured.
Max Fetch is appropriate for expected detection volume.
Detection closure and reopening settings match organizational workflow.
User Guide — Incident Layout
Each incident created by this integration uses the Vectra RUX Events Detection layout.
The layout is organized into two custom tabs:
Incident Info
Incident management, timeline information, linking, and closure details
Events Detection Info
Detection details, entity context, assignments, notes, and investigation data
In addition to these custom tabs, standard XSOAR tabs remain available:
War Room
Work Plan
Evidence Board
Related Incidents
Canvas
Incident Info Tab
The Incident Info tab provides a high-level summary of the incident alongside standard XSOAR management metadata.
Case Details Panel
The Case Details panel contains the primary incident metadata, including:
Incident name
Status
Severity
Owner
Tags
External references
Standard XSOAR incident fields
This panel serves as the primary incident management view.
Timeline Information Panel
The Timeline Information panel provides visibility into the incident lifecycle.
Created
Timestamp when the XSOAR incident was created
Occurred
Timestamp of the original detection event
Due Date
Configurable SLA due date
Last Updated
Timestamp of the most recent incident modification
Closed
Timestamp when the incident was closed
The panel also contains incident correlation buttons.
Link Incidents for this Entity
Searches XSOAR for open incidents that share the same Vectra Entity ID and links them together.
This allows analysts to quickly identify all active investigations involving the same host or account.
Link Incidents for this External Reference ID
Searches XSOAR for open incidents that share the same External Reference ID and links them together.
This is commonly used when multiple detections are associated with the same:
Jira issue
ServiceNow ticket
Vectra MDR ticket
External investigation
Note
These buttons link XSOAR incidents only. They do not represent all detections that may exist within the Vectra platform for the entity.
Closing Information Panel
The Closing Information panel records closure metadata.
Closed Time
Timestamp when the incident was closed
Close Reason
XSOAR closure category selected by the analyst
Close Notes
Analyst-provided closure notes
When outbound mirroring is enabled, closure notes are synchronized back to the Vectra detection.
Linked Incidents Panel
Displays all incidents currently linked to the incident.
Typical columns include:
XSOAR Incident ID
Name
Status
Severity
Detection ID
Entity Priority Status
Entity ID
Entity Type
This panel provides rapid navigation between related investigations.
Events Detection Info Tab
The Events Detection Info tab contains the primary Vectra detection and entity information.
Unless otherwise noted, all data displayed in this tab is refreshed during incoming mirror cycles.
Detection Information Panel
The Detection Information panel contains the primary detection metadata.
Key information includes:
Detection ID
Detection URL
Detection Type
Detection Category
MITRE ATT&CK mappings
Investigation Status
External Reference ID
Detection Tags
Triage State
Detection Close Reason
This panel is typically the starting point for investigation.
Entity Information Panel
The Entity Information panel provides context about the affected host or account.
Key information includes:
Entity ID
Entity Name
Entity Type
Entity URL
Entity Importance
Entity Urgency Score
Entity Priority Status
Entity UID
Entity Privilege Category
Entity IP Address
Entity urgency drives the XSOAR incident severity assigned during incident creation.
Important
Once an entity becomes prioritized in Vectra, all detections associated with that entity are treated as prioritized until the unresolved priority condition is cleared.
A reduction in urgency score alone does not automatically remove unresolved priority status.
Note
Entity External Reference ID support exists within Vectra but display within the XSOAR incident layout is planned for a future release.
Entity Assignment Data Panel
Displays assignment information associated with the entity in the Vectra platform.
The panel contains the Sync Entity Assignment button.
Assignment fields include:
Assigned To
Assigned By
Assigned Date
Assignment ID
Outcome
Resolved By
Resolved Date
Sync Entity Assignment
Retrieves the current assignment directly from the Vectra platform and populates the assignment fields displayed in the panel.
If no assignment exists, the assignment fields are cleared.
Note
Assignment information displayed in this panel reflects assignment within the Vectra platform only.
If analyst ownership is managed through the XSOAR Owner field, this panel may be ignored.
Note
Assignment data is not automatically refreshed during mirror cycles.
Use the Sync Entity Assignment button to retrieve the latest assignment information.
Event Summary Information Panel
The Event Summary Information panel displays cumulative activity associated with the detection.
Unlike observation-specific event fields, these values represent aggregate activity across the entire detection lifecycle.
Available information includes:
IP addresses
Domains
Ports
DNS values
Accounts
Hosts
External targets
Protocols
This panel is useful for understanding the overall scope of observed activity.
Detection Investigation Data Panel
The Detection Investigation Data panel contains information retrieved from the full detection record rather than the events stream.
The panel contains the Sync Detection Summary and EDR Process Context button.
Sync Detection Summary and EDR Process Context
Retrieves the full detection object from Vectra and updates:
Detection Summary
EDR Process Context information
This provides additional information not available through the Events API, including:
Grouped session information
Aggregated detection statistics
Additional investigation context
EDR telemetry
EDR Process Context Panel
When EDR integrations are available, Vectra may provide process-level telemetry associated with the detection.
The panel can display:
Query Status
Query Creation Time
Investigation Links
Query Links
Error Messages
Process Data
Process records typically include:
Process Name
Command Line
Creation Time
Account
Process ID
Parent Process ID
SHA256 Hash
MD5 Hash
Note
EDR Process Context data is only available when process telemetry exists for the detection.
Data Source Panel
Displays information about the sensor or integration that generated the detection.
Available fields include:
Data Source Type
Sensor Name
Sensor ID
This information can be useful when troubleshooting detection origin or validating data collection coverage.
Destination Information Panels
Several panels provide information about destination entities associated with the detection.
Destination Host Information
Displays destination hosts observed during detection activity.
Typical values include:
Host ID
Host Name
IP Address
Importance
Urgency Score
Privilege Category
Group Membership
Destination Account Information
Displays destination accounts associated with the detection.
Typical values include:
Account ID
Account Name
Importance
Urgency Score
Privilege Category
Group Membership
Destination Domain Information
Displays destination domains associated with the detection.
Typical values include:
Domain
DNS
External Target
These panels are populated directly from the event payload.
Detection Notes Panel
The Detection Notes panel provides visibility into notes associated with the detection.
The panel contains the Sync Detection Notes button.
Sync Detection Notes
Retrieves notes directly from the Vectra platform using the detection ID.
Any notes not previously retrieved are added to the XSOAR War Room.
The integration maintains an internal note cache to prevent duplicate note creation.
Notes originating from outbound mirroring are automatically excluded from retrieval to prevent note loops.
Note
Detection notes are ultimately surfaced in the XSOAR War Room rather than stored as visible incident fields.
Tip
Use the Sync Detection Notes button whenever collaborative investigation is occurring between XSOAR analysts and Vectra MDR operators to ensure the latest notes are visible.
Actions
This section documents all actions available in the integration, including both analyst-facing incident layout buttons and programmatic commands that can be executed from XSOAR playbooks or the War Room.
Action Types
The integration provides two categories of actions:
Incident Layout Buttons
Analyst-driven actions executed directly from the incident layout
Integration Commands
Commands available to playbooks, automations, and the War Room
Incident Layout Buttons
The following buttons appear within the incident layout and can be executed by analysts during an investigation.
Each button executes one or more API operations against either Cortex XSOAR or the Vectra platform.
Link Incidents for this Entity
Location
Automation
Searches XSOAR for all open incidents that:
Share the same Vectra Entity ID
Have a different Detection ID
Are not closed
Are not job-type incidents
Matching incidents are linked using the built-in XSOAR linkIncidents command.
This allows analysts to quickly identify all active investigations involving the same host or account.
Note
This operation links XSOAR incidents only.
It does not represent every detection currently associated with the entity inside the Vectra platform.
Link Incidents for this External Reference ID
Location
Automation
Searches XSOAR for all open incidents that:
Share the same External Reference ID
Have a different Detection ID
Matching incidents are linked together using linkIncidents.
Typical use cases include:
Jira issues
ServiceNow incidents
Vectra MDR tickets
Internal investigation identifiers
This button is useful when multiple detections belong to the same external investigation.
Sync Entity Assignment
Location
Automation
Executes:
using the current incident's:
Entity ID
Entity Type
The most recent assignment record is retrieved and mapped into the Entity Assignment fields displayed in the layout.
If no assignment exists, the fields are cleared.
Typical use cases include:
Verifying current ownership
Refreshing assignment information after reassignment
Validating assignment outcomes
Note
Assignment information is not automatically refreshed during mirror cycles.
Use this button whenever assignment accuracy is important.
Sync Detection Summary and EDR Process Context
Location
Automation
Executes:
using the current Detection ID.
The automation:
Retrieves the full detection object
Updates the Detection Summary
Populates EDR Process Context data when available
This provides richer investigation data than is available through the Events API alone.
Additional information may include:
Grouped session details
Aggregated detection statistics
Investigation metadata
EDR telemetry
Sync Detection Notes
Location
Automation
Executes:
using the current Detection ID.
Retrieved notes are compared against the internal note cache.
Previously unseen notes are added to the XSOAR War Room as Note entries.
Notes containing:
are automatically excluded to prevent note loops.
The internal note cache is updated after each execution.
Tip
This button is particularly useful when collaboration is occurring between XSOAR analysts and Vectra MDR operators.
Integration Commands
The integration exposes a comprehensive command set for use within:
Playbooks
Automations
Scripts
The War Room
All commands require a configured Vectra RUX Events Detection integration instance.
Detection Commands
Detection commands operate on individual detections and are the primary commands used in playbooks and investigations.
vectra-detection-list
Returns detections matching the specified filters.
vectra-detections-mark-asclosed
Closes one or more detections using the specified close reason.
vectra-detections-mark-asopen
Reopens one or more previously closed detections.
vectra-detection-describe
Retrieves the full detection record, including summary and EDR context where available.
vectra-detection-pcap-download
Downloads the PCAP associated with a detection and attaches it to the incident.
vectra-detection-investigation-status-update
Updates the investigation status of one or more detections.
vectra-detection-external-id-update
Updates the external reference ID associated with one or more detections.
vectra-detection-tag-list
Returns tags associated with a detection.
vectra-detection-tag-add
Adds one or more tags to a detection.
vectra-detection-tag-remove
Removes one or more tags from a detection.
vectra-detection-note-list
Returns notes associated with a detection.
vectra-detection-note-add
Adds a note to a detection.
vectra-detection-note-update
Updates an existing detection note.
vectra-detection-note-remove
Removes a detection note.
Entity Commands
Entity commands operate on hosts and accounts within the Vectra platform.
vectra-entity-list
Returns entities matching the specified filters.
vectra-entity-describe
Retrieves the full entity record.
vectra-entity-detection-list
Returns detections associated with an entity.
vectra-entity-external-id-update
Updates the external reference ID associated with an entity.
vectra-entity-unresolved-priority-reset
Clears unresolved priority status for eligible entities.
vectra-entity-note-add
Adds a note to an entity.
vectra-entity-note-update
Updates an existing entity note.
vectra-entity-note-remove
Removes an entity note.
vectra-entity-note-list
Returns notes associated with an entity.
vectra-entity-tag-add
Adds one or more tags to an entity.
vectra-entity-tag-remove
Removes one or more tags from an entity.
vectra-entity-tag-list
Returns tags associated with an entity.
vectra-entity-detections-mark-asclosed
Closes all active detections associated with an entity.
Assignment Commands
Assignment commands manage entity ownership and assignment workflows.
vectra-assignment-list
Returns assignment records matching the specified filters.
vectra-entity-assignment-add
Creates a new assignment for an entity.
vectra-entity-assignment-update
Reassigns an existing assignment to a different user.
Group Commands
Group commands manage entity membership within Vectra groups.
vectra-group-list
Returns groups defined in the Vectra platform.
vectra-group-assign
Assigns members to a group.
vectra-group-unassign
Removes members from a group.
User Commands
User commands provide access to Vectra user information.
vectra-user-list
Returns Vectra platform users and associated metadata.
Investigation Commands
Investigation commands provide access to the Vectra Investigation Query service.
vectra-investigation-query-send
Submits an investigation query and returns a request ID.
vectra-investigation-result-get
Retrieves the results of a previously submitted investigation query.
Note
All command required and available parameters are documented in Appendix A — Command Reference.
Most analysts will only need the descriptions in this section. The appendix provides the complete parameter reference for playbook developers and administrators.
Best Practices
This section provides operational guidance and recommended usage patterns for the Vectra RUX Events Detection integration.
While every organization operates differently, the practices described here have proven effective for maintaining a clean detection workflow and maximizing the value of the detection-centric incident model.
Analyst Actions vs Automation Actions
One of the strengths of the integration is that many detection attributes can be managed in two different ways:
Directly by an analyst through the incident layout.
Programmatically through integration commands and playbooks.
Both approaches ultimately update the same underlying Vectra detection object.
Investigation Status
Vectra RUX Investigation Status field
vectra-detection-investigation-status-update
External Reference ID
Vectra RUX External Reference ID field
vectra-detection-external-id-update
Detection Tags
Tags field
vectra-detection-tag-add / vectra-detection-tag-remove
Detection Notes
War Room note mirroring
vectra-detection-note-add / vectra-detection-note-update
Detection Closure
Standard XSOAR incident closure
vectra-detections-mark-asclosed
Detection Reopen
Standard XSOAR incident reopen
vectra-detections-mark-asopen
In general:
Analysts should use the incident layout during normal investigations.
Playbooks should use commands when actions need to be automated or applied in bulk.
Both methods participate in the same mirroring workflow and ultimately update the same Vectra detection.
Note
The incident layout is not merely a display of Vectra data. Several fields are intentionally editable and can be used as an alternative to executing integration commands.
Using External Reference IDs
External Reference IDs are one of the most powerful capabilities exposed by the integration.
They allow detections and entities to be associated with records in XSOAR or other external systems such as:
Jira
ServiceNow
Vectra MDR
Internal case management platforms
SIEM investigations
This creates a durable relationship between Vectra, Cortex XSOAR, and external workflow systems.
Detection External Reference ID
The Detection External Reference ID can be managed in either of the following ways:
Directly through the Vectra RUX External Reference ID field in the incident layout.
Programmatically using:
Both approaches update the same value stored on the detection within the Vectra platform.
Common use cases include:
Associating a detection with a Jira issue.
Associating a detection with a ServiceNow incident.
Associating a detection with a Vectra MDR ticket.
Grouping multiple Vectra detections or XSOAR incidents under a common investigation identifier.
When multiple detections share the same External Reference ID, analysts can use:
to quickly correlate them within XSOAR.
Entity External Reference ID
The Entity External Reference ID is managed using:
This allows hosts and accounts to be associated with external investigations independently of any individual detection.
Potential use cases include:
Associating a host with a long-running investigation.
Associating a VIP asset with a tracking ticket.
Reusing existing investigations when new detections are generated.
Note
Entity External Reference IDs are stored within Vectra today. Display of this value within the XSOAR incident layout is planned for a future release.
Recommendation
Establish a standardized naming convention before deploying at scale.
Examples:
SOC-12345
INC-2026-00421
JIRA-4211
Avoid free-form text values that may vary between analysts.
Investigation Status and Mirroring
The Vectra RUX Investigation Status field can be managed in either of the following ways:
Directly through the incident layout.
Programmatically using:
Both approaches update the same underlying Vectra detection and participate in the mirroring process.
Changes made in either Vectra or XSOAR are synchronized during the next mirror cycle.
Supported values include:
Open
Acknowledged
Escalated
Paused
Closed
Expired
Typical Investigation Workflows
The Vectra RUX Investigation Status field supports multiple workflow paths depending on how the organization chooses to manage detections.
Active Investigation Path
Use this path when the detection requires analyst review and response.
Open — Detection has been generated and awaits review.
Acknowledged — An analyst has reviewed the detection and accepted ownership.
Escalated — The detection requires active investigation or response.
Closed — The detection has been resolved and the investigation is complete.
Monitoring / Deferred Investigation Path
Use this path when the detection has been reviewed but does not currently justify active investigation or no response is provided by external teams.
Open — Detection has been generated and awaits review.
Acknowledged — An analyst has reviewed the detection.
Paused — The detection has been intentionally deferred, deprioritized or most commonly - there has been no response from external teams. No active investigation is currently planned.
Expired — The detection has aged out within the Vectra platform without further investigation activity.
Closed — The detection is formally closed through workflow automation or analyst action.
Note
Expiredis a Vectra detection state indicating that the detection is no longer actively being investigated. Some organizations choose to leave detections in the Expired state indefinitely, while others implement an automation that periodically identifies expired detections and closes the associated XSOAR incidents.
Recommendation
If your workflow uses the Paused → Expired path, consider creating a scheduled XSOAR job that periodically reviews expired detections and automatically closes the corresponding incidents. This helps maintain a clean incident queue while preserving a clear audit trail of analyst decisions.
Status updates are useful for:
Tracking analyst progress
Driving workflow automation
Coordinating with MDR teams
Maintaining investigation consistency
Important
Do not set Investigation Status to Closed if your intent is to formally close the incident.
Always use the standard XSOAR incident closure workflow.
This ensures:
The detection is properly closed in Vectra
The configured close reason is applied
Closing notes are synchronized
Audit history is preserved
Closing Incidents
When an incident is closed in XSOAR and outbound mirroring is enabled, the following sequence occurs:
The XSOAR incident is closed.
The corresponding Vectra detection is closed.
The configured close reason is applied.
Closing notes are synchronized back to Vectra.
Recommendation
Analysts should generally close detections using the standard XSOAR incident closure workflow rather than executing:
directly.
The incident closure workflow ensures close reasons, notes, and synchronization behavior remain consistent.
Choosing a Close Reason
Benign
Use when:
Activity is legitimate.
Activity represents a false positive.
No remediation was required.
Remediated
Use when:
Malicious activity was identified.
Corrective action was taken.
Risk has been eliminated.
Important
The integration-level setting:
defines the default close reason applied when incidents are closed.
If different close reasons are required for different workflows, use:
within playbooks where the close reason can be explicitly specified.
Note Mirroring
Detection notes can be synchronized in both directions.
Notes can be created:
Directly in Vectra.
Directly through integration commands.
Through the XSOAR War Room.
Commands available for note management include:
However, most analysts should use War Room notes and allow the mirroring framework to synchronize those notes automatically.
Inbound Synchronization
Notes created in Vectra are synchronized into the XSOAR War Room.
Two mechanisms exist:
Automatic
New notes are synchronized during incoming mirror cycles.
Manual
The analyst clicks:
to retrieve the latest notes immediately.
Outbound Synchronization
War Room entries tagged with the configured mirror tag are synchronized back to Vectra.
Default tag:
Notes synchronized from XSOAR receive the prefix:
to prevent synchronization loops.
Important Constraints
Notes larger than 1,000 characters are not synchronized.
Updates to existing XSOAR notes are not synchronized.
Updates to existing Vectra notes create new War Room entries.
Only newly created notes participate in synchronization.
Tag Management
Tags can be managed in either of the following ways:
Directly through the incident Tags field.
Programmatically using:
Both approaches ultimately update the same detection tag collection stored within Vectra.
Manual tag management is generally preferred during investigations.
Command-based tag management is most commonly used within automation and enrichment playbooks.
Best Practices
Establish a controlled tag vocabulary.
Avoid analyst-specific tags.
Avoid duplicate tags with slightly different spellings.
Document approved tag values.
User purpose-built fields such as investigation_status or external_reference_id instead of notes or tags.
Tag Synchronization Behavior
Changes made in either platform are synchronized.
When XSOAR performs an outbound synchronization:
The entire tag list is sent.
Existing tags are replaced.
Warning
Removing all tags from an XSOAR incident causes all tags on the corresponding Vectra detection to be removed during outbound synchronization.
Expire Inactive Detections
Vectra detections that are not attended to may go inactive over time if the bevahior is no longer presenting. A playbook has been created to periodically look for inactive detections that belong to open incidents to set the investigation status to expired. This can assist with accurate metric collection and also provides the SOC Analyst with a clear indicator of alerts that can be closed.
Create a scheduled recurring job to automatically run this playbook:
In Cortex XSOAR, navigate to Jobs (via the top menu or sidebar).
Click New Job.
Select Time triggered and enable Recurring. Set the schedule to Every 24 hours (or configure a specific daily time using a cron expression such as
0 0 * * *).Set the Name for the job (e.g.,
Expire Inactive Detections - Daily).Under Playbook, select Expire Inactive Detections - Vectra RUX.
Click Create new job to activate the job.
Fetch Volume and Performance
In high-volume environments, proper fetch tuning is important.
Recommended Starting Configuration
Max Fetch
50
Entity Types
Host and Account
Mirroring
Incoming and Outgoing
Scaling Considerations
As detection volume increases:
Increase Max Fetch gradually.
Monitor incident processing time.
Monitor XSOAR queue depth.
Monitor playbook execution times.
Reducing Incident Volume
Several options exist for limiting incident creation:
Prioritized Detections
Escalated Detections
Entity Type filtering
Tag-based pre-processing
Tip
Most organizations should begin with Max Fetch set to 50 and adjust based on observed workload rather than immediately increasing limits.
Tag-Based Incident Filtering
In addition to the Prioritized and Escalated filters, XSOAR pre-processing rules provide a flexible alternative for controlling which detections generate incidents.
This approach is particularly useful when the desired filter criterion is a tag applied in Vectra (legacy approach) rather than a prioritization or escalation state (recommended approach).
Implementation Pattern
Ingest all detections.
Apply a pre-processing rule.
Create incidents only when a designated tag exists.
Example tag:
Example Rule
Rule Name
Vectra RUX – Tag Filter
Condition
Incident Type = Vectra RUX Events Detection AND Tags contains xsoar-escalate
Action
Run Rule
Follow with a second rule:
Rule Name
Vectra RUX – Drop Untagged
Condition
Incident Type = Vectra RUX Events Detection
Action
Drop and Close
This approach allows Vectra-side tagging to determine whether an incident should exist within XSOAR.
Recommended Analyst Workflow
Every SOC operates differently, but the workflow below provides a strong starting point.
1. Take Ownership
Assign the incident to an analyst using the XSOAR Owner field.
If desired, synchronize the Vectra assignment using:
2. Acknowledge the Detection
Update the Investigation Status to:
This signals active review.
3. Identify Related Activity
Use:
to locate additional detections affecting the same entity.
If operating under a common ticket:
4. Review Detection Context
Review:
Detection Information
Entity Information
Event Summary Information
Understand:
Threat behavior
Entity risk
Network indicators
MITRE ATT&CK mappings
5. Retrieve Additional Context
Execute:
to retrieve the full detection record.
6. Pivot into Vectra
Use:
Detection URL
Entity URL
to investigate directly within the Vectra platform.
7. Synchronize Notes
Use:
to retrieve the latest collaboration notes.
Document findings in the War Room.
8. Run Investigation Queries
Advanced investigations can use:
and
to retrieve additional network telemetry.
9. Close the Incident
Use the standard XSOAR incident closure workflow.
Confirm:
Close Reason
Closing Notes
Detection disposition
The closure will automatically synchronize to Vectra.
Troubleshooting
Test Fails
Verify:
Server URL
Client ID
Client Secret Key
API Client permissions
Network connectivity
No Incidents Are Created
Verify:
Fetch Incidents is enabled.
First Fetch Time is appropriate.
Detection filters are not excluding all events.
The Events API is returning data.
Notes Are Not Synchronizing
Verify:
Outgoing mirroring is enabled.
Notes contain the configured mirror tag.
Notes are under 1,000 characters.
Detection Does Not Close
Verify:
Outgoing mirroring is enabled.
Close Detection on Incident Closure is enabled.
The detection remains active in Vectra.
Assignment Information Is Missing
Verify:
The entity is assigned in Vectra.
Sync Entity Assignment has been executed.
Key Takeaways
One XSOAR incident is created for each Vectra detection.
Entity context is preserved across all incidents.
Detection and entity data support bidirectional synchronization.
External Reference IDs provide powerful ticketing integration capabilities.
Notes, tags, status, and closures can be synchronized between platforms.
Tag-based filtering provides a flexible mechanism for controlling incident creation.
Detection-centric workflows enable significantly more granular automation than entity-centric incident models.
Appendix A — Command Reference
The following appendix contains the complete command reference, including all supported parameters, requirements, and operational notes.
Commands are grouped by category:
Detection Commands
Entity Commands
Assignment Commands
Group Commands
User Commands
Investigation Commands
This appendix provides the complete reference for all integration commands.
Commands may be executed from:
Cortex XSOAR playbooks
Automation scripts
The War Room
Commands that modify data within the Vectra platform are explicitly identified.
Detection Commands
vectra-detection-list
Returns detections matching the specified filters.
Parameters
created_after
No
Filter by detections created on or after this time. Accepts relative (for example: 2 days) or absolute (yyyy-mm-ddTHH:MM:SSZ) formats.
created_before
No
Filter by detections created on or before this time.
last_detected_after
No
Filter by detections last observed on or after this time.
last_detected_before
No
Filter by detections last observed on or before this time.
description
No
Filter by description containing the specified value.
detection_name
No
Filter by detection name.
detection_type
No
Filter by detection type.
detection_category
No
Filter by category: Command & Control, Botnet, Reconnaissance, Lateral Movement, Exfiltration, or Info.
include_info_category_detections
No
Include Info category detections. Default: true.
close_reason
No
Filter by close reason: benign or remediated.
detection_state
No
Filter by state: active, inactive, or fixed.
entity_type
No
Filter by entity type: account or host.
tags
No
Filter by detection tags. Comma-separated values supported.
is_triaged
No
Filter by triage status. Default: false.
page
No
Page number. Default: 1.
page_size
No
Results per page. Default: 50.
vectra-detections-mark-asclosed
Marks one or more detections as closed.
Warning
This command modifies data in the Vectra platform.
Parameters
detection_ids
Yes
Comma-separated list of detection IDs or a single detection ID.
close_reason
Yes
Close reason. Valid values: benign, remediated.
vectra-detections-mark-asopen
Reopens one or more previously closed detections.
Warning
This command modifies data in the Vectra platform.
Parameters
detection_ids
Yes
Comma-separated list of detection IDs or a single detection ID.
vectra-detection-describe
Returns the full detection record, including summary information and EDR context where available.
Parameters
detection_ids
Yes
One or more detection IDs (comma-separated).
page
No
Page number. Default: 1.
page_size
No
Results per page. Maximum: 5000. Default: 50.
vectra-detection-pcap-download
Downloads the PCAP associated with a detection and attaches it to the incident.
Parameters
detection_id
Yes
Detection ID.
vectra-detection-investigation-status-update
Updates the investigation status of one or more detections.
Warning
This command modifies data in the Vectra platform.
Parameters
detection_ids
Yes
Comma-separated list of detection IDs.
investigation_status
Yes
Valid values: open, acknowledged, escalated, paused, closed, expired.
vectra-detection-external-id-update
Updates the external reference ID associated with one or more detections.
Warning
This command modifies data in the Vectra platform.
Parameters
detection_ids
Yes
Comma-separated list of detection IDs.
external_reference_id
Yes
External reference identifier to assign.
vectra-detection-tag-list
Returns tags associated with a detection.
Parameters
detection_id
Yes
Detection ID.
vectra-detection-tag-add
Adds one or more tags to a detection.
Warning
This command modifies data in the Vectra platform.
Parameters
detection_id
Yes
Detection ID.
tags
Yes
Comma-separated tags to add.
vectra-detection-tag-remove
Removes one or more tags from a detection.
Warning
This command modifies data in the Vectra platform.
Parameters
detection_id
Yes
Detection ID.
tags
Yes
Comma-separated tags to remove.
vectra-detection-note-list
Returns notes associated with a detection.
Parameters
detection_id
Yes
Detection ID.
vectra-detection-note-add
Adds a note to a detection.
Warning
This command modifies data in the Vectra platform.
Parameters
detection_id
Yes
Detection ID.
note
Yes
Note content.
vectra-detection-note-update
Updates an existing detection note.
Warning
This command modifies data in the Vectra platform.
Parameters
detection_id
Yes
Detection ID.
note_id
Yes
Note ID.
note
Yes
Updated note content.
vectra-detection-note-remove
Removes a detection note.
Warning
This command modifies data in the Vectra platform.
Parameters
detection_id
Yes
Detection ID.
note_id
Yes
Note ID.
Entity Commands
vectra-entity-list
Returns entities matching the specified filters.
Parameters
entity_type
No
Entity type: account or host.
prioritized
No
Return only prioritized entities.
name
No
Partial entity name match.
tags
No
Entity tags.
state
No
Entity state: active or inactive.
ordering
No
Sort order. Prefix with - for descending order.
last_detection_timestamp
No
Return entities active since this timestamp.
last_modified_timestamp
No
Return entities modified since this timestamp.
page
No
Page number. Default: 1.
page_size
No
Results per page. Maximum: 5000. Default: 50.
vectra-entity-describe
Returns the full entity record.
Parameters
entity_id
Yes
Numeric entity ID.
entity_type
Yes
Entity type: host or account.
vectra-entity-detection-list
Returns detections associated with an entity.
Parameters
entity_id
Yes
Numeric entity ID.
entity_type
Yes
Entity type: host or account.
detection_category
No
Detection category filter.
detection_type
No
Detection type filter.
last_timestamp
No
Return detections active since this timestamp.
state
No
Detection state. Default: active.
tags
No
Detection tags.
page
No
Page number.
page_size
No
Results per page.
vectra-entity-external-id-update
Updates the external reference ID associated with an entity.
Warning
This command modifies data in the Vectra platform.
Parameters
entity_id
Yes
Numeric entity ID.
entity_type
Yes
Entity type: host or account.
external_reference_id
Yes
External reference identifier.
vectra-entity-unresolved-priority-reset
Clears unresolved priority status for eligible entities.
Warning
This command modifies data in the Vectra platform.
Note
Only entities below the current prioritization threshold can have unresolved priority cleared.
Parameters
entity_id
Yes
Numeric entity ID.
entity_type
Yes
Entity type: host or account.
vectra-entity-note-add
Adds a note to an entity.
Warning
This command modifies data in the Vectra platform.
Parameters
entity_id
Yes
Numeric entity ID.
entity_type
Yes
Entity type.
note
Yes
Note content.
vectra-entity-note-update
Updates an entity note.
Warning
This command modifies data in the Vectra platform.
Parameters
entity_id
Yes
Numeric entity ID.
entity_type
Yes
Entity type.
note_id
Yes
Note ID.
note
Yes
Updated note content.
vectra-entity-note-remove
Removes an entity note.
Warning
This command modifies data in the Vectra platform.
Parameters
entity_id
Yes
Numeric entity ID.
entity_type
Yes
Entity type.
note_id
Yes
Note ID.
vectra-entity-note-list
Returns notes associated with an entity.
Parameters
entity_id
Yes
Numeric entity ID.
entity_type
Yes
Entity type.
page
No
Page number.
page_size
No
Results per page.
vectra-entity-tag-add
Adds tags to an entity.
Warning
This command modifies data in the Vectra platform.
Parameters
entity_id
Yes
Numeric entity ID.
entity_type
Yes
Entity type.
tags
Yes
Comma-separated tags.
vectra-entity-tag-remove
Removes tags from an entity.
Warning
This command modifies data in the Vectra platform.
Parameters
entity_id
Yes
Numeric entity ID.
entity_type
Yes
Entity type.
tags
Yes
Comma-separated tags.
vectra-entity-tag-list
Returns tags associated with an entity.
Parameters
entity_id
Yes
Numeric entity ID.
entity_type
Yes
Entity type.
vectra-entity-detections-mark-asclosed
Closes all active detections associated with an entity.
Warning
This command modifies data in the Vectra platform.
Parameters
entity_id
Yes
Numeric entity ID.
entity_type
Yes
Entity type.
close_reason
Yes
Valid values: benign, remediated.
Assignment Commands
vectra-assignment-list
Returns assignment records matching the specified filters.
Parameters
entity_ids
No
Comma-separated list of entity IDs.
entity_type
No
Filter by entity type: account or host.
resolved
No
Filter by resolution status. Valid values: true, false.
assignees
No
Comma-separated list of user IDs.
resolution
No
Comma-separated list of outcome IDs.
created_after
No
Return assignments created after the specified timestamp.
page
No
Page number.
page_size
No
Results per page.
vectra-entity-assignment-add
Creates a new assignment for an entity.
Warning
This command modifies data in the Vectra platform.
Parameters
entity_id
Yes
Numeric entity ID.
entity_type
Yes
Entity type: account or host.
user_id
Yes
User ID of the assignee.
vectra-entity-assignment-update
Reassigns an existing assignment to a different user.
Warning
This command modifies data in the Vectra platform.
Parameters
assignment_id
Yes
Assignment ID.
user_id
Yes
User ID of the new assignee.
Group Commands
vectra-group-list
Returns groups defined in the Vectra platform.
Parameters
page
No
Page number.
page_size
No
Results per page.
vectra-group-assign
Assigns one or more members to a group.
Warning
This command modifies data in the Vectra platform.
Parameters
group_id
Yes
Group ID.
entity_ids
Yes
Comma-separated list of entity IDs.
entity_type
Yes
Entity type: account or host.
vectra-group-unassign
Removes one or more entities from a group.
Warning
This command modifies data in the Vectra platform.
Parameters
group_id
Yes
Group ID.
entity_ids
Yes
Comma-separated list of entity IDs.
entity_type
Yes
Entity type: account or host.
User Commands
vectra-user-list
Returns Vectra platform users and associated metadata.
Parameters
username
No
Filter by username.
role
No
Filter by role. Valid values include: Admin, Read-Only, Restricted Admin, Security Analyst, Settings Admin, and Super Admin.
last_login_timestamp
No
Return users who logged in at or after the specified timestamp.
Investigation Commands
vectra-investigation-query-send
Submits an investigation query and returns a request ID that can later be used to retrieve results.
Warning
This command executes an investigation query against the Vectra platform.
Parameters
query
Yes
Investigation query string.
version
No
Query language version. Example: 1.0.
Example
Typical Workflow
Submit the query using:
Record the returned request ID.
Retrieve results using:
vectra-investigation-result-get
Retrieves the results of a previously submitted investigation query.
This command is typically executed repeatedly until all desired results have been retrieved.
Parameters
id
Yes
Request ID returned by vectra-investigation-query-send.
page
No
Page number. Default: 1.
page_size
No
Results per page. Default: 50.
Typical Workflow
Submit an investigation query using:
Retrieve results using the returned request ID.
Continue paging through results until all records have been collected.
Appendix Summary
The Vectra RUX Events Detection integration exposes commands across six functional areas:
Detection Commands
14
Entity Commands
13
Assignment Commands
3
Group Commands
3
User Commands
1
Investigation Commands
2
Total Commands: 36
Commands may be executed from:
Cortex XSOAR playbooks
Automation scripts
Integration tasks
The War Room
Commands identified as write operations modify data within the Vectra platform and should be used appropriately within automation workflows.
Last updated
Was this helpful?