paloaltonetworks/pan-os-python

The PAN-OS SDK for Python is a package to help interact with Palo Alto Networks devices (including physical and virtualized Next-generation Firewalls and Panorama). The pan-os-python SDK is object oriented and mimics the traditional interaction with the device via the GUI or CLI/API.

Palo Alto Networks PAN-OS SDK for Python

The PAN-OS SDK for Python (pan-os-python) is a package to help interact with Palo Alto Networks devices (including physical and virtualized Next-generation Firewalls and Panorama). The pan-os-python SDK is object oriented and mimics the traditional interaction with the device via the GUI or CLI/API.

• Documentation: http://pan-os-python.readthedocs.io

---

---

Features

• Object model of Firewall and Panorama configuration
• Multiple connection methods including Panorama as a proxy
• All operations natively vsys-aware
• Support for high availability pairs and retry/recovery during node failure
• Batch User-ID operations
• Device API exception classification

Status

Palo Alto Networks PAN-OS SDK for Python is considered stable. It is fully tested and used in many production environments. Semantic versioning is applied to indicate bug fixes, new features, and breaking changes in each version.

Install

Install using pip:

pip install pan-os-python

Upgrade to the latest version:

pip install --upgrade pan-os-python

If you have poetry installed, you can also add pan-os-python to your project:

poetry add pan-os-python

How to import

To use pan-os-python in a project:

import panos

You can also be more specific about which modules you want to import:

from panos import firewall
from panos import network

A few examples

For configuration tasks, create a tree structure using the classes in each module. Nodes hierarchy must follow the model in the Configuration Tree.

The following examples assume the modules were imported as such:

from panos import firewall
from panos import network

Create an interface and commit:

fw = firewall.Firewall("10.0.0.1", api_username="admin", api_password="admin")
eth1 = network.EthernetInterface("ethernet1/1", mode="layer3")
fw.add(eth1)
eth1.create()
fw.commit()

Operational commands leverage the 'op' method of the device:

fw = firewall.Firewall("10.0.0.1", api_username="admin", api_password="admin")
print fw.op("show system info")

Some operational commands have methods to refresh the variables in an object:

# populates the version, serial, and model variables from the live device
fw.refresh_system_info()

See more examples in the Usage Guide.

Upgrade from pandevice

This pan-os-python package is the evolution of the older pandevice package. To upgrade from pandevice to pan-os-python, follow these steps.

Step 1. Ensure you are using python3

Python2 is end-of-life and not supported by pan-os-python.

Step 2. Uninstall pandevice:

pip uninstall pandevice
 # or
poetry remove pandevice

Step 3. Install pan-os-python:

pip3 install pan-os-python
 # or
poetry add pan-os-python

Step 4. Change the import statements in your code from pandevice to panos. For example:

import pandevice
from pandevice.firewall import Firewall

 # would change to

import panos
from panos.firewall import Firewall

Step 5. Test your script or application

There are no known breaking changes between pandevice v0.14.0 and pan-os-python v1.0.0, but it is a major upgrade so please verify everything works as expected.

Contributors

• Brian Torres-Gil - btorresgil
• Garfield Freeman - shinmog
• John Anderson - lampwins
• Aditya Sripal - AdityaSripal

Thank you to Kevin Steves, creator of the pan-python library

pan-os-python's Issues

dyn_address_group.py: error: unrecognized arguments: General

Hi I am trying to tag existing IP 10.34.20.94 on firewall 10.34.2.21 (PANOS 7.1.7 - model 5060 multi vsys) with tag General , getting error below:

$ python dyn_address_group.py 10.34.2.21 admin 'password' 10.34.20.94 General
usage: dyn_address_group.py [-h] [-v] [-q] [-r REGISTER] [-u UNREGISTER] [-l]
                            [-c]
                            hostname username password ip
dyn_address_group.py: error: unrecognized arguments: General

I am using pandevice (0.3.5)

Release pandevice 0.5.0

Update _type bulk methods

