In what I hope is a continuing series, I return with more information on using the Palo Alto API. Our previous post gave the introduction of the Request-PaloApi function, where we convert a Type, an Action, and their qualifiers to a web request. Today, we take a step back, and determine how to find the information for those qualifiers.
Palo Alto Management
The Palo Alto GUI replaces most of the functionality of the previously used CLI interface, making adoption a shade simpler, as it requires less rote memorization of commands and their parameters. This layer of obfuscation is helpful, in that it presents all necessary information in a simple to digest manner. However, when performing our tasks via the API, we want to remove that layer, and understand the actual process underneath.
One side benefit of using being within the GUI is that it contains a way for us to see what going on behind the scenes. Navigating to the IP of the Palo Alto normally takes you to the management front-end for the device. However, two other options exist to get more information. Navigating to the Palo Alto address /api takes you to a copy of the API Browser. The API browser contains a catalog of commands you can run and transfer into your code. Also residing within is a link to the API documentation, allowing you to get more information on the product.
While not shying away from reading the manual, there are some extra shortcuts that exist to make the transition to the API that much simpler. Even with the API browser, understanding what exact variables you need to change can be daunting or time consuming. This is where the debug menu becomes a fantastic ally.
Debug Menu Introduction
Similar to navigating to the API browser above, navigating to /debug provides another level of insight to our device. Upon initial launch of the debug menu, you will be greeted with what is likely a noisy and slightly overwhelming window. We can remedy this scenario, and prepare for our next steps by clicking twice. Initially on the Clear Debug button, and a second time on the debug checkbox. These steps clear the window, and ensure we receive full commands within it later.
Now that the debug window is clear, we should make use of it. Navigate back to the Management GUI, and do some configuration. Head to the network tab, and prepare an interface for use. Selecting Interface 1/5, we can configure it as an HA interface. Prior to selecting OK, it is a good idea to switch back to the debug window, and once again use the clear debug window. Acclimating yourself to this process will make the debug logs easier to review when we get to them. Upon clearing the log, we can then select OK, and initialize the interface.
The interface is online, and we can return to the debug menu. Upon return, the window will still be blank. Update the information using the refresh button within page. As it populates, it resembles what we were initially greeted with, a sizable amount of text, with little direction.
However, we do not need to worry about the plethora of information onscreen. Modifying a configuration through the GUI will typically result in one of three actions, Set, Edit, or Delete. Palo Alto provides a full list of configuration modification actions as well here. When reviewing the debug logs, we can use them as a start, to find what settings we manipulated.
Some of the eagle-eyed among us have already located the information we want to grab next. Within the image above, thanks to clearing the debug window prior to running the command, one of the top commands is a Set request, that if we follow along, points at interface 1/5.
<request cmd="set" obj="/config/devices/entry[@name='localhost.localdomain']/network/interface/ethernet/entry[@name='ethernet1/5']" cookie="6814035851546102" newonly="yes"> <ha/> </request>
We can now begin dissecting the request above. As a reminder about the Request-PaloApi function, we care about Type, Action, XPath, and Element. Reviewing the command start, we know that the Action is Set, and via the Palo Alto link above, we know this will be a request Type of Config. Halfway there, we can obtain the other information fairly simply as well.
The XPath is the location of the object that is changing, here that can be seen as what follows obj=. Element informs what our setting will be. This will be the information located between the request tags (<request></request>). Using this information, we can populate our Request-PaloApi function.
Request-PaloApi -ipAddress $ipAddress ` -paloKey $paloKey ` -apiType 'config' ` -apiAction 'set' ` -apiXpath "/config/devices/entry[@name='localhost.localdomain']/network/interface/ethernet/entry[@name='ethernet1/5']"` -apiElement '<ha/>'
This provides us an easy shortcut to getting information about our commands, allowing us to re-use them for automation or hands-off administration. A word of warning, however, some commands can be misleading when pulled from the Debug menu.
Configuration Translation Errors
<request cmd="edit" obj="/config/devices/entry[@name='localhost.localdomain']/template/entry[@name='Template_ASDF']/settings/default-vsys" cookie="1742958630071210"> <default-vsys>vsys1</default-vsys> </request>
Request-PaloApi -ipAddress $ipAddress ` -paloKey $paloKey ` -apiType 'config' ` -apiAction 'edit' ` -apiXpath "/config/devices/entry[@name='localhost.localdomain']/template/entry[@name='Template_ASDF']/settings/default-vsys" -apiElement '<default-vsys>vsys1</default-vsys>'
From a high level, this seems like it should work well. However, attempting to run this command will return an error. The reason comes from how the Palo Alto configuration looks on the backend. Palo Alto configuration is all based on XML, and we are attempting to add information to xpath default-vsys, however, our element also specifies default-vsys. An element expects some brackets, so our command should actually look like below.
Request-PaloApi -ipAddress $ipAddress ` -paloKey $paloKey ` -apiType 'config' ` -apiAction 'edit' ` -apiXpath "/config/devices/entry[@name='localhost.localdomain']/template/entry[@name='Template_ASDF']/settings" -apiElement '<default-vsys>vsys1</default-vsys>'
Contrasting Configuration requests in how they are formed, Operation commands are similar when it comes to parsing from the Debug Menu. Our process begins the same, open the debug menu, and clear it. We will work with Panorama to execute moving a device group to a new parent.
Open your Panorama instance, navigate to the Panorama tab, and select Device Groups from the left-hand pane. From here, select the device group you want to move. In the window that pops up, select the new Parent Device Group from the drop-down. Go to the debug window, clear debug, return to the GUI window, and select OK.
Return to the debug window, and refresh. Since we know we modified the AA61_aue_group, we can perform a search against that to locate the relevant information. You may locate some edits, however, those pertain to the devices contained within, looking for a request related to a Parent Device Group, we should locate the following.
<request cmd="op" cookie="1742958630071210"> <operations xml="yes"> <request> <move-dg> <entry name="AA61_aue_Group"> <new-parent-dg>Solutions_Shared</new-parent-dg> </entry> </move-dg> </request> </operations> </request>
This looks pretty straightforward. From our other blog post, we know that Operation requests typically require only Type and Command. Initial inspection shows a cmd=, however, that will actually show us the Type of request to make. Grabbing the type is simple, but what is the actual command.
The cmd field translates to all the information between the operations tags (<operations></operations>). By removing all returns and spacing between the brackets within, we can insert the request into our function Request-PaloApi.
Request-PaloApi -ipAddress $panoramaIp ` -paloKey $panoramaApiKey ` -apiType 'op' ` -apiCmd '<request><move-dg><entry name="AA61_aue_Group"><new-parent-dg>Solutions_Shared</new-parent-dg></entry></move-dg></request>'
Running the command above will queue a short job that migrates the device group to its new parent. Once more, this is beneficial when uncovering commands that are kept hidden under the GUI, but beneficial for repeated tasks.
Through effective use of the search function, and knowledge of what we items we will change, we can locate commands that let us be more hands-off with our devices. Knowledge of the underlying XML also helps when we want to back out of changes or remove items that prefer sticking around within the GUI.
We will look to provide more information around Palo Alto, and its API in subsequent posts. Keep an eye on the site for plenty of information.