| Table of Contents | ||||||
|---|---|---|---|---|---|---|
|
Overview
Cortex XDR is a cybersecurity platform developed by Palo Alto Networks that integrates multiple security functions into a single platform. It is designed to detect, investigate, and respond to advanced threats across endpoints, networks, and cloud environments. Extended Detection and Response (XDR) integrates data from various sources, including endpoints, networks, cloud environments, and third-party products, to provide comprehensive threat detection and response capabilities.
Integration overview
The data is collected using a Devo collector that can be run on the Devo Collector server or stand alone in a Docker container. The data is sent and stored in the Devo platform in these tables:
edr.cortex_xdr.incidentsedr.cortex_xdr.alertsedr.cortex_xdr.alerts_multiedr.cortex_xdr.alerts_multi_event
Cortex exposes REST API resources to extract data such as:
...
Resource type
...
Definition
...
Devo table
...
Incidents
...
delivers enterprise-wide protection by analyzing data from any source to stop sophisticated attacks.
Eliminate blind spots with complete visibility
Simplify security operations to cut mean time to respond (MTTR)
Harness the scale of the cloud for AI and analytics
Lower costs by consolidating tools and improving SOC efficiency.
Devo collector features
Feature | Details |
|---|---|
Allow parallel downloading ( |
|
Running environments |
|
Populated Devo events |
|
Flattening preprocessing |
|
Requires IP Whitelisting |
|
Data sources
Data source | Description | API endpoint | Collector service name | Devo table | Available from release | ||
|---|---|---|---|---|---|---|---|
Alerts | Get a list of alerts with multiple events. |
|
|
|
| ||
Incidents | Get Incidents: |
The response is concatenated using the AND condition (OR is not supported).
The maximum result set size is >100.
Offset is the zero-based number of incidents from the start of the result set.
| Note |
|---|
You can request to retrieve all or filtered results. |
Required license: Cortex XDR Prevent, Cortex XDR Pro per Endpoint, or Cortex XDR Pro per GB
URL: https://api-yourfqdn
Get Incident Alerts: | List Incidents: |
List Incident Alerts:
|
|
| List Incidents:
List Incident Alerts |
Get extra data fields of a specific incident including alerts and key artifacts.
Cortex XDR displays in the API response whether a PAN NGFW type alert contains a PCAP triggering packet.
| Note |
|---|
The API includes a limit rate of 10 API requests per minute. |
Required license: Cortex XDR Prevent, Cortex XDR Pro per Endpoint, or Cortex XDR Pro per GB
URL: https://api-yourfqdn
:
|
| ||
All Alerts | Get a list of alerts. |
|
|
|
|
|
| ||
Audit Managements | Get audit management logs. |
|
|
|
|
|
|
Alert multi-events
Get a list of alerts with multiple events.
Response is concatenated using AND condition (OR is not supported).
The maximum result set size is 100.
Offset is the zero-based number of alerts from the start of the result set.
Cortex XDR displays in the API response whether a PAN NGFW type alert contains a PCAP triggering packet.
| Note |
|---|
You can request to retrieve either all or filtered results. |
Required license: Cortex XDR Prevent, Cortex XDR Pro per Endpoint, or Cortex XDR Pro per GB
URL:
https://api-yourfqdnEndpoint:
/public_api/v1/alerts/get_alerts_multi_eventsDocumentation: https://docs-cortex.paloaltonetworks.com/r/Cortex-XDR-REST-API/Get-Alerts-Multi-Events-v1
edr.cortex_xdr.alerts_multiedr.cortex_xdr.alerts_multi_event
alert_tag and event_tagin the alert module definition.Vendor configuration
To pull the logs from the Cortex XDR endpoint you need this information:
...
Parameter
...
Description
...
URL API FQDN
...
The service address of the Cortex XDR installation
...
API_KEY
...
Your API Key
...
API_ID
...
Your API Key ID
Run the collector
...
|
Vendor configuration
Generate API key
Log in to your Cortex XDR console with an administrative account.
Go to the Settings menu (gear icon).
Go to API Keys under the Integrations section.
Click Add Key to generate a new API key.
Select the roles or permissions you want to assign to this key (these determine the actions the key can perform).
Click Create for generating the API Key along with an API Key ID. Save these securely, as you may not be able to retrieve them later.
API FQDN
The API FQDN (Fully Qualified Domain Name) can be found in the documentation or directly in the URL when you are logged into your Cortex XDR console.
It will usually be in the format:
https://<YOUR_REGION>.xdr.paloaltonetworks.com
Minimum configuration required for basic pulling
Although this collector supports advanced configuration, the fields required to download data with basic configuration are defined below.
| Info |
|---|
This minimum configuration refers exclusively to those specific parameters of this integration. There are more required parameters related to the generic behavior of the collector. Check setting sections for details. |
Setting | Details |
|---|---|
| The API Key is your unique identifier for Cortex XDR. |
| The API Key ID is your unique token used to authenticate the API key for Cortex XDR. |
| API FQDN is a unique host and domain name associated with each tenant for Cortex XDR. |
| Info |
|---|
See the Accepted authentication methods section to verify what settings are required based on the desired authentication method. |
Accepted authentication methods
Depending on how did you obtain your credentials, you will have to either fill or delete the following properties on the JSON credentials configuration block.
Authentication method | API key | API key ID | API FQDN | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
API KEY / API KEY ID / API FQDN |
|
|
|
Run the collector
Once the data source is configured, you can either send us the required information if you want us to host and manage the collector for you (Cloud collector), or deploy and host the collector in your own machine using a Docker image (On-premise collector).
| Rw ui tabs macro | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
The Collector Server is a managed platform that allows running sets of different collectors grouped by Devo domain destinations. To run an instance of this data collector, the next steps must be followed:
This data collector can be run in any machine that has the Docker service available because it should be executed as a docker container. The following sections explain how to prepare all the required setup for having the data collector running. StructureThe following directory structure should be created for being used when running the collector:
Devo credentialsIn Devo, go to Administration → Credentials → X.509 Certificates, download the Certificate, Private key and Chain CA and save them in 
Editing the config.yaml file
This data collector can be run in any machine that has the Docker service available because it should be executed as a docker container. The following sections explain how to prepare all the required setup for having the data collector running. StructureThe following directory structure should be created for being used when running the collector:
Devo credentialsIn Devo, go to Administration → Credentials → X.509 Certificates, download the Certificate, Private key and Chain CA and save them in
Editing the config.yaml file
Download the Docker imageThe collector should be deployed as a Docker container. Download the Docker image of the collector as a .tgz file by clicking the link in the following table: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Collector Docker image | SHA-256 hash | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
| Code Block |
|---|
gunzip -c <image_file>-<version>.tgz | docker load |
| Note |
|---|
Once the Docker image is imported, it will show the real name of the Docker image (including version info). Replace |
The Docker image can be deployed on the following services:
Docker
Execute the following command on the root directory <any_directory>/devo-collectors/<product_name>/
| Code Block |
|---|
docker run
--name collector-<product_name>
--volume $PWD/certs:/devo-collector/certs
--volume $PWD/config:/devo-collector/config
--volume $PWD/state:/devo-collector/state
--env CONFIG_FILE=config.yaml
--rm
--interactive
--tty
<image_name>:<version> |
| Note |
|---|
Replace |
Docker Compose
The following Docker Compose file can be used to execute the Docker container. It must be created in the <any_directory>/devo-collectors/<product_name>/ directory.
| Code Block |
|---|
version: '3'
services:
collector-<product_name>:
image: <image_name>:${IMAGE_VERSION:-latest}
container_name: collector-<product_name>
volumes:
- ./certs:/devo-collector/certs
- ./config:/devo-collector/config
- ./credentials:/devo-collector/credentials
- ./state:/devo-collector/state
environment:
- CONFIG_FILE=${CONFIG_FILE:-config.yaml} |
To run the container using docker-compose, execute the following command from the <any_directory>/devo-collectors/<product_name>/ directory:
| Code Block |
|---|
IMAGE_VERSION=<version> docker-compose up -d |
| Note |
|---|
Replace <product_name>, <image_name> and <version> with the proper values<devo_domain>.key
console_1:
type: console
inputs:
cortex_xdr:
id: <short_unique_id>
enabled: true
credentials:
api_key: <api_key>
api_key_id: <api_key_id>
services:
incidents:
api_fqdn: <api_fqdn>
request_period_in_seconds : <request_period_in_seconds> #optional
start_time: <start_time> #optional
include_incident_alerts: <include_incident_alerts> #Optional
override_devo_tag: <override_devo_tag> #optional
override_incident_alert_tag: <override_incident_alert_tag> #optional
alerts:
api_fqdn: <api_fqdn>
start_time: <start_time> # Example 2024-01-01T01:50:00Z
request_period_in_seconds: <request_period_in_seconds> #optional
override_devo_tag: <override_devo_tag> #optional
all_alerts:
api_fqdn: <api_fqdn>
start_time: <opt_start_time> # Example 2024-01-01T01:50:00Z #optional
request_period_in_seconds: <opt_request_period_in_seconds> #optional
override_devo_tag: <override_devo_tag> #optional
audit_managements:
api_fqdn: <api_fqdn>
start_time: <opt_start_time> # Example 2024-01-01T01:50:00Z #optional
request_period_in_seconds: <opt_request_period_in_seconds> #optional
override_devo_tag: <override_devo_tag> #optional
violations:
api_fqdn: <api_fqdn>
start_time: <opt_start_time> # Example 2024-01-01T01:50:00Z #optional
request_period_in_seconds: <opt_request_period_in_seconds> #optional
override_devo_tag: <override_devo_tag> #optional |
| Note |
|---|
All defined service entities will be executed by the collector. If you do not want to run any of them, just remove the entity from the |
| Info |
|---|
Please replace the placeholders with real world values following the description table below |
Parameter | Data type | Type | Value range / Format | Details | ||
|---|---|---|---|---|---|---|
|
|
|
| Use this param to give a unique id to this input service.
| ||
|
|
|
| Use this param to enable or disable the given input logic when running the collector. If the value is | ||
|
|
|
| The API Key is your unique identifier used as the | ||
|
|
|
| The API Key ID is your unique token used to authenticate the API Key. It is used in headers as | ||
|
|
|
| The {api_fqdn} FQDN is a unique host and domain name associated with each tenant. When you generate the API Key and Key ID, you are assigned an individual FQDN. ex: | ||
|
|
|
| Period in seconds used between each data pulling, this value will overwrite the default value 60 seconds | ||
|
|
| A devo tag | This parameter allows to define a custom devo tag. | ||
|
|
| A Incident Alert tag | This Tag is only applicable for Incidents service to override the tag of Incident alerts( Extra incident endpoint). Ex: | ||
|
|
| A boolean to Include Incidents alerts | By default the value of this boolean is ‘true’. If given ‘false’ we will not be able to get incident alerts data (Extra incidents data). Ex : | ||
|
|
| start time in utc | This parameter allows to get the data from provided start time. If not provided it will take current-time as time. Ex:- 2024-01-01T01:50:00Z |
Download the Docker image
The collector should be deployed as a Docker container. Download the Docker image of the collector as a .tgz file by clicking the link in the following table:
Collector Docker image | SHA-256 hash |
|---|---|
|
Use the following command to add the Docker image to the system:
| Code Block |
|---|
gunzip -c <image_file>-<version>.tgz | docker load |
| Note |
|---|
Once the Docker image is imported, it will show the real name of the Docker image (including version info). Replace |
The Docker image can be deployed on the following services:
Docker
Execute the following command on the root directory <any_directory>/devo-collectors/<product_name>/
| Code Block |
|---|
docker run
--name collector-<product_name>
--volume $PWD/certs:/devo-collector/certs
--volume $PWD/config:/devo-collector/config
--volume $PWD/state:/devo-collector/state
--env CONFIG_FILE=config.yaml
--rm
--interactive
--tty
<image_name>:<version> |
| Note |
|---|
Replace |
Docker Compose
The following Docker Compose file can be used to execute the Docker container. It must be created in the <any_directory>/devo-collectors/<product_name>/ directory.
| Code Block |
|---|
version: '3'
services:
collector-<product_name>:
image: <image_name>:${IMAGE_VERSION:-latest}
container_name: collector-<product_name>
volumes:
- ./certs:/devo-collector/certs
- ./config:/devo-collector/config
- ./credentials:/devo-collector/credentials
- ./state:/devo-collector/state
environment:
- CONFIG_FILE=${CONFIG_FILE:-config.yaml} |
To run the container using docker-compose, execute the following command from the <any_directory>/devo-collectors/<product_name>/ directory:
| Code Block |
|---|
IMAGE_VERSION=<version> docker-compose up -d |
| Note |
|---|
Replace |
Collector services detail
This section is intended to explain how to proceed with specific actions for services.
| Expand | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
Verify data collectionService componentsOnce the collector has been launched, it is important to check if the ingestion is performed in a proper way. To do so, go to the collector’s logs console. This service has the following components:
Setup is common for every service, so its output is displayed in this section. On the other hand, Pullers are specific to each Service, so their outputs are shown in their corresponding sections below. Setup outputA successful run has the following output messages for the setup module:
Restart the persistenceSome services in this collector use persistent storage to download events in an orderly fashion and avoid duplicates. In case you want to re-ingest historical data or recreate the persistence, you can restart the persistence of this collector by following these steps:
The collector will detect this change and will restart the persistence using the parameters of the configuration file or the default configuration in case it has not been provided.
|
| Expand | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
Verify data collectionPuller outputA successful initial run has the following output messages for the puller module: Note that the
After a successful collector’s execution (this is, no error logs were found), you should be able to see the following log message:
Restart the persistenceThis service makes use of persistence. You can check how to restart it above. |
| Expand | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
Verify data collectionPuller outputA successful initial run has the following output messages for the puller module: Note that the
After a successful collector’s execution (this is, no error logs were found), you should be able to see the following log message:
Restart the persistenceThis service makes use of persistence. You can check how to restart it above. |
| Expand | ||||||
|---|---|---|---|---|---|---|
| ||||||
Devo categorization and destinationAll events of this service are ingested into table Verify data collectionPuller outputA successful initial run has the following output messages for the puller module: Note that the
After a successful collector’s execution (this is, no error logs were found), you should be able to see the following log message:
Restart the persistenceThis service makes use of persistence. You can check how to restart it above. |
| Expand | ||||||
|---|---|---|---|---|---|---|
| ||||||
Devo categorization and destinationAll events of this service are ingested into table Verify data collectionPuller outputA successful initial run has the following output messages for the puller module: Note that the
After a successful collector’s execution (this is, no error logs were found), you should be able to see the following log message:
Restart the persistenceThis service makes use of persistence. You can check how to restart it above. |
Collector operations
This section is intended to explain how to proceed with specific operations of this collector.
| Expand | ||
|---|---|---|
| ||
The initialization module is in charge of setup and running the input (pulling logic) and output (delivering logic) services and validating the given configuration. |
| Expand | ||
|---|---|---|
| ||
The initialization module is in charge of setup and running the input (pulling logic) and output (delivering logic) services and validating the given configuration. A successful run has the following output messages for the initializer module, including all services together:
|
| Expand | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
The event delivery module is in charge of receiving the events from the internal queues where all events are injected by the pullers and delivering them using the selected compatible delivery method. A successful run has the following output messages for the initializer module:
By default, these information traces will be displayed every 10 minutes. Sender statisticsEach service displays its own performance statistics that allow checking how many events have been delivered to Devo by type:
|
| Expand | ||||
|---|---|---|---|---|
| ||||
To check the memory usage of this collector, look for the following log records in the collector which are displayed every 5 minutes by default, always after running the memory-free process.
Differences between
|
| Expand | ||
|---|---|---|
| ||
Sometimes it is necessary to activate the debug mode of the collector's logging. This debug mode increases the verbosity of the log and allows you to print execution traces that are very helpful in resolving incidents or detecting bottlenecks in heavy download processes.
For more information, visit the configuration and parameterization section corresponding to the chosen deployment mode. |
| Expand | |||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||
This collector has different security layers that detect both an invalid configuration and abnormal operation. This table will help you detect and resolve the common errors for the current services.
|
Change log
Release | Released on | Release type | Details | Recommendations | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
| Improvements
|
| |||||||||||||
|
| Improvements:
|
| |||||||||||||
|
| Improvements:
|
| |||||||||||||
|
| Improvements:
| |