Cortex XDR Custom SecOps Integration

Cortex XDR Custom SecOps Integration

The Cortex XDR Custom SecOps Integration allows you to poll and push adversary-related events to your Cortex XDR deployment. After configuring the integration, your Cortex deployment will be able to receive and process Lumu events. Using it lets you see adversarial activity detected by Lumu, giving your Security Operations team more visibility.


SecOps integration between Cortex XDR and Lumu

Requirements

  1. A Cortex XDR Pro subscription and Web access.
  2. Lumu Defender API key
    1. To retrieve an API token, please refer to the Defender API document.
  3. Script host.
    1. A scripting host is required to deploy the integration. This host must have Internet visibility over Lumu Defender API endpoints and Cortex XDR. According to the deployment model you select, you will need a host with:
      1.  Python 3.10+
                              OR
      1. A Docker-enabled host.
  1. Script package.
    1. Contact the Lumu Support Team to request the package we created to deploy the required files.

Contacted hosts

Allow all the traffic to the following hosts. These are required for the operation of this integration:

  • <INSTANCE>.xdr.us.paloaltonetworks.com

  • defender.lumu.io

Cortex XDR gives you a subdomain within xdr.us.paloaltonetworks.com, save it for the integration configuration file

Integration’s overview

The integration pushes Lumu adversary-related events into your Cortex XDR deployment after being configured by leveraging the CEF event API. As part of the integration deployment, you must define an External Alerts Mapping in your Cortex XDR console. After you define the alert mapping, your Cortex XDR deployment will see Lumu detections as alerts.

Prepare Cortex XDR for Lumu integration

Before you deploy and implement the Lumu Integration, you must prepare your Cortex XDR deployment to ensure the integration works as expected.

Identify your Cortex XDR instance

To identify your instance, log in to your Cortex XDR console. Check the URL and extract your instance name. Your Cortex XDR URL must look like <INSTANCE>.xdr.us.paloaltonetworks.com. That is your instance name.

Create a Custom Role

To preserve the principle of least privilege, we encourage you to create a dedicated custom role for the integration. This role will only be granted the features needed to make the integration work.

To create a new role, log in to your Cortex XDR console. Go to Settings > Configurations > Access Management > Roles, and follow these steps.

1. Click on the New Role Button
2. Fill in the Role Name and Description fields
3. Under the Components tab, go to the CONFIGURATIONS section. Then, change the External Alerts Mapping and Public API items to View/Edit

Create an API Key

You need to create an API key dedicated to run the integration script. To create it, go to Settings > Configurations > Integrations > API Keys, and follow these steps.

1. Click on the New Key button
2. Under the Role Name field, select the previously created role
3. Under the Security Level section, select the Standard option
4. Define an expiration date for the key by clicking the Enable Expiration Date checkbox 

From the API Keys window, extract the ID number of the created key. This will be needed later.

We recommend you define an expiration date for the API key. Bear in mind that you need to renew and reconfigure the integration before the key expires to keep the integration working.

Collect the required data from Lumu portal

The integration set-up process needs you to collect this information from Lumu portal:

  • Lumu Defender API key

  • Company UUID

Log in to your Lumu portal and run the following data collection procedures.

Collect the Lumu Defender API key

To collect the Lumu Defender API key, refer to the Defender API document.

Collect your Lumu company UUID

To collect your Lumu company UUID, log in to your Lumu portal. Once you are in the main window, copy the string below your company name.

Deploy the integration

There are 2 environment options to deploy the script, select the one that best fits your current infrastructure.

  • Run it as a Python script executing the install.sh bash file

    • Creates a Python virtual run time and its dependencies for you

    • Installs the crontab line in the host

  • Run it as a Docker container.

Whichever alternative you select, you need to first unpack the integration package shared by our Support team.

Unpack the deployment package provided by Lumu in your preferred path/folder. Keep in mind this location, as it will be required for further configurations. From now on, we will refer to this folder as <app_lumu_root>.

If you use the install script, use the uninstall.sh bash file to remove the integration from the host

Set up the configuration file

To set up the integration, you need to add and edit a configuration file. This file contains all the parameters needed to run properly. The configuration file looks as follows:

Inside the integration package, you will find a sample configuration file named companies_template.yml. Copy it and modify it based on your deployment.