• be more aware of vsys
• do vsys import on apply()

apply_similar() and create_similar() should import to vsys1 for interfaces with no vsys

In order to mimic the behavior of the firewall GUI which prevents interfaces without any vsys, the create() and apply() methods check for the VsysOperations.ALWAYS_IMPORT constant. If the constant is True, then the PanObject is imported into vsys1. All interfaces have the ALWAYS_IMPORT constant set to True. However, apply_similar() and create_similar() don't make this check, so the interfaces created by these methods end up without any vsys.

To correct this, PanObject._requires_import_consideration() should check for the ALWAYS_IMPORT constant, but since this constant exists in VsysOperations class, not PanObject class, the _requires_import_consideration() method should probably be moved to the VsysOperations class.

The PanObject._perform_vsys_dict_import_set() method should also probably be in the VsysOperations class, since it is specific to vsys importable objects.

Special vsys refresh method

For the vsys object, when refresh_children=False

Improve object referencing

As mentioned in #22 and later discussed in greater detail on Gitter, we would like the ability to have direct references to objects that make up a SecurityRule instead of just their names in string form.

@btorresgil and I agreed this functionality should not change the way the library interprets or stores the config tree. So objects will still be children of the same parents they have always been. We are simply talking about creating references to those objects in the SecurityRule at this time.

This will most likely entail a "link_references" like method that the developer will invoke after the SecurityRule and the objects have been refreshed or otherwise loaded.

My thinking is that we add additional attributes to the SecurityRule class to not interfere with the present functionality. So for example, source will still contain a list of string names, but source_obj will be added to store a list of objects.AddressObject and objects.AddressGroup objects. This way, the read/write functionality of the SecurityRule object is not changed. We could also make it so that when an object is added or removed from the source_obj list, the same thing happens to its corresponding string name in source string list.

Obviously the above would apply to all currently represented objects in the objects module that have anything to do with a SecurityRule.

Support for DHCP on data interface

We need to set DHCP on the data interface as well as management profile groups. There is a way to configure static IP on the interface today but not DHCP.

Create document explaining PAN-OS 8.0 TLS version change

This should be part of the documentation

Traceback: AttributeError: 'HA1' object has no attribute '_port'

File "/install/lib/pandevice/pandevice/base.py", line 596, in refresh
self._refresh_children(xml=obj)
File "/install/lib/pandevice/pandevice/base.py", line 692, in _refresh_children
l = childtype.refresh_all_from_xml(childroot)
File "/install/lib/pandevice/pandevice/base.py", line 998, in refresh_all_from_xml
instance = cls(variables=variables, **objvars)
File "/install/lib/pandevice/pandevice/ha.py", line 59, in init
super(HighAvailabilityInterface, self).init(_args, *_kwargs)
File "/install/lib/pandevice/pandevice/base.py", line 95, in init
setattr(self, varname, varvalue)
File "/install/lib/pandevice/pandevice/ha.py", line 71, in port
if value != self._port:
AttributeError: 'HA1' object has no attribute '_port'

This is due to 'port' variable is a property that first checks _port value. Due to new PanObject init system that initializes all variable, cannot access attributes from property setters. Add a check to see if the attribute exists first.

Panorama to commit 'templates'

When I commit from Panorama to the 'device group' it doesn't include 'templates' so how I actually commit 'templates' (network and device settings etc) ?

pano.commit_all(devicegroup="PROD")

With above I can only commit policy and object changes

SecurityRule 'any' attributes inconsistent behavior

policies.SecurityRule has certain attributes that default to the string value 'any'. However when a SecurityRule is created from a live device and that rule has attributes actually set to 'any' the value is represented as a list ['any']. This is inconsistent behavior and leads the developer to add extra checks to deal with these attributes when their value is actually set to 'any'.

Ensure there is a safe way to compare objects

Make vsys=None act like vsys="shared"

Doing vsys="shared" should raise a Warning to use None.

Traceback regarding noinit_variables

