Skip to content

Latest commit

 

History

History
801 lines (613 loc) · 25.3 KB

panxapi.rst

File metadata and controls

801 lines (613 loc) · 25.3 KB
Raw

panxapi.py

command line program for accessing the PAN-OS XML API

NAME

panxapi.py - command line program for accessing the PAN-OS XML API

SYNOPSIS

panxapi.py [options] [xpath]
   -d                    delete object at xpath
   -e element            edit XML element at xpath
   -g                    get candidate config at xpath
   -k                    generate API key
   -s                    show active config at xpath
   -S element            set XML element at xpath
   -U cmd                execute dynamic update command
   -C cmd                commit candidate configuration
   --validate            validate candidate configuration
   --force               force commit when conflict
   --partial part        commit specified part
   --sync                synchronous commit
   -A cmd                commit-all (Panorama)
   --ad-hoc query        perform ad hoc request
   --modify              insert known fields in ad hoc query
   -o cmd                execute operational command
   --export category     export files
   --import category     import files
   --log log-type        retrieve log files
   --report report-type  retrieve reports (dynamic|predefined|custom)
   --name name           report name/import file name
   --src src             clone source node xpath
                         export source file/path/directory
   --dst dst             move/clone destination node name
                         rename new name
                         export destination file/path/directory
   --move where          move after, before, bottom or top
   --rename              rename object at xpath to dst
   --clone               clone object at xpath, src xpath
   --override element    override template object at xpath
   -M element            multi-config XML element
   --file path           import file path
   --strict yes|no       multi-config strict-transactional
   --vsys vsys           VSYS for dynamic update/partial commit/
                         operational command/report/import
   -l api_username[:api_password]
   -h hostname
   -P port               URL port number
   --serial number       serial number for Panorama redirection/
                         commit-all/threat-pcap
   --group name          device group for commit-all
   --merge               merge with candidate for commit-all
   --nlogs num           retrieve num logs
   --skip num            skip num logs
   --filter filter       log selection filter
   --interval seconds    log/commit/report job query interval
   --timeout seconds     log/commit/report job query timeout
   --stime time          search time for threat-pcap
   --pcapid id           threat-pcap ID
   -K api_key
   -x                    print XML response to stdout
   -p                    print XML response in Python to stdout
   -j                    print XML response in JSON to stdout
   -r                    print result content when printing response
   --text                print text response to stdout
   -X                    convert text command to XML
   --ls                  print formatted PCAP listing to stdout
   --recursive           recursive export
   -H                    use http URL scheme (default https)
   -G                    use HTTP GET method (default POST)
   -D                    enable debug (multiple up to -DDD)
   -t tag                .panrc tagname
   -T seconds            urlopen() timeout
   --cafile path         file containing CA certificates
   --capath path         directory of hashed certificate files
   --version             display version
   --help                display usage

DESCRIPTION

panxapi.py is used to perform XML API requests on a PAN-OS firewall and Panorama. It uses the PanXapi class from the pan.xapi module to execute API requests.

The options are:

-d
Perform the action=delete device configuration API request with the xpath argument. delete is used to remove an existing object at the node specified by xpath.
-e element

Perform the action=edit device configuration API request with the element and xpath arguments. edit is used to replace an existing object at the node specified by xpath.

element can be an XML string, a path to a file containing XML, or the value - to specify the XML is on stdin.

-g
Perform the action=get device configuration API request with the optional xpath argument. get is used to retrieve the candidate configuration on the firewall.
-k

Perform the type=keygen key generation API request with the api_username and api_password arguments. This is used to generate an API key for the -K argument or a .panrc file.

If a .panrc tagname is specified the output will be hostname and api_key varname values for use in a .panrc file.

-s
Perform the action=show device configuration API request with the optional xpath argument. show is used to retrieve the active configuration on the firewall.
-S element

Perform the action=set device configuration API request with the element and xpath arguments. set is used to create a new object at the node specified by xpath.

element can be an XML string, a path to a file containing XML, or the value - to specify the XML is on stdin.

-U cmd

Perform the type=user-id dynamic object update API request with the cmd argument and optional --vsys argument. This is used to update dynamic objects including ip-user mappings and address objects.

cmd can be an XML string, a path to a file containing XML, or the value - to specify the XML is on stdin.

-C cmd

Perform the type=commit commit configuration API request with the cmd argument. This schedules a job to execute a configuration mode commit command to commit the candidate configuration.

cmd can be an XML string, a path to a file containing XML, or the value - to specify the XML is on stdin.

When cmd is the empty string the XML string will be created according to the --validate, --force, --partial and --vsys options specified. If no commit options are specified it defaults to '<commit></commit>'.

--validate
Validate the candidate configuration. Configuration validation is performed in a job; to see the validation result you can specify --sync.
--force
Force the commit command in the event of conflict.
--partial part

Commit or exclude the specified part of the configuration.

part can be:

  • device-and-network-excluded
  • policy-and-objects-excluded
  • shared-object-excluded
  • no-vsys
  • vsys

device-and-network-excluded applies when the device is in single-vsys mode and shared-object-excluded applies when the device is in multi-vsys mode.

Multiple parts can be specified by using multiple --partial options or separating each part with comma (,). Virtual systems for the vsys part can be specified with --vsys.

--sync
Perform a synchronous commit.
-A cmd

Perform the type=commit commit configuration API request with the cmd argument and specify action=all. This is used to push shared policy from Panorama to managed firewalls.

cmd can be an XML string, a path to a file containing XML, or the value - to specify the XML is on stdin.

When cmd is the empty string the XML string will be created according to the --serial, --group, --merge and --vsys options specified.

--ad-hoc query

When no other API request is specified, this performs an ad hoc (custom) API request using the query string specified. When other API requests are specified, this is used to modify (replace) and augment (add to) the standard parameters in the request.

Query string must be field=value pairs separated by ampersand (&). The string will be URL-encoded before performing the API request.

--ad-hoc can be used to construct API requests that are not directly supported by pan.xapi or panxapi.py.

--modify

Modify an ad hoc query by inserting known fields. By default the query is not modified.

The known fields that can be inserted are:

  • xpath
  • key (api_key)
  • user (api_username)
  • password (api_password)
  • target (--serial)
-o cmd

Perform the type=op operational command API request with the cmd argument.

cmd can be a text string (see -X), an XML string, a path to a file containing XML, or the value - to specify the XML is on stdin.

--export category

Perform the type=export export file API request.

category specifies the type of file to export or list:

  • application-pcap
  • threat-pcap
  • filter-pcap
  • dlp-pcap
  • configuration
  • certificate
  • others (see XML API Reference)
--import category

Perform the type=import import file API request.

category specifies the type of file to import:

  • certificate
  • configuration
  • keypair
  • license
  • others - use the API Browser to see a full list of import categories

The --name option is used to specify the file name.

The --vsys option is used to set the location to a specific Virtual System.

The --ad-hoc option is used to specify additional import arguments, for example:

  • certificate-name
  • format
  • passphrase
--log log-type

Perform the type=log retrieve log API request with the log-type argument.

log-type specifies the type of log to retrieve and can be:

  • config
  • hipmatch
  • system
  • threat
  • traffic
  • url
  • wildfire

Also see the --nlogs, --skip and --filter options.

--report report-type

Perform the type=report retrieve report API request with the report-type argument.

report-type (reporttype= argument) specifies the type of report to retrieve and can be:

  • dynamic
  • predefined
  • custom
--name name

Specify the file name (filename= argument) for --import.

Specify the report name (reportname= argument) for --report. This can also be custom-dynamic-report to specify a custom dynamic report.

The --ad-hoc option is used to specify additional report arguments, for example:

  • cmd
  • topn
  • period
