Working with Address Groups
This tutorial covers how to add & populate Static and Dynamic Address Groups to PAN-OS using API. If you are looking into adding IPs to Dynamic Address Groups using the Dynamic Address Group API, please refer to the dedicated tutorial.
This tutorial has 2 sections: the first section covers static Address Groups, the second section covers Dynamic Address Groups.
#
RequirementsTo follow this tutorial, it is recommended that that you are familiar with the concepts of Palo Alto Networks Next-Generation Firewalls, Security Policies and APIs. Some basic understanding of XML is also recommended.
Make sure you have a Palo Alto Networks Next-Generation Firewall deployed and that you have administrative access to its Management interface via HTTPS. To avoid potential disruptions, it's recommended to run all the tests on a non-production environment.
No specific programming language expertise is required, although Python is recommended. Examples with both XML API, REST API and pan-python are provided.
#
Static Address GroupsStatic Address Groups are address groups whose content is statically defined inside the PAN-OS configuration. They are traditional Address Groups. To change the members of a static address groups, you should change the PAN-OS config and commit.
#
Steps- Grab the API Key
- Create an Address object (optional)
- Create an Address Group
- Edit the Address Group (optional)
- Commit!
#
Step 1: Grab the API Key- XML API
- REST API
- pan-python
Please refer to the XML API Quickstart for instructions.
Please refer to the REST API Quickstart for instructions.
Please refer to the pan-python guide for details.
#
Step 2: Create an Address object (optional)Static Address Groups cannot be empty. If you don't have an Address object already defined or you don't want to use it, you should create at least an Address object before creating the Address Group.
The following code will create a new Address object called TutorialEntry
with IP 1.1.1.1/32
(Hello there Cloudflare!)
- XML API
- REST API
- pan-python (CLI)
- pan-python (Python)
The following code is for a Unix shell. To avoid fighting with string escapes, we use environment variables to store API Key, XPath and the new entry.
Response should be:
Response should be:
Response should be:
#
Step 3: Create the Address GroupNow we can create our static Address Group, we will call it TutorialAddressGroup.
- XML API
- REST API
- pan-python (CLI)
- pan-python (Python)
The following code is for a Unix shell. To avoid fighting with string escapes, we use environment variables to store API Key, XPath and the new entry.
Response should be:
Response should be:
Response should be:
#
Step 4: Edit the Address Group (optional)We could commit now, but for the sake of this tutorial let's edit the address group we created to add a new entry and remove the existing one.
Before starting, create a new Address object called TutorialEntry2 following Step 2.
- XML API
- REST API
- pan-python (CLI)
- pan-python (Python)
We can use an edit request here for the PAN-OS XML API. It is a bit weird, as the element should overlap with the XPath (<static>
appears on both XPath and inside the element).
Response should be:
Using PUT we can replace the existing definition of the AddressGroup with a new one:
Response should be:
Response should be:
#
Step 5: Commit!This is where pan-python and the SDKs start shining. The commit process via the API is asynchronous and has 2 steps:
- Send the commit request. This will start a commit job and return a job id
- Periodically check with the API the status of the job. When the job has finished the API response includes the commit result
This process is easy to implement with the SDKs as they include functions to issue the commit request and automatically follow the resulting job.
- XML API
- REST API
- pan-python (CLI)
- pan-python (Python)
Let's do a commit in the hard way. First we send the request and then we follow the job using curl
.
Response should be (jobid will be different):
Now with the jobid we can poll the API to check the status of the job:
When the commit job is still running, the status will be ACT:
Once finished, the status will be FIN and you can check if the commit was successful by looking at the <result>
tag:
Not supported yet use the PAN-OS XML API to commit.
pan-python can do all the tracking work for you. Just use the --sync
command line argument to tell panxapy.py
to start tracking the commit job:
Response should be similar to:
The pan-python library exposes a nice function to start the commit and track the job for you (note sync=True in the commit call):
#
Dynamic Address GroupsDynamic Address Groups are defined as boolean expressions over IP tags. Every time an IP is tagged using the Dynamic Address Group API, PAN-OS evaluates the expression associated with a Dynamic Address Group. If the result is true, then the IP is automatically added to the Dynamic Address Group.
Dynamic Address Groups is a powerful mechanism that could be used to cover many use cases, for details about populating the Dynamic Address Group refer to the dedicated tutorial.
#
Steps- Grab the API Key
- Add a new Dynamic Address Group
- Commit!
- Populate the Dynamic Address Group
#
Step 1: Grab the API KeySee Step 1 of Static Address Groups
#
Step 2: Add a new Dynamic Address GroupThe content of a Dynamic Address Group is not a static list of Address objects, like for Static Address Groups, but a filter. A filter is a boolean expression built on IP tags.
In this example we will create a new Dynamic Address Group called TutorialDAG with filter tag1 AND tag2
. All the IPs pushed via the DAG API with both tag1
and tag2
will be automatically added to this DAG.
- XML API
- REST API
- pan-python (CLI)
- pan-python (Python)
Note the element content is URL encoded:
Response should be:
Response should be:
Response should be:
#
Step 3: Commit!See Step 5 of Static Address Group section
#
Step 4: Populate the Dynamic Address GroupNot covered here, check the dedicated tutorial