Removed all no-init variable system when PanObject init method was rewritten to handle variable initialization. But this part was accidentally not removed.

panorama.Panorama.refresh_devices() raises "TypeError: 'NoneType' object is not iterable"

The devicegroup_opxml variable can be None, and you can't iterate over None. If this is None, set it to an empty list.

>>> from pandevice import firewall gives SyntaxError: invalid syntax

I got SyntaxError: invalid syntax for 'from pandevice import firewall'

$ python
Python 2.6.6 (r266:84292, May 22 2015, 08:34:51) 
[GCC 4.4.7 20120313 (Red Hat 4.4.7-15)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import pandevice

>>> from pandevice import firewall
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/lib/python2.6/site-packages/pandevice/firewall.py", line 32, in <module>
    from pandevice import device
  File "/usr/lib/python2.6/site-packages/pandevice/device.py", line 22, in <module>
    from base import PanObject, Root, MEMBER, ENTRY
  File "/usr/lib/python2.6/site-packages/pandevice/base.py", line 1095
    option_paths = {opt: re.sub(r"\([\w\d|-]*\)", opt, path) for opt in options}
                                                               ^
SyntaxError: invalid syntax

Live device tests

Suite of unittests that test against a live device to check PanObjects across different versions of PAN-OS

PanObject.update() method does not handle bool params correctly

Traceback when updating a SecurityRule object parameter disabled using the update() method. create(), apply(), delete(), etc seem to work fine, just update() is affected.

If disabled param is set to False:

In [16]: rule1.disabled=False

In [17]: rule1.update('disabled')
DEBUG:pandevice.base:010401000111: update called on <class 'pandevice.policies.SecurityRule'> object "test1" and variable "disabled"
DEBUG2:pan.xapi:query: {'xpath': "/config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1']/rulebase/security/rules/entry[@name='test1']/disabled", 'action': 'edit', 'type': 'config', 'key': '******', 'element': '<disabled />'}
DEBUG2:pan.xapi:URI: https://10.3.4.243:443/api/?xpath=/config/devices/entry[@name='localhost.localdomain']/vsys/entry[@name='vsys1']/rulebase/security/rules/entry[@name='test1']/disabled&action=edit&type=config&key=******&element=<disabled />
DEBUG2:pan.xapi:method: POST
---------------------------------------------------------------------------
PanDeviceXapiError                        Traceback (most recent call last)
<ipython-input-17-510aedfe47a9> in <module>()
----> 1 rule1.update('disabled')

/Users/btorres-gil/.virtualenvs/pandevice-released/lib/python2.7/site-packages/pandevice/base.pyc in update(self, variable)
    597                 element.text = value
    598             device.xapi.edit(xpath, ET.tostring(element),
--> 599                              retry_on_peer=self.HA_SYNC)
    600
    601     def _get_param_specific_info(self, variable):

/Users/btorres-gil/.virtualenvs/pandevice-released/lib/python2.7/site-packages/pandevice/base.pyc in method(self, *args, **kwargs)
   2851                                 raise the_exception
   2852                         else:
-> 2853                             raise the_exception
   2854                 return result
   2855

PanDeviceXapiError: Edit breaks config validity

If disabled param is set to True:

In [19]: rule1.disabled=True

In [20]: rule1.update('disabled')
DEBUG:pandevice.base:010401000111: update called on <class 'pandevice.policies.SecurityRule'> object "test1" and variable "disabled"
---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
<ipython-input-20-510aedfe47a9> in <module>()
----> 1 rule1.update('disabled')

/Users/btorres-gil/.virtualenvs/pandevice-released/lib/python2.7/site-packages/pandevice/base.pyc in update(self, variable)
    596                 # Regular text variables
    597                 element.text = value
--> 598             device.xapi.edit(xpath, ET.tostring(element),
    599                              retry_on_peer=self.HA_SYNC)
    600

/usr/local/Cellar/python/2.7.13/Frameworks/Python.framework/Versions/2.7/lib/python2.7/xml/etree/ElementTree.pyc in tostring(element, encoding, method)
   1124     file = dummy()
   1125     file.write = data.append
-> 1126     ElementTree(element).write(file, encoding, method=method)
   1127     return "".join(data)
   1128

/usr/local/Cellar/python/2.7.13/Frameworks/Python.framework/Versions/2.7/lib/python2.7/xml/etree/ElementTree.pyc in write(self, file_or_filename, encoding, xml_declaration, default_namespace, method)
    818                 )
    819             serialize = _serialize[method]