--src src

Specify the source file, path or directory for --export and the source XPath for --clone.

The src argument is used to specify:

  • date directory for application-pcap and threat-pcap PCAP file listing
  • PCAP file path for exporting application-pcap, threat-pcap and dlp-pcap
  • file name for exporting filter-pcap
--dst dst

The --dst argument is used with --export to specify:

  • a destination directory for exported file (retains original file name)
  • a file or path for exported file (file saved with new file name)

The --dst argument is used with --move, --rename and --clone to specify destination node name (e.g., rule10).

--move where

Perform the action=move device configuration API request with the xpath, where and dst arguments.

This moves the location of an existing node in the configuration specified by xpath. where is used to specify the location of the node and can be after, before, bottom or top. --dst is used to specify the relative destination node name when where is after or before.

--move is most frequently used to reorder rules (security, nat, qos, etc.) within the rulebase, however can be used to move other nodes in the configuration.

--rename

Perform the action=rename device configuration API request with the xpath and newname arguments.

This renames an existing node in the configuration specified by xpath. --dst is used to specify the new name for the node.

--clone

Perform the action=clone device configuration API request with the xpath, from and newname arguments.

This clones (copies) an existing node in the configuration specified by xpath. --src is used to specify the source XPath and --dst is used to specify the new name for the cloned node.

--override element

Perform the action=override device configuration API request with the element and xpath arguments. override is used to create a new object at the node specified by xpath when the xpath is part of a template applied by Panorama. Only specific nodes in the Device and Network categories can be overridden.

element can be an XML string, a path to a file containing XML, or the value - to specify the XML is on stdin.

-M element

Performs the action=multi-config device configuration API request with the element and optional strict-transactional argument. multi-config is used to perform multiple configuration API requests with transactional support.

element can be an XML string, a path to a file containing XML, or the value - to specify the XML is on stdin.

--file path
Specify the path to a file to import.
--strict yes|no

When --strict is yes the strict-transactional multi-config API request argument is set to yes and additional checks are performed:

  • When a commit operation is active or a commit is pending, the operation will fail.
  • When there are uncommitted changes for the user performing the operation, they will be rolled back before performing the multi-config operation.
--vsys vsys

Specify optional vsys for dynamic update (-U), partial vsys commit (--partial vsys), commit-all (-A), operational commands (-o) and import (--import).

vsys can be specified using name (vsys2) or number (2).

Multiple virtual systems can be specified by using multiple --vsys options or separating each vsys with comma (,).

-l api_username[:api_password]

Specify the api_username and api_password which are used to generate the api_key used in API requests.

api_password is optional and when not specified the password is read from stdin.

-h hostname
Specify the hostname which is used to generate the URI for API requests.
-P port
Specify the port number used in the URL. This can be used to perform port forwarding using for example ssh(1).
--serial number

Specify the serial number used for Panorama to device redirection. This sets the target argument to the serial number specified for the following API requests:

Request Request Type
key generation keygen
device configuration config
commit configuration commit
dynamic object update user-id
operational command op
export file export
report retrieval report

When an API request is made on Panorama and the serial number is specified, Panorama will redirect the request to the managed device with the serial number.

--group name
Specify the device group name used for Panorama commit-all (-A).
--merge
Specify the merge-with-candidate-cfg option for Panorama commit-all (-A).
--nlogs num

Specify the number of logs to retrieve for the --log option.

The default is 20 and the maximum is 5000.

pan.xapi currently loads the entire XML document into memory using the ElementTree module. A large number of log entries can cause a memory exception which may not be possible to catch. If you see exceptions when using a large --nlog value try reducing it.

--skip num

Specify the number of logs to skip for the --log option. This can be used to retieve log entries in batches by skipping previously retrieved logs.

The default is 0.

--filter filter
Specify the log query selection filter for the --log option. This is a set of log filter expressions as can be specified in the Monitor tab in the Web UI.
--interval seconds

A floating point number specifying the query interval in seconds between each non-finished job status response.

The default is 0.5 seconds.

--timeout seconds

The maximum number of seconds to wait for the job to finish.

The default is to try forever.

--stime time
Specify the search time for threat-pcap export.
--pcapid id
Specify the PCAP ID for threat-pcap export.
-K api_key
Specify the api_key used in API requests. This is not required to perform API requests if the api_username and api_password are provided using the -l argument or a .panrc file.
-x
Print XML response to stdout.
-p
Print XML response in Python to stdout.
-j
Print XML response in JSON to stdout.
-r
Print result content when printing the response (removes outer <response><result> elements). If a <result> element is not present this prints the entire response. This option applies to -x, -p and -j response output; if none of these options are specified -x is implied.
--text

Print text (response content-type is text/plain) to stdout.

This is used for retrieving exported response pages.

-X

Convert a CLI-style cmd argument to XML. This works by converting all unquoted arguments in cmd to start and end elements and treating double quoted arguments as text after removing the quotes. For example:

  • show system info
    • <show><system><info></info></system></show>
  • show interface "ethernet1/1"
    • <show><interface>ethernet1/1</interface></show>
--ls
Print formatted PCAP listing to stdout. For use with --export.
--recursive
Export recursively. This copies the PCAP files to the YYYYMMDD directory in their path, and creates the directory if needed.
-H
Use the http URL scheme for API requests. The default is to use the https URL scheme.
-G
Use the HTTP GET method for API requests. The default is to use the HTTP POST method with Content-Type application/x-www-form-urlencoded.
-D
Enable debugging. May be specified multiple times up to 3 to increase debugging output.
-t tag
Specify tagname for .panrc.
-T seconds
Specify the timeout value for urlopen().
--cafile path
Specify the cafile value for HTTPS requests. cafile is a file containing CA certificates to be used for SSL server certificate verification. By default the SSL server certificate is not verified.
--capath path
Specify the capath value for HTTPS requests. capath is a directory of hashed certificate files to be used for SSL server certificate verification. By default the SSL server certificate is not verified.
--version
Display version.
--help
Display command options.
xpath
XPath for request. xpath can be a string, a path to a file containing the XPath, or the value - to specify the XPath is on stdin.

FILES

.panrc
.panrc file.

EXIT STATUS

panxapi.py exits with 0 on success and 1 if an error occurs.

EXAMPLES

Generate an API key.

$ panxapi.py -l admin:admin -h 172.29.9.253 -k
keygen: success
API key:  "C2M1P2h1tDEz8zF3SwhF2dWC1gzzhnE1qU39EmHtGZM="

Create a .panrc file with the API key.

$ echo 'hostname=172.29.9.253' >.panrc
$ echo 'api_key=C2M1P2h1tDEz8zF3SwhF2dWC1gzzhnE1qU39EmHtGZM=' >>.panrc

Retrieve the active configuration and write it to a file.

$ panxapi.py -sxr >active.xml
show: success

Retrieve and display a security rule from the active configuration.

$ xpath="/config/devices/entry/vsys/entry/rulebase/security/rules/entry[@name='rule7']"
$ panxapi.py -sxr $xpath | head
show: success
<entry name="rule7">
  <option>
    <disable-server-response-inspection>no</disable-server-response-inspection>
  </option>
  <from>
    <member>trust</member>
  </from>
  <to>
    <member>dmz</member>
  </to>

Edit the application of a security rule.

$ echo '<application><member>rsync</member></application>' >app.xml
$ panxapi.py -e app.xml $xpath/application
edit: success [code="20"]: command succeeded

Retrieve and display modified application from the candidate configuration.

$ panxapi.py -gxr $xpath/application
get: success [code="19"]
<application admin="admin" time="2013/03/02 15:17:31"><member admin="admin" time="2013/03/02 15:17:31">rsync</member></application>