-
  lumu:
    uuid: "<COMPANY-UUID>"
    defender_key: "<DEFENDER-KEY>"
    include_muted_updates: false # Boolean: true | false
    throttle: 1 # INT<[0-5]> minutes
    incident_types: ["C2C", "Malware", "DGA", "Mining", "Spam", "Phishing", "Network Scan"] # ["C2C", "Malware", "DGA", "Mining", "Spam", "Phishing",  Network Scan"] | [] | null
  app:
    # DeviceVendor, DeviceProduct, and DeviceVersion are reserved headers for the integration
    DeviceVendor: "Lumu"    # Do not change this
    DeviceProduct: "Lumu"   # Do not change this
    DeviceVersion: "1.0"    # Do not change this
    Severity: # [ Critical, High, Medium, Low ]
      C2C: High
      Malware: Medium
      DGA: Medium
      Mining: Low
      Spam: Low
      Phishing: Low
    api:
      url: "https://api-<INSTANCE-FQDN>"
      api_key: "<API-KEY>"
      api_key_id: "<API-KEY-ID>"
-
  COMPANY 2
-
  COMPANY 3
-
  ...

Before completing the app section of the YAML file check the right names of each Status in the Cortex XDR Web console, in case the status name has changed, then update the YAML fields and values related.

For MSP deployments, you can add multiple instances of this configuration block in your configuration file.

Mandatory fields

Within the configuration file, fill in these fields:

From Lumu

  • COMPANY-UUID: The company ID collected from Lumu portal

  • DEFENDER-KEY: The Lumu Defender API key

From Cortex XDR

  • INSTANCE-FQDN: Cortex XDR console Fully-Qualified Domain Name. This has the format <hostname>.xdr.<location>.paloaltonetworks.com

  • API-KEY: Cortex XDR API key

  • API-KEY-ID: Cortex XDR API key ID extracted from the API Keys window

Prepare Python on your environment

If Docker is your chosen deployment method, you may skip this step.

If Python is your chosen deployment method, you will need to create a Virtual environment for each integration to avoid conflicts between them and your operating system tools. Make sure you follow the steps in our Preparing Environment for Custom Integrations article

Deploy integration as script

To deploy the integration as a script, you need to run the install.sh script inside the integration package.

Make sure the install.sh script has the execution permission before running it.

To run the installation script, go to the app_lumu_root folder, then execute this line through CLI.

./install.sh

The installation script will set up the Python environment and an auxiliary cron job.

It’s not recommended to change the default running interval of the cron job. This helps the integration script to recover from potential failures.

if you want to restart or uninstall the integration run the ./restart all and ./uninstall all respectively

Main Script details

To use the script, you must locate yourself on the path selected for deployment (<app_root_path>). Use the following command to show the help command line

python cortex_lumu.py --help

Usage: cortex_lumu.py [options]

OptionsDescription
-h, --helpshow this help message and exit
--config CONFIGCONFIG FILE PATH of the companies(s). (Default: companies.yml)
-v, --verboseVerbosity level (Default INFO)
-l {screen,file}, --logging {screen,file}Logging option (Default screen)
--hours HOURSDatabase maintenance time (USE IT WITH CAUTION)

The script will run as a daemon process. To keep this integration working, you need to guarantee the script is running all the time.

The integration will run smoothly if the configuration within the YAML configuration file is correct. If the script gives errors, solve them based on the log output.

Usage examples

Task: basic usage or standard usage

Use the following command to listen to Lumu operational events and forward alerts in your Cortex XDR instance:

python cortex_lumu.py --config CONFIG -l screen --hours HOURS

The application will run reading the CONFIG file and keep the preceding HOURS tickets/incidents, by default 720 (30 days)

Task: save script log to file

Use the option --logging=file to store a record of all tasks run by the script. Using this, all the script output will be redirected to a file named lumu.log in the folder where you have deployed the script.

python cortex_lumu.py --config CONFIG -l file --hours HOURS

Other tasks

The above samples can be combined according to your needs.

Troubleshooting

To identify failures on the script execution, use the -v flag to activate DEBUG logs. 

The application runs one instance at a time. The script will block multiple attempts to run the same integration if one is already running. If this is the case, the following message appears.