--> 820             serialize(write, self._root, encoding, qnames, namespaces)
    821         if file_or_filename is not file:
    822             file.close()

/usr/local/Cellar/python/2.7.13/Frameworks/Python.framework/Versions/2.7/lib/python2.7/xml/etree/ElementTree.pyc in _serialize_xml(write, elem, encoding, qnames, namespaces)
    935                 write(">")
    936                 if text:
--> 937                     write(_escape_cdata(text, encoding))
    938                 for e in elem:
    939                     _serialize_xml(write, e, encoding, qnames, None)

/usr/local/Cellar/python/2.7.13/Frameworks/Python.framework/Versions/2.7/lib/python2.7/xml/etree/ElementTree.pyc in _escape_cdata(text, encoding)
   1073         return text.encode(encoding, "xmlcharrefreplace")
   1074     except (TypeError, AttributeError):
-> 1075         _raise_serialization_error(text)
   1076
   1077 def _escape_attrib(text, encoding):

/usr/local/Cellar/python/2.7.13/Frameworks/Python.framework/Versions/2.7/lib/python2.7/xml/etree/ElementTree.pyc in _raise_serialization_error(text)
   1050 def _raise_serialization_error(text):
   1051     raise TypeError(
-> 1052         "cannot serialize %r (type %s)" % (text, type(text).__name__)
   1053         )
   1054

TypeError: cannot serialize True (type bool)

Support for Panorama 'shared' objects

Feature request to add support for 'shared' objects in panorama.

I guess this is annoying because these objects are located at /config/shared. My initial thought is to add a special refresh method in panorama.Panorama much like the way the predefined module works, but I'm not sure on where to store objects as we need read/write access and the xpath for these is not like the normal objects.

That being said, I see this as an obvious must for #26

User defined Services, ServiceGroups, Applications, ApplicationGroups, and ApplicationFilters

Need objects for user defined:

• Services
• Service Groups
• Applications (lower priority)
• Application Groups
• Application Filters (lower priority)

I also would like to get all of the predefined applications and services, but I know this response is large and thus slow, so maybe a not being part of the normal pandevice.refresh() but a separate call to explicitly retrieve these. Or maybe another parameter on the refresh call?

The reason for needing more than just the name of the predefined applications is to also know the standard ports. Basically I am looking to programmatically choose an appropriate (best guess) application to use in a rule, based on some set of ports given.

Support Templates

Support bulk operations in pandevice

Define a new kind of object that contains other PanObjects. This container itself does not generate xpath or xml like a PanObject does, but if create() or another method like it is called on the container, this would cause the children of the container to be created in an optimized way.

This container object would also handle situations such as namespaces, for example, the shared namespace could be handled with a container object.

Predefined module should support tag objects

Add object type and methods to support predefined tag objects in the predefined sub module.

Create test cases for network module

Reorder refresh() args, xml should be last

Current refresh() signature:

refresh(running_config=False, xml=None, refresh_children=True, exceptions=True)

xml is a rarely used argument, so it should be:

refresh(running_config=False, refresh_children=True, exceptions=True, xml=None)

Add new example script for bulk operations

pandevice.errors.PanURLError: URLError: reason: [SSL: CERTIFICATE_VERIFY_FAILED]

Getting below since 2 days, my Panorama is 7.1.9 and firewall 7.1.7:

