Using cURL to access the RESTful API of a Palo Alto Networks Firewall

There may be a situation where you would need to access the API of a Palo Alto Networks firewall. Some IT administrators may be more comfortable using cURL to access an API than a scripting language like PYTHON. Here's a few examples of how to perform some tasks using cURL.

The first thing you need to do is get an API key. How do you get an API Key? You query the firewall itself.

?type=keygen is the parameter to use.

curl -k "https://<firewall ip>/api/?type=keygen&user=<username>&password=<password>"

Make sure you wrap your url with Quotes. I tried this before and would get an error 400 response. 

You will get a response in xml. The value for key is the API key.

curl -k "https://192.168.1.1/api/?type=keygen&user=admin&password=admin"

<response status = 'success'>

<result>     

 <key>

   1234....

 </key>

 </result>

</response>

Then you can query the firewall using the API key instead of passing a username and password.

curl -k "https://<firewall ip>/api/?type=<api type>&<parameters>&key=<api-key>"

To get a list of api types and what commands to pass, you can use the REST API browser on the firewall. Just bring up a browser and authenticate against your firewall. After that you can add the path /api to the url.   https://<firewall ip>/api

Here you have the different api "types" you can query the firewall. Each of these types have some caveats as to the way you send your


For our first example, lets execute an operational command. From the cli the equivalent command would be "show system info".


If you drill down the Operational Commands to show system and info you will see the REST API URL at the bottom of the page. This is the url path you would copy to your curl command.

user@ubuntu-vm:~/API/curl$ curl -k "https://192.168.1.1/api/?

type=op&cmd=<show><system><info></info></system></show>&key=<API-KEY>"

<response status="success">

<result>

<system>

<hostname>NG-FW</hostname>

<ip-address>192.168.1.1</ip-address>

<netmask>255.255.255.0</netmask>

<default-gateway>192.168.1.254</default-gateway>

... TRUNCATED...

Notice that the command is in XML format. The firewall takes input and outputs in XML. 

This is important to note as you'll need to know the XPATH for most queries.

The following is to query the hostname with. You will need to add "action=get" as one of the parameters to read the hostname.

user@ubuntu-vm:~/API/curl$ curl -k "https://192.168.1.1/api/?type=config&action=get&xpath=/config/devices/entry\[@name='localhost.localdomain'\]/deviceconfig/system/hostname&key=<API-KEY>"

<response status="success" code="19"><result total-count="1" count="1">

  <hostname>NG-FW</hostname>

Notice that I had to put the literal '\[' for special characters like the square brackets. cURL would complain if I didn't have this.

curl: (3) [globbing] bad range specification in column 78

Now that we did a get. Let's try a set. When we do a set command, we need an extra parameter "element" that will contain the xml of the new content.

user@ubuntu-vm:~/API/curl$ curl -k "https://192.168.1.1/api/?type=config&action=set&xpath=/config/devices/entry\[@name='localhost.localdomain'\]/deviceconfig/system&element=<hostname>test</hostname>&key=<API-KEY>"

<response status="success" code="20"><msg>command succeeded</msg></response>

Doing a get command again shows us the hostname is changed.

user@ubuntu-vm:~/API/curl$curl -k "https://192.168.1.1/api/?type=config&action=get&xpath=/config/devices/entry\[@name='localhost.localdomain'\]/deviceconfig/system/hostname&key=<API-KEY>"

<response status="success" code="19"><result total-count="1" count="1">

  <hostname admin="admin" time="2015/10/14 11:08:11">test</hostname>

Next you need to commit the set command.

user@ubuntu-vm:~/API/curl$curl -k "https://192.168.1.1/api/?type=commit&cmd=<commit></commit>&key=<API-KEY>"

<response status="success" code="19"><result><msg><line>Commit job enqueued with jobid 699</line></msg><job>69

The response code will return a job id.

The last API type I'll cover are logs. Log retrieval is an asynchronous process so you need to query the particular log type first which will create a job id in the response and then query the FW again with the job id. Here’s an example using a threat log.

The first one is to generate the job id.

curl -k "https://<FW-IP>/api/?type=log&log-type=threat&key=<API-KEY>

The second will show you the results after the job task is finished.

curl -k "https://<FW-IP>/api/?type=log&action=get&jobid=<JOB-ID>&key=<API-KEY>

user@ubuntu-vm:~$ curl -k "https://192.168.1.1/api/?type=log&log-type=threat&key=<API-KEY>"

<response status="success" code="19"><result><msg><line>query job enqueued with jobid 3605</line></msg><job>3605</job></result></response>

user@ubuntu-vm:~$ curl -k "https://192.168.1.1/api/?type=log&action=get&jobid=3605&key=<API-KEY>"

<response status="success"><result>

  <job>

    <tenq>17:57:29</tenq>

    <tdeq>17:57:29</tdeq>

    <tlast>17:57:30</tlast>

    <status>FIN</status>

    <id>3605</id>

    <cached-logs>33</cached-logs>

  </job>

  <log>

   ... TRUNCATED ...

  </log>

  <meta>

    <devices>

      <entry name="localhost.localdomain">

        <hostname>localhost.localdomain</hostname>

        <vsys>

          <entry name="vsys1">

            <display-name>vsys1</display-name>

          </entry>

        </vsys>

      </entry>

    </devices>

  </meta>

Gathering and graphing snmp stats on a Palo Alto Networks Firewall

So I was task to the challenge of gathering cpu utilization and active sessions on a Palo Alto Networks Firewall.

There are two CPUs on a Firewall. There is a management plane cpu and a data plane cpu.

The OIDs are below.

