Getting started with Palo Alto REST API

PanOS REST API is an incredibly powerful tool to manage both Palo Alto Firewalls and Panorama through various API platforms such as Postman, Python or even CLI. Using the API for a while, I find it extremely useful especially working with larger configuration files. You can easily scrape through the entire configuration tree and find only the elements that you need.

What is a REST API?

API stands for Application Programming Interface, which is a way to communicate between different applications/services. In simpler terms, it is a set of rules that allow two systems to talk to each other. The server exposes the API and allows the client to talk to it.

Most APIs in the world are RESTful which means they follow a set of rules or constraints known as Representational State Transfer. RESTful API organizes resources into unique URIs that differentiate different types of resources (Objects, Security Policies, NAT Policies etc) on a server. The client can then request a particular resource by making a request over HTTP.

A REST API is like a waiter at a restaurant that helps different software programs talk to each other. Imagine you're at a restaurant with your friends, and you want to order some food. You don't go into the kitchen and cook the food yourself, right? Instead, you give your order to the waiter, who takes it to the kitchen. The chef prepares your food, and the waiter brings it back to you.

In this scenario, the REST API is the waiter, and the different software programs are you and the kitchen. REST stands for "Representational State Transfer," and API stands for "Application Programming Interface." So, a REST API is a set of rules or guidelines that software programs follow to communicate with each other, request information, or send data.

You might think that the CLI and Web-GUI already provide robust management to the firewall so, why do I need another option? In this blog post, we will go through the PanOS REST API fundamentals and some of the use cases.

💡

Please note that the firewalls and Panorama support two types of API: XML and REST. This blog post examples solely focus on REST API.

The XML API uses a tree of XML nodes to map firewall or Panorama functionality. To make an API request, you can specify the XPath to the XML node that corresponds to a specific setting. XPath allows you to navigate through the hierarchical XML tree structure of the firewall.

REST API on the other hand uses CRUD (Create, Read, Update and Delete) to view, create, delete or make changes to the firewall/panorama configurations.

Getting started with PanOS REST API

API Key

To access the API (XML or REST), we need to enable API access for the firewall administrators and get the API key. If the Admins are part of the built-in roles such as 'superuser', they should already have access to the REST API and we just need to generate the API Key. It is recommended to use a dedicated user account for API access and provide the least amount of access.

For this example, I'm going to create an 'admin-role' with only access to the REST API and associate an 'Admin' account with it.

You can generate the API Key by making a GET or POST request to the firewall using the following syntax, curl -k -X GET 'https://<firewall>/api/?type=keygen&user=<username>&password=<password>'

suresh@mac:~|⇒  curl -k -X GET 'https://palo-lab.local/api/?type=keygen&user=rest-api-user&password=Password123'

<response status = 'success'><result><key>LUFRPT1ueFpaNXFCUGM2ckxXNGFIeVRscVkrL21tZHM9aldDN1pQMUxMN0FDRCtIa0tUczBSbHhlTDZtZWFUb1F4d3FhSnpRTVVwS3VsYXlxblODJFS2xWczUwL3FlRQ==</key></result></response>%

Please copy the API key and store it in a secure place such as a Password Manager. We will use this Key throughout the examples.

If you want to retrieve the key using Python, here is how to do it

import requests
import xml.etree.ElementTree as ET

query = {'type':'keygen', 'user':'rest-api-user', 'password':'Password123'}

response = requests.get('https://palo-lab.local/api', params=query, verify=False)

# Parse the XML string
root = ET.fromstring(response.text)

# Find the key element and get its text
api_key = root.find(".//key").text

print(api_key)

REST API Document

You can access the REST API documentation by navigating to the following URL, https://FIREWALL_IP/restapi-doc as shown below. You can explore the different URIs, query parameters and body requirements available to make a successful API call.

First API Call

By default, the firewall and Panorama support API requests over HTTPS. To authenticate the API request to the firewall or Panorama, provide the API key in any of the following ways:

Use the custom HTTP header, X-PAN-KEY: <key> to include the API key in the HTTP header.
For the XML API, include the API key as a query parameter in the HTTP request URL. (not applied to REST API)

💡

Some of the tutorials I've seen mention passing the API-Key as a Query Parameter (PanOS 9.x) however, this method doesn't seem to be working on 10.2

GET - Address / Objects

Let's make a GET request to retrieve all the Address Objects configured on the firewall. I'm using Postman to send the API calls however, you can choose whichever platform is available to you.

The API Doc below shows all the information we need to make the API call which are the URL, URI and query parameters.

Location is the mandatory query parameter, since we are connecting to the Firewall, the location will be the vsys. If you are connecting to the Panorama, the location would become device-group.

I'm also specifying the API key within the Headers as shown below.

Once you hit 'send', you will get a JSON output which contains all the objects currently configured on the firewall.

CURL

Alternatively, you can use the CURL command to make the API call as shown below. My personal preference is to use Postman whenever possible.

curl -X GET 'https://palo-lab.local/restapi/v10.2/Objects/Addresses?location=vsys&vsys=vsys1' -H 'X-PAN-KEY: LUFRPT0wVGgrZ2VCb082WFNKWmRha0puUnZodE9sWXc9aldDN1pQMUxMN0FDRCtIa0tUczBSbHhlTDZtZWFUb1F4d3FhSnpRTVVwS2ZaK0I0N2pTVE5TaXhQQndPbysxeQ==' -k | jq

{
  "@status": "success",
  "@code": "19",
  "result": {
    "@total-count": "3",
    "@count": "3",
    "entry": [
      {
        "@name": "Google-DNS",
        "@location": "vsys",
        "@vsys": "vsys1",
        "ip-netmask": "8.8.8.8/32"
      },
      {
        "@name": "SMTP-SERVER",
        "@location": "vsys",
        "@vsys": "vsys1",
        "ip-netmask": "192.178.10.8/32"
      },
      {
        "@name": "CLIENT-SUBNET",
        "@location": "vsys",
        "@vsys": "vsys1",
        "ip-netmask": "10.2.35.0/24"
      }
    ]
  }
}

POST - Address / Objects

We can also use the API to create (POST) various resources on the firewall. The following example shows how to create an Address Object via the API.

One of the additional parameters required for POST is the Name of the Object. The body of the request should be JSON as shown below. You can find all of the required parameters from the restapi-doc URL I mentioned above.