python pandevice.pano.commit_all.py
Traceback (most recent call last):
  File "pandevice.pano.commit_all.py", line 18, in <module>
    id=pano.commit_all(cmd="<commit-all><shared-policy><include-template>yes</include-template><device-group><entry name='MR-DC1-PROD'/></device-group></shared-policy></commit-all>")
  File "/usr/lib/python2.7/site-packages/pandevice/panorama.py", line 186, in commit_all
    cmd=cmd)
  File "/usr/lib/python2.7/site-packages/pandevice/base.py", line 2293, in _commit
    commit_response = self.xapi.commit(cmd=cmd,
  File "/usr/lib/python2.7/site-packages/pandevice/base.py", line 1646, in xapi
    self._xapi_private = self.generate_xapi()
  File "/usr/lib/python2.7/site-packages/pandevice/base.py", line 1694, in generate_xapi
    kwargs = {'api_key': self.api_key,
  File "/usr/lib/python2.7/site-packages/pandevice/base.py", line 1640, in api_key
    self._api_key = self._retrieve_api_key()
  File "/usr/lib/python2.7/site-packages/pandevice/base.py", line 1780, in _retrieve_api_key
    xapi.keygen(retry_on_peer=False)
  File "/usr/lib/python2.7/site-packages/pandevice/base.py", line 1571, in method
    raise the_exception
pandevice.errors.PanURLError: URLError: reason: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:579)

Here is my simple script:

$ cat pandevice.pano.commit_all.py 
#!/usr/bin/python
#.....imports omitted
import time
pano = panorama.Panorama("10.34.2.249", "admin", "password")
id=pano.commit_all(cmd="<commit-all><shared-policy><include-template>yes</include-template><device-group><entry name='MR-DC1-PROD'/></device-group></shared-policy></commit-all>")
time.sleep(300)
cmd = 'show jobs id "' + id + '"'
print pano.op(cmd, xml=True)

Support python 3

This is an enhancement request to support python 3.

If you would like to vote for python 3 support, please comment below with:

• the exact versions of python 3 you require
• the reason you use python 3 instead of 2.7
• if there is a project on hold due to no python 3 support

Thank you for your help. You may also contact me with details at [email protected].

ParamPath needs a way to exclude variables from the XML document posted

The path of individual parameters must be explicitly set for it to show up in the resulting XML document. A path of None is valid and means "this parameter should not show up in the XML (for this version)."

Switch testing to use pytest runner

Traceback: AttributeError: 'Firewall' object has no attribute 'name'

fw.delete()
File "pandevice/pandevice/firewall.py", line 295, in delete
self.parent.remove_by_name(getattr(self, "name"), type(self))
AttributeError: 'Firewall' object has no attribute 'name'

Some childtype relationships are missing

Support for changes to firewall/Panorama administrators

Better documentation of op command syntax

There is often confusion about the double-quotes needed for text values in an operational command, since this is different than how the command looks on the firewall CLI. This requirement is documented in pan-python, but not in pandevice.

pan-python documentation:
https://github.com/kevinsteves/pan-python/blob/master/doc/pan.xapi.rst#opcmdnone-vsysnone-cmd_xmlfalse

Better documentation of this is needed in pandevice docs to reduce confusion.

API reference anchors are offset

This is most likely due to the graphviz section for the config tree diagram which is rendered late and pushed the page down making the anchor position wrong.

Possible solution is remove the config diagrams from the module pages and link to them in configtree.rst instead.

Created a subinterface class to replace Layer2Subinterface and Layer3Subinterface

escape character

I have function like below

def commit(job, fw):       
        print "fw" + str(job) + " is ACTIVE"
        fw.commit()
        time.sleep(120)
        cmd = "show jobs processed \| match mit"
        print fw.op(cmd, xml=True)
        return

but getting following error. Do you know how to correctly escape that '|' ?

$ python pandevice.fw.commit_all.py
active
fw2 is ACTIVE
Traceback (most recent call last):
  File "pandevice.fw.commit_all.py", line 26, in <module>
    commit(2,fw2)
  File "pandevice.fw.commit_all.py", line 16, in commit
    print fw.op(cmd, xml=True)
  File "/usr/lib/python2.7/site-packages/pandevice/firewall.py", line 201, in op
    return super(Firewall, self).op(cmd, vsys, xml, cmd_xml, extra_qs, retry_on_peer)
  File "/usr/lib/python2.7/site-packages/pandevice/base.py", line 1664, in op
    element = self.xapi.op(cmd, vsys, cmd_xml, extra_qs, retry_on_peer=retry_on_peer)
  File "/usr/lib/python2.7/site-packages/pandevice/base.py", line 1573, in method
    raise the_exception
pandevice.errors.PanDeviceXapiError: Illegal parameter [request]

getting None from active()

I'm trying to use 'active()' to find active firewall in my HA cluster. My cluster members have IPs '10.34.2.21' and '10.34.2.20'. Currently '10.34.2.21' is active

$ cat pandevice.fw.commit_all.py
#!/usr/bin/python
from pandevice import base
from pandevice import firewall
from pandevice import panorama
from pandevice import policies
from pandevice import objects
from pandevice import network
from pandevice import device
fw = base.PanDevice('10.34.2.21', 'admin', 'password',vsys='vsys1')
print fw.active()

But no matter what cluster member I test, I got 'None' in response ?

$ python pandevice.fw.commit_all.py
None

Regarding Documentation

Hello @btorresgil

Could you please update the documentation please ?

I checked the below link and couldn't found anything.
https://pandevice.readthedocs.org

Thanks !

Regression created with vartype=encrypted, sha1 variable is missing

pandevice.errors.PanDeviceXapiError: Illegal parameter [request]

I tried to display job status on Panorama:

$ cat pandevice.dev-pano.commit_all.py
#!/usr/bin/python
from pandevice import base
from pandevice import firewall
from pandevice import panorama
from pandevice import policies
from pandevice import objects
from pandevice import network
from pandevice import device
pano = panorama.Panorama("xxx", "admin", "xxx")
print pano.op("show jobs id 4936", xml=True)

and got below error (using pandevice 0.3.5 and python 2.7.5)

Traceback (most recent call last):
  File "pandevice.dev-pano.commit_all.py", line 16, in <module>
    print pano.op("show jobs id 4936", xml=True)
  File "/usr/lib/python2.7/site-packages/pandevice/panorama.py", line 137, in op
    return super(Panorama, self).op(cmd, vsys=None, xml=xml, cmd_xml=cmd_xml, extra_qs=extra_qs, retry_on_peer=retry_on_peer)
  File "/usr/lib/python2.7/site-packages/pandevice/base.py", line 1664, in op
    element = self.xapi.op(cmd, vsys, cmd_xml, extra_qs, retry_on_peer=retry_on_peer)
  File "/usr/lib/python2.7/site-packages/pandevice/base.py", line 1573, in method
    raise the_exception
pandevice.errors.PanDeviceXapiError: Illegal parameter [request]

Support for retrieving predefined objects.ApplicationObject and objects.ServiceObject

Per conversation in previous FR, I am opening this issue to formally request this functionality.

Again, the wish is to pull in the predefined objects that exist in firewall. Perhaps as an optional parameter "include_predefined" in the refresh methods?

Add support for objects changing their xpath based on the parent

network.Arp and network.IPv6Address both need this functionality

More fully implement it network.Zone

Doc: How to use Vsys

Bad rst reference in README.rst

The reference :ref:classtree works in read the docs, but not in github.

Tests: show, get, set, edit, delete for PanObject

policies.SecurityRule support for 'target'

Would like to have the SecurityRule object support the 'target' parameter available when using panorama. I suppose it would be nice to link the target firewall(s) in the object if the association is available.

Add GlobalProtect PanObjects

Config tree reorganizer

This should have the ability to move objects that live under a vsys (as well as vsys importables) to the correct vsys object.

Check the vsys params for what's imported.