Active sessions: .1.3.6.1.4.1.25461.2.1.2.3.3

MGMT Utilization: .1.3.6.1.2.1.25.3.3.1.2.1

Data Plane Utilization: .1.3.6.1.2.1.25.3.3.1.2.2



The first step is to enable snmp on the Firewall.

Under

Device/Setup/Operations/Miscellaneous/SNMP Setup

enter your community string and pick the version.

Now I'm using unsecured snmp v2 because I didn't know how to use snmpv3 on the Splunk Application that I'm going to use to generate charts.

on an ubuntu vm I tested it.

admin@ubuntu-poc-vm:~$ snmpget 10.48.64.112 -v 2c -c public .1.3.6.1.2.1.25.3.2.1.3.2
iso.3.6.1.2.1.25.3.2.1.3.2 = STRING: "Slot-1 Data Processor"
admin@ubuntu-poc-vm:~$ snmpget 10.48.64.112 -v 2c -c public .1.3.6.1.2.1.25.3.2.1.3.1
iso.3.6.1.2.1.25.3.2.1.3.1 = STRING: "Management Processor"
admin@ubuntu-poc-vm:~$ snmpget 10.48.64.112 -v 2c -c public .1.3.6.1.2.1.25.3.3.1.2.1
iso.3.6.1.2.1.25.3.3.1.2.1 = INTEGER: 23
admin@ubuntu-poc-vm:~$ snmpwalk 10.48.64.112 -v 2c -c public .1.3.6.1.2.1.25.3.3.1.2.2
iso.3.6.1.2.1.25.3.3.1.2.2 = INTEGER: 5


Next I setup Splunk on a Windows 7 VM. It was pretty easy as you go to their website and download the app for your particular flavor of OS.

Once installed you hop onto the webui and change your credentials.

Next you need to install the SNMP Modular Input app. It's free.

Then you need to go Settings > Data Inputs > SNMP > Add New

Here I created a new input for each SNMP OID that I wanted to query.

 There's a reason for this. I could have added a list of OIDs using comma delimited but I had a hard time trying parsing the data I wanted to graph. If someone has a better method let me know.

Last I used set source type to Manual and the actual source type to "snmp_ta" which is the SNMP Modular app.

Next I went to Manage App and looked for snmp_ta app and edited the permissions. I made the app visible.

A new icon appears in the dashboard and now I can double click it to examine the data being polled.

I first click on data summary and select the source tab and choose your source.

I should now see all the data that SNMP Modular Input queried from the firewall.

Now it's time to manipulate the data and create some nice graphs. First I have to manipulate the search fields.

I add a pipe and enter fields value.

This will specifically give me the value what is return from the SNMP OID.

Next I choose the Visualization tab and click on Pivot. I will only have 1 field to use which is the value field.

 

Next I choose the graph I want to create. I chose line chart.

 Then on the Y Axis I make sure the field says #value and I can label this as Data Plane CPU.

Then on the X Axis side I choose _time which will graph the data collected over time.

Make sure the Null Values say connected to give me a nice line graph instead of a bunch of dots.

Last I save this panel and give it a name so I can put it on my Dashboard.

Now you may say, Big deal, all this work to do that. I can just spin up Solar Winds and it's really easy. No need to create search queries and add pipes and then do all this to create one graph. Well the reason for using Splunk is that Palo Alto Networks has a nice plug-in (it's free) that works directly with Splunk. So with one tab I can check on all the traffic, threats and wildfire data collected and on the other tab I can look at the CPU Utilization and Session counts. This gives me one single pane of glass instead of having to jump onto different management tools to give me the same information.

Automating a Palo Alto Networks Firewall using Python

In my last post I used a python script to extract information from a Palo Alto Networks Firewall using pan-python. In this post I'll illustrate how to configure a firewall using the API.

Palo Alto Networks uses XML as the data structure for it's representation of the configuration file. Automating a firewall takes three steps.

• Creating the xml file
• Pushing the xml file to the firewall
• Committing the candidate configuration

 I created a sample xml configuration file that would add an IP address to a sub-interface with a vlan tag of 1 on interface ethernet1/3.

<entry name="ethernet1/3">
  <layer3>
    <units>
      <entry name="ethernet1/3.1">
        <tag>1</tag>
        <ip>
          <entry name="30.4.1.2/24"/>
        </ip>
      </entry>
      </entry>
    </units>
  </layer3>
</entry>

This is going to be placed into a text file called sub-int.xml which I'll use later.

In my script I read from the file and and place it into a variable called data. I strip the newlines so that I don't have separate each line into an array.

Last you need to commit the config. One thing about the api is that the commit call needs an xml element <commit/>

When I tried it without a cmd ie. xapi.commit(), I got the following error.


pan.xapi.PanXapiError: Missing value for parameter "cmd".

This was confusing at first, until I spoke with a Palo Alto networks Solutions Architect about it and he explained that you need to tell it which type of commit you want. There are a few options such as commit, commit partial and commit full. I think there should be a default setting.  Commit without any input should mean a normal commit. Maybe I'll modify a git cloned repository.


script
-----------
import pan.xapi
from cred import get_pan_credentials
credentials = get_pan_credentials()

print credentials
xapi = pan.xapi.PanXapi(**credentials)

xpath = "/config/devices/entry/network/interface/ethernet"

#open xml file and read it into a variable called data.
with open ("sub-int.xml", "r") as myfile:
    data=myfile.read().replace('\n', '')

#set the config using the above xpath
xapi.set(xpath,element=data)

#commit the config. Make sure to add the xml command.
xapi.commit('<commit/>')



-------------

Here's the resulting screen cap: