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.incidents
edr.cortex_xdr.alerts
edr.cortex_xdr.alerts_multi
edr.cortex_xdr.alerts_multi_event
Cortex exposes REST API resources to extract data such as:
...
Resource type
...
Definition
...
Devo table
...
Incidents
Get a list of incidents filtered by a list of incident IDs, modification time, or creation time.
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
...
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.
Cortex XDR collector migration guide (from 1.x.x to 2.x.x)
If you need to migrate an old collector version to a more recent one, please check the migration process in this article.
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: 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. |
|
|
|
|
|
|
|
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-yourfqdn
| ||
Audit Managements | Get audit management logs. |
|
|
|
Documentation: https://docs-cortex.paloaltonetworks.com/r/Cortex-XDR-REST-API/Get-Alerts-Multi-Events-v1
edr.cortex_xdr.alerts_multi
edr.cortex_xdr.alerts_multi_event
alert_tag
and event_tag
in 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
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 tab | ||
---|---|---|
|
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:
In the Collector Server GUI, access the domain where you want to create this instance, click Add Collector, search for “Cortex XDR - Integrations Factory”, then click on the result.
In the Version field, select the latest value.
In the Collector Name field, set the value you prefer (this name must be unique inside the same Collector Server domain).
In the Parameters section, establish the Collector Parameters as follows below:Collector services detail
Info |
---|
Please, replace the placeholders |
Code Block |
---|
{
"cortex_xdr": {
"id": 1,
"enabled": true,
"credentials": {
"api_key": "<api_key_value>",
"api_key_id": "<api_key_id_value>"
},
"services": {
"incidents": {
"api_fqdn": "<api_fqdn_value>",
"api_endpoint": "{api_fqdn}/public_api/v1/incidents/get_incidents",
"incident_extra_data_endpoint": "{api_fqdn}/public_api/v1/incidents/get_incident_extra_data",
"tag": "<opt_tag_value>",
"alert_tag": "<opt_alert_tag_value>",
"request_period_in_seconds": "<opt_request_period_in_seconds_value>",
"start_time": "<opt_start_time>"
},
"alerts": {
"api_fqdn": "<api_fqdn_value>",
"api_endpoint": "{api_fqdn}/public_api/v1/alerts/get_alerts_multi_events",
"alert_tag": "<opt_alert_tag_value>",
"event_tag": "<opt_event_tag_value>",
"request_period_in_seconds": "<opt_request_period_in_seconds_value>",
"start_time": "<opt_start_time>"
}
}
}
} |
Info |
---|
The value chosen for the |
Rw tab | ||
---|---|---|
|
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.
Structure
The following directory structure should be created for being used when running the collector:
Code Block |
---|
<any_directory>
└── devo-collectors/
└── <product_name>/
├── certs/
│ ├── chain.crt
│ ├── <your_domain>.key
│ └── <your_domain>.crt
├── state/
└── config/
└── config.yaml |
Note |
---|
Replace |
Devo credentials
In Devo, go to Administration → Credentials → X.509 Certificates, download the Certificate, Private key and Chain CA and save them in <product_name>/certs/
. Learn more about security credentials in Devo here.
...
Note |
---|
Replace |
Editing the config.yaml file
Code Block |
---|
globals:
debug: false
id: not_used
name: cortex_xdr
persistence:
type: filesystem
config:
directory_name: state
outputs:
devo_1:
type: devo_platform
config:
address: collector-us.devo.io
port: 443
type: SSL
chain: chain.crt
cert: <devo_domain>.crt
key: <devo_domain>.key
console_1:
type: console
inputs:
cortex_xdr:
id: <short_unique_id>
enabled: true
credentials:
api_key: <api_key_value>
api_key_id: <api_key_id_value>
services:
incidents:
request_period_in_seconds : <request_period_in_seconds_value> #optional
start_time: <start_time> #optional
api_fqdn: <api_fqdn_value>
api_endpoint: <api_endpoint_value>
incident_extra_data_endpoint: <incident_extra_data_endpoint_value>
alerts:
start_time: <start_time_value> # Example 2024-01-01T01:50:00Z
request_period_in_seconds: <request_period_in_seconds_value> #optional
api_fqdn: <api_fqdn_value>
api_endpoint: <api_endpoint_value> |
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
...
collector-cortex_xdr_if-docker-image-1.4.0
...
84f0a7a60aa6c771d103e577070494d39068dc73c9f1d962aebce92f9db7c248
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 |
Change log
Release
Released on
Release type
Details
Recommendations
|
|
|
|
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
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:
Use the following command to add the Docker image to the system:
The Docker image can be deployed on the following services: DockerExecute the following command on the root directory
Docker ComposeThe following Docker Compose file can be used to execute the Docker container. It must be created in the
To run the container using docker-compose, execute the following command from the
|
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 | Recommendations | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
| |||||||||||||
| |||||||||||||||
|
|
| |||||||||||||
| |||||||||||||||
|
|
| |||||||||||||
| |||||||||||||||
|
|
| |||||||||||||
| |||||||||||||||
|
|
| |||||||||||||
|
| ||||||||||||||
|
|
| |||||||||||||
|
| ||||||||||||||
|
| | |||||||||||||
|