python cortex_lumu.py

Stopping the integration 240023, it might have another older instance running, check if is feasible or not

older pid: 229809 - cwd: /home/lumu/Documents/repos/lumu-cortex-xdr - since: 2024-04-22 19:13:22.410000  

cmdline: /home/lumu/Documents/repos/lumu-cortex-xdr/venv31013/bin/python /home/lumu/Documents/repos/lumu-cortex-xdr/cortex_lumu.py

If the integration throws errors, these can be found in errors.log file in the app directory.

Run it as a Docker container

If you choose to deploy your integrations in a Docker-based model, you must install the Docker engine in your device. Please refer to the Install Docker Engine documentation, and follow the specific instructions for your operating system.

The integration can be deployed in a docker environment. To do so, run the following commands located in the integration folder:

1. Build the Docker image

docker build \
      --build-arg APP_CONFIG=<YAML FILE> \
      --tag img-lumu-cortex-xdr .
Do not forget the dot "."

2. Create and run the Docker container

docker run \
      --restart unless-stopped \
      --log-driver json-file --log-opt max-size=30m \
      --log-opt max-file=3 \
-d \
      --name lumu-cortex-xdr img-lumu-cortex-xdr

Troubleshooting

For troubleshooting purposes, you can run the following commands:

To log in to your container using an interactive shell:

docker exec -it lumu-cortex-xdr bash

To collect integration logs:

docker logs -f lumu-cortex-xdr

Further steps

Once the integration starts running, a test alert is pushed to Cortex XDR. You must use this alert to configure the External Alert Mapping for Lumu alerts. To configure this, log in to your Cortex CDR Web console and go to Settings > Configurations > Data Collection > External Alert Mapping. Follow these steps:

1. Look for the Lumu Lumu row and right click over it. Then, click on the Filter and Map option
2. On the Lumu screen, you will see the sample alert. Click on the Next button.
3. Fill in the mapping fields according to the following table  
       
NameLumu Alerts Mapping
Description[Optional]
Timestamptimestamp
timestamp will ask for Value conversion. Leave as it is and click on the Apply button.

SeveritySeverity
Fill in the mapping values by using this guide [map the values] (Critical: Critical, High: High, Medium: Medium, Low: Low)
Alert NameName
Source IPsource_ip
Descriptiondescription
External Idexternal_id
Categorycategory
Actionaction
Fill in the mapping values by using this guide [map the values] (Reported: Reported , Blocked: Blocked)

Hostnamehostname

Expected results

After running the script, you will see the Lumu-related events (alerts) in the Alerts Table section. 

If there are any incidents creation cause of alerts,they can be seen in the Incident section

The integration only will sync new incidents from the moment you activate the integration. Make sure your integration script is running all the time.

    Still can’t find an answer?
    Send a message to our experts.
    Contact Us

        • Related Articles

        • Wazuh XDR Custom SecOps Integration

          The Wazuh XDR Custom SecOps Integration allows you to poll and push adversary-related events to your Wazuh deployment. After configuring the integration, your Wazuh deployment will be able to receive and process Lumu events. By using it, you will be ...

        • Palo Alto Cortex XSOAR Out-of-the-Box SecOps Integration

          The Palo Alto Cortex XSOAR Out-of-the-box SecOps integration with the Lumu Content Pack for Cortex XSOAR allows you to operate all of your Lumu detections as Cortex incidents. After installing and configuring a new instance of the Lumu Content Pack ...

        • ServiceNow Custom SecOps Integration

          This article shows how to leverage ServiceNow API and Lumu Defender API to enhance your SecOps capabilities, pushing Lumu incidents into a ServiceNow deployment Incident Tickets, and syncing both systems. Requirements ServiceNow active subscription ...

        • GLPI Custom SecOps Integration

          This article shows how to leverage GLPI API and Lumu Defender API to enhance your SecOps capabilities, pushing Lumu incidents into a GLPI deployment as Service Tickets, and syncing both systems. Requirements A GLPI active server and Web access. An ...

        • Chronicle SIEM Custom SecOps Integration

          The Chronicle SIEM Custom SecOps integration allows you to receive Lumu detections and related operating events. In this article, you will find out how to configure your Chronicle SIEM instance and its Lumu integration to enhance your current ...