Palo Alto Next-Gen Firewall Custom Integration with Lumu Defender API

Palo Alto Next-Gen Firewall Custom Integration with Lumu Defender API

Before going through this article, check our Out-of-the-box App Integrations category. This is the recommended way to integrate the components of your cybersecurity stack with Lumu. If the product you are looking to integrate is there, it is advised to use that integration instead.
The Lumu Defender API offers a framework to help you leverage Lumu’s integrations with your existing cybersecurity stack, including Security Information and Event Management (SIEM), Security Orchestration, Automation, and Response (SOAR), Endpoint Detection and Response (EDR); incident response systems; and more.
To get started with the Lumu Defender API, consult our get started documentation .

This article shows how to leverage adversarial information from Lumu and feed Palo Alto Dynamic Address Groups (DAG) and Custom URL Category.

Typical setup of Palo Alto with Lumu Defender API Typical setup of Palo Alto with Lumu Defender API.
This article is just an example of how this integration can be carried out and is delivered as is, so please use it at your own discretion. 

Requirements

  1. Palo Alto firewall with PANOS 9.0+.
  2. Dedicated administrator user in Palo Alto Firewall for Lumu integration.
  3. A host to deploy the scripting code. This host must be able to reach both Palo Alto and Lumu Defender API host ( https://defender.lumu.io ).
  4. Python 3.6+.
  5. Requests module for Python from PyPI .
  6. Pan-os-python module from  PyPI .
A Dynamic Address Group (DAG) and Custom URL Category are required, these objects must be used in security policies to achieve IP and URL filtering.

Install Requests and pan-os-python modules

The modules must be installed in the script host you selected. The following commands can be used to install the requests package for Python libraries. Use the one that best suits you. This module allows you to send HTTP requests using Python .

Option 1: pip :

[sudo] pip install requests

Option 2: easy_install :

[sudo] easy_install requests

The following command install the pan-os-python package (using pip ):

[sudo] pip install pan-os-python

Deploy the script

First, contact the Lumu support team  to request the package we created to deploy the required files.

Script location

Once you receive the Python package provided by Lumu, unpack the file in your preferred path / folder. Keep in mind, this location will be required for further configurations. This folder will be referred from now on as <paloalto_lumu_root> .

Script details

For using the script, you must locate yourself on the path selected for deployment ( <paloalto_lumu_root> ). Use the following command to show all options available for the package:

<paloalto_lumu_root>$python lumu-to-paloalto.py --help

This is a reference of the options you have access to through this script:

lumu-to-paloalto.py [option]

Option

Description

-h, --help

show the help message and exit

--config=CONFIG

Load options from config file

- --hostname=HOSTNAME

From Palo Alto firewall

--username=API_USERNAME,
--user=API_USERNAME

Palo Alto user

--password=API_PASSWORD

Palo Alto password

--vsys=VSYS

Specify the vsys target (vsysN)

--tag=TAG

Tag to be used to register IP IoCs

--custom-url-category-name=CUSTOM_URL_CATEGORY_NAME

Custom URL Category name to use for recording domains

--dag

Indicates if you want to feed a Dynamic Address Group

--custom-url-category

Indicates if you want to feed a Custom URL Category

--overwrite-category

Indicates if you want to replace the Custom URL category

--include-subdomains,
--include_subdomains

Indicates if we must include subdirectories for Custom URL Category

--include-subdirectories,
--include_subdirectories

Indicates if we must include subdirectories for Custom URL Category

--commit

Indicates if the script will commit the changes on Custom URL Category

--company-key=COMPANY_KEY,
--company_key=COMPANY_KEY

Lumu Defender API key

--logging=LOGGING

Logging option (default screen)

-v, --verbose

Verbosity level of the log

-t, --use-saved-timestamp

Indicates the script to use the saved timestamp from the latest adversary contact, if any

--hours=HOURS

To specify a number of past hours

--from=FROM

To specify a specific “from” date

--adversary-types=ADVERSARY-TYPES

To specify the adversary type to filter (case-sensitive). Possible values are: C2C, Malware, DGA, Mining, Spam, Phishing

Considerations

You can populate the following Custom Objects in Palo Alto configuration:

  1. Dynamic Address Groups: to store and block IP IoCs.
  2. Custom URL Categories: to store and block URLs based on adversary domains.

You can run the script to populate any of the above or both of them. Following, you can see the flags for each option:

Dynamic Address Group (DAG)

For populating a Dynamic Address Group, you can use the --dag flag together with the --tag parameter, as in the following example:

python lumu-to-paloalto.py --hostname x.y.z.w --username lumu-admin --password changeme --company-key XXXxxXXXXxxxx --dag --tag lumu-iocs

By default, the script feeds the Dynamic Address Groups without overwriting its content. If you want to fully overwrite the group, you can use the flag --overwrite-dag .

Custom URL Category

For populating URL in a Custom URL Category, you can use the --custom-url-category flag and define the name of the category using the --custom-url-category-name parameter, as in the following example:

python lumu-to-paloalto.py --hostname x.y.z.w --username lumu-admin --password changeme --company-key XXXxxXXXXxxxx --custom-url-category --custom-url-category-name "Lumu Blocklist"

By default, the script feeds the Custom URL Category without overwriting its content, to fully overwrite the category, you can use the flag --overwrite-category . To add wildcards to the URLs to block subdomains or subdirectories, combine the flags --include-subdomains and - -include-subdirectories . These flags will add the strings *. and /* in the beginning and at the end.

Note : Remember to commit your changes after feeding the Custom URL Category. To do so, use the flag --commit .

Usage examples

We provide here some examples of how to use the script:

Task: query and add all adversarial data for the last 30 days

Use the following command for querying and posting to Palo Alto all adversarial data found in your organization by Lumu in the last 30 days:

<paloalto_lumu_root>python lumu-to-paloalto.py --hostname x.y.z.w --username lumu-admin --password changeme --company-key XXXxxXXXXxxxx --dag --tag lumu-iocs --custom-url-category --custom-url-category-name "Lumu Blocklist" 

With this script, you will query the latest 30 days of contacted adversaries recorded in your Lumu Subscription. Only new IoCs will be fed in your Dynamic Address Group or your Custom URL Category .

Task: query and add all adversarial data since the last runtime

For control purposes, the script stores the latest runtime in a file called timestamp.stmp . If it is the first time you run the script, you will automatically get all the data of the last 30 days. The next time you run this query, it will get the latest runtime timestamp from the timestamp.stmp file.

<paloalto_lumu_root>/python lumu-to-paloalto.py --hostname x.y.z.w --username lumu-admin --password changeme --company-key XXXxxXXXXxxxx --dag --tag lumu-iocs --custom-url-category --custom-url-category-name "Lumu Blocklist" --use-saved-timestamp

To ignore the saved timestamp, remove the --use-saved-timestamp flag.

Task: Query and add all adversarial data of the last X hours

Use the following command to query all adversarial data from your Lumu subscription for the specified numbers of hours:

<paloalto_lumu_root>/python lumu-to-paloalto.py --hostname x.y.z.w --username lumu-admin --password changeme --company-key XXXxxXXXXxxxx --dag --tag lumu-iocs --custom-url-category --custom-url-category-name "Lumu Blocklist" --hours X

Task: query and add all adversarial data since a specific date

For filtering data from a specific date, use the flag --from followed by a date string in the standard format published in RFC 3339 and ISO 8601: YYYY-MM-DDTHH:mm:ss:sssZ.

<paloalto_lumu_root>/python lumu-to-paloalto.py --hostname x.y.z.w --username lumu-admin --password changeme --company-key XXXxxXXXXxxxx --dag --tag lumu-iocs --custom-url-category --custom-url-category-name "Lumu Blocklist" --from 2021-05-01T00:00:00.000Z

Task: filter adversarial types

To query filtered adversarial types before adding them to your Palo Alto Dynamic Address Group or Custom URL Category, use the parameter --adversary-types followed by a list of the adversarial types separated by commas.

For this particular example, the adversary types to filter are C2C , Phishing , and DGA :

<paloalto_lumu_root>/python lumu-ioc-to-crowdstrike.py --url https://api.us-2.crowdstrike.com --client-id XXXXXXX --client-secret YYYYYYYY --company-key ZZZZZZZZZ --hours 24 --adversary-types C2C,Phishing,DGA

Task: save output to file

Use the parameter --logging file to store a record of all tasks run. With this parameter, all the script output will be redirected to a file named lumu.log in the root of the selected path for the deployment of the script ( <paloalto_lumu_root> ).

<paloalto_lumu_root>/python lumu-to-paloalto.py --hostname x.y.z.w --username lumu-admin --password changeme --company-key XXXxxXXXXxxxx --dag --tag lumu-iocs --custom-url-category --custom-url-category-name "Lumu Blocklist" --hours 24 --logging file

Note : The samples mentioned in this article can be combined according to your needs. Bear in mind that --hours and --from parameters are mutually exclusive. If both parameters are present, then --hours will be used.

Expected results

For each script run, it is expected that the defined Dynamic Address Group and Custom URL Category will be populated with more indicators, as in the following examples:

Dynamic Address Group Dynamic Address Group

Custom URL Category Custom URL Category
Remember that you need to configure each object into a Security Profile and a URL Filtering Profile. 
Security Policy Security Policy

URL Filtering Profile

URL Filtering Profile

Further considerations

To run this script on a timely-basis, consider implementing a scheduled job in Windows or a cron task in Unix-based systems. We recommend using the --use-saved-timestamp flag to query and add different adversarial data for each runtime.

Troubleshooting

Use the -v flag to investigate errors on the script. This will provide you with details for identifying failures in the script execution.


        • Related Articles

        • Palo Alto Next-Gen Firewall Out-of-the-box Response Integration

          To learn more about Out-of-the-box Integrations and their benefits, please refer to this article. This article shows how to create an external block list using Palo Alto Next-Gen Firewall. Requirements Palo Alto Next-Gen Firewall A Lumu Defender ...
        • Crowdstrike Custom Response Integration with Lumu Defender API

          Before going through this article, check our Out-of-the-box App Integrations category. This is the recommended way to integrate the components of your cybersecurity stack with Lumu. If the product you are looking to integrate is there, it is advised ...
        • Custom Integrations - Lumu Defender API

          For getting started with Lumu integrations with third-party solutions, consult our Integrations guide. The Lumu Defender API offers a framework to help you leverage the value of existing investments by integrating Lumu’s real-time information on ...
        • ConnectWise Manage Custom Integration with Lumu Defender API

          Before going through this article, check our Out-of-the-box App Integrations category. This is the recommended way to integrate the components of your cybersecurity stack with Lumu. If the product you are looking to integrate is there, it is advised ...
        • Microsoft Defender Custom Response Integration

          This article shows how to leverage the Lumu Defender API to integrate API indicators from Windows Defender Requirements Lumu Defender API key. Windows Defender Cloud (Endpoint Plan 1 or 2) Azure Application The Azure application must have API ...