PANOS REST API

October 2011
Business Development

the network security company

tm
PANOS REST API
•  External system can connect to device management interface or
Panorama over SSL
-  Connection is treated as general admin web access
Ø  same source address restriction and timeout settings

• Device Config/Report data

• REST API over SSL

• External System
•  Used to:
-  Read/Write Device or Panorama Configuration
-  Extract report data in XML format

-  Execute Operational Commands

•  Requires a key generated with admin ID and password info

-  Or a current authenticated administrative session
PANOS REST API - keygen

•  Keygen for API communication

• Key generation request example:

• https://hostname/api/?type=keygen&user=username&password=password

• Key generation response example:

• <response status="success”><result><key>0RgWc42Oi0vDx2WRUIUM6A=</key></
result></response>
PANOS REST API - xpath
•  xpath
-  Hierarchical XML path within firewall configuration file

• Image at right depicts XML

Device Configuration of a Palo
Alto Networks Firewall
•  The same data can be viewed
using the REST API at the
following xpath:
• /config/devices/entry/
deviceconfig

• Utilize xpath to isolate viewing

or to manipulate portions of the
configuration
PANOS REST API - browser

• API Browser: https://hostname/api

• xpath constructor for op commands
• and information retrieval
PANOS REST API - xpath

•  Utilize CLI debug mode for determining xpath and syntax

