You can talk to firewalls and Panorama from Palo Alto Networks in various ways. The well-known GUI (which I really love, by the way) and the CLI are quite common at first glance. Nearly everyone using the Palos is familiar with these configuration options.
When it comes to automation at some point, either to configure those devices or just to read out some KPIs for your monitoring, APIs are in place. Plural because Palo has two APIs: The so-called “XML API” and the “REST API“. Let’s get started with both of them:
First things first: Why are there two APIs? What are the differences?
For this post, I’m using Postman v11.1.14 and a PA-440 with PAN-OS 11.2.0. The starting point for all API documentation is https://<FQDN-of-your-firewall-or-panorama>/api.
Authentication
Regardless of which API you’re using, you first have to get an API key which is used for authenticating every single API request later on. Of course, you need an admin account which is allowed to use the API, configurable through “Admin Roles”. (PANW: Enable API Access.) Please use the “POST” method (data in the body) rather than “GET” (data in URL) to avoid presenting your username & password in the web server log! [Thanks to Sven W. for the hint.] Using cURL this looks like:
1 |
curl --location https://pa-mgmt.weberlab.de/api/?type=keygen --request POST --data "user=weberjoh&password=ThisIsThePassword" |
While the response shows the API key:
1 2 3 4 5 |
<response status = 'success'> <result> <key>1xrfg6kEHM7EAV2psz6n1xrfg6kEHM7EAV2psz6n1xrfg6kEHM7EAV2psz6n1xrfg6kEHM7EAV2psz6n1xrfg6kEHM7EAV2psz6n1xrfg6kEHM7EAV2psz6n1xrfg6kEHM7EAV2psz6n1xrfg6kEHM7EAV2psz6n==</key> </result> </response> |
Using Postman with some variables my “Get API Key” request looks as follows:
Copy this received API key into its own variable, e.g. {{palo-api-key}}. For the remainder, I’m using several variables within Postman. The “location” and “vsys” variables are mandatory for the REST API later on. Note the “secret” type for passwords/keys:
Note that your generated API key is valid indefinitely by default. You can change this behaviour (and/or “expire” all current API keys) at Device -> Setup -> Management -> Authentication Settings:
“XML API”
With the XML-based API, you can do everything which can be done through the GUI/CLI as well. (Internally, the GUI and CLI are using this XML API as well.) That is: Configuring the whole firewall (template/device group) incl. commit, but also showing everything.
Start exploring the API within your browser by accessing the following URL:
1 |
https://<FQDN-of-your-firewall-or-panorama>/api |
You’ll find the CLI command structure, e.g. the “show” commands within the “Operational Commands” section:
Sending a “show system info”, for example, will be this:
1 |
{{palo-url}}/api/?type=op&cmd=<show><system><info></info></system></show> |
A “show counter global filter severity drop” will be this:
1 |
{{palo-url}}/api/?type=op&cmd=<show><counter><global><filter><severity>drop</severity></filter></global></counter></show> |
debug cli on
Another way to identify the corresponding API request to a known CLI command is the usage of debug cli on within the CLI itself. With this, you’ll see the XML line when using CLI commands which you can use for your scripts, e.g.:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
weberjoh@pa> debug cli on weberjoh@pa> show session info (container-tag: session container-tag: info pop-tag: pop-tag:) ((eol-matched: . #t) (context-inserted-at-end-p: . #f)) <request cmd="op" cookie="4212596744180554" uid="1001"><operations><show><session><info/></session></show></operations></request> 2023-12-14 12:49:21 <response status="success"><result><![CDATA[target-dp: *.dp0 -------------------------------------------------------------------------------- Number of sessions supported: 199998 Number of allocated sessions: 735 Number of active TCP sessions: 101 Number of active UDP sessions: 540 Number of active ICMP sessions: 67 Number of active GTPc sessions: 0 Number of active HTTP2-5gc sessions: 0 |
“REST API”
This API is more standardised compared to the XML API. The REST-based API can be used for CRUDding objects, policies, and network stuff. (It is not implemented to get KPIs such as routing tables, interface statistics, or hardware metrics.) Start exploring the usable objects at your NGFW/Panorama GUI again:
1 |
https://<FQDN-of-your-firewall-or-panorama>/restapi-doc/ |
The input and outputs are in JSON now. (This is a good thing compared to the outdated XML API approach.) Anyway, if needed you can specify the output to be XML again.
Getting all address objects, for example, is this (GET). Note the query parameters of the “location” and “vsys”, for which I’m using Postman variables:
1 |
{{palo-url}}/restapi/{{palo-restapi-version}}/Objects/Addresses?location={{palo-location}}&vsys={{palo-vsys}} |
Tip: I’m using JSON Crack to visualise such output: (shortened screenshot)
Showing a single address, referenced by its name, is this (GET):
1 |
{{palo-url}}/restapi/{{palo-restapi-version}}/Objects/Addresses?location={{palo-location}}&vsys={{palo-vsys}}&name=h_ib1.weberdns.de_v6 |
Adding a new address object goes like this (POST):
1 |
{{palo-url}}/restapi/{{palo-restapi-version}}/Objects/Addresses?location={{palo-location}}&vsys={{palo-vsys}}&name=h_new-test-address |
with a body of:
1 2 3 4 5 6 7 8 9 10 11 |
{ "entry": { "ip-netmask": "7.7.7.7", "tag": { "member": [ "TEMP" ] }, "@name": "h_new-test-address" } } |
Editing (PUT) and deleting (DEL) objects are quite similar.
And finally, as always, a commit (POST) without any params:
1 |
{{palo-url}}/restapi/{{palo-restapi-version}}/System/Configuration:commit |
Soli Deo Gloria.
Photo by Lenny Kuhne on Unsplash.
Hi Johannes,
nice article! I have one question: Where did you find the REST endpoint for the commit? (/restapi/{{palo-restapi-version}}/System/Configuration:commit)
I searched in the swagger UI and did quite a lot of research – but never found the REST API method for doing a commit – only the ones for XML API.
Are there even more things on the “system”-endpoint that we can do via REST API?
Regards
Michael
Hey Michael.
I found it under the REST API doc: https:///restapi-doc/ at the very end (System -> Configuration). Maybe they have added this with PAN-OS 11.2, since I can’t find it on a PAN-OS 11.1 firewall as well. ;) Which PAN-OS version are you using currently?
Moin Johannes, vielen Dank für den Hinweis! Das ist immer wieder blöd gwesen, wenn man alles über Rest macht, aber den commit dann über xmlapi machen musste! Leider muss ich aber erstmal auf 10.2 bleiben.
Gruß
Christian
Ahh ok that would explain it. We are using v11.1.2-h3