Commit candidate configuration.

$ panxapi.py -C ''
commit: success [code="19"]: Commit job enqueued with jobid 912

Show job id.

$ panxapi.py -Xjro 'show jobs id "912"'
op: success
{
  "job": {
    "details": null,
    "id": "912",
    "progress": "99",
    "result": "PEND",
    "status": "ACT",
    "stoppable": "yes",
    "tenq": "2013/03/02 15:21:26",
    "tfin": "Still Active",
    "type": "Commit",
    "warnings": null
  }
}

Save security rule.

$ panxapi.py -sxr $xpath >rule.xml
show: success

Delete security rule.

$ panxapi.py -d $xpath
delete: success [code="20"]: command succeeded

Commit Policy and Object configuration.

$ panxapi.py --partial device-and-network-excluded
commit: success [code="19"]: Commit job enqueued with jobid 914

Add security rule.

$ xpath2="/config/devices/entry/vsys/entry/rulebase/security/rules"
$ panxapi.py -S rule.xml $xpath2
set: success [code="20"]: command succeeded

Move security rule.

$ panxapi.py --move top $xpath
move: success [code="20"]: command succeeded

Rename security rule.

$ panxapi.py --rename --dst rule7-b $xpath
rename: success [code="20"]: command succeeded

Retrieve WildFire logs matching filter.

$ panxapi.py --log wildfire -xr --filter '(misc eq wajam_install.exe)'
log: success [code="19"]
<job>
    <tenq>11:29:24</tenq>
    <tdeq>11:29:25</tdeq>
    <tlast>11:29:26</tlast>
    <status>FIN</status>
    <id>89</id>
  </job>
  <log>
    <logs count="1" progress="100">
      <entry logid="5910273572261068816">
[...]

Retrieve report using the --ad-hoc option.

$ panxapi.py -x --modify --ad-hoc 'type=report&reporttype=dynamic&reportname=acc-summary'
ad_hoc: success
<response status="success"><report logtype="appstat" reportname="acc-summary">
    <result end="2013/09/13 23:59:59" end-epoch="1379141999" generated-at="2013/09/14 10:34:31" generated-at-epoch="1379180071" logtype="appstat" name="acc summary" range="Friday, September 13, 2013" start="2013/09/13 00:00:00" start-epoch="1379055600">
      <entry>
        <name>paloalto-wildfire-cloud</name>
        <risk-of-name>1</risk-of-name>
        <nbytes>9005951</nbytes>
        <nthreats>0</nthreats>
        <nsess>723</nsess>
        <npkts>20924</npkts>
      </entry>
[...]

Validate candidate configuration.

$ panxapi.py -C '' --validate --sync
commit: success: "Configuration is valid"

Export threat-pcap file on PAN-OS 6.0.

$ panxapi.py --export threat-pcap --pcapid 1200628399744221211 \
> --serial 001609032345
export: success
exported threat-pcap: 1200628399744221211.pcap

Export certificate with additional parameters:

$ panxapi.py --export certificate \
> --ad-hoc 'certificate-name=GlobalProtectCA&format=pem&include-key=yes&passphrase=paloalto'
export: success
exported certificate: globalprotectca.pem

Print operational command variable using shell pipeline.

$ (panxapi.py -Xpro 'show system info'; \
> echo "print(var1['system']['serial'])") | python
op: success
001606022345

SEE ALSO

pan.xapi, panconf.py

PAN-OS and Panorama API Guide
https://docs.paloaltonetworks.com/pan-os/11-1/pan-os-panorama-api.html
PAN-OS XML API multi-config Request
https://docs.paloaltonetworks.com/pan-os/11-1/pan-os-panorama-api/pan-os-xml-api-request-types/configuration-api/multi-config-request-api
PAN-OS XML API Labs with pan-python
http://api-lab.paloaltonetworks.com/

AUTHORS

Kevin Steves <[email protected]>