-  Log in to device or Panorama via console or SSH session
>debug cli on
>configure
#set vsys vsys1 address demo-obj ip-netmask 1.2.3.4/32
Response includes:
<request cmd="set" obj="/config/devices/entry
[@name='localhost.localdomain']/vsys/entry[@name='vsys1']/
address/entry[@name=’demo-obj']"
cookie="0265032970635834"><ip-netmask>1.2.3.4/32</ip-
netmask></request>
Strip out extraneous XML and cookie:
xpath=/config/devices/entry/vsys/entry[@name='vsys1']/address/entry
[@name=’demo-obj']&element=<ip-netmask>1.2.3.4/32</ip-netmask>

Page 6 | © 2011 Palo Alto Networks. Proprietary and Confidential.

PANOS REST API - xpath
•  Same object name, different xpath:
-  Single VSYS or VSYS Specific
/config/devices/entry/vsys/entry[@name='vsys1']/address/entry
[@name=’demo-obj']
-  Shared Objects (Panorama, devices)
/config/shared/address/entry[@name=’demo-obj’]
-  Panorama Device Group
/config/devices/entry/device-group/entry[@name='DG1']/address/entry
[@name=’demo-obj’]
-  Understand context of where objects and policies belong
Ø  Shared objects can be utilized by multiple VSYS within a single device or by
many devices managed by Panorama
Ø  VSYS specific objects are only available to that VSYS
Ø  Device Group specific objects are only available to devices that belong to the
group

Page 7 | © 2011 Palo Alto Networks. Proprietary and Confidential.

PANOS REST API - config

•  type = config
•  Specify the action [show | get | set | edit | delete | rename | move]

• Example, IP Address for an interface (ethernet1/3)

• xpath=/config/devices/entry/network/interface/ethernet/entry
[@name='ethernet1/3’]
• Show the current IP Address for interface ethernet1/3 from
running config
• https://hostname/api/?type=config&action=show&key=keyvalue&
xpath=devices/entry/network/interface/ethernet/entry[@name='ethernet1/3’]/
layer3/ip
• <response status="success”><result><ip><entry name="192.168.10.1/24"/></ip></
result></response>
PANOS REST API - config
•  type = config
•  Specify the action [show | get | set | edit | delete | rename | move ]

• Add another IP Address to interface ethernet1/3 in the

candidate configuration
• https://hostname/api/?type=config&action=set&key=keyvalue&xpath=/
config/devices/entry/network/interface/ethernet/entry[@name='ethernet1/3']/
layer3/ip&element=<entry name='1.2.3.4/24'/>
<response status="success" code="20”><msg>command succeeded</msg></
response>

• Commit your candidate configuration to make the change live

• https://hostname/api/?
type=commit&action=set&key=keyvalue&cmd=<commit></commit>
• <response status="success" code="19"> <result> <msg> <line>Commit job
enqueued with jobid 9</line> </msg> <job>9</job> </result> </response>
PANOS REST API - report
•  type = report
•  Specify the reporttype [dynamic | predefined | custom ]
•  Specify reportname
•  Can specify the period OR starttime & endtime *optional

Example : Get Application Top 3 data from ACC

• https://hostname/api/?type=report&reporttype=dynamic&
reportname=top-app-summary&period=last-hour&topn=3&key=keyvalue
<response status="success"> <report reportname="top-app-summary" logtype="trsum">
<result name="Top applications" logtype="trsum" start="2011/10/10 16:58:02" start-
epoch="1318291082" end="2011/10/10 17:58:01" end-epoch="1318294681" generated-
at="2011/10/10 17:58:02" generated-at-epoch="1318294682"> <entry> <app>yahoo-
toolbar</app> <risk-of-app>2</risk-of-app> <bytes>2746868295</bytes>
<sessions>406209</sessions> </entry> <entry> <app>web-browsing</app> <risk-of-
app>4</risk-of-app> <bytes>2489995505</bytes> <sessions>218078</sessions> </entry>
<entry> <app>ssl</app> <risk-of-app>4</risk-of-app><bytes>1700670245</bytes>
<sessions>100718</sessions> </entry></result></report></response>
PANOS REST API - report
•  type = report
•  Specify the reporttype [dynamic | predefined | custom ]
•  Specify reportname
•  Can specify the period OR starttime & endtime *optional

“top-attackers-summary” data from dynamic report

• https://hostname/api/?type=report&reporttype=dynamic&
reportname=top-attackers-summary&key=keyvalue
<response status="success"><report name="Top Attackers" logtype="thsum"
start="2011/10/10 19:34:43" start-epoch="1318300483" end="2011/10/10 20:34:42"
end-epoch="1318304082" generated-at="2011/10/10 20:34:43" generated-at-
epoch="1318304083"><entry><src>172.16.2.101</src><resolved-
src>172.16.2.101</resolved-src><srcuser/><sessions>1114</sessions></
entry><entry><src>172.16.1.100</src><resolved-src>172.16.1.100</resolved-
src><srcuser/><sessions>745</sessions></entry></report></response>
PANOS REST API – op
Operational Commands
•  Setting, Showing, Clearing runtime parameters
https://hostname/api/?
key=keyvalue&type=op&cmd=<show><resource><limit><session/></limit></
resource></show>
<response cmd=“status” status="success”><result>current session 0 max
session 2097152</result></response>

•  Saving and loading configuration to/from disk

https://hostname/api/?
key=keyvalue&type=op&cmd=<save><config><to>abc.xml</to></config></
save>
<response status="success”><result>Config saved to abc.xml.</result></
response>
PANOS REST API – op
•  Commit
https://hostname/api/?key=keyvalue&type=commit&force=yes
<response status="success" code=”20”><msg>command succeeded</
msg></response>

•  Support for Packet Capture (PCAP) File Listings and Exports

https://hostname/api/?key=keyvalue&type=export&category=application-
pcap&from=20100504/2-2200-722971.pcap&to=out.pcap
Download of out.pcap will automatically commence

•  Requesting system level operations…e.g. Content upgrade

https://hostname/api/?key=keyvalue&type=op&cmd=<show><operational-
mode></operational-mode></show>
<response status="success”><result>normal</result></response>
 PANOS REST API - examples

•  Easy to use in a web browser

Get a key:
https://10.xx.10.50/api/?type=keygen&user=admin&password=admin
Backup your config:
https://10.xx.10.50/api/?
type=config&action=show&key=0RgWc42Oi0vDx2WRUIUM6A=
Generate a report:
https://10.xx.10.50/api/?type=report&reporttype=dynamic&reportname=top-
app-summary&period=last-
hour&topn=5&key=0RgWc42Oi0vDx2WRUIUM6A=

Page 14 | © 2011 Palo Alto Networks. Proprietary and Confidential.

PANOS REST API - examples
•  Example of API Based Custom Reporting Web Application

Page 15 | © 2011 Palo Alto Networks. Proprietary and Confidential.

PANOS REST API - examples
•  Automated Provisioning for Virtual or Multi-Tennant
Environments

•  PAN-perl Package available on DevCenter

-  https://live.paloaltonetworks.com/docs/DOC-1910
-  Includes convenience libraries, templates, sample integrations

Page 16 | © 2011 Palo Alto Networks. Proprietary and Confidential.

For More Information: DevCenter
•  Online Community for customers, partners, employees to share
and discuss custom content at:
-  https://live.paloaltonetworks.com/community/devcenter
•  Custom Content and Information
-  API integration, Custom App-IDs, Custom Signatures, CLI Scripts, etc.
-  DevCenter community offers documentation, guidelines, samples, etc.

•  Support?
-  For issues with API’s or PANOS components, open ticket with Support
-  For scripts, etc. Support is best effort by DevCenter community
members
-  Use discussion threads to ask questions
Ø  Members (SEs, Customers, Partners, PMs, Support) offer & receive help from each other

•  Licensing for posted content

-  free distribution of original and modified content, including for
commercial purpose with attribution