pan-os xml api labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set...

54
PAN-OS XML API Labs with pan-python version 2020/03/10 23:35:50 Palo Alto Networks Inc March 10, 2020

Upload: others

Post on 22-Mar-2020

6 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

PAN-OS XML API Labs with pan-python

version 20200310 233550

Palo Alto Networks Inc

March 10 2020

ContentsPAN-OS XML API Labs with pan-python 1

Lab PAN-OS Configuration 1

set Format Configuration 1

XML Format Configuration 3

Introduction to the PAN-OS API 12

About the API 12

The API Browser 13

API Command Types 13

Module 1 Getting Started 14

Introducing pan-python 14

Example Install pan-python Using pip 14

Lab 1 14

API Key Generation 14

Example Generate API Key 14

Example Generate panrc Format Without tagname 15

Example Generate panrc Format With tagname 15

Example Create panrc File Using Shell Output Redirection 15

Example Verify panrc File 16

Lab 2 16

Execute Operational Commands 16

Example show system info 18

Lab 3 19

Module 2 Configuration 20

Configuration API Introduction 20

Actions 20

XPath 21

Find the right XPath 22

Technique 1 API Browser 22

Technique 2 Debug CLI 22

Technique 3 Debug GUI 22

Retrieve Configuration - show and get 23

Example Retrieve Administrator Accounts using get and show 24

Lab 4 24

Lab 5 25

Modify Configuration - set and edit 26

Example Disable and Enable Security Rule Using set and edit 26

Difference between set and edit 26

Lab Firewall address Objects 26

Lab 6 27

Lab 7 28

Lab 8 29

Commit Configuration 29

Example Perform Synchronous commit 29

Lab 9 30

Delete Configuration 31

Example Delete Secondary NTP Server 31

Lab 10 32

Example Get Multiple Objects 32

Lab 11 33

XPath Behavioral Differences (Optional) 33

Lab 12 33

Module 3 User-ID 34

User-ID API Introduction 34

Overview 34

User-ID API Call Structure 35

User-ID with pan-python 35

Login and Logout 36

Login Timeout 36

Logout name 36

Example Add User to IP Mappings (login) 37

Lab 13 37

User Groups (Optional) 38

Groups Updates 39

Example Add User to Group Mappings (groups) 40

Lab 14 40

Register-user and Unregister-user - DUG Objects 41

Tags 42

Persistency 42

Timeout Attribute 42

Example Add Tag to User Mappings (register-user) 44

Lab 15 45

Register and Unregister - DAG Objects 47

Tags 48

Persistent Attribute 48

Timeout Attribute 48

Example Add Tag to IP Mappings (register) 50

Lab 16 51

Resources 53

PAN-OS XML API Labs with pan-python

Lab PAN-OS Configuration

set Format ConfigurationThe following PAN-OS configuration is required as a starting point for the labs

NOTE This configuration uses the default credentials admin admin and adminr admin If you apply thisconfiguration to your own firewall be certain to change the passwords from the default Do not apply thisconfiguration to a production firewall Use this configuration at your own risk

If you need a firewall to run this lab on you can easily deploy a firewall in AWS A firewall license is not necessary forany steps in this lab

1 set deviceconfig system type static 2 set deviceconfig system update-server updatespaloaltonetworkscom 3 set deviceconfig system update-schedule 4 set deviceconfig system timezone USPacific 5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service disable-http yes 7 set deviceconfig system hostname PA-VM 8 set deviceconfig system ip-address 1921681103 9 set deviceconfig system netmask 2552552550 10 set deviceconfig system default-gateway 1921681254 11 set deviceconfig system dns-setting servers primary 8888 12 set deviceconfig system ntp-servers primary-ntp-server ntp-server-address uspoolntporg 13 set deviceconfig system ntp-servers primary-ntp-server authentication-type none 14 set deviceconfig system ntp-servers secondary-ntp-server ntp-server-address north-americapoolntporg 15 set deviceconfig system ntp-servers secondary-ntp-server authentication-type none 16 set deviceconfig setting config rematch yes 17 set deviceconfig setting management hostname-type-in-syslog FQDN 18 set deviceconfig setting management disable-predefined-reports [ spyware-infected-hosts top-application-categories top-technology-categories bandwidth-trend risk-trend threat-trend top-users top-attacker-sources top-attacker-destinations top-victim-sources top-victim-destinations top-attackers-by-source-countries top-attackers-by-destination-countries top-victims-by-source-countries top-victims-by-destination-countries top-sources top-destinations top-destination-countries top-source-countries top-connections top-ingress-interfaces top-egress-interfaces top-ingress-zones top-egress-zones top-applications top-http-applications top-rules top-attacks top-spyware-threats top-viruses top-vulnerabilities wildfire-file-digests top-websites top-url-categories top-url-users top-url-user-behavior top-blocked-websites top-blocked-url-categories top-blocked-url-users top-blocked-url-user-behavior blocked-credential-post unknown-tcp-connections unknown-udp-connections top-denied-sources top-denied-destinations top-denied-applications risky-users SaaS Application Usage gtp-events-summary gtp-malicious-wildfire-submissions gtp-security-events gtp-v1-causes gtp-v2-causes gtp-users-visiting-malicious-url top-gtp-attacker-destinations top-gtp-attacker-sources top-gtp-victim-destinations top-gtp-victim-sources sctp-error-causes sctp-events-summary sctp-security-events ] 19 set deviceconfig setting auto-mac-detect yes 20 set network interface ethernet ethernet11 virtual-wire 21 set network interface ethernet ethernet12 virtual-wire 22 set network profiles monitor-profile default interval 3 23 set network profiles monitor-profile default threshold 5 24 set network profiles monitor-profile default action wait-recover 25 set network ike crypto-profiles ike-crypto-profiles default encryption [ aes-128-cbc 3des ] 26 set network ike crypto-profiles ike-crypto-profiles default hash sha1 27 set network ike crypto-profiles ike-crypto-profiles default dh-group group2 28 set network ike crypto-profiles ike-crypto-profiles default lifetime hours 8 29 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-128 encryption aes-128-cbc 30 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-128 hash sha256 31 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-128 dh-group group19 32 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-128 lifetime hours 8 33 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-256 encryption aes-256-cbc 34 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-256 hash sha384 35 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-256 dh-group group20 36 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-256 lifetime hours 8 37 set network ike crypto-profiles ipsec-crypto-profiles default esp encryption [ aes-128-cbc 3des ] 38 set network ike crypto-profiles ipsec-crypto-profiles default esp authentication sha1 39 set network ike crypto-profiles ipsec-crypto-profiles default dh-group group2 40 set network ike crypto-profiles ipsec-crypto-profiles default lifetime hours 1 41 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-128 esp encryption aes-128-gcm 42 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-128 esp authentication none 43 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-128 dh-group group19 44 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-128 lifetime hours 1 45 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 esp encryption aes-256-gcm

PAN-OS XML API Labs with pan-python

1

46 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 esp authentication none 47 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 dh-group group20 48 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 lifetime hours 1 49 set network ike crypto-profiles global-protect-app-crypto-profiles default encryption aes-128-cbc 50 set network ike crypto-profiles global-protect-app-crypto-profiles default authentication sha1 51 set network qos profile default class-bandwidth-type mbps class class1 priority real-time 52 set network qos profile default class-bandwidth-type mbps class class2 priority high 53 set network qos profile default class-bandwidth-type mbps class class3 priority high 54 set network qos profile default class-bandwidth-type mbps class class4 priority medium 55 set network qos profile default class-bandwidth-type mbps class class5 priority medium 56 set network qos profile default class-bandwidth-type mbps class class6 priority low 57 set network qos profile default class-bandwidth-type mbps class class7 priority low 58 set network qos profile default class-bandwidth-type mbps class class8 priority low 59 set network virtual-router default protocol bgp enable no 60 set network virtual-router default protocol bgp dampening-profile default cutoff 125 61 set network virtual-router default protocol bgp dampening-profile default reuse 05 62 set network virtual-router default protocol bgp dampening-profile default max-hold-time 900 63 set network virtual-router default protocol bgp dampening-profile default decay-half-life-reachable 300 64 set network virtual-router default protocol bgp dampening-profile default decay-half-life-unreachable 900 65 set network virtual-router default protocol bgp dampening-profile default enable yes 66 set network virtual-wire default-vwire interface1 ethernet11 67 set network virtual-wire default-vwire interface2 ethernet12 68 set shared application 69 set shared application-group 70 set shared service 71 set shared service-group 72 set shared botnet configuration http dynamic-dns enabled yes 73 set shared botnet configuration http dynamic-dns threshold 5 74 set shared botnet configuration http malware-sites enabled yes 75 set shared botnet configuration http malware-sites threshold 5 76 set shared botnet configuration http recent-domains enabled yes 77 set shared botnet configuration http recent-domains threshold 5 78 set shared botnet configuration http ip-domains enabled yes 79 set shared botnet configuration http ip-domains threshold 10 80 set shared botnet configuration http executables-from-unknown-sites enabled yes 81 set shared botnet configuration http executables-from-unknown-sites threshold 5 82 set shared botnet configuration other-applications irc yes 83 set shared botnet configuration unknown-applications unknown-tcp destinations-per-hour 10 84 set shared botnet configuration unknown-applications unknown-tcp sessions-per-hour 10 85 set shared botnet configuration unknown-applications unknown-tcp session-length maximum-bytes 100 86 set shared botnet configuration unknown-applications unknown-tcp session-length minimum-bytes 50 87 set shared botnet configuration unknown-applications unknown-udp destinations-per-hour 10 88 set shared botnet configuration unknown-applications unknown-udp sessions-per-hour 10 89 set shared botnet configuration unknown-applications unknown-udp session-length maximum-bytes 100 90 set shared botnet configuration unknown-applications unknown-udp session-length minimum-bytes 50 91 set shared botnet report topn 100 92 set shared botnet report scheduled yes 93 set shared content-preview application 94 set shared content-preview application-type category 95 set shared content-preview application-type technology 96 set shared local-user-database user-group 97 set zone trust network virtual-wire ethernet12 98 set zone untrust network virtual-wire ethernet11 99 set user-id-collector setting enable-mapping-timeout yes100 set user-id-collector setting ip-user-mapping-timeout 45101 set service-group102 set service103 set schedule104 set rulebase security rules rule2 to untrust105 set rulebase security rules rule2 from trust

PAN-OS XML API Labs with pan-python

2

106 set rulebase security rules rule2 source any107 set rulebase security rules rule2 source-user any108 set rulebase security rules rule2 category any109 set rulebase security rules rule2 application any110 set rulebase security rules rule2 service application-default111 set rulebase security rules rule2 hip-profiles any112 set rulebase security rules rule2 action deny113 set rulebase security rules rule2 destination group2114 set rulebase security rules rule1 to untrust115 set rulebase security rules rule1 from trust116 set rulebase security rules rule1 source any117 set rulebase security rules rule1 destination any118 set rulebase security rules rule1 source-user any119 set rulebase security rules rule1 category any120 set rulebase security rules rule1 application any121 set rulebase security rules rule1 service any122 set rulebase security rules rule1 hip-profiles any123 set rulebase security rules rule1 action allow124 set import network interface [ ethernet11 ethernet12 ]125 set dynamic-user-group dug1 filter tag01 or tag02126 set application-group127 set application128 set address-group group1 static [ addr1 addr2 addr3 ]129 set address-group group2 dynamic filter tag01 or tag02130 set address addr1 ip-netmask 10001131 set address addr2 ip-netmask 10002132 set address addr3 ip-netmask 10003133 set address addr4 ip-netmask 10004134 set address addr5 ip-netmask 10005135 set mgt-config users admin phash $1$fniyibcj$0tm9SixJwwOkFkDnEqVw136 set mgt-config users admin permissions role-based superuser yes137 set mgt-config users adminr permissions role-based superreader yes138 set mgt-config users adminr phash $1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1

XML Format ConfigurationThe following PAN-OS configuration is required as a starting point for the labs

NOTE This configuration uses the default credentials admin admin and adminr admin If you apply thisconfiguration to your own firewall be certain to change the passwords from the default Do not apply thisconfiguration to a production firewall Use this configuration at your own risk

If you need a firewall to run this lab on you can easily deploy a firewall in AWS A firewall license is not necessary forany steps in this lab

1 ltconfig urldb=paloaltonetworks version=910gt 2 ltmgt-configgt 3 ltusersgt 4 ltentry name=admingt 5 ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt 6 ltpermissionsgt 7 ltrole-basedgt 8 ltsuperusergtyesltsuperusergt 9 ltrole-basedgt 10 ltpermissionsgt 11 ltentrygt 12 ltentry name=adminrgt 13 ltpermissionsgt 14 ltrole-basedgt 15 ltsuperreadergtyesltsuperreadergt 16 ltrole-basedgt

PAN-OS XML API Labs with pan-python

3

17 ltpermissionsgt 18 ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt 19 ltentrygt 20 ltusersgt 21 ltmgt-configgt 22 ltsharedgt 23 ltapplication gt 24 ltapplication-group gt 25 ltservice gt 26 ltservice-group gt 27 ltbotnetgt 28 ltconfigurationgt 29 lthttpgt 30 ltdynamic-dnsgt 31 ltenabledgtyesltenabledgt 32 ltthresholdgt5ltthresholdgt 33 ltdynamic-dnsgt 34 ltmalware-sitesgt 35 ltenabledgtyesltenabledgt 36 ltthresholdgt5ltthresholdgt 37 ltmalware-sitesgt 38 ltrecent-domainsgt 39 ltenabledgtyesltenabledgt 40 ltthresholdgt5ltthresholdgt 41 ltrecent-domainsgt 42 ltip-domainsgt 43 ltenabledgtyesltenabledgt 44 ltthresholdgt10ltthresholdgt 45 ltip-domainsgt 46 ltexecutables-from-unknown-sitesgt 47 ltenabledgtyesltenabledgt 48 ltthresholdgt5ltthresholdgt 49 ltexecutables-from-unknown-sitesgt 50 lthttpgt 51 ltother-applicationsgt 52 ltircgtyesltircgt 53 ltother-applicationsgt 54 ltunknown-applicationsgt 55 ltunknown-tcpgt 56 ltdestinations-per-hourgt10ltdestinations-per-hourgt 57 ltsessions-per-hourgt10ltsessions-per-hourgt 58 ltsession-lengthgt 59 ltmaximum-bytesgt100ltmaximum-bytesgt 60 ltminimum-bytesgt50ltminimum-bytesgt 61 ltsession-lengthgt 62 ltunknown-tcpgt 63 ltunknown-udpgt 64 ltdestinations-per-hourgt10ltdestinations-per-hourgt 65 ltsessions-per-hourgt10ltsessions-per-hourgt 66 ltsession-lengthgt 67 ltmaximum-bytesgt100ltmaximum-bytesgt 68 ltminimum-bytesgt50ltminimum-bytesgt 69 ltsession-lengthgt 70 ltunknown-udpgt 71 ltunknown-applicationsgt 72 ltconfigurationgt 73 ltreportgt 74 lttopngt100lttopngt 75 ltscheduledgtyesltscheduledgt 76 ltreportgt

PAN-OS XML API Labs with pan-python

4

77 ltbotnetgt 78 ltcontent-previewgt 79 ltapplication gt 80 ltapplication-typegt 81 ltcategory gt 82 lttechnology gt 83 ltapplication-typegt 84 ltcontent-previewgt 85 ltlocal-user-databasegt 86 ltuser-group gt 87 ltlocal-user-databasegt 88 ltsharedgt 89 ltdevicesgt 90 ltentry name=localhostlocaldomaingt 91 ltnetworkgt 92 ltinterfacegt 93 ltethernetgt 94 ltentry name=ethernet11gt 95 ltvirtual-wire gt 96 ltentrygt 97 ltentry name=ethernet12gt 98 ltvirtual-wire gt 99 ltentrygt100 ltethernetgt101 ltinterfacegt102 ltprofilesgt103 ltmonitor-profilegt104 ltentry name=defaultgt105 ltintervalgt3ltintervalgt106 ltthresholdgt5ltthresholdgt107 ltactiongtwait-recoverltactiongt108 ltentrygt109 ltmonitor-profilegt110 ltprofilesgt111 ltikegt112 ltcrypto-profilesgt113 ltike-crypto-profilesgt114 ltentry name=defaultgt115 ltencryptiongt116 ltmembergtaes-128-cbcltmembergt117 ltmembergt3desltmembergt118 ltencryptiongt119 lthashgt120 ltmembergtsha1ltmembergt121 lthashgt122 ltdh-groupgt123 ltmembergtgroup2ltmembergt124 ltdh-groupgt125 ltlifetimegt126 lthoursgt8lthoursgt127 ltlifetimegt128 ltentrygt129 ltentry name=Suite-B-GCM-128gt130 ltencryptiongt131 ltmembergtaes-128-cbcltmembergt132 ltencryptiongt133 lthashgt134 ltmembergtsha256ltmembergt135 lthashgt136 ltdh-groupgt

PAN-OS XML API Labs with pan-python

5

137 ltmembergtgroup19ltmembergt138 ltdh-groupgt139 ltlifetimegt140 lthoursgt8lthoursgt141 ltlifetimegt142 ltentrygt143 ltentry name=Suite-B-GCM-256gt144 ltencryptiongt145 ltmembergtaes-256-cbcltmembergt146 ltencryptiongt147 lthashgt148 ltmembergtsha384ltmembergt149 lthashgt150 ltdh-groupgt151 ltmembergtgroup20ltmembergt152 ltdh-groupgt153 ltlifetimegt154 lthoursgt8lthoursgt155 ltlifetimegt156 ltentrygt157 ltike-crypto-profilesgt158 ltipsec-crypto-profilesgt159 ltentry name=defaultgt160 ltespgt161 ltencryptiongt162 ltmembergtaes-128-cbcltmembergt163 ltmembergt3desltmembergt164 ltencryptiongt165 ltauthenticationgt166 ltmembergtsha1ltmembergt167 ltauthenticationgt168 ltespgt169 ltdh-groupgtgroup2ltdh-groupgt170 ltlifetimegt171 lthoursgt1lthoursgt172 ltlifetimegt173 ltentrygt174 ltentry name=Suite-B-GCM-128gt175 ltespgt176 ltencryptiongt177 ltmembergtaes-128-gcmltmembergt178 ltencryptiongt179 ltauthenticationgt180 ltmembergtnoneltmembergt181 ltauthenticationgt182 ltespgt183 ltdh-groupgtgroup19ltdh-groupgt184 ltlifetimegt185 lthoursgt1lthoursgt186 ltlifetimegt187 ltentrygt188 ltentry name=Suite-B-GCM-256gt189 ltespgt190 ltencryptiongt191 ltmembergtaes-256-gcmltmembergt192 ltencryptiongt193 ltauthenticationgt194 ltmembergtnoneltmembergt195 ltauthenticationgt196 ltespgt

PAN-OS XML API Labs with pan-python

6

197 ltdh-groupgtgroup20ltdh-groupgt198 ltlifetimegt199 lthoursgt1lthoursgt200 ltlifetimegt201 ltentrygt202 ltipsec-crypto-profilesgt203 ltglobal-protect-app-crypto-profilesgt204 ltentry name=defaultgt205 ltencryptiongt206 ltmembergtaes-128-cbcltmembergt207 ltencryptiongt208 ltauthenticationgt209 ltmembergtsha1ltmembergt210 ltauthenticationgt211 ltentrygt212 ltglobal-protect-app-crypto-profilesgt213 ltcrypto-profilesgt214 ltikegt215 ltqosgt216 ltprofilegt217 ltentry name=defaultgt218 ltclass-bandwidth-typegt219 ltmbpsgt220 ltclassgt221 ltentry name=class1gt222 ltprioritygtreal-timeltprioritygt223 ltentrygt224 ltentry name=class2gt225 ltprioritygthighltprioritygt226 ltentrygt227 ltentry name=class3gt228 ltprioritygthighltprioritygt229 ltentrygt230 ltentry name=class4gt231 ltprioritygtmediumltprioritygt232 ltentrygt233 ltentry name=class5gt234 ltprioritygtmediumltprioritygt235 ltentrygt236 ltentry name=class6gt237 ltprioritygtlowltprioritygt238 ltentrygt239 ltentry name=class7gt240 ltprioritygtlowltprioritygt241 ltentrygt242 ltentry name=class8gt243 ltprioritygtlowltprioritygt244 ltentrygt245 ltclassgt246 ltmbpsgt247 ltclass-bandwidth-typegt248 ltentrygt249 ltprofilegt250 ltqosgt251 ltvirtual-routergt252 ltentry name=defaultgt253 ltprotocolgt254 ltbgpgt255 ltenablegtnoltenablegt256 ltdampening-profilegt

PAN-OS XML API Labs with pan-python

7

257 ltentry name=defaultgt258 ltcutoffgt125ltcutoffgt259 ltreusegt05ltreusegt260 ltmax-hold-timegt900ltmax-hold-timegt261 ltdecay-half-life-reachablegt300ltdecay-half-life-reachablegt262 ltdecay-half-life-unreachablegt900ltdecay-half-life-unreachablegt263 ltenablegtyesltenablegt264 ltentrygt265 ltdampening-profilegt266 ltbgpgt267 ltprotocolgt268 ltentrygt269 ltvirtual-routergt270 ltvirtual-wiregt271 ltentry name=default-vwiregt272 ltinterface1gtethernet11ltinterface1gt273 ltinterface2gtethernet12ltinterface2gt274 ltentrygt275 ltvirtual-wiregt276 ltnetworkgt277 ltdeviceconfiggt278 ltsystemgt279 lttypegt280 ltstatic gt281 lttypegt282 ltupdate-servergtupdatespaloaltonetworkscomltupdate-servergt283 ltupdate-schedule gt284 lttimezonegtUSPacificlttimezonegt285 ltservicegt286 ltdisable-telnetgtyesltdisable-telnetgt287 ltdisable-httpgtyesltdisable-httpgt288 ltservicegt289 lthostnamegtPA-VMlthostnamegt290 ltip-addressgt1921681103ltip-addressgt291 ltnetmaskgt2552552550ltnetmaskgt292 ltdefault-gatewaygt1921681254ltdefault-gatewaygt293 ltdns-settinggt294 ltserversgt295 ltprimarygt8888ltprimarygt296 ltserversgt297 ltdns-settinggt298 ltntp-serversgt299 ltprimary-ntp-servergt300 ltntp-server-addressgtuspoolntporgltntp-server-addressgt301 ltauthentication-typegt302 ltnone gt303 ltauthentication-typegt304 ltprimary-ntp-servergt305 ltsecondary-ntp-servergt306 ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt307 ltauthentication-typegt308 ltnone gt309 ltauthentication-typegt310 ltsecondary-ntp-servergt311 ltntp-serversgt312 ltsystemgt313 ltsettinggt314 ltconfiggt315 ltrematchgtyesltrematchgt316 ltconfiggt

PAN-OS XML API Labs with pan-python

8

317 ltmanagementgt318 lthostname-type-in-sysloggtFQDNlthostname-type-in-sysloggt319 ltdisable-predefined-reportsgt320 ltmembergtspyware-infected-hostsltmembergt321 ltmembergttop-application-categoriesltmembergt322 ltmembergttop-technology-categoriesltmembergt323 ltmembergtbandwidth-trendltmembergt324 ltmembergtrisk-trendltmembergt325 ltmembergtthreat-trendltmembergt326 ltmembergttop-usersltmembergt327 ltmembergttop-attacker-sourcesltmembergt328 ltmembergttop-attacker-destinationsltmembergt329 ltmembergttop-victim-sourcesltmembergt330 ltmembergttop-victim-destinationsltmembergt331 ltmembergttop-attackers-by-source-countriesltmembergt332 ltmembergttop-attackers-by-destination-countriesltmembergt333 ltmembergttop-victims-by-source-countriesltmembergt334 ltmembergttop-victims-by-destination-countriesltmembergt335 ltmembergttop-sourcesltmembergt336 ltmembergttop-destinationsltmembergt337 ltmembergttop-destination-countriesltmembergt338 ltmembergttop-source-countriesltmembergt339 ltmembergttop-connectionsltmembergt340 ltmembergttop-ingress-interfacesltmembergt341 ltmembergttop-egress-interfacesltmembergt342 ltmembergttop-ingress-zonesltmembergt343 ltmembergttop-egress-zonesltmembergt344 ltmembergttop-applicationsltmembergt345 ltmembergttop-http-applicationsltmembergt346 ltmembergttop-rulesltmembergt347 ltmembergttop-attacksltmembergt348 ltmembergttop-spyware-threatsltmembergt349 ltmembergttop-virusesltmembergt350 ltmembergttop-vulnerabilitiesltmembergt351 ltmembergtwildfire-file-digestsltmembergt352 ltmembergttop-websitesltmembergt353 ltmembergttop-url-categoriesltmembergt354 ltmembergttop-url-usersltmembergt355 ltmembergttop-url-user-behaviorltmembergt356 ltmembergttop-blocked-websitesltmembergt357 ltmembergttop-blocked-url-categoriesltmembergt358 ltmembergttop-blocked-url-usersltmembergt359 ltmembergttop-blocked-url-user-behaviorltmembergt360 ltmembergtblocked-credential-postltmembergt361 ltmembergtunknown-tcp-connectionsltmembergt362 ltmembergtunknown-udp-connectionsltmembergt363 ltmembergttop-denied-sourcesltmembergt364 ltmembergttop-denied-destinationsltmembergt365 ltmembergttop-denied-applicationsltmembergt366 ltmembergtrisky-usersltmembergt367 ltmembergtSaaS Application Usageltmembergt368 ltmembergtgtp-events-summaryltmembergt369 ltmembergtgtp-malicious-wildfire-submissionsltmembergt370 ltmembergtgtp-security-eventsltmembergt371 ltmembergtgtp-v1-causesltmembergt372 ltmembergtgtp-v2-causesltmembergt373 ltmembergtgtp-users-visiting-malicious-urlltmembergt374 ltmembergttop-gtp-attacker-destinationsltmembergt375 ltmembergttop-gtp-attacker-sourcesltmembergt376 ltmembergttop-gtp-victim-destinationsltmembergt

PAN-OS XML API Labs with pan-python

9

377 ltmembergttop-gtp-victim-sourcesltmembergt378 ltmembergtsctp-error-causesltmembergt379 ltmembergtsctp-events-summaryltmembergt380 ltmembergtsctp-security-eventsltmembergt381 ltdisable-predefined-reportsgt382 ltmanagementgt383 ltauto-mac-detectgtyesltauto-mac-detectgt384 ltsettinggt385 ltdeviceconfiggt386 ltvsysgt387 ltentry name=vsys1gt388 ltapplication gt389 ltapplication-group gt390 ltzonegt391 ltentry name=trustgt392 ltnetworkgt393 ltvirtual-wiregt394 ltmembergtethernet12ltmembergt395 ltvirtual-wiregt396 ltnetworkgt397 ltentrygt398 ltentry name=untrustgt399 ltnetworkgt400 ltvirtual-wiregt401 ltmembergtethernet11ltmembergt402 ltvirtual-wiregt403 ltnetworkgt404 ltentrygt405 ltzonegt406 ltservice gt407 ltservice-group gt408 ltschedule gt409 ltrulebasegt410 ltsecuritygt411 ltrulesgt412 ltentry name=rule2 uuid=031613c5-a691-4887-b284-5af2915e7c36gt413 lttogt414 ltmembergtuntrustltmembergt415 lttogt416 ltfromgt417 ltmembergttrustltmembergt418 ltfromgt419 ltsourcegt420 ltmembergtanyltmembergt421 ltsourcegt422 ltsource-usergt423 ltmembergtanyltmembergt424 ltsource-usergt425 ltcategorygt426 ltmembergtanyltmembergt427 ltcategorygt428 ltapplicationgt429 ltmembergtanyltmembergt430 ltapplicationgt431 ltservicegt432 ltmembergtapplication-defaultltmembergt433 ltservicegt434 lthip-profilesgt435 ltmembergtanyltmembergt436 lthip-profilesgt

PAN-OS XML API Labs with pan-python

10

437 ltactiongtdenyltactiongt438 ltdestinationgt439 ltmembergtgroup2ltmembergt440 ltdestinationgt441 ltentrygt442 ltentry name=rule1 uuid=c678a3fb-0e9b-45b7-aa4f-66a3e8864339gt443 lttogt444 ltmembergtuntrustltmembergt445 lttogt446 ltfromgt447 ltmembergttrustltmembergt448 ltfromgt449 ltsourcegt450 ltmembergtanyltmembergt451 ltsourcegt452 ltdestinationgt453 ltmembergtanyltmembergt454 ltdestinationgt455 ltsource-usergt456 ltmembergtanyltmembergt457 ltsource-usergt458 ltcategorygt459 ltmembergtanyltmembergt460 ltcategorygt461 ltapplicationgt462 ltmembergtanyltmembergt463 ltapplicationgt464 ltservicegt465 ltmembergtanyltmembergt466 ltservicegt467 lthip-profilesgt468 ltmembergtanyltmembergt469 lthip-profilesgt470 ltactiongtallowltactiongt471 ltentrygt472 ltrulesgt473 ltsecuritygt474 ltrulebasegt475 ltimportgt476 ltnetworkgt477 ltinterfacegt478 ltmembergtethernet11ltmembergt479 ltmembergtethernet12ltmembergt480 ltinterfacegt481 ltnetworkgt482 ltimportgt483 ltaddressgt484 ltentry name=addr1gt485 ltip-netmaskgt10001ltip-netmaskgt486 ltentrygt487 ltentry name=addr2gt488 ltip-netmaskgt10002ltip-netmaskgt489 ltentrygt490 ltentry name=addr3gt491 ltip-netmaskgt10003ltip-netmaskgt492 ltentrygt493 ltentry name=addr4gt494 ltip-netmaskgt10004ltip-netmaskgt495 ltentrygt496 ltentry name=addr5gt

PAN-OS XML API Labs with pan-python

11

497 ltip-netmaskgt10005ltip-netmaskgt498 ltentrygt499 ltaddressgt500 ltaddress-groupgt501 ltentry name=group1gt502 ltstaticgt503 ltmembergtaddr1ltmembergt504 ltmembergtaddr2ltmembergt505 ltmembergtaddr3ltmembergt506 ltstaticgt507 ltentrygt508 ltentry name=group2gt509 ltdynamicgt510 ltfiltergttag01 or tag02ltfiltergt511 ltdynamicgt512 ltentrygt513 ltaddress-groupgt514 ltuser-id-collectorgt515 ltsettinggt516 ltenable-mapping-timeoutgtyesltenable-mapping-timeoutgt517 ltip-user-mapping-timeoutgt45ltip-user-mapping-timeoutgt518 ltsettinggt519 ltuser-id-collectorgt520 ltdynamic-user-groupgt521 ltentry name=dug1gt522 ltfiltergttag01 or tag02ltfiltergt523 ltentrygt524 ltdynamic-user-groupgt525 ltentrygt526 ltvsysgt527 ltentrygt528 ltdevicesgt529 ltconfiggt

Introduction to the PAN-OS API

About the API

APIrsquos are very important to Palo Alto Networks Security automation is key to the success of any organization inpreventing cyber attacks So Palo Alto Networks products have comprehensive APIs to enable automation

In this lab wersquoll focus on the PAN-OS API which is the API for the Palo Alto Networks Next-generation Firewall andPanorama Management Center

When connecting to the PAN-OS API

bull Access the API on the management interface using HTTPS just as you would connect to the GUI

bull Connections to the API are treated as general web admin access They create a session just like you wereaccessing the GUI

bull Authentication requires an API key which is generated through an API call

Introduction to the PAN-OS API

12

Some examples of how you might use the PAN-OS API include but are not limited to

bull Read write verify and commit configuration

bull Download reports in XML format

bull Execute operational commands to check health and status

bull Collect logs and pcaps

bull Update dynamic address groups

bull Update user-id mappings

bull And much more

The API BrowserThe Next-generation Firewall and Panorama have an API Browser built in which allows you to explore the API andtrigger simple API calls in the browser itself

You can access the API Browser by adding api to the URL after the IP address of the firewall For example if yourfirewall is at 10001 the URL of the API Browser is https10001api

Lab exercise Try connecting to the API Browser on the firewall in your lab Explore a little to get familiar thencontinue with the lab

API Command TypesThere are several API types as shown in the main page of the API browser

API Types

API Type Description

keygen Generate an API Key (not shown in API Browser)

config Retrieve or modify the configuration

commit Commit the configuration

export Export files packet captures and keys

import Import files certificates response pages and branding

op Operational commands (like lsquoshowrsquo commands)

report Retrieve predefined dynamic and custom reports

user-id UserIP mappings and Dynamic Address Groups

This lab focuses on the following 5 types but the concepts needed to understand these 5 types are the sameconcepts for all the other types

bull keygen

bull config

bull commit

bull op

bull user-id

Introduction to the PAN-OS API

13

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 2: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

ContentsPAN-OS XML API Labs with pan-python 1

Lab PAN-OS Configuration 1

set Format Configuration 1

XML Format Configuration 3

Introduction to the PAN-OS API 12

About the API 12

The API Browser 13

API Command Types 13

Module 1 Getting Started 14

Introducing pan-python 14

Example Install pan-python Using pip 14

Lab 1 14

API Key Generation 14

Example Generate API Key 14

Example Generate panrc Format Without tagname 15

Example Generate panrc Format With tagname 15

Example Create panrc File Using Shell Output Redirection 15

Example Verify panrc File 16

Lab 2 16

Execute Operational Commands 16

Example show system info 18

Lab 3 19

Module 2 Configuration 20

Configuration API Introduction 20

Actions 20

XPath 21

Find the right XPath 22

Technique 1 API Browser 22

Technique 2 Debug CLI 22

Technique 3 Debug GUI 22

Retrieve Configuration - show and get 23

Example Retrieve Administrator Accounts using get and show 24

Lab 4 24

Lab 5 25

Modify Configuration - set and edit 26

Example Disable and Enable Security Rule Using set and edit 26

Difference between set and edit 26

Lab Firewall address Objects 26

Lab 6 27

Lab 7 28

Lab 8 29

Commit Configuration 29

Example Perform Synchronous commit 29

Lab 9 30

Delete Configuration 31

Example Delete Secondary NTP Server 31

Lab 10 32

Example Get Multiple Objects 32

Lab 11 33

XPath Behavioral Differences (Optional) 33

Lab 12 33

Module 3 User-ID 34

User-ID API Introduction 34

Overview 34

User-ID API Call Structure 35

User-ID with pan-python 35

Login and Logout 36

Login Timeout 36

Logout name 36

Example Add User to IP Mappings (login) 37

Lab 13 37

User Groups (Optional) 38

Groups Updates 39

Example Add User to Group Mappings (groups) 40

Lab 14 40

Register-user and Unregister-user - DUG Objects 41

Tags 42

Persistency 42

Timeout Attribute 42

Example Add Tag to User Mappings (register-user) 44

Lab 15 45

Register and Unregister - DAG Objects 47

Tags 48

Persistent Attribute 48

Timeout Attribute 48

Example Add Tag to IP Mappings (register) 50

Lab 16 51

Resources 53

PAN-OS XML API Labs with pan-python

Lab PAN-OS Configuration

set Format ConfigurationThe following PAN-OS configuration is required as a starting point for the labs

NOTE This configuration uses the default credentials admin admin and adminr admin If you apply thisconfiguration to your own firewall be certain to change the passwords from the default Do not apply thisconfiguration to a production firewall Use this configuration at your own risk

If you need a firewall to run this lab on you can easily deploy a firewall in AWS A firewall license is not necessary forany steps in this lab

1 set deviceconfig system type static 2 set deviceconfig system update-server updatespaloaltonetworkscom 3 set deviceconfig system update-schedule 4 set deviceconfig system timezone USPacific 5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service disable-http yes 7 set deviceconfig system hostname PA-VM 8 set deviceconfig system ip-address 1921681103 9 set deviceconfig system netmask 2552552550 10 set deviceconfig system default-gateway 1921681254 11 set deviceconfig system dns-setting servers primary 8888 12 set deviceconfig system ntp-servers primary-ntp-server ntp-server-address uspoolntporg 13 set deviceconfig system ntp-servers primary-ntp-server authentication-type none 14 set deviceconfig system ntp-servers secondary-ntp-server ntp-server-address north-americapoolntporg 15 set deviceconfig system ntp-servers secondary-ntp-server authentication-type none 16 set deviceconfig setting config rematch yes 17 set deviceconfig setting management hostname-type-in-syslog FQDN 18 set deviceconfig setting management disable-predefined-reports [ spyware-infected-hosts top-application-categories top-technology-categories bandwidth-trend risk-trend threat-trend top-users top-attacker-sources top-attacker-destinations top-victim-sources top-victim-destinations top-attackers-by-source-countries top-attackers-by-destination-countries top-victims-by-source-countries top-victims-by-destination-countries top-sources top-destinations top-destination-countries top-source-countries top-connections top-ingress-interfaces top-egress-interfaces top-ingress-zones top-egress-zones top-applications top-http-applications top-rules top-attacks top-spyware-threats top-viruses top-vulnerabilities wildfire-file-digests top-websites top-url-categories top-url-users top-url-user-behavior top-blocked-websites top-blocked-url-categories top-blocked-url-users top-blocked-url-user-behavior blocked-credential-post unknown-tcp-connections unknown-udp-connections top-denied-sources top-denied-destinations top-denied-applications risky-users SaaS Application Usage gtp-events-summary gtp-malicious-wildfire-submissions gtp-security-events gtp-v1-causes gtp-v2-causes gtp-users-visiting-malicious-url top-gtp-attacker-destinations top-gtp-attacker-sources top-gtp-victim-destinations top-gtp-victim-sources sctp-error-causes sctp-events-summary sctp-security-events ] 19 set deviceconfig setting auto-mac-detect yes 20 set network interface ethernet ethernet11 virtual-wire 21 set network interface ethernet ethernet12 virtual-wire 22 set network profiles monitor-profile default interval 3 23 set network profiles monitor-profile default threshold 5 24 set network profiles monitor-profile default action wait-recover 25 set network ike crypto-profiles ike-crypto-profiles default encryption [ aes-128-cbc 3des ] 26 set network ike crypto-profiles ike-crypto-profiles default hash sha1 27 set network ike crypto-profiles ike-crypto-profiles default dh-group group2 28 set network ike crypto-profiles ike-crypto-profiles default lifetime hours 8 29 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-128 encryption aes-128-cbc 30 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-128 hash sha256 31 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-128 dh-group group19 32 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-128 lifetime hours 8 33 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-256 encryption aes-256-cbc 34 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-256 hash sha384 35 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-256 dh-group group20 36 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-256 lifetime hours 8 37 set network ike crypto-profiles ipsec-crypto-profiles default esp encryption [ aes-128-cbc 3des ] 38 set network ike crypto-profiles ipsec-crypto-profiles default esp authentication sha1 39 set network ike crypto-profiles ipsec-crypto-profiles default dh-group group2 40 set network ike crypto-profiles ipsec-crypto-profiles default lifetime hours 1 41 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-128 esp encryption aes-128-gcm 42 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-128 esp authentication none 43 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-128 dh-group group19 44 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-128 lifetime hours 1 45 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 esp encryption aes-256-gcm

PAN-OS XML API Labs with pan-python

1

46 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 esp authentication none 47 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 dh-group group20 48 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 lifetime hours 1 49 set network ike crypto-profiles global-protect-app-crypto-profiles default encryption aes-128-cbc 50 set network ike crypto-profiles global-protect-app-crypto-profiles default authentication sha1 51 set network qos profile default class-bandwidth-type mbps class class1 priority real-time 52 set network qos profile default class-bandwidth-type mbps class class2 priority high 53 set network qos profile default class-bandwidth-type mbps class class3 priority high 54 set network qos profile default class-bandwidth-type mbps class class4 priority medium 55 set network qos profile default class-bandwidth-type mbps class class5 priority medium 56 set network qos profile default class-bandwidth-type mbps class class6 priority low 57 set network qos profile default class-bandwidth-type mbps class class7 priority low 58 set network qos profile default class-bandwidth-type mbps class class8 priority low 59 set network virtual-router default protocol bgp enable no 60 set network virtual-router default protocol bgp dampening-profile default cutoff 125 61 set network virtual-router default protocol bgp dampening-profile default reuse 05 62 set network virtual-router default protocol bgp dampening-profile default max-hold-time 900 63 set network virtual-router default protocol bgp dampening-profile default decay-half-life-reachable 300 64 set network virtual-router default protocol bgp dampening-profile default decay-half-life-unreachable 900 65 set network virtual-router default protocol bgp dampening-profile default enable yes 66 set network virtual-wire default-vwire interface1 ethernet11 67 set network virtual-wire default-vwire interface2 ethernet12 68 set shared application 69 set shared application-group 70 set shared service 71 set shared service-group 72 set shared botnet configuration http dynamic-dns enabled yes 73 set shared botnet configuration http dynamic-dns threshold 5 74 set shared botnet configuration http malware-sites enabled yes 75 set shared botnet configuration http malware-sites threshold 5 76 set shared botnet configuration http recent-domains enabled yes 77 set shared botnet configuration http recent-domains threshold 5 78 set shared botnet configuration http ip-domains enabled yes 79 set shared botnet configuration http ip-domains threshold 10 80 set shared botnet configuration http executables-from-unknown-sites enabled yes 81 set shared botnet configuration http executables-from-unknown-sites threshold 5 82 set shared botnet configuration other-applications irc yes 83 set shared botnet configuration unknown-applications unknown-tcp destinations-per-hour 10 84 set shared botnet configuration unknown-applications unknown-tcp sessions-per-hour 10 85 set shared botnet configuration unknown-applications unknown-tcp session-length maximum-bytes 100 86 set shared botnet configuration unknown-applications unknown-tcp session-length minimum-bytes 50 87 set shared botnet configuration unknown-applications unknown-udp destinations-per-hour 10 88 set shared botnet configuration unknown-applications unknown-udp sessions-per-hour 10 89 set shared botnet configuration unknown-applications unknown-udp session-length maximum-bytes 100 90 set shared botnet configuration unknown-applications unknown-udp session-length minimum-bytes 50 91 set shared botnet report topn 100 92 set shared botnet report scheduled yes 93 set shared content-preview application 94 set shared content-preview application-type category 95 set shared content-preview application-type technology 96 set shared local-user-database user-group 97 set zone trust network virtual-wire ethernet12 98 set zone untrust network virtual-wire ethernet11 99 set user-id-collector setting enable-mapping-timeout yes100 set user-id-collector setting ip-user-mapping-timeout 45101 set service-group102 set service103 set schedule104 set rulebase security rules rule2 to untrust105 set rulebase security rules rule2 from trust

PAN-OS XML API Labs with pan-python

2

106 set rulebase security rules rule2 source any107 set rulebase security rules rule2 source-user any108 set rulebase security rules rule2 category any109 set rulebase security rules rule2 application any110 set rulebase security rules rule2 service application-default111 set rulebase security rules rule2 hip-profiles any112 set rulebase security rules rule2 action deny113 set rulebase security rules rule2 destination group2114 set rulebase security rules rule1 to untrust115 set rulebase security rules rule1 from trust116 set rulebase security rules rule1 source any117 set rulebase security rules rule1 destination any118 set rulebase security rules rule1 source-user any119 set rulebase security rules rule1 category any120 set rulebase security rules rule1 application any121 set rulebase security rules rule1 service any122 set rulebase security rules rule1 hip-profiles any123 set rulebase security rules rule1 action allow124 set import network interface [ ethernet11 ethernet12 ]125 set dynamic-user-group dug1 filter tag01 or tag02126 set application-group127 set application128 set address-group group1 static [ addr1 addr2 addr3 ]129 set address-group group2 dynamic filter tag01 or tag02130 set address addr1 ip-netmask 10001131 set address addr2 ip-netmask 10002132 set address addr3 ip-netmask 10003133 set address addr4 ip-netmask 10004134 set address addr5 ip-netmask 10005135 set mgt-config users admin phash $1$fniyibcj$0tm9SixJwwOkFkDnEqVw136 set mgt-config users admin permissions role-based superuser yes137 set mgt-config users adminr permissions role-based superreader yes138 set mgt-config users adminr phash $1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1

XML Format ConfigurationThe following PAN-OS configuration is required as a starting point for the labs

NOTE This configuration uses the default credentials admin admin and adminr admin If you apply thisconfiguration to your own firewall be certain to change the passwords from the default Do not apply thisconfiguration to a production firewall Use this configuration at your own risk

If you need a firewall to run this lab on you can easily deploy a firewall in AWS A firewall license is not necessary forany steps in this lab

1 ltconfig urldb=paloaltonetworks version=910gt 2 ltmgt-configgt 3 ltusersgt 4 ltentry name=admingt 5 ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt 6 ltpermissionsgt 7 ltrole-basedgt 8 ltsuperusergtyesltsuperusergt 9 ltrole-basedgt 10 ltpermissionsgt 11 ltentrygt 12 ltentry name=adminrgt 13 ltpermissionsgt 14 ltrole-basedgt 15 ltsuperreadergtyesltsuperreadergt 16 ltrole-basedgt

PAN-OS XML API Labs with pan-python

3

17 ltpermissionsgt 18 ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt 19 ltentrygt 20 ltusersgt 21 ltmgt-configgt 22 ltsharedgt 23 ltapplication gt 24 ltapplication-group gt 25 ltservice gt 26 ltservice-group gt 27 ltbotnetgt 28 ltconfigurationgt 29 lthttpgt 30 ltdynamic-dnsgt 31 ltenabledgtyesltenabledgt 32 ltthresholdgt5ltthresholdgt 33 ltdynamic-dnsgt 34 ltmalware-sitesgt 35 ltenabledgtyesltenabledgt 36 ltthresholdgt5ltthresholdgt 37 ltmalware-sitesgt 38 ltrecent-domainsgt 39 ltenabledgtyesltenabledgt 40 ltthresholdgt5ltthresholdgt 41 ltrecent-domainsgt 42 ltip-domainsgt 43 ltenabledgtyesltenabledgt 44 ltthresholdgt10ltthresholdgt 45 ltip-domainsgt 46 ltexecutables-from-unknown-sitesgt 47 ltenabledgtyesltenabledgt 48 ltthresholdgt5ltthresholdgt 49 ltexecutables-from-unknown-sitesgt 50 lthttpgt 51 ltother-applicationsgt 52 ltircgtyesltircgt 53 ltother-applicationsgt 54 ltunknown-applicationsgt 55 ltunknown-tcpgt 56 ltdestinations-per-hourgt10ltdestinations-per-hourgt 57 ltsessions-per-hourgt10ltsessions-per-hourgt 58 ltsession-lengthgt 59 ltmaximum-bytesgt100ltmaximum-bytesgt 60 ltminimum-bytesgt50ltminimum-bytesgt 61 ltsession-lengthgt 62 ltunknown-tcpgt 63 ltunknown-udpgt 64 ltdestinations-per-hourgt10ltdestinations-per-hourgt 65 ltsessions-per-hourgt10ltsessions-per-hourgt 66 ltsession-lengthgt 67 ltmaximum-bytesgt100ltmaximum-bytesgt 68 ltminimum-bytesgt50ltminimum-bytesgt 69 ltsession-lengthgt 70 ltunknown-udpgt 71 ltunknown-applicationsgt 72 ltconfigurationgt 73 ltreportgt 74 lttopngt100lttopngt 75 ltscheduledgtyesltscheduledgt 76 ltreportgt

PAN-OS XML API Labs with pan-python

4

77 ltbotnetgt 78 ltcontent-previewgt 79 ltapplication gt 80 ltapplication-typegt 81 ltcategory gt 82 lttechnology gt 83 ltapplication-typegt 84 ltcontent-previewgt 85 ltlocal-user-databasegt 86 ltuser-group gt 87 ltlocal-user-databasegt 88 ltsharedgt 89 ltdevicesgt 90 ltentry name=localhostlocaldomaingt 91 ltnetworkgt 92 ltinterfacegt 93 ltethernetgt 94 ltentry name=ethernet11gt 95 ltvirtual-wire gt 96 ltentrygt 97 ltentry name=ethernet12gt 98 ltvirtual-wire gt 99 ltentrygt100 ltethernetgt101 ltinterfacegt102 ltprofilesgt103 ltmonitor-profilegt104 ltentry name=defaultgt105 ltintervalgt3ltintervalgt106 ltthresholdgt5ltthresholdgt107 ltactiongtwait-recoverltactiongt108 ltentrygt109 ltmonitor-profilegt110 ltprofilesgt111 ltikegt112 ltcrypto-profilesgt113 ltike-crypto-profilesgt114 ltentry name=defaultgt115 ltencryptiongt116 ltmembergtaes-128-cbcltmembergt117 ltmembergt3desltmembergt118 ltencryptiongt119 lthashgt120 ltmembergtsha1ltmembergt121 lthashgt122 ltdh-groupgt123 ltmembergtgroup2ltmembergt124 ltdh-groupgt125 ltlifetimegt126 lthoursgt8lthoursgt127 ltlifetimegt128 ltentrygt129 ltentry name=Suite-B-GCM-128gt130 ltencryptiongt131 ltmembergtaes-128-cbcltmembergt132 ltencryptiongt133 lthashgt134 ltmembergtsha256ltmembergt135 lthashgt136 ltdh-groupgt

PAN-OS XML API Labs with pan-python

5

137 ltmembergtgroup19ltmembergt138 ltdh-groupgt139 ltlifetimegt140 lthoursgt8lthoursgt141 ltlifetimegt142 ltentrygt143 ltentry name=Suite-B-GCM-256gt144 ltencryptiongt145 ltmembergtaes-256-cbcltmembergt146 ltencryptiongt147 lthashgt148 ltmembergtsha384ltmembergt149 lthashgt150 ltdh-groupgt151 ltmembergtgroup20ltmembergt152 ltdh-groupgt153 ltlifetimegt154 lthoursgt8lthoursgt155 ltlifetimegt156 ltentrygt157 ltike-crypto-profilesgt158 ltipsec-crypto-profilesgt159 ltentry name=defaultgt160 ltespgt161 ltencryptiongt162 ltmembergtaes-128-cbcltmembergt163 ltmembergt3desltmembergt164 ltencryptiongt165 ltauthenticationgt166 ltmembergtsha1ltmembergt167 ltauthenticationgt168 ltespgt169 ltdh-groupgtgroup2ltdh-groupgt170 ltlifetimegt171 lthoursgt1lthoursgt172 ltlifetimegt173 ltentrygt174 ltentry name=Suite-B-GCM-128gt175 ltespgt176 ltencryptiongt177 ltmembergtaes-128-gcmltmembergt178 ltencryptiongt179 ltauthenticationgt180 ltmembergtnoneltmembergt181 ltauthenticationgt182 ltespgt183 ltdh-groupgtgroup19ltdh-groupgt184 ltlifetimegt185 lthoursgt1lthoursgt186 ltlifetimegt187 ltentrygt188 ltentry name=Suite-B-GCM-256gt189 ltespgt190 ltencryptiongt191 ltmembergtaes-256-gcmltmembergt192 ltencryptiongt193 ltauthenticationgt194 ltmembergtnoneltmembergt195 ltauthenticationgt196 ltespgt

PAN-OS XML API Labs with pan-python

6

197 ltdh-groupgtgroup20ltdh-groupgt198 ltlifetimegt199 lthoursgt1lthoursgt200 ltlifetimegt201 ltentrygt202 ltipsec-crypto-profilesgt203 ltglobal-protect-app-crypto-profilesgt204 ltentry name=defaultgt205 ltencryptiongt206 ltmembergtaes-128-cbcltmembergt207 ltencryptiongt208 ltauthenticationgt209 ltmembergtsha1ltmembergt210 ltauthenticationgt211 ltentrygt212 ltglobal-protect-app-crypto-profilesgt213 ltcrypto-profilesgt214 ltikegt215 ltqosgt216 ltprofilegt217 ltentry name=defaultgt218 ltclass-bandwidth-typegt219 ltmbpsgt220 ltclassgt221 ltentry name=class1gt222 ltprioritygtreal-timeltprioritygt223 ltentrygt224 ltentry name=class2gt225 ltprioritygthighltprioritygt226 ltentrygt227 ltentry name=class3gt228 ltprioritygthighltprioritygt229 ltentrygt230 ltentry name=class4gt231 ltprioritygtmediumltprioritygt232 ltentrygt233 ltentry name=class5gt234 ltprioritygtmediumltprioritygt235 ltentrygt236 ltentry name=class6gt237 ltprioritygtlowltprioritygt238 ltentrygt239 ltentry name=class7gt240 ltprioritygtlowltprioritygt241 ltentrygt242 ltentry name=class8gt243 ltprioritygtlowltprioritygt244 ltentrygt245 ltclassgt246 ltmbpsgt247 ltclass-bandwidth-typegt248 ltentrygt249 ltprofilegt250 ltqosgt251 ltvirtual-routergt252 ltentry name=defaultgt253 ltprotocolgt254 ltbgpgt255 ltenablegtnoltenablegt256 ltdampening-profilegt

PAN-OS XML API Labs with pan-python

7

257 ltentry name=defaultgt258 ltcutoffgt125ltcutoffgt259 ltreusegt05ltreusegt260 ltmax-hold-timegt900ltmax-hold-timegt261 ltdecay-half-life-reachablegt300ltdecay-half-life-reachablegt262 ltdecay-half-life-unreachablegt900ltdecay-half-life-unreachablegt263 ltenablegtyesltenablegt264 ltentrygt265 ltdampening-profilegt266 ltbgpgt267 ltprotocolgt268 ltentrygt269 ltvirtual-routergt270 ltvirtual-wiregt271 ltentry name=default-vwiregt272 ltinterface1gtethernet11ltinterface1gt273 ltinterface2gtethernet12ltinterface2gt274 ltentrygt275 ltvirtual-wiregt276 ltnetworkgt277 ltdeviceconfiggt278 ltsystemgt279 lttypegt280 ltstatic gt281 lttypegt282 ltupdate-servergtupdatespaloaltonetworkscomltupdate-servergt283 ltupdate-schedule gt284 lttimezonegtUSPacificlttimezonegt285 ltservicegt286 ltdisable-telnetgtyesltdisable-telnetgt287 ltdisable-httpgtyesltdisable-httpgt288 ltservicegt289 lthostnamegtPA-VMlthostnamegt290 ltip-addressgt1921681103ltip-addressgt291 ltnetmaskgt2552552550ltnetmaskgt292 ltdefault-gatewaygt1921681254ltdefault-gatewaygt293 ltdns-settinggt294 ltserversgt295 ltprimarygt8888ltprimarygt296 ltserversgt297 ltdns-settinggt298 ltntp-serversgt299 ltprimary-ntp-servergt300 ltntp-server-addressgtuspoolntporgltntp-server-addressgt301 ltauthentication-typegt302 ltnone gt303 ltauthentication-typegt304 ltprimary-ntp-servergt305 ltsecondary-ntp-servergt306 ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt307 ltauthentication-typegt308 ltnone gt309 ltauthentication-typegt310 ltsecondary-ntp-servergt311 ltntp-serversgt312 ltsystemgt313 ltsettinggt314 ltconfiggt315 ltrematchgtyesltrematchgt316 ltconfiggt

PAN-OS XML API Labs with pan-python

8

317 ltmanagementgt318 lthostname-type-in-sysloggtFQDNlthostname-type-in-sysloggt319 ltdisable-predefined-reportsgt320 ltmembergtspyware-infected-hostsltmembergt321 ltmembergttop-application-categoriesltmembergt322 ltmembergttop-technology-categoriesltmembergt323 ltmembergtbandwidth-trendltmembergt324 ltmembergtrisk-trendltmembergt325 ltmembergtthreat-trendltmembergt326 ltmembergttop-usersltmembergt327 ltmembergttop-attacker-sourcesltmembergt328 ltmembergttop-attacker-destinationsltmembergt329 ltmembergttop-victim-sourcesltmembergt330 ltmembergttop-victim-destinationsltmembergt331 ltmembergttop-attackers-by-source-countriesltmembergt332 ltmembergttop-attackers-by-destination-countriesltmembergt333 ltmembergttop-victims-by-source-countriesltmembergt334 ltmembergttop-victims-by-destination-countriesltmembergt335 ltmembergttop-sourcesltmembergt336 ltmembergttop-destinationsltmembergt337 ltmembergttop-destination-countriesltmembergt338 ltmembergttop-source-countriesltmembergt339 ltmembergttop-connectionsltmembergt340 ltmembergttop-ingress-interfacesltmembergt341 ltmembergttop-egress-interfacesltmembergt342 ltmembergttop-ingress-zonesltmembergt343 ltmembergttop-egress-zonesltmembergt344 ltmembergttop-applicationsltmembergt345 ltmembergttop-http-applicationsltmembergt346 ltmembergttop-rulesltmembergt347 ltmembergttop-attacksltmembergt348 ltmembergttop-spyware-threatsltmembergt349 ltmembergttop-virusesltmembergt350 ltmembergttop-vulnerabilitiesltmembergt351 ltmembergtwildfire-file-digestsltmembergt352 ltmembergttop-websitesltmembergt353 ltmembergttop-url-categoriesltmembergt354 ltmembergttop-url-usersltmembergt355 ltmembergttop-url-user-behaviorltmembergt356 ltmembergttop-blocked-websitesltmembergt357 ltmembergttop-blocked-url-categoriesltmembergt358 ltmembergttop-blocked-url-usersltmembergt359 ltmembergttop-blocked-url-user-behaviorltmembergt360 ltmembergtblocked-credential-postltmembergt361 ltmembergtunknown-tcp-connectionsltmembergt362 ltmembergtunknown-udp-connectionsltmembergt363 ltmembergttop-denied-sourcesltmembergt364 ltmembergttop-denied-destinationsltmembergt365 ltmembergttop-denied-applicationsltmembergt366 ltmembergtrisky-usersltmembergt367 ltmembergtSaaS Application Usageltmembergt368 ltmembergtgtp-events-summaryltmembergt369 ltmembergtgtp-malicious-wildfire-submissionsltmembergt370 ltmembergtgtp-security-eventsltmembergt371 ltmembergtgtp-v1-causesltmembergt372 ltmembergtgtp-v2-causesltmembergt373 ltmembergtgtp-users-visiting-malicious-urlltmembergt374 ltmembergttop-gtp-attacker-destinationsltmembergt375 ltmembergttop-gtp-attacker-sourcesltmembergt376 ltmembergttop-gtp-victim-destinationsltmembergt

PAN-OS XML API Labs with pan-python

9

377 ltmembergttop-gtp-victim-sourcesltmembergt378 ltmembergtsctp-error-causesltmembergt379 ltmembergtsctp-events-summaryltmembergt380 ltmembergtsctp-security-eventsltmembergt381 ltdisable-predefined-reportsgt382 ltmanagementgt383 ltauto-mac-detectgtyesltauto-mac-detectgt384 ltsettinggt385 ltdeviceconfiggt386 ltvsysgt387 ltentry name=vsys1gt388 ltapplication gt389 ltapplication-group gt390 ltzonegt391 ltentry name=trustgt392 ltnetworkgt393 ltvirtual-wiregt394 ltmembergtethernet12ltmembergt395 ltvirtual-wiregt396 ltnetworkgt397 ltentrygt398 ltentry name=untrustgt399 ltnetworkgt400 ltvirtual-wiregt401 ltmembergtethernet11ltmembergt402 ltvirtual-wiregt403 ltnetworkgt404 ltentrygt405 ltzonegt406 ltservice gt407 ltservice-group gt408 ltschedule gt409 ltrulebasegt410 ltsecuritygt411 ltrulesgt412 ltentry name=rule2 uuid=031613c5-a691-4887-b284-5af2915e7c36gt413 lttogt414 ltmembergtuntrustltmembergt415 lttogt416 ltfromgt417 ltmembergttrustltmembergt418 ltfromgt419 ltsourcegt420 ltmembergtanyltmembergt421 ltsourcegt422 ltsource-usergt423 ltmembergtanyltmembergt424 ltsource-usergt425 ltcategorygt426 ltmembergtanyltmembergt427 ltcategorygt428 ltapplicationgt429 ltmembergtanyltmembergt430 ltapplicationgt431 ltservicegt432 ltmembergtapplication-defaultltmembergt433 ltservicegt434 lthip-profilesgt435 ltmembergtanyltmembergt436 lthip-profilesgt

PAN-OS XML API Labs with pan-python

10

437 ltactiongtdenyltactiongt438 ltdestinationgt439 ltmembergtgroup2ltmembergt440 ltdestinationgt441 ltentrygt442 ltentry name=rule1 uuid=c678a3fb-0e9b-45b7-aa4f-66a3e8864339gt443 lttogt444 ltmembergtuntrustltmembergt445 lttogt446 ltfromgt447 ltmembergttrustltmembergt448 ltfromgt449 ltsourcegt450 ltmembergtanyltmembergt451 ltsourcegt452 ltdestinationgt453 ltmembergtanyltmembergt454 ltdestinationgt455 ltsource-usergt456 ltmembergtanyltmembergt457 ltsource-usergt458 ltcategorygt459 ltmembergtanyltmembergt460 ltcategorygt461 ltapplicationgt462 ltmembergtanyltmembergt463 ltapplicationgt464 ltservicegt465 ltmembergtanyltmembergt466 ltservicegt467 lthip-profilesgt468 ltmembergtanyltmembergt469 lthip-profilesgt470 ltactiongtallowltactiongt471 ltentrygt472 ltrulesgt473 ltsecuritygt474 ltrulebasegt475 ltimportgt476 ltnetworkgt477 ltinterfacegt478 ltmembergtethernet11ltmembergt479 ltmembergtethernet12ltmembergt480 ltinterfacegt481 ltnetworkgt482 ltimportgt483 ltaddressgt484 ltentry name=addr1gt485 ltip-netmaskgt10001ltip-netmaskgt486 ltentrygt487 ltentry name=addr2gt488 ltip-netmaskgt10002ltip-netmaskgt489 ltentrygt490 ltentry name=addr3gt491 ltip-netmaskgt10003ltip-netmaskgt492 ltentrygt493 ltentry name=addr4gt494 ltip-netmaskgt10004ltip-netmaskgt495 ltentrygt496 ltentry name=addr5gt

PAN-OS XML API Labs with pan-python

11

497 ltip-netmaskgt10005ltip-netmaskgt498 ltentrygt499 ltaddressgt500 ltaddress-groupgt501 ltentry name=group1gt502 ltstaticgt503 ltmembergtaddr1ltmembergt504 ltmembergtaddr2ltmembergt505 ltmembergtaddr3ltmembergt506 ltstaticgt507 ltentrygt508 ltentry name=group2gt509 ltdynamicgt510 ltfiltergttag01 or tag02ltfiltergt511 ltdynamicgt512 ltentrygt513 ltaddress-groupgt514 ltuser-id-collectorgt515 ltsettinggt516 ltenable-mapping-timeoutgtyesltenable-mapping-timeoutgt517 ltip-user-mapping-timeoutgt45ltip-user-mapping-timeoutgt518 ltsettinggt519 ltuser-id-collectorgt520 ltdynamic-user-groupgt521 ltentry name=dug1gt522 ltfiltergttag01 or tag02ltfiltergt523 ltentrygt524 ltdynamic-user-groupgt525 ltentrygt526 ltvsysgt527 ltentrygt528 ltdevicesgt529 ltconfiggt

Introduction to the PAN-OS API

About the API

APIrsquos are very important to Palo Alto Networks Security automation is key to the success of any organization inpreventing cyber attacks So Palo Alto Networks products have comprehensive APIs to enable automation

In this lab wersquoll focus on the PAN-OS API which is the API for the Palo Alto Networks Next-generation Firewall andPanorama Management Center

When connecting to the PAN-OS API

bull Access the API on the management interface using HTTPS just as you would connect to the GUI

bull Connections to the API are treated as general web admin access They create a session just like you wereaccessing the GUI

bull Authentication requires an API key which is generated through an API call

Introduction to the PAN-OS API

12

Some examples of how you might use the PAN-OS API include but are not limited to

bull Read write verify and commit configuration

bull Download reports in XML format

bull Execute operational commands to check health and status

bull Collect logs and pcaps

bull Update dynamic address groups

bull Update user-id mappings

bull And much more

The API BrowserThe Next-generation Firewall and Panorama have an API Browser built in which allows you to explore the API andtrigger simple API calls in the browser itself

You can access the API Browser by adding api to the URL after the IP address of the firewall For example if yourfirewall is at 10001 the URL of the API Browser is https10001api

Lab exercise Try connecting to the API Browser on the firewall in your lab Explore a little to get familiar thencontinue with the lab

API Command TypesThere are several API types as shown in the main page of the API browser

API Types

API Type Description

keygen Generate an API Key (not shown in API Browser)

config Retrieve or modify the configuration

commit Commit the configuration

export Export files packet captures and keys

import Import files certificates response pages and branding

op Operational commands (like lsquoshowrsquo commands)

report Retrieve predefined dynamic and custom reports

user-id UserIP mappings and Dynamic Address Groups

This lab focuses on the following 5 types but the concepts needed to understand these 5 types are the sameconcepts for all the other types

bull keygen

bull config

bull commit

bull op

bull user-id

Introduction to the PAN-OS API

13

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 3: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Lab 8 29

Commit Configuration 29

Example Perform Synchronous commit 29

Lab 9 30

Delete Configuration 31

Example Delete Secondary NTP Server 31

Lab 10 32

Example Get Multiple Objects 32

Lab 11 33

XPath Behavioral Differences (Optional) 33

Lab 12 33

Module 3 User-ID 34

User-ID API Introduction 34

Overview 34

User-ID API Call Structure 35

User-ID with pan-python 35

Login and Logout 36

Login Timeout 36

Logout name 36

Example Add User to IP Mappings (login) 37

Lab 13 37

User Groups (Optional) 38

Groups Updates 39

Example Add User to Group Mappings (groups) 40

Lab 14 40

Register-user and Unregister-user - DUG Objects 41

Tags 42

Persistency 42

Timeout Attribute 42

Example Add Tag to User Mappings (register-user) 44

Lab 15 45

Register and Unregister - DAG Objects 47

Tags 48

Persistent Attribute 48

Timeout Attribute 48

Example Add Tag to IP Mappings (register) 50

Lab 16 51

Resources 53

PAN-OS XML API Labs with pan-python

Lab PAN-OS Configuration

set Format ConfigurationThe following PAN-OS configuration is required as a starting point for the labs

NOTE This configuration uses the default credentials admin admin and adminr admin If you apply thisconfiguration to your own firewall be certain to change the passwords from the default Do not apply thisconfiguration to a production firewall Use this configuration at your own risk

If you need a firewall to run this lab on you can easily deploy a firewall in AWS A firewall license is not necessary forany steps in this lab

1 set deviceconfig system type static 2 set deviceconfig system update-server updatespaloaltonetworkscom 3 set deviceconfig system update-schedule 4 set deviceconfig system timezone USPacific 5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service disable-http yes 7 set deviceconfig system hostname PA-VM 8 set deviceconfig system ip-address 1921681103 9 set deviceconfig system netmask 2552552550 10 set deviceconfig system default-gateway 1921681254 11 set deviceconfig system dns-setting servers primary 8888 12 set deviceconfig system ntp-servers primary-ntp-server ntp-server-address uspoolntporg 13 set deviceconfig system ntp-servers primary-ntp-server authentication-type none 14 set deviceconfig system ntp-servers secondary-ntp-server ntp-server-address north-americapoolntporg 15 set deviceconfig system ntp-servers secondary-ntp-server authentication-type none 16 set deviceconfig setting config rematch yes 17 set deviceconfig setting management hostname-type-in-syslog FQDN 18 set deviceconfig setting management disable-predefined-reports [ spyware-infected-hosts top-application-categories top-technology-categories bandwidth-trend risk-trend threat-trend top-users top-attacker-sources top-attacker-destinations top-victim-sources top-victim-destinations top-attackers-by-source-countries top-attackers-by-destination-countries top-victims-by-source-countries top-victims-by-destination-countries top-sources top-destinations top-destination-countries top-source-countries top-connections top-ingress-interfaces top-egress-interfaces top-ingress-zones top-egress-zones top-applications top-http-applications top-rules top-attacks top-spyware-threats top-viruses top-vulnerabilities wildfire-file-digests top-websites top-url-categories top-url-users top-url-user-behavior top-blocked-websites top-blocked-url-categories top-blocked-url-users top-blocked-url-user-behavior blocked-credential-post unknown-tcp-connections unknown-udp-connections top-denied-sources top-denied-destinations top-denied-applications risky-users SaaS Application Usage gtp-events-summary gtp-malicious-wildfire-submissions gtp-security-events gtp-v1-causes gtp-v2-causes gtp-users-visiting-malicious-url top-gtp-attacker-destinations top-gtp-attacker-sources top-gtp-victim-destinations top-gtp-victim-sources sctp-error-causes sctp-events-summary sctp-security-events ] 19 set deviceconfig setting auto-mac-detect yes 20 set network interface ethernet ethernet11 virtual-wire 21 set network interface ethernet ethernet12 virtual-wire 22 set network profiles monitor-profile default interval 3 23 set network profiles monitor-profile default threshold 5 24 set network profiles monitor-profile default action wait-recover 25 set network ike crypto-profiles ike-crypto-profiles default encryption [ aes-128-cbc 3des ] 26 set network ike crypto-profiles ike-crypto-profiles default hash sha1 27 set network ike crypto-profiles ike-crypto-profiles default dh-group group2 28 set network ike crypto-profiles ike-crypto-profiles default lifetime hours 8 29 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-128 encryption aes-128-cbc 30 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-128 hash sha256 31 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-128 dh-group group19 32 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-128 lifetime hours 8 33 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-256 encryption aes-256-cbc 34 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-256 hash sha384 35 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-256 dh-group group20 36 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-256 lifetime hours 8 37 set network ike crypto-profiles ipsec-crypto-profiles default esp encryption [ aes-128-cbc 3des ] 38 set network ike crypto-profiles ipsec-crypto-profiles default esp authentication sha1 39 set network ike crypto-profiles ipsec-crypto-profiles default dh-group group2 40 set network ike crypto-profiles ipsec-crypto-profiles default lifetime hours 1 41 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-128 esp encryption aes-128-gcm 42 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-128 esp authentication none 43 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-128 dh-group group19 44 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-128 lifetime hours 1 45 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 esp encryption aes-256-gcm

PAN-OS XML API Labs with pan-python

1

46 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 esp authentication none 47 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 dh-group group20 48 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 lifetime hours 1 49 set network ike crypto-profiles global-protect-app-crypto-profiles default encryption aes-128-cbc 50 set network ike crypto-profiles global-protect-app-crypto-profiles default authentication sha1 51 set network qos profile default class-bandwidth-type mbps class class1 priority real-time 52 set network qos profile default class-bandwidth-type mbps class class2 priority high 53 set network qos profile default class-bandwidth-type mbps class class3 priority high 54 set network qos profile default class-bandwidth-type mbps class class4 priority medium 55 set network qos profile default class-bandwidth-type mbps class class5 priority medium 56 set network qos profile default class-bandwidth-type mbps class class6 priority low 57 set network qos profile default class-bandwidth-type mbps class class7 priority low 58 set network qos profile default class-bandwidth-type mbps class class8 priority low 59 set network virtual-router default protocol bgp enable no 60 set network virtual-router default protocol bgp dampening-profile default cutoff 125 61 set network virtual-router default protocol bgp dampening-profile default reuse 05 62 set network virtual-router default protocol bgp dampening-profile default max-hold-time 900 63 set network virtual-router default protocol bgp dampening-profile default decay-half-life-reachable 300 64 set network virtual-router default protocol bgp dampening-profile default decay-half-life-unreachable 900 65 set network virtual-router default protocol bgp dampening-profile default enable yes 66 set network virtual-wire default-vwire interface1 ethernet11 67 set network virtual-wire default-vwire interface2 ethernet12 68 set shared application 69 set shared application-group 70 set shared service 71 set shared service-group 72 set shared botnet configuration http dynamic-dns enabled yes 73 set shared botnet configuration http dynamic-dns threshold 5 74 set shared botnet configuration http malware-sites enabled yes 75 set shared botnet configuration http malware-sites threshold 5 76 set shared botnet configuration http recent-domains enabled yes 77 set shared botnet configuration http recent-domains threshold 5 78 set shared botnet configuration http ip-domains enabled yes 79 set shared botnet configuration http ip-domains threshold 10 80 set shared botnet configuration http executables-from-unknown-sites enabled yes 81 set shared botnet configuration http executables-from-unknown-sites threshold 5 82 set shared botnet configuration other-applications irc yes 83 set shared botnet configuration unknown-applications unknown-tcp destinations-per-hour 10 84 set shared botnet configuration unknown-applications unknown-tcp sessions-per-hour 10 85 set shared botnet configuration unknown-applications unknown-tcp session-length maximum-bytes 100 86 set shared botnet configuration unknown-applications unknown-tcp session-length minimum-bytes 50 87 set shared botnet configuration unknown-applications unknown-udp destinations-per-hour 10 88 set shared botnet configuration unknown-applications unknown-udp sessions-per-hour 10 89 set shared botnet configuration unknown-applications unknown-udp session-length maximum-bytes 100 90 set shared botnet configuration unknown-applications unknown-udp session-length minimum-bytes 50 91 set shared botnet report topn 100 92 set shared botnet report scheduled yes 93 set shared content-preview application 94 set shared content-preview application-type category 95 set shared content-preview application-type technology 96 set shared local-user-database user-group 97 set zone trust network virtual-wire ethernet12 98 set zone untrust network virtual-wire ethernet11 99 set user-id-collector setting enable-mapping-timeout yes100 set user-id-collector setting ip-user-mapping-timeout 45101 set service-group102 set service103 set schedule104 set rulebase security rules rule2 to untrust105 set rulebase security rules rule2 from trust

PAN-OS XML API Labs with pan-python

2

106 set rulebase security rules rule2 source any107 set rulebase security rules rule2 source-user any108 set rulebase security rules rule2 category any109 set rulebase security rules rule2 application any110 set rulebase security rules rule2 service application-default111 set rulebase security rules rule2 hip-profiles any112 set rulebase security rules rule2 action deny113 set rulebase security rules rule2 destination group2114 set rulebase security rules rule1 to untrust115 set rulebase security rules rule1 from trust116 set rulebase security rules rule1 source any117 set rulebase security rules rule1 destination any118 set rulebase security rules rule1 source-user any119 set rulebase security rules rule1 category any120 set rulebase security rules rule1 application any121 set rulebase security rules rule1 service any122 set rulebase security rules rule1 hip-profiles any123 set rulebase security rules rule1 action allow124 set import network interface [ ethernet11 ethernet12 ]125 set dynamic-user-group dug1 filter tag01 or tag02126 set application-group127 set application128 set address-group group1 static [ addr1 addr2 addr3 ]129 set address-group group2 dynamic filter tag01 or tag02130 set address addr1 ip-netmask 10001131 set address addr2 ip-netmask 10002132 set address addr3 ip-netmask 10003133 set address addr4 ip-netmask 10004134 set address addr5 ip-netmask 10005135 set mgt-config users admin phash $1$fniyibcj$0tm9SixJwwOkFkDnEqVw136 set mgt-config users admin permissions role-based superuser yes137 set mgt-config users adminr permissions role-based superreader yes138 set mgt-config users adminr phash $1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1

XML Format ConfigurationThe following PAN-OS configuration is required as a starting point for the labs

NOTE This configuration uses the default credentials admin admin and adminr admin If you apply thisconfiguration to your own firewall be certain to change the passwords from the default Do not apply thisconfiguration to a production firewall Use this configuration at your own risk

If you need a firewall to run this lab on you can easily deploy a firewall in AWS A firewall license is not necessary forany steps in this lab

1 ltconfig urldb=paloaltonetworks version=910gt 2 ltmgt-configgt 3 ltusersgt 4 ltentry name=admingt 5 ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt 6 ltpermissionsgt 7 ltrole-basedgt 8 ltsuperusergtyesltsuperusergt 9 ltrole-basedgt 10 ltpermissionsgt 11 ltentrygt 12 ltentry name=adminrgt 13 ltpermissionsgt 14 ltrole-basedgt 15 ltsuperreadergtyesltsuperreadergt 16 ltrole-basedgt

PAN-OS XML API Labs with pan-python

3

17 ltpermissionsgt 18 ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt 19 ltentrygt 20 ltusersgt 21 ltmgt-configgt 22 ltsharedgt 23 ltapplication gt 24 ltapplication-group gt 25 ltservice gt 26 ltservice-group gt 27 ltbotnetgt 28 ltconfigurationgt 29 lthttpgt 30 ltdynamic-dnsgt 31 ltenabledgtyesltenabledgt 32 ltthresholdgt5ltthresholdgt 33 ltdynamic-dnsgt 34 ltmalware-sitesgt 35 ltenabledgtyesltenabledgt 36 ltthresholdgt5ltthresholdgt 37 ltmalware-sitesgt 38 ltrecent-domainsgt 39 ltenabledgtyesltenabledgt 40 ltthresholdgt5ltthresholdgt 41 ltrecent-domainsgt 42 ltip-domainsgt 43 ltenabledgtyesltenabledgt 44 ltthresholdgt10ltthresholdgt 45 ltip-domainsgt 46 ltexecutables-from-unknown-sitesgt 47 ltenabledgtyesltenabledgt 48 ltthresholdgt5ltthresholdgt 49 ltexecutables-from-unknown-sitesgt 50 lthttpgt 51 ltother-applicationsgt 52 ltircgtyesltircgt 53 ltother-applicationsgt 54 ltunknown-applicationsgt 55 ltunknown-tcpgt 56 ltdestinations-per-hourgt10ltdestinations-per-hourgt 57 ltsessions-per-hourgt10ltsessions-per-hourgt 58 ltsession-lengthgt 59 ltmaximum-bytesgt100ltmaximum-bytesgt 60 ltminimum-bytesgt50ltminimum-bytesgt 61 ltsession-lengthgt 62 ltunknown-tcpgt 63 ltunknown-udpgt 64 ltdestinations-per-hourgt10ltdestinations-per-hourgt 65 ltsessions-per-hourgt10ltsessions-per-hourgt 66 ltsession-lengthgt 67 ltmaximum-bytesgt100ltmaximum-bytesgt 68 ltminimum-bytesgt50ltminimum-bytesgt 69 ltsession-lengthgt 70 ltunknown-udpgt 71 ltunknown-applicationsgt 72 ltconfigurationgt 73 ltreportgt 74 lttopngt100lttopngt 75 ltscheduledgtyesltscheduledgt 76 ltreportgt

PAN-OS XML API Labs with pan-python

4

77 ltbotnetgt 78 ltcontent-previewgt 79 ltapplication gt 80 ltapplication-typegt 81 ltcategory gt 82 lttechnology gt 83 ltapplication-typegt 84 ltcontent-previewgt 85 ltlocal-user-databasegt 86 ltuser-group gt 87 ltlocal-user-databasegt 88 ltsharedgt 89 ltdevicesgt 90 ltentry name=localhostlocaldomaingt 91 ltnetworkgt 92 ltinterfacegt 93 ltethernetgt 94 ltentry name=ethernet11gt 95 ltvirtual-wire gt 96 ltentrygt 97 ltentry name=ethernet12gt 98 ltvirtual-wire gt 99 ltentrygt100 ltethernetgt101 ltinterfacegt102 ltprofilesgt103 ltmonitor-profilegt104 ltentry name=defaultgt105 ltintervalgt3ltintervalgt106 ltthresholdgt5ltthresholdgt107 ltactiongtwait-recoverltactiongt108 ltentrygt109 ltmonitor-profilegt110 ltprofilesgt111 ltikegt112 ltcrypto-profilesgt113 ltike-crypto-profilesgt114 ltentry name=defaultgt115 ltencryptiongt116 ltmembergtaes-128-cbcltmembergt117 ltmembergt3desltmembergt118 ltencryptiongt119 lthashgt120 ltmembergtsha1ltmembergt121 lthashgt122 ltdh-groupgt123 ltmembergtgroup2ltmembergt124 ltdh-groupgt125 ltlifetimegt126 lthoursgt8lthoursgt127 ltlifetimegt128 ltentrygt129 ltentry name=Suite-B-GCM-128gt130 ltencryptiongt131 ltmembergtaes-128-cbcltmembergt132 ltencryptiongt133 lthashgt134 ltmembergtsha256ltmembergt135 lthashgt136 ltdh-groupgt

PAN-OS XML API Labs with pan-python

5

137 ltmembergtgroup19ltmembergt138 ltdh-groupgt139 ltlifetimegt140 lthoursgt8lthoursgt141 ltlifetimegt142 ltentrygt143 ltentry name=Suite-B-GCM-256gt144 ltencryptiongt145 ltmembergtaes-256-cbcltmembergt146 ltencryptiongt147 lthashgt148 ltmembergtsha384ltmembergt149 lthashgt150 ltdh-groupgt151 ltmembergtgroup20ltmembergt152 ltdh-groupgt153 ltlifetimegt154 lthoursgt8lthoursgt155 ltlifetimegt156 ltentrygt157 ltike-crypto-profilesgt158 ltipsec-crypto-profilesgt159 ltentry name=defaultgt160 ltespgt161 ltencryptiongt162 ltmembergtaes-128-cbcltmembergt163 ltmembergt3desltmembergt164 ltencryptiongt165 ltauthenticationgt166 ltmembergtsha1ltmembergt167 ltauthenticationgt168 ltespgt169 ltdh-groupgtgroup2ltdh-groupgt170 ltlifetimegt171 lthoursgt1lthoursgt172 ltlifetimegt173 ltentrygt174 ltentry name=Suite-B-GCM-128gt175 ltespgt176 ltencryptiongt177 ltmembergtaes-128-gcmltmembergt178 ltencryptiongt179 ltauthenticationgt180 ltmembergtnoneltmembergt181 ltauthenticationgt182 ltespgt183 ltdh-groupgtgroup19ltdh-groupgt184 ltlifetimegt185 lthoursgt1lthoursgt186 ltlifetimegt187 ltentrygt188 ltentry name=Suite-B-GCM-256gt189 ltespgt190 ltencryptiongt191 ltmembergtaes-256-gcmltmembergt192 ltencryptiongt193 ltauthenticationgt194 ltmembergtnoneltmembergt195 ltauthenticationgt196 ltespgt

PAN-OS XML API Labs with pan-python

6

197 ltdh-groupgtgroup20ltdh-groupgt198 ltlifetimegt199 lthoursgt1lthoursgt200 ltlifetimegt201 ltentrygt202 ltipsec-crypto-profilesgt203 ltglobal-protect-app-crypto-profilesgt204 ltentry name=defaultgt205 ltencryptiongt206 ltmembergtaes-128-cbcltmembergt207 ltencryptiongt208 ltauthenticationgt209 ltmembergtsha1ltmembergt210 ltauthenticationgt211 ltentrygt212 ltglobal-protect-app-crypto-profilesgt213 ltcrypto-profilesgt214 ltikegt215 ltqosgt216 ltprofilegt217 ltentry name=defaultgt218 ltclass-bandwidth-typegt219 ltmbpsgt220 ltclassgt221 ltentry name=class1gt222 ltprioritygtreal-timeltprioritygt223 ltentrygt224 ltentry name=class2gt225 ltprioritygthighltprioritygt226 ltentrygt227 ltentry name=class3gt228 ltprioritygthighltprioritygt229 ltentrygt230 ltentry name=class4gt231 ltprioritygtmediumltprioritygt232 ltentrygt233 ltentry name=class5gt234 ltprioritygtmediumltprioritygt235 ltentrygt236 ltentry name=class6gt237 ltprioritygtlowltprioritygt238 ltentrygt239 ltentry name=class7gt240 ltprioritygtlowltprioritygt241 ltentrygt242 ltentry name=class8gt243 ltprioritygtlowltprioritygt244 ltentrygt245 ltclassgt246 ltmbpsgt247 ltclass-bandwidth-typegt248 ltentrygt249 ltprofilegt250 ltqosgt251 ltvirtual-routergt252 ltentry name=defaultgt253 ltprotocolgt254 ltbgpgt255 ltenablegtnoltenablegt256 ltdampening-profilegt

PAN-OS XML API Labs with pan-python

7

257 ltentry name=defaultgt258 ltcutoffgt125ltcutoffgt259 ltreusegt05ltreusegt260 ltmax-hold-timegt900ltmax-hold-timegt261 ltdecay-half-life-reachablegt300ltdecay-half-life-reachablegt262 ltdecay-half-life-unreachablegt900ltdecay-half-life-unreachablegt263 ltenablegtyesltenablegt264 ltentrygt265 ltdampening-profilegt266 ltbgpgt267 ltprotocolgt268 ltentrygt269 ltvirtual-routergt270 ltvirtual-wiregt271 ltentry name=default-vwiregt272 ltinterface1gtethernet11ltinterface1gt273 ltinterface2gtethernet12ltinterface2gt274 ltentrygt275 ltvirtual-wiregt276 ltnetworkgt277 ltdeviceconfiggt278 ltsystemgt279 lttypegt280 ltstatic gt281 lttypegt282 ltupdate-servergtupdatespaloaltonetworkscomltupdate-servergt283 ltupdate-schedule gt284 lttimezonegtUSPacificlttimezonegt285 ltservicegt286 ltdisable-telnetgtyesltdisable-telnetgt287 ltdisable-httpgtyesltdisable-httpgt288 ltservicegt289 lthostnamegtPA-VMlthostnamegt290 ltip-addressgt1921681103ltip-addressgt291 ltnetmaskgt2552552550ltnetmaskgt292 ltdefault-gatewaygt1921681254ltdefault-gatewaygt293 ltdns-settinggt294 ltserversgt295 ltprimarygt8888ltprimarygt296 ltserversgt297 ltdns-settinggt298 ltntp-serversgt299 ltprimary-ntp-servergt300 ltntp-server-addressgtuspoolntporgltntp-server-addressgt301 ltauthentication-typegt302 ltnone gt303 ltauthentication-typegt304 ltprimary-ntp-servergt305 ltsecondary-ntp-servergt306 ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt307 ltauthentication-typegt308 ltnone gt309 ltauthentication-typegt310 ltsecondary-ntp-servergt311 ltntp-serversgt312 ltsystemgt313 ltsettinggt314 ltconfiggt315 ltrematchgtyesltrematchgt316 ltconfiggt

PAN-OS XML API Labs with pan-python

8

317 ltmanagementgt318 lthostname-type-in-sysloggtFQDNlthostname-type-in-sysloggt319 ltdisable-predefined-reportsgt320 ltmembergtspyware-infected-hostsltmembergt321 ltmembergttop-application-categoriesltmembergt322 ltmembergttop-technology-categoriesltmembergt323 ltmembergtbandwidth-trendltmembergt324 ltmembergtrisk-trendltmembergt325 ltmembergtthreat-trendltmembergt326 ltmembergttop-usersltmembergt327 ltmembergttop-attacker-sourcesltmembergt328 ltmembergttop-attacker-destinationsltmembergt329 ltmembergttop-victim-sourcesltmembergt330 ltmembergttop-victim-destinationsltmembergt331 ltmembergttop-attackers-by-source-countriesltmembergt332 ltmembergttop-attackers-by-destination-countriesltmembergt333 ltmembergttop-victims-by-source-countriesltmembergt334 ltmembergttop-victims-by-destination-countriesltmembergt335 ltmembergttop-sourcesltmembergt336 ltmembergttop-destinationsltmembergt337 ltmembergttop-destination-countriesltmembergt338 ltmembergttop-source-countriesltmembergt339 ltmembergttop-connectionsltmembergt340 ltmembergttop-ingress-interfacesltmembergt341 ltmembergttop-egress-interfacesltmembergt342 ltmembergttop-ingress-zonesltmembergt343 ltmembergttop-egress-zonesltmembergt344 ltmembergttop-applicationsltmembergt345 ltmembergttop-http-applicationsltmembergt346 ltmembergttop-rulesltmembergt347 ltmembergttop-attacksltmembergt348 ltmembergttop-spyware-threatsltmembergt349 ltmembergttop-virusesltmembergt350 ltmembergttop-vulnerabilitiesltmembergt351 ltmembergtwildfire-file-digestsltmembergt352 ltmembergttop-websitesltmembergt353 ltmembergttop-url-categoriesltmembergt354 ltmembergttop-url-usersltmembergt355 ltmembergttop-url-user-behaviorltmembergt356 ltmembergttop-blocked-websitesltmembergt357 ltmembergttop-blocked-url-categoriesltmembergt358 ltmembergttop-blocked-url-usersltmembergt359 ltmembergttop-blocked-url-user-behaviorltmembergt360 ltmembergtblocked-credential-postltmembergt361 ltmembergtunknown-tcp-connectionsltmembergt362 ltmembergtunknown-udp-connectionsltmembergt363 ltmembergttop-denied-sourcesltmembergt364 ltmembergttop-denied-destinationsltmembergt365 ltmembergttop-denied-applicationsltmembergt366 ltmembergtrisky-usersltmembergt367 ltmembergtSaaS Application Usageltmembergt368 ltmembergtgtp-events-summaryltmembergt369 ltmembergtgtp-malicious-wildfire-submissionsltmembergt370 ltmembergtgtp-security-eventsltmembergt371 ltmembergtgtp-v1-causesltmembergt372 ltmembergtgtp-v2-causesltmembergt373 ltmembergtgtp-users-visiting-malicious-urlltmembergt374 ltmembergttop-gtp-attacker-destinationsltmembergt375 ltmembergttop-gtp-attacker-sourcesltmembergt376 ltmembergttop-gtp-victim-destinationsltmembergt

PAN-OS XML API Labs with pan-python

9

377 ltmembergttop-gtp-victim-sourcesltmembergt378 ltmembergtsctp-error-causesltmembergt379 ltmembergtsctp-events-summaryltmembergt380 ltmembergtsctp-security-eventsltmembergt381 ltdisable-predefined-reportsgt382 ltmanagementgt383 ltauto-mac-detectgtyesltauto-mac-detectgt384 ltsettinggt385 ltdeviceconfiggt386 ltvsysgt387 ltentry name=vsys1gt388 ltapplication gt389 ltapplication-group gt390 ltzonegt391 ltentry name=trustgt392 ltnetworkgt393 ltvirtual-wiregt394 ltmembergtethernet12ltmembergt395 ltvirtual-wiregt396 ltnetworkgt397 ltentrygt398 ltentry name=untrustgt399 ltnetworkgt400 ltvirtual-wiregt401 ltmembergtethernet11ltmembergt402 ltvirtual-wiregt403 ltnetworkgt404 ltentrygt405 ltzonegt406 ltservice gt407 ltservice-group gt408 ltschedule gt409 ltrulebasegt410 ltsecuritygt411 ltrulesgt412 ltentry name=rule2 uuid=031613c5-a691-4887-b284-5af2915e7c36gt413 lttogt414 ltmembergtuntrustltmembergt415 lttogt416 ltfromgt417 ltmembergttrustltmembergt418 ltfromgt419 ltsourcegt420 ltmembergtanyltmembergt421 ltsourcegt422 ltsource-usergt423 ltmembergtanyltmembergt424 ltsource-usergt425 ltcategorygt426 ltmembergtanyltmembergt427 ltcategorygt428 ltapplicationgt429 ltmembergtanyltmembergt430 ltapplicationgt431 ltservicegt432 ltmembergtapplication-defaultltmembergt433 ltservicegt434 lthip-profilesgt435 ltmembergtanyltmembergt436 lthip-profilesgt

PAN-OS XML API Labs with pan-python

10

437 ltactiongtdenyltactiongt438 ltdestinationgt439 ltmembergtgroup2ltmembergt440 ltdestinationgt441 ltentrygt442 ltentry name=rule1 uuid=c678a3fb-0e9b-45b7-aa4f-66a3e8864339gt443 lttogt444 ltmembergtuntrustltmembergt445 lttogt446 ltfromgt447 ltmembergttrustltmembergt448 ltfromgt449 ltsourcegt450 ltmembergtanyltmembergt451 ltsourcegt452 ltdestinationgt453 ltmembergtanyltmembergt454 ltdestinationgt455 ltsource-usergt456 ltmembergtanyltmembergt457 ltsource-usergt458 ltcategorygt459 ltmembergtanyltmembergt460 ltcategorygt461 ltapplicationgt462 ltmembergtanyltmembergt463 ltapplicationgt464 ltservicegt465 ltmembergtanyltmembergt466 ltservicegt467 lthip-profilesgt468 ltmembergtanyltmembergt469 lthip-profilesgt470 ltactiongtallowltactiongt471 ltentrygt472 ltrulesgt473 ltsecuritygt474 ltrulebasegt475 ltimportgt476 ltnetworkgt477 ltinterfacegt478 ltmembergtethernet11ltmembergt479 ltmembergtethernet12ltmembergt480 ltinterfacegt481 ltnetworkgt482 ltimportgt483 ltaddressgt484 ltentry name=addr1gt485 ltip-netmaskgt10001ltip-netmaskgt486 ltentrygt487 ltentry name=addr2gt488 ltip-netmaskgt10002ltip-netmaskgt489 ltentrygt490 ltentry name=addr3gt491 ltip-netmaskgt10003ltip-netmaskgt492 ltentrygt493 ltentry name=addr4gt494 ltip-netmaskgt10004ltip-netmaskgt495 ltentrygt496 ltentry name=addr5gt

PAN-OS XML API Labs with pan-python

11

497 ltip-netmaskgt10005ltip-netmaskgt498 ltentrygt499 ltaddressgt500 ltaddress-groupgt501 ltentry name=group1gt502 ltstaticgt503 ltmembergtaddr1ltmembergt504 ltmembergtaddr2ltmembergt505 ltmembergtaddr3ltmembergt506 ltstaticgt507 ltentrygt508 ltentry name=group2gt509 ltdynamicgt510 ltfiltergttag01 or tag02ltfiltergt511 ltdynamicgt512 ltentrygt513 ltaddress-groupgt514 ltuser-id-collectorgt515 ltsettinggt516 ltenable-mapping-timeoutgtyesltenable-mapping-timeoutgt517 ltip-user-mapping-timeoutgt45ltip-user-mapping-timeoutgt518 ltsettinggt519 ltuser-id-collectorgt520 ltdynamic-user-groupgt521 ltentry name=dug1gt522 ltfiltergttag01 or tag02ltfiltergt523 ltentrygt524 ltdynamic-user-groupgt525 ltentrygt526 ltvsysgt527 ltentrygt528 ltdevicesgt529 ltconfiggt

Introduction to the PAN-OS API

About the API

APIrsquos are very important to Palo Alto Networks Security automation is key to the success of any organization inpreventing cyber attacks So Palo Alto Networks products have comprehensive APIs to enable automation

In this lab wersquoll focus on the PAN-OS API which is the API for the Palo Alto Networks Next-generation Firewall andPanorama Management Center

When connecting to the PAN-OS API

bull Access the API on the management interface using HTTPS just as you would connect to the GUI

bull Connections to the API are treated as general web admin access They create a session just like you wereaccessing the GUI

bull Authentication requires an API key which is generated through an API call

Introduction to the PAN-OS API

12

Some examples of how you might use the PAN-OS API include but are not limited to

bull Read write verify and commit configuration

bull Download reports in XML format

bull Execute operational commands to check health and status

bull Collect logs and pcaps

bull Update dynamic address groups

bull Update user-id mappings

bull And much more

The API BrowserThe Next-generation Firewall and Panorama have an API Browser built in which allows you to explore the API andtrigger simple API calls in the browser itself

You can access the API Browser by adding api to the URL after the IP address of the firewall For example if yourfirewall is at 10001 the URL of the API Browser is https10001api

Lab exercise Try connecting to the API Browser on the firewall in your lab Explore a little to get familiar thencontinue with the lab

API Command TypesThere are several API types as shown in the main page of the API browser

API Types

API Type Description

keygen Generate an API Key (not shown in API Browser)

config Retrieve or modify the configuration

commit Commit the configuration

export Export files packet captures and keys

import Import files certificates response pages and branding

op Operational commands (like lsquoshowrsquo commands)

report Retrieve predefined dynamic and custom reports

user-id UserIP mappings and Dynamic Address Groups

This lab focuses on the following 5 types but the concepts needed to understand these 5 types are the sameconcepts for all the other types

bull keygen

bull config

bull commit

bull op

bull user-id

Introduction to the PAN-OS API

13

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 4: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

PAN-OS XML API Labs with pan-python

Lab PAN-OS Configuration

set Format ConfigurationThe following PAN-OS configuration is required as a starting point for the labs

NOTE This configuration uses the default credentials admin admin and adminr admin If you apply thisconfiguration to your own firewall be certain to change the passwords from the default Do not apply thisconfiguration to a production firewall Use this configuration at your own risk

If you need a firewall to run this lab on you can easily deploy a firewall in AWS A firewall license is not necessary forany steps in this lab

1 set deviceconfig system type static 2 set deviceconfig system update-server updatespaloaltonetworkscom 3 set deviceconfig system update-schedule 4 set deviceconfig system timezone USPacific 5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service disable-http yes 7 set deviceconfig system hostname PA-VM 8 set deviceconfig system ip-address 1921681103 9 set deviceconfig system netmask 2552552550 10 set deviceconfig system default-gateway 1921681254 11 set deviceconfig system dns-setting servers primary 8888 12 set deviceconfig system ntp-servers primary-ntp-server ntp-server-address uspoolntporg 13 set deviceconfig system ntp-servers primary-ntp-server authentication-type none 14 set deviceconfig system ntp-servers secondary-ntp-server ntp-server-address north-americapoolntporg 15 set deviceconfig system ntp-servers secondary-ntp-server authentication-type none 16 set deviceconfig setting config rematch yes 17 set deviceconfig setting management hostname-type-in-syslog FQDN 18 set deviceconfig setting management disable-predefined-reports [ spyware-infected-hosts top-application-categories top-technology-categories bandwidth-trend risk-trend threat-trend top-users top-attacker-sources top-attacker-destinations top-victim-sources top-victim-destinations top-attackers-by-source-countries top-attackers-by-destination-countries top-victims-by-source-countries top-victims-by-destination-countries top-sources top-destinations top-destination-countries top-source-countries top-connections top-ingress-interfaces top-egress-interfaces top-ingress-zones top-egress-zones top-applications top-http-applications top-rules top-attacks top-spyware-threats top-viruses top-vulnerabilities wildfire-file-digests top-websites top-url-categories top-url-users top-url-user-behavior top-blocked-websites top-blocked-url-categories top-blocked-url-users top-blocked-url-user-behavior blocked-credential-post unknown-tcp-connections unknown-udp-connections top-denied-sources top-denied-destinations top-denied-applications risky-users SaaS Application Usage gtp-events-summary gtp-malicious-wildfire-submissions gtp-security-events gtp-v1-causes gtp-v2-causes gtp-users-visiting-malicious-url top-gtp-attacker-destinations top-gtp-attacker-sources top-gtp-victim-destinations top-gtp-victim-sources sctp-error-causes sctp-events-summary sctp-security-events ] 19 set deviceconfig setting auto-mac-detect yes 20 set network interface ethernet ethernet11 virtual-wire 21 set network interface ethernet ethernet12 virtual-wire 22 set network profiles monitor-profile default interval 3 23 set network profiles monitor-profile default threshold 5 24 set network profiles monitor-profile default action wait-recover 25 set network ike crypto-profiles ike-crypto-profiles default encryption [ aes-128-cbc 3des ] 26 set network ike crypto-profiles ike-crypto-profiles default hash sha1 27 set network ike crypto-profiles ike-crypto-profiles default dh-group group2 28 set network ike crypto-profiles ike-crypto-profiles default lifetime hours 8 29 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-128 encryption aes-128-cbc 30 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-128 hash sha256 31 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-128 dh-group group19 32 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-128 lifetime hours 8 33 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-256 encryption aes-256-cbc 34 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-256 hash sha384 35 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-256 dh-group group20 36 set network ike crypto-profiles ike-crypto-profiles Suite-B-GCM-256 lifetime hours 8 37 set network ike crypto-profiles ipsec-crypto-profiles default esp encryption [ aes-128-cbc 3des ] 38 set network ike crypto-profiles ipsec-crypto-profiles default esp authentication sha1 39 set network ike crypto-profiles ipsec-crypto-profiles default dh-group group2 40 set network ike crypto-profiles ipsec-crypto-profiles default lifetime hours 1 41 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-128 esp encryption aes-128-gcm 42 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-128 esp authentication none 43 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-128 dh-group group19 44 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-128 lifetime hours 1 45 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 esp encryption aes-256-gcm

PAN-OS XML API Labs with pan-python

1

46 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 esp authentication none 47 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 dh-group group20 48 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 lifetime hours 1 49 set network ike crypto-profiles global-protect-app-crypto-profiles default encryption aes-128-cbc 50 set network ike crypto-profiles global-protect-app-crypto-profiles default authentication sha1 51 set network qos profile default class-bandwidth-type mbps class class1 priority real-time 52 set network qos profile default class-bandwidth-type mbps class class2 priority high 53 set network qos profile default class-bandwidth-type mbps class class3 priority high 54 set network qos profile default class-bandwidth-type mbps class class4 priority medium 55 set network qos profile default class-bandwidth-type mbps class class5 priority medium 56 set network qos profile default class-bandwidth-type mbps class class6 priority low 57 set network qos profile default class-bandwidth-type mbps class class7 priority low 58 set network qos profile default class-bandwidth-type mbps class class8 priority low 59 set network virtual-router default protocol bgp enable no 60 set network virtual-router default protocol bgp dampening-profile default cutoff 125 61 set network virtual-router default protocol bgp dampening-profile default reuse 05 62 set network virtual-router default protocol bgp dampening-profile default max-hold-time 900 63 set network virtual-router default protocol bgp dampening-profile default decay-half-life-reachable 300 64 set network virtual-router default protocol bgp dampening-profile default decay-half-life-unreachable 900 65 set network virtual-router default protocol bgp dampening-profile default enable yes 66 set network virtual-wire default-vwire interface1 ethernet11 67 set network virtual-wire default-vwire interface2 ethernet12 68 set shared application 69 set shared application-group 70 set shared service 71 set shared service-group 72 set shared botnet configuration http dynamic-dns enabled yes 73 set shared botnet configuration http dynamic-dns threshold 5 74 set shared botnet configuration http malware-sites enabled yes 75 set shared botnet configuration http malware-sites threshold 5 76 set shared botnet configuration http recent-domains enabled yes 77 set shared botnet configuration http recent-domains threshold 5 78 set shared botnet configuration http ip-domains enabled yes 79 set shared botnet configuration http ip-domains threshold 10 80 set shared botnet configuration http executables-from-unknown-sites enabled yes 81 set shared botnet configuration http executables-from-unknown-sites threshold 5 82 set shared botnet configuration other-applications irc yes 83 set shared botnet configuration unknown-applications unknown-tcp destinations-per-hour 10 84 set shared botnet configuration unknown-applications unknown-tcp sessions-per-hour 10 85 set shared botnet configuration unknown-applications unknown-tcp session-length maximum-bytes 100 86 set shared botnet configuration unknown-applications unknown-tcp session-length minimum-bytes 50 87 set shared botnet configuration unknown-applications unknown-udp destinations-per-hour 10 88 set shared botnet configuration unknown-applications unknown-udp sessions-per-hour 10 89 set shared botnet configuration unknown-applications unknown-udp session-length maximum-bytes 100 90 set shared botnet configuration unknown-applications unknown-udp session-length minimum-bytes 50 91 set shared botnet report topn 100 92 set shared botnet report scheduled yes 93 set shared content-preview application 94 set shared content-preview application-type category 95 set shared content-preview application-type technology 96 set shared local-user-database user-group 97 set zone trust network virtual-wire ethernet12 98 set zone untrust network virtual-wire ethernet11 99 set user-id-collector setting enable-mapping-timeout yes100 set user-id-collector setting ip-user-mapping-timeout 45101 set service-group102 set service103 set schedule104 set rulebase security rules rule2 to untrust105 set rulebase security rules rule2 from trust

PAN-OS XML API Labs with pan-python

2

106 set rulebase security rules rule2 source any107 set rulebase security rules rule2 source-user any108 set rulebase security rules rule2 category any109 set rulebase security rules rule2 application any110 set rulebase security rules rule2 service application-default111 set rulebase security rules rule2 hip-profiles any112 set rulebase security rules rule2 action deny113 set rulebase security rules rule2 destination group2114 set rulebase security rules rule1 to untrust115 set rulebase security rules rule1 from trust116 set rulebase security rules rule1 source any117 set rulebase security rules rule1 destination any118 set rulebase security rules rule1 source-user any119 set rulebase security rules rule1 category any120 set rulebase security rules rule1 application any121 set rulebase security rules rule1 service any122 set rulebase security rules rule1 hip-profiles any123 set rulebase security rules rule1 action allow124 set import network interface [ ethernet11 ethernet12 ]125 set dynamic-user-group dug1 filter tag01 or tag02126 set application-group127 set application128 set address-group group1 static [ addr1 addr2 addr3 ]129 set address-group group2 dynamic filter tag01 or tag02130 set address addr1 ip-netmask 10001131 set address addr2 ip-netmask 10002132 set address addr3 ip-netmask 10003133 set address addr4 ip-netmask 10004134 set address addr5 ip-netmask 10005135 set mgt-config users admin phash $1$fniyibcj$0tm9SixJwwOkFkDnEqVw136 set mgt-config users admin permissions role-based superuser yes137 set mgt-config users adminr permissions role-based superreader yes138 set mgt-config users adminr phash $1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1

XML Format ConfigurationThe following PAN-OS configuration is required as a starting point for the labs

NOTE This configuration uses the default credentials admin admin and adminr admin If you apply thisconfiguration to your own firewall be certain to change the passwords from the default Do not apply thisconfiguration to a production firewall Use this configuration at your own risk

If you need a firewall to run this lab on you can easily deploy a firewall in AWS A firewall license is not necessary forany steps in this lab

1 ltconfig urldb=paloaltonetworks version=910gt 2 ltmgt-configgt 3 ltusersgt 4 ltentry name=admingt 5 ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt 6 ltpermissionsgt 7 ltrole-basedgt 8 ltsuperusergtyesltsuperusergt 9 ltrole-basedgt 10 ltpermissionsgt 11 ltentrygt 12 ltentry name=adminrgt 13 ltpermissionsgt 14 ltrole-basedgt 15 ltsuperreadergtyesltsuperreadergt 16 ltrole-basedgt

PAN-OS XML API Labs with pan-python

3

17 ltpermissionsgt 18 ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt 19 ltentrygt 20 ltusersgt 21 ltmgt-configgt 22 ltsharedgt 23 ltapplication gt 24 ltapplication-group gt 25 ltservice gt 26 ltservice-group gt 27 ltbotnetgt 28 ltconfigurationgt 29 lthttpgt 30 ltdynamic-dnsgt 31 ltenabledgtyesltenabledgt 32 ltthresholdgt5ltthresholdgt 33 ltdynamic-dnsgt 34 ltmalware-sitesgt 35 ltenabledgtyesltenabledgt 36 ltthresholdgt5ltthresholdgt 37 ltmalware-sitesgt 38 ltrecent-domainsgt 39 ltenabledgtyesltenabledgt 40 ltthresholdgt5ltthresholdgt 41 ltrecent-domainsgt 42 ltip-domainsgt 43 ltenabledgtyesltenabledgt 44 ltthresholdgt10ltthresholdgt 45 ltip-domainsgt 46 ltexecutables-from-unknown-sitesgt 47 ltenabledgtyesltenabledgt 48 ltthresholdgt5ltthresholdgt 49 ltexecutables-from-unknown-sitesgt 50 lthttpgt 51 ltother-applicationsgt 52 ltircgtyesltircgt 53 ltother-applicationsgt 54 ltunknown-applicationsgt 55 ltunknown-tcpgt 56 ltdestinations-per-hourgt10ltdestinations-per-hourgt 57 ltsessions-per-hourgt10ltsessions-per-hourgt 58 ltsession-lengthgt 59 ltmaximum-bytesgt100ltmaximum-bytesgt 60 ltminimum-bytesgt50ltminimum-bytesgt 61 ltsession-lengthgt 62 ltunknown-tcpgt 63 ltunknown-udpgt 64 ltdestinations-per-hourgt10ltdestinations-per-hourgt 65 ltsessions-per-hourgt10ltsessions-per-hourgt 66 ltsession-lengthgt 67 ltmaximum-bytesgt100ltmaximum-bytesgt 68 ltminimum-bytesgt50ltminimum-bytesgt 69 ltsession-lengthgt 70 ltunknown-udpgt 71 ltunknown-applicationsgt 72 ltconfigurationgt 73 ltreportgt 74 lttopngt100lttopngt 75 ltscheduledgtyesltscheduledgt 76 ltreportgt

PAN-OS XML API Labs with pan-python

4

77 ltbotnetgt 78 ltcontent-previewgt 79 ltapplication gt 80 ltapplication-typegt 81 ltcategory gt 82 lttechnology gt 83 ltapplication-typegt 84 ltcontent-previewgt 85 ltlocal-user-databasegt 86 ltuser-group gt 87 ltlocal-user-databasegt 88 ltsharedgt 89 ltdevicesgt 90 ltentry name=localhostlocaldomaingt 91 ltnetworkgt 92 ltinterfacegt 93 ltethernetgt 94 ltentry name=ethernet11gt 95 ltvirtual-wire gt 96 ltentrygt 97 ltentry name=ethernet12gt 98 ltvirtual-wire gt 99 ltentrygt100 ltethernetgt101 ltinterfacegt102 ltprofilesgt103 ltmonitor-profilegt104 ltentry name=defaultgt105 ltintervalgt3ltintervalgt106 ltthresholdgt5ltthresholdgt107 ltactiongtwait-recoverltactiongt108 ltentrygt109 ltmonitor-profilegt110 ltprofilesgt111 ltikegt112 ltcrypto-profilesgt113 ltike-crypto-profilesgt114 ltentry name=defaultgt115 ltencryptiongt116 ltmembergtaes-128-cbcltmembergt117 ltmembergt3desltmembergt118 ltencryptiongt119 lthashgt120 ltmembergtsha1ltmembergt121 lthashgt122 ltdh-groupgt123 ltmembergtgroup2ltmembergt124 ltdh-groupgt125 ltlifetimegt126 lthoursgt8lthoursgt127 ltlifetimegt128 ltentrygt129 ltentry name=Suite-B-GCM-128gt130 ltencryptiongt131 ltmembergtaes-128-cbcltmembergt132 ltencryptiongt133 lthashgt134 ltmembergtsha256ltmembergt135 lthashgt136 ltdh-groupgt

PAN-OS XML API Labs with pan-python

5

137 ltmembergtgroup19ltmembergt138 ltdh-groupgt139 ltlifetimegt140 lthoursgt8lthoursgt141 ltlifetimegt142 ltentrygt143 ltentry name=Suite-B-GCM-256gt144 ltencryptiongt145 ltmembergtaes-256-cbcltmembergt146 ltencryptiongt147 lthashgt148 ltmembergtsha384ltmembergt149 lthashgt150 ltdh-groupgt151 ltmembergtgroup20ltmembergt152 ltdh-groupgt153 ltlifetimegt154 lthoursgt8lthoursgt155 ltlifetimegt156 ltentrygt157 ltike-crypto-profilesgt158 ltipsec-crypto-profilesgt159 ltentry name=defaultgt160 ltespgt161 ltencryptiongt162 ltmembergtaes-128-cbcltmembergt163 ltmembergt3desltmembergt164 ltencryptiongt165 ltauthenticationgt166 ltmembergtsha1ltmembergt167 ltauthenticationgt168 ltespgt169 ltdh-groupgtgroup2ltdh-groupgt170 ltlifetimegt171 lthoursgt1lthoursgt172 ltlifetimegt173 ltentrygt174 ltentry name=Suite-B-GCM-128gt175 ltespgt176 ltencryptiongt177 ltmembergtaes-128-gcmltmembergt178 ltencryptiongt179 ltauthenticationgt180 ltmembergtnoneltmembergt181 ltauthenticationgt182 ltespgt183 ltdh-groupgtgroup19ltdh-groupgt184 ltlifetimegt185 lthoursgt1lthoursgt186 ltlifetimegt187 ltentrygt188 ltentry name=Suite-B-GCM-256gt189 ltespgt190 ltencryptiongt191 ltmembergtaes-256-gcmltmembergt192 ltencryptiongt193 ltauthenticationgt194 ltmembergtnoneltmembergt195 ltauthenticationgt196 ltespgt

PAN-OS XML API Labs with pan-python

6

197 ltdh-groupgtgroup20ltdh-groupgt198 ltlifetimegt199 lthoursgt1lthoursgt200 ltlifetimegt201 ltentrygt202 ltipsec-crypto-profilesgt203 ltglobal-protect-app-crypto-profilesgt204 ltentry name=defaultgt205 ltencryptiongt206 ltmembergtaes-128-cbcltmembergt207 ltencryptiongt208 ltauthenticationgt209 ltmembergtsha1ltmembergt210 ltauthenticationgt211 ltentrygt212 ltglobal-protect-app-crypto-profilesgt213 ltcrypto-profilesgt214 ltikegt215 ltqosgt216 ltprofilegt217 ltentry name=defaultgt218 ltclass-bandwidth-typegt219 ltmbpsgt220 ltclassgt221 ltentry name=class1gt222 ltprioritygtreal-timeltprioritygt223 ltentrygt224 ltentry name=class2gt225 ltprioritygthighltprioritygt226 ltentrygt227 ltentry name=class3gt228 ltprioritygthighltprioritygt229 ltentrygt230 ltentry name=class4gt231 ltprioritygtmediumltprioritygt232 ltentrygt233 ltentry name=class5gt234 ltprioritygtmediumltprioritygt235 ltentrygt236 ltentry name=class6gt237 ltprioritygtlowltprioritygt238 ltentrygt239 ltentry name=class7gt240 ltprioritygtlowltprioritygt241 ltentrygt242 ltentry name=class8gt243 ltprioritygtlowltprioritygt244 ltentrygt245 ltclassgt246 ltmbpsgt247 ltclass-bandwidth-typegt248 ltentrygt249 ltprofilegt250 ltqosgt251 ltvirtual-routergt252 ltentry name=defaultgt253 ltprotocolgt254 ltbgpgt255 ltenablegtnoltenablegt256 ltdampening-profilegt

PAN-OS XML API Labs with pan-python

7

257 ltentry name=defaultgt258 ltcutoffgt125ltcutoffgt259 ltreusegt05ltreusegt260 ltmax-hold-timegt900ltmax-hold-timegt261 ltdecay-half-life-reachablegt300ltdecay-half-life-reachablegt262 ltdecay-half-life-unreachablegt900ltdecay-half-life-unreachablegt263 ltenablegtyesltenablegt264 ltentrygt265 ltdampening-profilegt266 ltbgpgt267 ltprotocolgt268 ltentrygt269 ltvirtual-routergt270 ltvirtual-wiregt271 ltentry name=default-vwiregt272 ltinterface1gtethernet11ltinterface1gt273 ltinterface2gtethernet12ltinterface2gt274 ltentrygt275 ltvirtual-wiregt276 ltnetworkgt277 ltdeviceconfiggt278 ltsystemgt279 lttypegt280 ltstatic gt281 lttypegt282 ltupdate-servergtupdatespaloaltonetworkscomltupdate-servergt283 ltupdate-schedule gt284 lttimezonegtUSPacificlttimezonegt285 ltservicegt286 ltdisable-telnetgtyesltdisable-telnetgt287 ltdisable-httpgtyesltdisable-httpgt288 ltservicegt289 lthostnamegtPA-VMlthostnamegt290 ltip-addressgt1921681103ltip-addressgt291 ltnetmaskgt2552552550ltnetmaskgt292 ltdefault-gatewaygt1921681254ltdefault-gatewaygt293 ltdns-settinggt294 ltserversgt295 ltprimarygt8888ltprimarygt296 ltserversgt297 ltdns-settinggt298 ltntp-serversgt299 ltprimary-ntp-servergt300 ltntp-server-addressgtuspoolntporgltntp-server-addressgt301 ltauthentication-typegt302 ltnone gt303 ltauthentication-typegt304 ltprimary-ntp-servergt305 ltsecondary-ntp-servergt306 ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt307 ltauthentication-typegt308 ltnone gt309 ltauthentication-typegt310 ltsecondary-ntp-servergt311 ltntp-serversgt312 ltsystemgt313 ltsettinggt314 ltconfiggt315 ltrematchgtyesltrematchgt316 ltconfiggt

PAN-OS XML API Labs with pan-python

8

317 ltmanagementgt318 lthostname-type-in-sysloggtFQDNlthostname-type-in-sysloggt319 ltdisable-predefined-reportsgt320 ltmembergtspyware-infected-hostsltmembergt321 ltmembergttop-application-categoriesltmembergt322 ltmembergttop-technology-categoriesltmembergt323 ltmembergtbandwidth-trendltmembergt324 ltmembergtrisk-trendltmembergt325 ltmembergtthreat-trendltmembergt326 ltmembergttop-usersltmembergt327 ltmembergttop-attacker-sourcesltmembergt328 ltmembergttop-attacker-destinationsltmembergt329 ltmembergttop-victim-sourcesltmembergt330 ltmembergttop-victim-destinationsltmembergt331 ltmembergttop-attackers-by-source-countriesltmembergt332 ltmembergttop-attackers-by-destination-countriesltmembergt333 ltmembergttop-victims-by-source-countriesltmembergt334 ltmembergttop-victims-by-destination-countriesltmembergt335 ltmembergttop-sourcesltmembergt336 ltmembergttop-destinationsltmembergt337 ltmembergttop-destination-countriesltmembergt338 ltmembergttop-source-countriesltmembergt339 ltmembergttop-connectionsltmembergt340 ltmembergttop-ingress-interfacesltmembergt341 ltmembergttop-egress-interfacesltmembergt342 ltmembergttop-ingress-zonesltmembergt343 ltmembergttop-egress-zonesltmembergt344 ltmembergttop-applicationsltmembergt345 ltmembergttop-http-applicationsltmembergt346 ltmembergttop-rulesltmembergt347 ltmembergttop-attacksltmembergt348 ltmembergttop-spyware-threatsltmembergt349 ltmembergttop-virusesltmembergt350 ltmembergttop-vulnerabilitiesltmembergt351 ltmembergtwildfire-file-digestsltmembergt352 ltmembergttop-websitesltmembergt353 ltmembergttop-url-categoriesltmembergt354 ltmembergttop-url-usersltmembergt355 ltmembergttop-url-user-behaviorltmembergt356 ltmembergttop-blocked-websitesltmembergt357 ltmembergttop-blocked-url-categoriesltmembergt358 ltmembergttop-blocked-url-usersltmembergt359 ltmembergttop-blocked-url-user-behaviorltmembergt360 ltmembergtblocked-credential-postltmembergt361 ltmembergtunknown-tcp-connectionsltmembergt362 ltmembergtunknown-udp-connectionsltmembergt363 ltmembergttop-denied-sourcesltmembergt364 ltmembergttop-denied-destinationsltmembergt365 ltmembergttop-denied-applicationsltmembergt366 ltmembergtrisky-usersltmembergt367 ltmembergtSaaS Application Usageltmembergt368 ltmembergtgtp-events-summaryltmembergt369 ltmembergtgtp-malicious-wildfire-submissionsltmembergt370 ltmembergtgtp-security-eventsltmembergt371 ltmembergtgtp-v1-causesltmembergt372 ltmembergtgtp-v2-causesltmembergt373 ltmembergtgtp-users-visiting-malicious-urlltmembergt374 ltmembergttop-gtp-attacker-destinationsltmembergt375 ltmembergttop-gtp-attacker-sourcesltmembergt376 ltmembergttop-gtp-victim-destinationsltmembergt

PAN-OS XML API Labs with pan-python

9

377 ltmembergttop-gtp-victim-sourcesltmembergt378 ltmembergtsctp-error-causesltmembergt379 ltmembergtsctp-events-summaryltmembergt380 ltmembergtsctp-security-eventsltmembergt381 ltdisable-predefined-reportsgt382 ltmanagementgt383 ltauto-mac-detectgtyesltauto-mac-detectgt384 ltsettinggt385 ltdeviceconfiggt386 ltvsysgt387 ltentry name=vsys1gt388 ltapplication gt389 ltapplication-group gt390 ltzonegt391 ltentry name=trustgt392 ltnetworkgt393 ltvirtual-wiregt394 ltmembergtethernet12ltmembergt395 ltvirtual-wiregt396 ltnetworkgt397 ltentrygt398 ltentry name=untrustgt399 ltnetworkgt400 ltvirtual-wiregt401 ltmembergtethernet11ltmembergt402 ltvirtual-wiregt403 ltnetworkgt404 ltentrygt405 ltzonegt406 ltservice gt407 ltservice-group gt408 ltschedule gt409 ltrulebasegt410 ltsecuritygt411 ltrulesgt412 ltentry name=rule2 uuid=031613c5-a691-4887-b284-5af2915e7c36gt413 lttogt414 ltmembergtuntrustltmembergt415 lttogt416 ltfromgt417 ltmembergttrustltmembergt418 ltfromgt419 ltsourcegt420 ltmembergtanyltmembergt421 ltsourcegt422 ltsource-usergt423 ltmembergtanyltmembergt424 ltsource-usergt425 ltcategorygt426 ltmembergtanyltmembergt427 ltcategorygt428 ltapplicationgt429 ltmembergtanyltmembergt430 ltapplicationgt431 ltservicegt432 ltmembergtapplication-defaultltmembergt433 ltservicegt434 lthip-profilesgt435 ltmembergtanyltmembergt436 lthip-profilesgt

PAN-OS XML API Labs with pan-python

10

437 ltactiongtdenyltactiongt438 ltdestinationgt439 ltmembergtgroup2ltmembergt440 ltdestinationgt441 ltentrygt442 ltentry name=rule1 uuid=c678a3fb-0e9b-45b7-aa4f-66a3e8864339gt443 lttogt444 ltmembergtuntrustltmembergt445 lttogt446 ltfromgt447 ltmembergttrustltmembergt448 ltfromgt449 ltsourcegt450 ltmembergtanyltmembergt451 ltsourcegt452 ltdestinationgt453 ltmembergtanyltmembergt454 ltdestinationgt455 ltsource-usergt456 ltmembergtanyltmembergt457 ltsource-usergt458 ltcategorygt459 ltmembergtanyltmembergt460 ltcategorygt461 ltapplicationgt462 ltmembergtanyltmembergt463 ltapplicationgt464 ltservicegt465 ltmembergtanyltmembergt466 ltservicegt467 lthip-profilesgt468 ltmembergtanyltmembergt469 lthip-profilesgt470 ltactiongtallowltactiongt471 ltentrygt472 ltrulesgt473 ltsecuritygt474 ltrulebasegt475 ltimportgt476 ltnetworkgt477 ltinterfacegt478 ltmembergtethernet11ltmembergt479 ltmembergtethernet12ltmembergt480 ltinterfacegt481 ltnetworkgt482 ltimportgt483 ltaddressgt484 ltentry name=addr1gt485 ltip-netmaskgt10001ltip-netmaskgt486 ltentrygt487 ltentry name=addr2gt488 ltip-netmaskgt10002ltip-netmaskgt489 ltentrygt490 ltentry name=addr3gt491 ltip-netmaskgt10003ltip-netmaskgt492 ltentrygt493 ltentry name=addr4gt494 ltip-netmaskgt10004ltip-netmaskgt495 ltentrygt496 ltentry name=addr5gt

PAN-OS XML API Labs with pan-python

11

497 ltip-netmaskgt10005ltip-netmaskgt498 ltentrygt499 ltaddressgt500 ltaddress-groupgt501 ltentry name=group1gt502 ltstaticgt503 ltmembergtaddr1ltmembergt504 ltmembergtaddr2ltmembergt505 ltmembergtaddr3ltmembergt506 ltstaticgt507 ltentrygt508 ltentry name=group2gt509 ltdynamicgt510 ltfiltergttag01 or tag02ltfiltergt511 ltdynamicgt512 ltentrygt513 ltaddress-groupgt514 ltuser-id-collectorgt515 ltsettinggt516 ltenable-mapping-timeoutgtyesltenable-mapping-timeoutgt517 ltip-user-mapping-timeoutgt45ltip-user-mapping-timeoutgt518 ltsettinggt519 ltuser-id-collectorgt520 ltdynamic-user-groupgt521 ltentry name=dug1gt522 ltfiltergttag01 or tag02ltfiltergt523 ltentrygt524 ltdynamic-user-groupgt525 ltentrygt526 ltvsysgt527 ltentrygt528 ltdevicesgt529 ltconfiggt

Introduction to the PAN-OS API

About the API

APIrsquos are very important to Palo Alto Networks Security automation is key to the success of any organization inpreventing cyber attacks So Palo Alto Networks products have comprehensive APIs to enable automation

In this lab wersquoll focus on the PAN-OS API which is the API for the Palo Alto Networks Next-generation Firewall andPanorama Management Center

When connecting to the PAN-OS API

bull Access the API on the management interface using HTTPS just as you would connect to the GUI

bull Connections to the API are treated as general web admin access They create a session just like you wereaccessing the GUI

bull Authentication requires an API key which is generated through an API call

Introduction to the PAN-OS API

12

Some examples of how you might use the PAN-OS API include but are not limited to

bull Read write verify and commit configuration

bull Download reports in XML format

bull Execute operational commands to check health and status

bull Collect logs and pcaps

bull Update dynamic address groups

bull Update user-id mappings

bull And much more

The API BrowserThe Next-generation Firewall and Panorama have an API Browser built in which allows you to explore the API andtrigger simple API calls in the browser itself

You can access the API Browser by adding api to the URL after the IP address of the firewall For example if yourfirewall is at 10001 the URL of the API Browser is https10001api

Lab exercise Try connecting to the API Browser on the firewall in your lab Explore a little to get familiar thencontinue with the lab

API Command TypesThere are several API types as shown in the main page of the API browser

API Types

API Type Description

keygen Generate an API Key (not shown in API Browser)

config Retrieve or modify the configuration

commit Commit the configuration

export Export files packet captures and keys

import Import files certificates response pages and branding

op Operational commands (like lsquoshowrsquo commands)

report Retrieve predefined dynamic and custom reports

user-id UserIP mappings and Dynamic Address Groups

This lab focuses on the following 5 types but the concepts needed to understand these 5 types are the sameconcepts for all the other types

bull keygen

bull config

bull commit

bull op

bull user-id

Introduction to the PAN-OS API

13

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 5: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

46 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 esp authentication none 47 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 dh-group group20 48 set network ike crypto-profiles ipsec-crypto-profiles Suite-B-GCM-256 lifetime hours 1 49 set network ike crypto-profiles global-protect-app-crypto-profiles default encryption aes-128-cbc 50 set network ike crypto-profiles global-protect-app-crypto-profiles default authentication sha1 51 set network qos profile default class-bandwidth-type mbps class class1 priority real-time 52 set network qos profile default class-bandwidth-type mbps class class2 priority high 53 set network qos profile default class-bandwidth-type mbps class class3 priority high 54 set network qos profile default class-bandwidth-type mbps class class4 priority medium 55 set network qos profile default class-bandwidth-type mbps class class5 priority medium 56 set network qos profile default class-bandwidth-type mbps class class6 priority low 57 set network qos profile default class-bandwidth-type mbps class class7 priority low 58 set network qos profile default class-bandwidth-type mbps class class8 priority low 59 set network virtual-router default protocol bgp enable no 60 set network virtual-router default protocol bgp dampening-profile default cutoff 125 61 set network virtual-router default protocol bgp dampening-profile default reuse 05 62 set network virtual-router default protocol bgp dampening-profile default max-hold-time 900 63 set network virtual-router default protocol bgp dampening-profile default decay-half-life-reachable 300 64 set network virtual-router default protocol bgp dampening-profile default decay-half-life-unreachable 900 65 set network virtual-router default protocol bgp dampening-profile default enable yes 66 set network virtual-wire default-vwire interface1 ethernet11 67 set network virtual-wire default-vwire interface2 ethernet12 68 set shared application 69 set shared application-group 70 set shared service 71 set shared service-group 72 set shared botnet configuration http dynamic-dns enabled yes 73 set shared botnet configuration http dynamic-dns threshold 5 74 set shared botnet configuration http malware-sites enabled yes 75 set shared botnet configuration http malware-sites threshold 5 76 set shared botnet configuration http recent-domains enabled yes 77 set shared botnet configuration http recent-domains threshold 5 78 set shared botnet configuration http ip-domains enabled yes 79 set shared botnet configuration http ip-domains threshold 10 80 set shared botnet configuration http executables-from-unknown-sites enabled yes 81 set shared botnet configuration http executables-from-unknown-sites threshold 5 82 set shared botnet configuration other-applications irc yes 83 set shared botnet configuration unknown-applications unknown-tcp destinations-per-hour 10 84 set shared botnet configuration unknown-applications unknown-tcp sessions-per-hour 10 85 set shared botnet configuration unknown-applications unknown-tcp session-length maximum-bytes 100 86 set shared botnet configuration unknown-applications unknown-tcp session-length minimum-bytes 50 87 set shared botnet configuration unknown-applications unknown-udp destinations-per-hour 10 88 set shared botnet configuration unknown-applications unknown-udp sessions-per-hour 10 89 set shared botnet configuration unknown-applications unknown-udp session-length maximum-bytes 100 90 set shared botnet configuration unknown-applications unknown-udp session-length minimum-bytes 50 91 set shared botnet report topn 100 92 set shared botnet report scheduled yes 93 set shared content-preview application 94 set shared content-preview application-type category 95 set shared content-preview application-type technology 96 set shared local-user-database user-group 97 set zone trust network virtual-wire ethernet12 98 set zone untrust network virtual-wire ethernet11 99 set user-id-collector setting enable-mapping-timeout yes100 set user-id-collector setting ip-user-mapping-timeout 45101 set service-group102 set service103 set schedule104 set rulebase security rules rule2 to untrust105 set rulebase security rules rule2 from trust

PAN-OS XML API Labs with pan-python

2

106 set rulebase security rules rule2 source any107 set rulebase security rules rule2 source-user any108 set rulebase security rules rule2 category any109 set rulebase security rules rule2 application any110 set rulebase security rules rule2 service application-default111 set rulebase security rules rule2 hip-profiles any112 set rulebase security rules rule2 action deny113 set rulebase security rules rule2 destination group2114 set rulebase security rules rule1 to untrust115 set rulebase security rules rule1 from trust116 set rulebase security rules rule1 source any117 set rulebase security rules rule1 destination any118 set rulebase security rules rule1 source-user any119 set rulebase security rules rule1 category any120 set rulebase security rules rule1 application any121 set rulebase security rules rule1 service any122 set rulebase security rules rule1 hip-profiles any123 set rulebase security rules rule1 action allow124 set import network interface [ ethernet11 ethernet12 ]125 set dynamic-user-group dug1 filter tag01 or tag02126 set application-group127 set application128 set address-group group1 static [ addr1 addr2 addr3 ]129 set address-group group2 dynamic filter tag01 or tag02130 set address addr1 ip-netmask 10001131 set address addr2 ip-netmask 10002132 set address addr3 ip-netmask 10003133 set address addr4 ip-netmask 10004134 set address addr5 ip-netmask 10005135 set mgt-config users admin phash $1$fniyibcj$0tm9SixJwwOkFkDnEqVw136 set mgt-config users admin permissions role-based superuser yes137 set mgt-config users adminr permissions role-based superreader yes138 set mgt-config users adminr phash $1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1

XML Format ConfigurationThe following PAN-OS configuration is required as a starting point for the labs

NOTE This configuration uses the default credentials admin admin and adminr admin If you apply thisconfiguration to your own firewall be certain to change the passwords from the default Do not apply thisconfiguration to a production firewall Use this configuration at your own risk

If you need a firewall to run this lab on you can easily deploy a firewall in AWS A firewall license is not necessary forany steps in this lab

1 ltconfig urldb=paloaltonetworks version=910gt 2 ltmgt-configgt 3 ltusersgt 4 ltentry name=admingt 5 ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt 6 ltpermissionsgt 7 ltrole-basedgt 8 ltsuperusergtyesltsuperusergt 9 ltrole-basedgt 10 ltpermissionsgt 11 ltentrygt 12 ltentry name=adminrgt 13 ltpermissionsgt 14 ltrole-basedgt 15 ltsuperreadergtyesltsuperreadergt 16 ltrole-basedgt

PAN-OS XML API Labs with pan-python

3

17 ltpermissionsgt 18 ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt 19 ltentrygt 20 ltusersgt 21 ltmgt-configgt 22 ltsharedgt 23 ltapplication gt 24 ltapplication-group gt 25 ltservice gt 26 ltservice-group gt 27 ltbotnetgt 28 ltconfigurationgt 29 lthttpgt 30 ltdynamic-dnsgt 31 ltenabledgtyesltenabledgt 32 ltthresholdgt5ltthresholdgt 33 ltdynamic-dnsgt 34 ltmalware-sitesgt 35 ltenabledgtyesltenabledgt 36 ltthresholdgt5ltthresholdgt 37 ltmalware-sitesgt 38 ltrecent-domainsgt 39 ltenabledgtyesltenabledgt 40 ltthresholdgt5ltthresholdgt 41 ltrecent-domainsgt 42 ltip-domainsgt 43 ltenabledgtyesltenabledgt 44 ltthresholdgt10ltthresholdgt 45 ltip-domainsgt 46 ltexecutables-from-unknown-sitesgt 47 ltenabledgtyesltenabledgt 48 ltthresholdgt5ltthresholdgt 49 ltexecutables-from-unknown-sitesgt 50 lthttpgt 51 ltother-applicationsgt 52 ltircgtyesltircgt 53 ltother-applicationsgt 54 ltunknown-applicationsgt 55 ltunknown-tcpgt 56 ltdestinations-per-hourgt10ltdestinations-per-hourgt 57 ltsessions-per-hourgt10ltsessions-per-hourgt 58 ltsession-lengthgt 59 ltmaximum-bytesgt100ltmaximum-bytesgt 60 ltminimum-bytesgt50ltminimum-bytesgt 61 ltsession-lengthgt 62 ltunknown-tcpgt 63 ltunknown-udpgt 64 ltdestinations-per-hourgt10ltdestinations-per-hourgt 65 ltsessions-per-hourgt10ltsessions-per-hourgt 66 ltsession-lengthgt 67 ltmaximum-bytesgt100ltmaximum-bytesgt 68 ltminimum-bytesgt50ltminimum-bytesgt 69 ltsession-lengthgt 70 ltunknown-udpgt 71 ltunknown-applicationsgt 72 ltconfigurationgt 73 ltreportgt 74 lttopngt100lttopngt 75 ltscheduledgtyesltscheduledgt 76 ltreportgt

PAN-OS XML API Labs with pan-python

4

77 ltbotnetgt 78 ltcontent-previewgt 79 ltapplication gt 80 ltapplication-typegt 81 ltcategory gt 82 lttechnology gt 83 ltapplication-typegt 84 ltcontent-previewgt 85 ltlocal-user-databasegt 86 ltuser-group gt 87 ltlocal-user-databasegt 88 ltsharedgt 89 ltdevicesgt 90 ltentry name=localhostlocaldomaingt 91 ltnetworkgt 92 ltinterfacegt 93 ltethernetgt 94 ltentry name=ethernet11gt 95 ltvirtual-wire gt 96 ltentrygt 97 ltentry name=ethernet12gt 98 ltvirtual-wire gt 99 ltentrygt100 ltethernetgt101 ltinterfacegt102 ltprofilesgt103 ltmonitor-profilegt104 ltentry name=defaultgt105 ltintervalgt3ltintervalgt106 ltthresholdgt5ltthresholdgt107 ltactiongtwait-recoverltactiongt108 ltentrygt109 ltmonitor-profilegt110 ltprofilesgt111 ltikegt112 ltcrypto-profilesgt113 ltike-crypto-profilesgt114 ltentry name=defaultgt115 ltencryptiongt116 ltmembergtaes-128-cbcltmembergt117 ltmembergt3desltmembergt118 ltencryptiongt119 lthashgt120 ltmembergtsha1ltmembergt121 lthashgt122 ltdh-groupgt123 ltmembergtgroup2ltmembergt124 ltdh-groupgt125 ltlifetimegt126 lthoursgt8lthoursgt127 ltlifetimegt128 ltentrygt129 ltentry name=Suite-B-GCM-128gt130 ltencryptiongt131 ltmembergtaes-128-cbcltmembergt132 ltencryptiongt133 lthashgt134 ltmembergtsha256ltmembergt135 lthashgt136 ltdh-groupgt

PAN-OS XML API Labs with pan-python

5

137 ltmembergtgroup19ltmembergt138 ltdh-groupgt139 ltlifetimegt140 lthoursgt8lthoursgt141 ltlifetimegt142 ltentrygt143 ltentry name=Suite-B-GCM-256gt144 ltencryptiongt145 ltmembergtaes-256-cbcltmembergt146 ltencryptiongt147 lthashgt148 ltmembergtsha384ltmembergt149 lthashgt150 ltdh-groupgt151 ltmembergtgroup20ltmembergt152 ltdh-groupgt153 ltlifetimegt154 lthoursgt8lthoursgt155 ltlifetimegt156 ltentrygt157 ltike-crypto-profilesgt158 ltipsec-crypto-profilesgt159 ltentry name=defaultgt160 ltespgt161 ltencryptiongt162 ltmembergtaes-128-cbcltmembergt163 ltmembergt3desltmembergt164 ltencryptiongt165 ltauthenticationgt166 ltmembergtsha1ltmembergt167 ltauthenticationgt168 ltespgt169 ltdh-groupgtgroup2ltdh-groupgt170 ltlifetimegt171 lthoursgt1lthoursgt172 ltlifetimegt173 ltentrygt174 ltentry name=Suite-B-GCM-128gt175 ltespgt176 ltencryptiongt177 ltmembergtaes-128-gcmltmembergt178 ltencryptiongt179 ltauthenticationgt180 ltmembergtnoneltmembergt181 ltauthenticationgt182 ltespgt183 ltdh-groupgtgroup19ltdh-groupgt184 ltlifetimegt185 lthoursgt1lthoursgt186 ltlifetimegt187 ltentrygt188 ltentry name=Suite-B-GCM-256gt189 ltespgt190 ltencryptiongt191 ltmembergtaes-256-gcmltmembergt192 ltencryptiongt193 ltauthenticationgt194 ltmembergtnoneltmembergt195 ltauthenticationgt196 ltespgt

PAN-OS XML API Labs with pan-python

6

197 ltdh-groupgtgroup20ltdh-groupgt198 ltlifetimegt199 lthoursgt1lthoursgt200 ltlifetimegt201 ltentrygt202 ltipsec-crypto-profilesgt203 ltglobal-protect-app-crypto-profilesgt204 ltentry name=defaultgt205 ltencryptiongt206 ltmembergtaes-128-cbcltmembergt207 ltencryptiongt208 ltauthenticationgt209 ltmembergtsha1ltmembergt210 ltauthenticationgt211 ltentrygt212 ltglobal-protect-app-crypto-profilesgt213 ltcrypto-profilesgt214 ltikegt215 ltqosgt216 ltprofilegt217 ltentry name=defaultgt218 ltclass-bandwidth-typegt219 ltmbpsgt220 ltclassgt221 ltentry name=class1gt222 ltprioritygtreal-timeltprioritygt223 ltentrygt224 ltentry name=class2gt225 ltprioritygthighltprioritygt226 ltentrygt227 ltentry name=class3gt228 ltprioritygthighltprioritygt229 ltentrygt230 ltentry name=class4gt231 ltprioritygtmediumltprioritygt232 ltentrygt233 ltentry name=class5gt234 ltprioritygtmediumltprioritygt235 ltentrygt236 ltentry name=class6gt237 ltprioritygtlowltprioritygt238 ltentrygt239 ltentry name=class7gt240 ltprioritygtlowltprioritygt241 ltentrygt242 ltentry name=class8gt243 ltprioritygtlowltprioritygt244 ltentrygt245 ltclassgt246 ltmbpsgt247 ltclass-bandwidth-typegt248 ltentrygt249 ltprofilegt250 ltqosgt251 ltvirtual-routergt252 ltentry name=defaultgt253 ltprotocolgt254 ltbgpgt255 ltenablegtnoltenablegt256 ltdampening-profilegt

PAN-OS XML API Labs with pan-python

7

257 ltentry name=defaultgt258 ltcutoffgt125ltcutoffgt259 ltreusegt05ltreusegt260 ltmax-hold-timegt900ltmax-hold-timegt261 ltdecay-half-life-reachablegt300ltdecay-half-life-reachablegt262 ltdecay-half-life-unreachablegt900ltdecay-half-life-unreachablegt263 ltenablegtyesltenablegt264 ltentrygt265 ltdampening-profilegt266 ltbgpgt267 ltprotocolgt268 ltentrygt269 ltvirtual-routergt270 ltvirtual-wiregt271 ltentry name=default-vwiregt272 ltinterface1gtethernet11ltinterface1gt273 ltinterface2gtethernet12ltinterface2gt274 ltentrygt275 ltvirtual-wiregt276 ltnetworkgt277 ltdeviceconfiggt278 ltsystemgt279 lttypegt280 ltstatic gt281 lttypegt282 ltupdate-servergtupdatespaloaltonetworkscomltupdate-servergt283 ltupdate-schedule gt284 lttimezonegtUSPacificlttimezonegt285 ltservicegt286 ltdisable-telnetgtyesltdisable-telnetgt287 ltdisable-httpgtyesltdisable-httpgt288 ltservicegt289 lthostnamegtPA-VMlthostnamegt290 ltip-addressgt1921681103ltip-addressgt291 ltnetmaskgt2552552550ltnetmaskgt292 ltdefault-gatewaygt1921681254ltdefault-gatewaygt293 ltdns-settinggt294 ltserversgt295 ltprimarygt8888ltprimarygt296 ltserversgt297 ltdns-settinggt298 ltntp-serversgt299 ltprimary-ntp-servergt300 ltntp-server-addressgtuspoolntporgltntp-server-addressgt301 ltauthentication-typegt302 ltnone gt303 ltauthentication-typegt304 ltprimary-ntp-servergt305 ltsecondary-ntp-servergt306 ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt307 ltauthentication-typegt308 ltnone gt309 ltauthentication-typegt310 ltsecondary-ntp-servergt311 ltntp-serversgt312 ltsystemgt313 ltsettinggt314 ltconfiggt315 ltrematchgtyesltrematchgt316 ltconfiggt

PAN-OS XML API Labs with pan-python

8

317 ltmanagementgt318 lthostname-type-in-sysloggtFQDNlthostname-type-in-sysloggt319 ltdisable-predefined-reportsgt320 ltmembergtspyware-infected-hostsltmembergt321 ltmembergttop-application-categoriesltmembergt322 ltmembergttop-technology-categoriesltmembergt323 ltmembergtbandwidth-trendltmembergt324 ltmembergtrisk-trendltmembergt325 ltmembergtthreat-trendltmembergt326 ltmembergttop-usersltmembergt327 ltmembergttop-attacker-sourcesltmembergt328 ltmembergttop-attacker-destinationsltmembergt329 ltmembergttop-victim-sourcesltmembergt330 ltmembergttop-victim-destinationsltmembergt331 ltmembergttop-attackers-by-source-countriesltmembergt332 ltmembergttop-attackers-by-destination-countriesltmembergt333 ltmembergttop-victims-by-source-countriesltmembergt334 ltmembergttop-victims-by-destination-countriesltmembergt335 ltmembergttop-sourcesltmembergt336 ltmembergttop-destinationsltmembergt337 ltmembergttop-destination-countriesltmembergt338 ltmembergttop-source-countriesltmembergt339 ltmembergttop-connectionsltmembergt340 ltmembergttop-ingress-interfacesltmembergt341 ltmembergttop-egress-interfacesltmembergt342 ltmembergttop-ingress-zonesltmembergt343 ltmembergttop-egress-zonesltmembergt344 ltmembergttop-applicationsltmembergt345 ltmembergttop-http-applicationsltmembergt346 ltmembergttop-rulesltmembergt347 ltmembergttop-attacksltmembergt348 ltmembergttop-spyware-threatsltmembergt349 ltmembergttop-virusesltmembergt350 ltmembergttop-vulnerabilitiesltmembergt351 ltmembergtwildfire-file-digestsltmembergt352 ltmembergttop-websitesltmembergt353 ltmembergttop-url-categoriesltmembergt354 ltmembergttop-url-usersltmembergt355 ltmembergttop-url-user-behaviorltmembergt356 ltmembergttop-blocked-websitesltmembergt357 ltmembergttop-blocked-url-categoriesltmembergt358 ltmembergttop-blocked-url-usersltmembergt359 ltmembergttop-blocked-url-user-behaviorltmembergt360 ltmembergtblocked-credential-postltmembergt361 ltmembergtunknown-tcp-connectionsltmembergt362 ltmembergtunknown-udp-connectionsltmembergt363 ltmembergttop-denied-sourcesltmembergt364 ltmembergttop-denied-destinationsltmembergt365 ltmembergttop-denied-applicationsltmembergt366 ltmembergtrisky-usersltmembergt367 ltmembergtSaaS Application Usageltmembergt368 ltmembergtgtp-events-summaryltmembergt369 ltmembergtgtp-malicious-wildfire-submissionsltmembergt370 ltmembergtgtp-security-eventsltmembergt371 ltmembergtgtp-v1-causesltmembergt372 ltmembergtgtp-v2-causesltmembergt373 ltmembergtgtp-users-visiting-malicious-urlltmembergt374 ltmembergttop-gtp-attacker-destinationsltmembergt375 ltmembergttop-gtp-attacker-sourcesltmembergt376 ltmembergttop-gtp-victim-destinationsltmembergt

PAN-OS XML API Labs with pan-python

9

377 ltmembergttop-gtp-victim-sourcesltmembergt378 ltmembergtsctp-error-causesltmembergt379 ltmembergtsctp-events-summaryltmembergt380 ltmembergtsctp-security-eventsltmembergt381 ltdisable-predefined-reportsgt382 ltmanagementgt383 ltauto-mac-detectgtyesltauto-mac-detectgt384 ltsettinggt385 ltdeviceconfiggt386 ltvsysgt387 ltentry name=vsys1gt388 ltapplication gt389 ltapplication-group gt390 ltzonegt391 ltentry name=trustgt392 ltnetworkgt393 ltvirtual-wiregt394 ltmembergtethernet12ltmembergt395 ltvirtual-wiregt396 ltnetworkgt397 ltentrygt398 ltentry name=untrustgt399 ltnetworkgt400 ltvirtual-wiregt401 ltmembergtethernet11ltmembergt402 ltvirtual-wiregt403 ltnetworkgt404 ltentrygt405 ltzonegt406 ltservice gt407 ltservice-group gt408 ltschedule gt409 ltrulebasegt410 ltsecuritygt411 ltrulesgt412 ltentry name=rule2 uuid=031613c5-a691-4887-b284-5af2915e7c36gt413 lttogt414 ltmembergtuntrustltmembergt415 lttogt416 ltfromgt417 ltmembergttrustltmembergt418 ltfromgt419 ltsourcegt420 ltmembergtanyltmembergt421 ltsourcegt422 ltsource-usergt423 ltmembergtanyltmembergt424 ltsource-usergt425 ltcategorygt426 ltmembergtanyltmembergt427 ltcategorygt428 ltapplicationgt429 ltmembergtanyltmembergt430 ltapplicationgt431 ltservicegt432 ltmembergtapplication-defaultltmembergt433 ltservicegt434 lthip-profilesgt435 ltmembergtanyltmembergt436 lthip-profilesgt

PAN-OS XML API Labs with pan-python

10

437 ltactiongtdenyltactiongt438 ltdestinationgt439 ltmembergtgroup2ltmembergt440 ltdestinationgt441 ltentrygt442 ltentry name=rule1 uuid=c678a3fb-0e9b-45b7-aa4f-66a3e8864339gt443 lttogt444 ltmembergtuntrustltmembergt445 lttogt446 ltfromgt447 ltmembergttrustltmembergt448 ltfromgt449 ltsourcegt450 ltmembergtanyltmembergt451 ltsourcegt452 ltdestinationgt453 ltmembergtanyltmembergt454 ltdestinationgt455 ltsource-usergt456 ltmembergtanyltmembergt457 ltsource-usergt458 ltcategorygt459 ltmembergtanyltmembergt460 ltcategorygt461 ltapplicationgt462 ltmembergtanyltmembergt463 ltapplicationgt464 ltservicegt465 ltmembergtanyltmembergt466 ltservicegt467 lthip-profilesgt468 ltmembergtanyltmembergt469 lthip-profilesgt470 ltactiongtallowltactiongt471 ltentrygt472 ltrulesgt473 ltsecuritygt474 ltrulebasegt475 ltimportgt476 ltnetworkgt477 ltinterfacegt478 ltmembergtethernet11ltmembergt479 ltmembergtethernet12ltmembergt480 ltinterfacegt481 ltnetworkgt482 ltimportgt483 ltaddressgt484 ltentry name=addr1gt485 ltip-netmaskgt10001ltip-netmaskgt486 ltentrygt487 ltentry name=addr2gt488 ltip-netmaskgt10002ltip-netmaskgt489 ltentrygt490 ltentry name=addr3gt491 ltip-netmaskgt10003ltip-netmaskgt492 ltentrygt493 ltentry name=addr4gt494 ltip-netmaskgt10004ltip-netmaskgt495 ltentrygt496 ltentry name=addr5gt

PAN-OS XML API Labs with pan-python

11

497 ltip-netmaskgt10005ltip-netmaskgt498 ltentrygt499 ltaddressgt500 ltaddress-groupgt501 ltentry name=group1gt502 ltstaticgt503 ltmembergtaddr1ltmembergt504 ltmembergtaddr2ltmembergt505 ltmembergtaddr3ltmembergt506 ltstaticgt507 ltentrygt508 ltentry name=group2gt509 ltdynamicgt510 ltfiltergttag01 or tag02ltfiltergt511 ltdynamicgt512 ltentrygt513 ltaddress-groupgt514 ltuser-id-collectorgt515 ltsettinggt516 ltenable-mapping-timeoutgtyesltenable-mapping-timeoutgt517 ltip-user-mapping-timeoutgt45ltip-user-mapping-timeoutgt518 ltsettinggt519 ltuser-id-collectorgt520 ltdynamic-user-groupgt521 ltentry name=dug1gt522 ltfiltergttag01 or tag02ltfiltergt523 ltentrygt524 ltdynamic-user-groupgt525 ltentrygt526 ltvsysgt527 ltentrygt528 ltdevicesgt529 ltconfiggt

Introduction to the PAN-OS API

About the API

APIrsquos are very important to Palo Alto Networks Security automation is key to the success of any organization inpreventing cyber attacks So Palo Alto Networks products have comprehensive APIs to enable automation

In this lab wersquoll focus on the PAN-OS API which is the API for the Palo Alto Networks Next-generation Firewall andPanorama Management Center

When connecting to the PAN-OS API

bull Access the API on the management interface using HTTPS just as you would connect to the GUI

bull Connections to the API are treated as general web admin access They create a session just like you wereaccessing the GUI

bull Authentication requires an API key which is generated through an API call

Introduction to the PAN-OS API

12

Some examples of how you might use the PAN-OS API include but are not limited to

bull Read write verify and commit configuration

bull Download reports in XML format

bull Execute operational commands to check health and status

bull Collect logs and pcaps

bull Update dynamic address groups

bull Update user-id mappings

bull And much more

The API BrowserThe Next-generation Firewall and Panorama have an API Browser built in which allows you to explore the API andtrigger simple API calls in the browser itself

You can access the API Browser by adding api to the URL after the IP address of the firewall For example if yourfirewall is at 10001 the URL of the API Browser is https10001api

Lab exercise Try connecting to the API Browser on the firewall in your lab Explore a little to get familiar thencontinue with the lab

API Command TypesThere are several API types as shown in the main page of the API browser

API Types

API Type Description

keygen Generate an API Key (not shown in API Browser)

config Retrieve or modify the configuration

commit Commit the configuration

export Export files packet captures and keys

import Import files certificates response pages and branding

op Operational commands (like lsquoshowrsquo commands)

report Retrieve predefined dynamic and custom reports

user-id UserIP mappings and Dynamic Address Groups

This lab focuses on the following 5 types but the concepts needed to understand these 5 types are the sameconcepts for all the other types

bull keygen

bull config

bull commit

bull op

bull user-id

Introduction to the PAN-OS API

13

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 6: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

106 set rulebase security rules rule2 source any107 set rulebase security rules rule2 source-user any108 set rulebase security rules rule2 category any109 set rulebase security rules rule2 application any110 set rulebase security rules rule2 service application-default111 set rulebase security rules rule2 hip-profiles any112 set rulebase security rules rule2 action deny113 set rulebase security rules rule2 destination group2114 set rulebase security rules rule1 to untrust115 set rulebase security rules rule1 from trust116 set rulebase security rules rule1 source any117 set rulebase security rules rule1 destination any118 set rulebase security rules rule1 source-user any119 set rulebase security rules rule1 category any120 set rulebase security rules rule1 application any121 set rulebase security rules rule1 service any122 set rulebase security rules rule1 hip-profiles any123 set rulebase security rules rule1 action allow124 set import network interface [ ethernet11 ethernet12 ]125 set dynamic-user-group dug1 filter tag01 or tag02126 set application-group127 set application128 set address-group group1 static [ addr1 addr2 addr3 ]129 set address-group group2 dynamic filter tag01 or tag02130 set address addr1 ip-netmask 10001131 set address addr2 ip-netmask 10002132 set address addr3 ip-netmask 10003133 set address addr4 ip-netmask 10004134 set address addr5 ip-netmask 10005135 set mgt-config users admin phash $1$fniyibcj$0tm9SixJwwOkFkDnEqVw136 set mgt-config users admin permissions role-based superuser yes137 set mgt-config users adminr permissions role-based superreader yes138 set mgt-config users adminr phash $1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1

XML Format ConfigurationThe following PAN-OS configuration is required as a starting point for the labs

NOTE This configuration uses the default credentials admin admin and adminr admin If you apply thisconfiguration to your own firewall be certain to change the passwords from the default Do not apply thisconfiguration to a production firewall Use this configuration at your own risk

If you need a firewall to run this lab on you can easily deploy a firewall in AWS A firewall license is not necessary forany steps in this lab

1 ltconfig urldb=paloaltonetworks version=910gt 2 ltmgt-configgt 3 ltusersgt 4 ltentry name=admingt 5 ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt 6 ltpermissionsgt 7 ltrole-basedgt 8 ltsuperusergtyesltsuperusergt 9 ltrole-basedgt 10 ltpermissionsgt 11 ltentrygt 12 ltentry name=adminrgt 13 ltpermissionsgt 14 ltrole-basedgt 15 ltsuperreadergtyesltsuperreadergt 16 ltrole-basedgt

PAN-OS XML API Labs with pan-python

3

17 ltpermissionsgt 18 ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt 19 ltentrygt 20 ltusersgt 21 ltmgt-configgt 22 ltsharedgt 23 ltapplication gt 24 ltapplication-group gt 25 ltservice gt 26 ltservice-group gt 27 ltbotnetgt 28 ltconfigurationgt 29 lthttpgt 30 ltdynamic-dnsgt 31 ltenabledgtyesltenabledgt 32 ltthresholdgt5ltthresholdgt 33 ltdynamic-dnsgt 34 ltmalware-sitesgt 35 ltenabledgtyesltenabledgt 36 ltthresholdgt5ltthresholdgt 37 ltmalware-sitesgt 38 ltrecent-domainsgt 39 ltenabledgtyesltenabledgt 40 ltthresholdgt5ltthresholdgt 41 ltrecent-domainsgt 42 ltip-domainsgt 43 ltenabledgtyesltenabledgt 44 ltthresholdgt10ltthresholdgt 45 ltip-domainsgt 46 ltexecutables-from-unknown-sitesgt 47 ltenabledgtyesltenabledgt 48 ltthresholdgt5ltthresholdgt 49 ltexecutables-from-unknown-sitesgt 50 lthttpgt 51 ltother-applicationsgt 52 ltircgtyesltircgt 53 ltother-applicationsgt 54 ltunknown-applicationsgt 55 ltunknown-tcpgt 56 ltdestinations-per-hourgt10ltdestinations-per-hourgt 57 ltsessions-per-hourgt10ltsessions-per-hourgt 58 ltsession-lengthgt 59 ltmaximum-bytesgt100ltmaximum-bytesgt 60 ltminimum-bytesgt50ltminimum-bytesgt 61 ltsession-lengthgt 62 ltunknown-tcpgt 63 ltunknown-udpgt 64 ltdestinations-per-hourgt10ltdestinations-per-hourgt 65 ltsessions-per-hourgt10ltsessions-per-hourgt 66 ltsession-lengthgt 67 ltmaximum-bytesgt100ltmaximum-bytesgt 68 ltminimum-bytesgt50ltminimum-bytesgt 69 ltsession-lengthgt 70 ltunknown-udpgt 71 ltunknown-applicationsgt 72 ltconfigurationgt 73 ltreportgt 74 lttopngt100lttopngt 75 ltscheduledgtyesltscheduledgt 76 ltreportgt

PAN-OS XML API Labs with pan-python

4

77 ltbotnetgt 78 ltcontent-previewgt 79 ltapplication gt 80 ltapplication-typegt 81 ltcategory gt 82 lttechnology gt 83 ltapplication-typegt 84 ltcontent-previewgt 85 ltlocal-user-databasegt 86 ltuser-group gt 87 ltlocal-user-databasegt 88 ltsharedgt 89 ltdevicesgt 90 ltentry name=localhostlocaldomaingt 91 ltnetworkgt 92 ltinterfacegt 93 ltethernetgt 94 ltentry name=ethernet11gt 95 ltvirtual-wire gt 96 ltentrygt 97 ltentry name=ethernet12gt 98 ltvirtual-wire gt 99 ltentrygt100 ltethernetgt101 ltinterfacegt102 ltprofilesgt103 ltmonitor-profilegt104 ltentry name=defaultgt105 ltintervalgt3ltintervalgt106 ltthresholdgt5ltthresholdgt107 ltactiongtwait-recoverltactiongt108 ltentrygt109 ltmonitor-profilegt110 ltprofilesgt111 ltikegt112 ltcrypto-profilesgt113 ltike-crypto-profilesgt114 ltentry name=defaultgt115 ltencryptiongt116 ltmembergtaes-128-cbcltmembergt117 ltmembergt3desltmembergt118 ltencryptiongt119 lthashgt120 ltmembergtsha1ltmembergt121 lthashgt122 ltdh-groupgt123 ltmembergtgroup2ltmembergt124 ltdh-groupgt125 ltlifetimegt126 lthoursgt8lthoursgt127 ltlifetimegt128 ltentrygt129 ltentry name=Suite-B-GCM-128gt130 ltencryptiongt131 ltmembergtaes-128-cbcltmembergt132 ltencryptiongt133 lthashgt134 ltmembergtsha256ltmembergt135 lthashgt136 ltdh-groupgt

PAN-OS XML API Labs with pan-python

5

137 ltmembergtgroup19ltmembergt138 ltdh-groupgt139 ltlifetimegt140 lthoursgt8lthoursgt141 ltlifetimegt142 ltentrygt143 ltentry name=Suite-B-GCM-256gt144 ltencryptiongt145 ltmembergtaes-256-cbcltmembergt146 ltencryptiongt147 lthashgt148 ltmembergtsha384ltmembergt149 lthashgt150 ltdh-groupgt151 ltmembergtgroup20ltmembergt152 ltdh-groupgt153 ltlifetimegt154 lthoursgt8lthoursgt155 ltlifetimegt156 ltentrygt157 ltike-crypto-profilesgt158 ltipsec-crypto-profilesgt159 ltentry name=defaultgt160 ltespgt161 ltencryptiongt162 ltmembergtaes-128-cbcltmembergt163 ltmembergt3desltmembergt164 ltencryptiongt165 ltauthenticationgt166 ltmembergtsha1ltmembergt167 ltauthenticationgt168 ltespgt169 ltdh-groupgtgroup2ltdh-groupgt170 ltlifetimegt171 lthoursgt1lthoursgt172 ltlifetimegt173 ltentrygt174 ltentry name=Suite-B-GCM-128gt175 ltespgt176 ltencryptiongt177 ltmembergtaes-128-gcmltmembergt178 ltencryptiongt179 ltauthenticationgt180 ltmembergtnoneltmembergt181 ltauthenticationgt182 ltespgt183 ltdh-groupgtgroup19ltdh-groupgt184 ltlifetimegt185 lthoursgt1lthoursgt186 ltlifetimegt187 ltentrygt188 ltentry name=Suite-B-GCM-256gt189 ltespgt190 ltencryptiongt191 ltmembergtaes-256-gcmltmembergt192 ltencryptiongt193 ltauthenticationgt194 ltmembergtnoneltmembergt195 ltauthenticationgt196 ltespgt

PAN-OS XML API Labs with pan-python

6

197 ltdh-groupgtgroup20ltdh-groupgt198 ltlifetimegt199 lthoursgt1lthoursgt200 ltlifetimegt201 ltentrygt202 ltipsec-crypto-profilesgt203 ltglobal-protect-app-crypto-profilesgt204 ltentry name=defaultgt205 ltencryptiongt206 ltmembergtaes-128-cbcltmembergt207 ltencryptiongt208 ltauthenticationgt209 ltmembergtsha1ltmembergt210 ltauthenticationgt211 ltentrygt212 ltglobal-protect-app-crypto-profilesgt213 ltcrypto-profilesgt214 ltikegt215 ltqosgt216 ltprofilegt217 ltentry name=defaultgt218 ltclass-bandwidth-typegt219 ltmbpsgt220 ltclassgt221 ltentry name=class1gt222 ltprioritygtreal-timeltprioritygt223 ltentrygt224 ltentry name=class2gt225 ltprioritygthighltprioritygt226 ltentrygt227 ltentry name=class3gt228 ltprioritygthighltprioritygt229 ltentrygt230 ltentry name=class4gt231 ltprioritygtmediumltprioritygt232 ltentrygt233 ltentry name=class5gt234 ltprioritygtmediumltprioritygt235 ltentrygt236 ltentry name=class6gt237 ltprioritygtlowltprioritygt238 ltentrygt239 ltentry name=class7gt240 ltprioritygtlowltprioritygt241 ltentrygt242 ltentry name=class8gt243 ltprioritygtlowltprioritygt244 ltentrygt245 ltclassgt246 ltmbpsgt247 ltclass-bandwidth-typegt248 ltentrygt249 ltprofilegt250 ltqosgt251 ltvirtual-routergt252 ltentry name=defaultgt253 ltprotocolgt254 ltbgpgt255 ltenablegtnoltenablegt256 ltdampening-profilegt

PAN-OS XML API Labs with pan-python

7

257 ltentry name=defaultgt258 ltcutoffgt125ltcutoffgt259 ltreusegt05ltreusegt260 ltmax-hold-timegt900ltmax-hold-timegt261 ltdecay-half-life-reachablegt300ltdecay-half-life-reachablegt262 ltdecay-half-life-unreachablegt900ltdecay-half-life-unreachablegt263 ltenablegtyesltenablegt264 ltentrygt265 ltdampening-profilegt266 ltbgpgt267 ltprotocolgt268 ltentrygt269 ltvirtual-routergt270 ltvirtual-wiregt271 ltentry name=default-vwiregt272 ltinterface1gtethernet11ltinterface1gt273 ltinterface2gtethernet12ltinterface2gt274 ltentrygt275 ltvirtual-wiregt276 ltnetworkgt277 ltdeviceconfiggt278 ltsystemgt279 lttypegt280 ltstatic gt281 lttypegt282 ltupdate-servergtupdatespaloaltonetworkscomltupdate-servergt283 ltupdate-schedule gt284 lttimezonegtUSPacificlttimezonegt285 ltservicegt286 ltdisable-telnetgtyesltdisable-telnetgt287 ltdisable-httpgtyesltdisable-httpgt288 ltservicegt289 lthostnamegtPA-VMlthostnamegt290 ltip-addressgt1921681103ltip-addressgt291 ltnetmaskgt2552552550ltnetmaskgt292 ltdefault-gatewaygt1921681254ltdefault-gatewaygt293 ltdns-settinggt294 ltserversgt295 ltprimarygt8888ltprimarygt296 ltserversgt297 ltdns-settinggt298 ltntp-serversgt299 ltprimary-ntp-servergt300 ltntp-server-addressgtuspoolntporgltntp-server-addressgt301 ltauthentication-typegt302 ltnone gt303 ltauthentication-typegt304 ltprimary-ntp-servergt305 ltsecondary-ntp-servergt306 ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt307 ltauthentication-typegt308 ltnone gt309 ltauthentication-typegt310 ltsecondary-ntp-servergt311 ltntp-serversgt312 ltsystemgt313 ltsettinggt314 ltconfiggt315 ltrematchgtyesltrematchgt316 ltconfiggt

PAN-OS XML API Labs with pan-python

8

317 ltmanagementgt318 lthostname-type-in-sysloggtFQDNlthostname-type-in-sysloggt319 ltdisable-predefined-reportsgt320 ltmembergtspyware-infected-hostsltmembergt321 ltmembergttop-application-categoriesltmembergt322 ltmembergttop-technology-categoriesltmembergt323 ltmembergtbandwidth-trendltmembergt324 ltmembergtrisk-trendltmembergt325 ltmembergtthreat-trendltmembergt326 ltmembergttop-usersltmembergt327 ltmembergttop-attacker-sourcesltmembergt328 ltmembergttop-attacker-destinationsltmembergt329 ltmembergttop-victim-sourcesltmembergt330 ltmembergttop-victim-destinationsltmembergt331 ltmembergttop-attackers-by-source-countriesltmembergt332 ltmembergttop-attackers-by-destination-countriesltmembergt333 ltmembergttop-victims-by-source-countriesltmembergt334 ltmembergttop-victims-by-destination-countriesltmembergt335 ltmembergttop-sourcesltmembergt336 ltmembergttop-destinationsltmembergt337 ltmembergttop-destination-countriesltmembergt338 ltmembergttop-source-countriesltmembergt339 ltmembergttop-connectionsltmembergt340 ltmembergttop-ingress-interfacesltmembergt341 ltmembergttop-egress-interfacesltmembergt342 ltmembergttop-ingress-zonesltmembergt343 ltmembergttop-egress-zonesltmembergt344 ltmembergttop-applicationsltmembergt345 ltmembergttop-http-applicationsltmembergt346 ltmembergttop-rulesltmembergt347 ltmembergttop-attacksltmembergt348 ltmembergttop-spyware-threatsltmembergt349 ltmembergttop-virusesltmembergt350 ltmembergttop-vulnerabilitiesltmembergt351 ltmembergtwildfire-file-digestsltmembergt352 ltmembergttop-websitesltmembergt353 ltmembergttop-url-categoriesltmembergt354 ltmembergttop-url-usersltmembergt355 ltmembergttop-url-user-behaviorltmembergt356 ltmembergttop-blocked-websitesltmembergt357 ltmembergttop-blocked-url-categoriesltmembergt358 ltmembergttop-blocked-url-usersltmembergt359 ltmembergttop-blocked-url-user-behaviorltmembergt360 ltmembergtblocked-credential-postltmembergt361 ltmembergtunknown-tcp-connectionsltmembergt362 ltmembergtunknown-udp-connectionsltmembergt363 ltmembergttop-denied-sourcesltmembergt364 ltmembergttop-denied-destinationsltmembergt365 ltmembergttop-denied-applicationsltmembergt366 ltmembergtrisky-usersltmembergt367 ltmembergtSaaS Application Usageltmembergt368 ltmembergtgtp-events-summaryltmembergt369 ltmembergtgtp-malicious-wildfire-submissionsltmembergt370 ltmembergtgtp-security-eventsltmembergt371 ltmembergtgtp-v1-causesltmembergt372 ltmembergtgtp-v2-causesltmembergt373 ltmembergtgtp-users-visiting-malicious-urlltmembergt374 ltmembergttop-gtp-attacker-destinationsltmembergt375 ltmembergttop-gtp-attacker-sourcesltmembergt376 ltmembergttop-gtp-victim-destinationsltmembergt

PAN-OS XML API Labs with pan-python

9

377 ltmembergttop-gtp-victim-sourcesltmembergt378 ltmembergtsctp-error-causesltmembergt379 ltmembergtsctp-events-summaryltmembergt380 ltmembergtsctp-security-eventsltmembergt381 ltdisable-predefined-reportsgt382 ltmanagementgt383 ltauto-mac-detectgtyesltauto-mac-detectgt384 ltsettinggt385 ltdeviceconfiggt386 ltvsysgt387 ltentry name=vsys1gt388 ltapplication gt389 ltapplication-group gt390 ltzonegt391 ltentry name=trustgt392 ltnetworkgt393 ltvirtual-wiregt394 ltmembergtethernet12ltmembergt395 ltvirtual-wiregt396 ltnetworkgt397 ltentrygt398 ltentry name=untrustgt399 ltnetworkgt400 ltvirtual-wiregt401 ltmembergtethernet11ltmembergt402 ltvirtual-wiregt403 ltnetworkgt404 ltentrygt405 ltzonegt406 ltservice gt407 ltservice-group gt408 ltschedule gt409 ltrulebasegt410 ltsecuritygt411 ltrulesgt412 ltentry name=rule2 uuid=031613c5-a691-4887-b284-5af2915e7c36gt413 lttogt414 ltmembergtuntrustltmembergt415 lttogt416 ltfromgt417 ltmembergttrustltmembergt418 ltfromgt419 ltsourcegt420 ltmembergtanyltmembergt421 ltsourcegt422 ltsource-usergt423 ltmembergtanyltmembergt424 ltsource-usergt425 ltcategorygt426 ltmembergtanyltmembergt427 ltcategorygt428 ltapplicationgt429 ltmembergtanyltmembergt430 ltapplicationgt431 ltservicegt432 ltmembergtapplication-defaultltmembergt433 ltservicegt434 lthip-profilesgt435 ltmembergtanyltmembergt436 lthip-profilesgt

PAN-OS XML API Labs with pan-python

10

437 ltactiongtdenyltactiongt438 ltdestinationgt439 ltmembergtgroup2ltmembergt440 ltdestinationgt441 ltentrygt442 ltentry name=rule1 uuid=c678a3fb-0e9b-45b7-aa4f-66a3e8864339gt443 lttogt444 ltmembergtuntrustltmembergt445 lttogt446 ltfromgt447 ltmembergttrustltmembergt448 ltfromgt449 ltsourcegt450 ltmembergtanyltmembergt451 ltsourcegt452 ltdestinationgt453 ltmembergtanyltmembergt454 ltdestinationgt455 ltsource-usergt456 ltmembergtanyltmembergt457 ltsource-usergt458 ltcategorygt459 ltmembergtanyltmembergt460 ltcategorygt461 ltapplicationgt462 ltmembergtanyltmembergt463 ltapplicationgt464 ltservicegt465 ltmembergtanyltmembergt466 ltservicegt467 lthip-profilesgt468 ltmembergtanyltmembergt469 lthip-profilesgt470 ltactiongtallowltactiongt471 ltentrygt472 ltrulesgt473 ltsecuritygt474 ltrulebasegt475 ltimportgt476 ltnetworkgt477 ltinterfacegt478 ltmembergtethernet11ltmembergt479 ltmembergtethernet12ltmembergt480 ltinterfacegt481 ltnetworkgt482 ltimportgt483 ltaddressgt484 ltentry name=addr1gt485 ltip-netmaskgt10001ltip-netmaskgt486 ltentrygt487 ltentry name=addr2gt488 ltip-netmaskgt10002ltip-netmaskgt489 ltentrygt490 ltentry name=addr3gt491 ltip-netmaskgt10003ltip-netmaskgt492 ltentrygt493 ltentry name=addr4gt494 ltip-netmaskgt10004ltip-netmaskgt495 ltentrygt496 ltentry name=addr5gt

PAN-OS XML API Labs with pan-python

11

497 ltip-netmaskgt10005ltip-netmaskgt498 ltentrygt499 ltaddressgt500 ltaddress-groupgt501 ltentry name=group1gt502 ltstaticgt503 ltmembergtaddr1ltmembergt504 ltmembergtaddr2ltmembergt505 ltmembergtaddr3ltmembergt506 ltstaticgt507 ltentrygt508 ltentry name=group2gt509 ltdynamicgt510 ltfiltergttag01 or tag02ltfiltergt511 ltdynamicgt512 ltentrygt513 ltaddress-groupgt514 ltuser-id-collectorgt515 ltsettinggt516 ltenable-mapping-timeoutgtyesltenable-mapping-timeoutgt517 ltip-user-mapping-timeoutgt45ltip-user-mapping-timeoutgt518 ltsettinggt519 ltuser-id-collectorgt520 ltdynamic-user-groupgt521 ltentry name=dug1gt522 ltfiltergttag01 or tag02ltfiltergt523 ltentrygt524 ltdynamic-user-groupgt525 ltentrygt526 ltvsysgt527 ltentrygt528 ltdevicesgt529 ltconfiggt

Introduction to the PAN-OS API

About the API

APIrsquos are very important to Palo Alto Networks Security automation is key to the success of any organization inpreventing cyber attacks So Palo Alto Networks products have comprehensive APIs to enable automation

In this lab wersquoll focus on the PAN-OS API which is the API for the Palo Alto Networks Next-generation Firewall andPanorama Management Center

When connecting to the PAN-OS API

bull Access the API on the management interface using HTTPS just as you would connect to the GUI

bull Connections to the API are treated as general web admin access They create a session just like you wereaccessing the GUI

bull Authentication requires an API key which is generated through an API call

Introduction to the PAN-OS API

12

Some examples of how you might use the PAN-OS API include but are not limited to

bull Read write verify and commit configuration

bull Download reports in XML format

bull Execute operational commands to check health and status

bull Collect logs and pcaps

bull Update dynamic address groups

bull Update user-id mappings

bull And much more

The API BrowserThe Next-generation Firewall and Panorama have an API Browser built in which allows you to explore the API andtrigger simple API calls in the browser itself

You can access the API Browser by adding api to the URL after the IP address of the firewall For example if yourfirewall is at 10001 the URL of the API Browser is https10001api

Lab exercise Try connecting to the API Browser on the firewall in your lab Explore a little to get familiar thencontinue with the lab

API Command TypesThere are several API types as shown in the main page of the API browser

API Types

API Type Description

keygen Generate an API Key (not shown in API Browser)

config Retrieve or modify the configuration

commit Commit the configuration

export Export files packet captures and keys

import Import files certificates response pages and branding

op Operational commands (like lsquoshowrsquo commands)

report Retrieve predefined dynamic and custom reports

user-id UserIP mappings and Dynamic Address Groups

This lab focuses on the following 5 types but the concepts needed to understand these 5 types are the sameconcepts for all the other types

bull keygen

bull config

bull commit

bull op

bull user-id

Introduction to the PAN-OS API

13

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 7: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

17 ltpermissionsgt 18 ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt 19 ltentrygt 20 ltusersgt 21 ltmgt-configgt 22 ltsharedgt 23 ltapplication gt 24 ltapplication-group gt 25 ltservice gt 26 ltservice-group gt 27 ltbotnetgt 28 ltconfigurationgt 29 lthttpgt 30 ltdynamic-dnsgt 31 ltenabledgtyesltenabledgt 32 ltthresholdgt5ltthresholdgt 33 ltdynamic-dnsgt 34 ltmalware-sitesgt 35 ltenabledgtyesltenabledgt 36 ltthresholdgt5ltthresholdgt 37 ltmalware-sitesgt 38 ltrecent-domainsgt 39 ltenabledgtyesltenabledgt 40 ltthresholdgt5ltthresholdgt 41 ltrecent-domainsgt 42 ltip-domainsgt 43 ltenabledgtyesltenabledgt 44 ltthresholdgt10ltthresholdgt 45 ltip-domainsgt 46 ltexecutables-from-unknown-sitesgt 47 ltenabledgtyesltenabledgt 48 ltthresholdgt5ltthresholdgt 49 ltexecutables-from-unknown-sitesgt 50 lthttpgt 51 ltother-applicationsgt 52 ltircgtyesltircgt 53 ltother-applicationsgt 54 ltunknown-applicationsgt 55 ltunknown-tcpgt 56 ltdestinations-per-hourgt10ltdestinations-per-hourgt 57 ltsessions-per-hourgt10ltsessions-per-hourgt 58 ltsession-lengthgt 59 ltmaximum-bytesgt100ltmaximum-bytesgt 60 ltminimum-bytesgt50ltminimum-bytesgt 61 ltsession-lengthgt 62 ltunknown-tcpgt 63 ltunknown-udpgt 64 ltdestinations-per-hourgt10ltdestinations-per-hourgt 65 ltsessions-per-hourgt10ltsessions-per-hourgt 66 ltsession-lengthgt 67 ltmaximum-bytesgt100ltmaximum-bytesgt 68 ltminimum-bytesgt50ltminimum-bytesgt 69 ltsession-lengthgt 70 ltunknown-udpgt 71 ltunknown-applicationsgt 72 ltconfigurationgt 73 ltreportgt 74 lttopngt100lttopngt 75 ltscheduledgtyesltscheduledgt 76 ltreportgt

PAN-OS XML API Labs with pan-python

4

77 ltbotnetgt 78 ltcontent-previewgt 79 ltapplication gt 80 ltapplication-typegt 81 ltcategory gt 82 lttechnology gt 83 ltapplication-typegt 84 ltcontent-previewgt 85 ltlocal-user-databasegt 86 ltuser-group gt 87 ltlocal-user-databasegt 88 ltsharedgt 89 ltdevicesgt 90 ltentry name=localhostlocaldomaingt 91 ltnetworkgt 92 ltinterfacegt 93 ltethernetgt 94 ltentry name=ethernet11gt 95 ltvirtual-wire gt 96 ltentrygt 97 ltentry name=ethernet12gt 98 ltvirtual-wire gt 99 ltentrygt100 ltethernetgt101 ltinterfacegt102 ltprofilesgt103 ltmonitor-profilegt104 ltentry name=defaultgt105 ltintervalgt3ltintervalgt106 ltthresholdgt5ltthresholdgt107 ltactiongtwait-recoverltactiongt108 ltentrygt109 ltmonitor-profilegt110 ltprofilesgt111 ltikegt112 ltcrypto-profilesgt113 ltike-crypto-profilesgt114 ltentry name=defaultgt115 ltencryptiongt116 ltmembergtaes-128-cbcltmembergt117 ltmembergt3desltmembergt118 ltencryptiongt119 lthashgt120 ltmembergtsha1ltmembergt121 lthashgt122 ltdh-groupgt123 ltmembergtgroup2ltmembergt124 ltdh-groupgt125 ltlifetimegt126 lthoursgt8lthoursgt127 ltlifetimegt128 ltentrygt129 ltentry name=Suite-B-GCM-128gt130 ltencryptiongt131 ltmembergtaes-128-cbcltmembergt132 ltencryptiongt133 lthashgt134 ltmembergtsha256ltmembergt135 lthashgt136 ltdh-groupgt

PAN-OS XML API Labs with pan-python

5

137 ltmembergtgroup19ltmembergt138 ltdh-groupgt139 ltlifetimegt140 lthoursgt8lthoursgt141 ltlifetimegt142 ltentrygt143 ltentry name=Suite-B-GCM-256gt144 ltencryptiongt145 ltmembergtaes-256-cbcltmembergt146 ltencryptiongt147 lthashgt148 ltmembergtsha384ltmembergt149 lthashgt150 ltdh-groupgt151 ltmembergtgroup20ltmembergt152 ltdh-groupgt153 ltlifetimegt154 lthoursgt8lthoursgt155 ltlifetimegt156 ltentrygt157 ltike-crypto-profilesgt158 ltipsec-crypto-profilesgt159 ltentry name=defaultgt160 ltespgt161 ltencryptiongt162 ltmembergtaes-128-cbcltmembergt163 ltmembergt3desltmembergt164 ltencryptiongt165 ltauthenticationgt166 ltmembergtsha1ltmembergt167 ltauthenticationgt168 ltespgt169 ltdh-groupgtgroup2ltdh-groupgt170 ltlifetimegt171 lthoursgt1lthoursgt172 ltlifetimegt173 ltentrygt174 ltentry name=Suite-B-GCM-128gt175 ltespgt176 ltencryptiongt177 ltmembergtaes-128-gcmltmembergt178 ltencryptiongt179 ltauthenticationgt180 ltmembergtnoneltmembergt181 ltauthenticationgt182 ltespgt183 ltdh-groupgtgroup19ltdh-groupgt184 ltlifetimegt185 lthoursgt1lthoursgt186 ltlifetimegt187 ltentrygt188 ltentry name=Suite-B-GCM-256gt189 ltespgt190 ltencryptiongt191 ltmembergtaes-256-gcmltmembergt192 ltencryptiongt193 ltauthenticationgt194 ltmembergtnoneltmembergt195 ltauthenticationgt196 ltespgt

PAN-OS XML API Labs with pan-python

6

197 ltdh-groupgtgroup20ltdh-groupgt198 ltlifetimegt199 lthoursgt1lthoursgt200 ltlifetimegt201 ltentrygt202 ltipsec-crypto-profilesgt203 ltglobal-protect-app-crypto-profilesgt204 ltentry name=defaultgt205 ltencryptiongt206 ltmembergtaes-128-cbcltmembergt207 ltencryptiongt208 ltauthenticationgt209 ltmembergtsha1ltmembergt210 ltauthenticationgt211 ltentrygt212 ltglobal-protect-app-crypto-profilesgt213 ltcrypto-profilesgt214 ltikegt215 ltqosgt216 ltprofilegt217 ltentry name=defaultgt218 ltclass-bandwidth-typegt219 ltmbpsgt220 ltclassgt221 ltentry name=class1gt222 ltprioritygtreal-timeltprioritygt223 ltentrygt224 ltentry name=class2gt225 ltprioritygthighltprioritygt226 ltentrygt227 ltentry name=class3gt228 ltprioritygthighltprioritygt229 ltentrygt230 ltentry name=class4gt231 ltprioritygtmediumltprioritygt232 ltentrygt233 ltentry name=class5gt234 ltprioritygtmediumltprioritygt235 ltentrygt236 ltentry name=class6gt237 ltprioritygtlowltprioritygt238 ltentrygt239 ltentry name=class7gt240 ltprioritygtlowltprioritygt241 ltentrygt242 ltentry name=class8gt243 ltprioritygtlowltprioritygt244 ltentrygt245 ltclassgt246 ltmbpsgt247 ltclass-bandwidth-typegt248 ltentrygt249 ltprofilegt250 ltqosgt251 ltvirtual-routergt252 ltentry name=defaultgt253 ltprotocolgt254 ltbgpgt255 ltenablegtnoltenablegt256 ltdampening-profilegt

PAN-OS XML API Labs with pan-python

7

257 ltentry name=defaultgt258 ltcutoffgt125ltcutoffgt259 ltreusegt05ltreusegt260 ltmax-hold-timegt900ltmax-hold-timegt261 ltdecay-half-life-reachablegt300ltdecay-half-life-reachablegt262 ltdecay-half-life-unreachablegt900ltdecay-half-life-unreachablegt263 ltenablegtyesltenablegt264 ltentrygt265 ltdampening-profilegt266 ltbgpgt267 ltprotocolgt268 ltentrygt269 ltvirtual-routergt270 ltvirtual-wiregt271 ltentry name=default-vwiregt272 ltinterface1gtethernet11ltinterface1gt273 ltinterface2gtethernet12ltinterface2gt274 ltentrygt275 ltvirtual-wiregt276 ltnetworkgt277 ltdeviceconfiggt278 ltsystemgt279 lttypegt280 ltstatic gt281 lttypegt282 ltupdate-servergtupdatespaloaltonetworkscomltupdate-servergt283 ltupdate-schedule gt284 lttimezonegtUSPacificlttimezonegt285 ltservicegt286 ltdisable-telnetgtyesltdisable-telnetgt287 ltdisable-httpgtyesltdisable-httpgt288 ltservicegt289 lthostnamegtPA-VMlthostnamegt290 ltip-addressgt1921681103ltip-addressgt291 ltnetmaskgt2552552550ltnetmaskgt292 ltdefault-gatewaygt1921681254ltdefault-gatewaygt293 ltdns-settinggt294 ltserversgt295 ltprimarygt8888ltprimarygt296 ltserversgt297 ltdns-settinggt298 ltntp-serversgt299 ltprimary-ntp-servergt300 ltntp-server-addressgtuspoolntporgltntp-server-addressgt301 ltauthentication-typegt302 ltnone gt303 ltauthentication-typegt304 ltprimary-ntp-servergt305 ltsecondary-ntp-servergt306 ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt307 ltauthentication-typegt308 ltnone gt309 ltauthentication-typegt310 ltsecondary-ntp-servergt311 ltntp-serversgt312 ltsystemgt313 ltsettinggt314 ltconfiggt315 ltrematchgtyesltrematchgt316 ltconfiggt

PAN-OS XML API Labs with pan-python

8

317 ltmanagementgt318 lthostname-type-in-sysloggtFQDNlthostname-type-in-sysloggt319 ltdisable-predefined-reportsgt320 ltmembergtspyware-infected-hostsltmembergt321 ltmembergttop-application-categoriesltmembergt322 ltmembergttop-technology-categoriesltmembergt323 ltmembergtbandwidth-trendltmembergt324 ltmembergtrisk-trendltmembergt325 ltmembergtthreat-trendltmembergt326 ltmembergttop-usersltmembergt327 ltmembergttop-attacker-sourcesltmembergt328 ltmembergttop-attacker-destinationsltmembergt329 ltmembergttop-victim-sourcesltmembergt330 ltmembergttop-victim-destinationsltmembergt331 ltmembergttop-attackers-by-source-countriesltmembergt332 ltmembergttop-attackers-by-destination-countriesltmembergt333 ltmembergttop-victims-by-source-countriesltmembergt334 ltmembergttop-victims-by-destination-countriesltmembergt335 ltmembergttop-sourcesltmembergt336 ltmembergttop-destinationsltmembergt337 ltmembergttop-destination-countriesltmembergt338 ltmembergttop-source-countriesltmembergt339 ltmembergttop-connectionsltmembergt340 ltmembergttop-ingress-interfacesltmembergt341 ltmembergttop-egress-interfacesltmembergt342 ltmembergttop-ingress-zonesltmembergt343 ltmembergttop-egress-zonesltmembergt344 ltmembergttop-applicationsltmembergt345 ltmembergttop-http-applicationsltmembergt346 ltmembergttop-rulesltmembergt347 ltmembergttop-attacksltmembergt348 ltmembergttop-spyware-threatsltmembergt349 ltmembergttop-virusesltmembergt350 ltmembergttop-vulnerabilitiesltmembergt351 ltmembergtwildfire-file-digestsltmembergt352 ltmembergttop-websitesltmembergt353 ltmembergttop-url-categoriesltmembergt354 ltmembergttop-url-usersltmembergt355 ltmembergttop-url-user-behaviorltmembergt356 ltmembergttop-blocked-websitesltmembergt357 ltmembergttop-blocked-url-categoriesltmembergt358 ltmembergttop-blocked-url-usersltmembergt359 ltmembergttop-blocked-url-user-behaviorltmembergt360 ltmembergtblocked-credential-postltmembergt361 ltmembergtunknown-tcp-connectionsltmembergt362 ltmembergtunknown-udp-connectionsltmembergt363 ltmembergttop-denied-sourcesltmembergt364 ltmembergttop-denied-destinationsltmembergt365 ltmembergttop-denied-applicationsltmembergt366 ltmembergtrisky-usersltmembergt367 ltmembergtSaaS Application Usageltmembergt368 ltmembergtgtp-events-summaryltmembergt369 ltmembergtgtp-malicious-wildfire-submissionsltmembergt370 ltmembergtgtp-security-eventsltmembergt371 ltmembergtgtp-v1-causesltmembergt372 ltmembergtgtp-v2-causesltmembergt373 ltmembergtgtp-users-visiting-malicious-urlltmembergt374 ltmembergttop-gtp-attacker-destinationsltmembergt375 ltmembergttop-gtp-attacker-sourcesltmembergt376 ltmembergttop-gtp-victim-destinationsltmembergt

PAN-OS XML API Labs with pan-python

9

377 ltmembergttop-gtp-victim-sourcesltmembergt378 ltmembergtsctp-error-causesltmembergt379 ltmembergtsctp-events-summaryltmembergt380 ltmembergtsctp-security-eventsltmembergt381 ltdisable-predefined-reportsgt382 ltmanagementgt383 ltauto-mac-detectgtyesltauto-mac-detectgt384 ltsettinggt385 ltdeviceconfiggt386 ltvsysgt387 ltentry name=vsys1gt388 ltapplication gt389 ltapplication-group gt390 ltzonegt391 ltentry name=trustgt392 ltnetworkgt393 ltvirtual-wiregt394 ltmembergtethernet12ltmembergt395 ltvirtual-wiregt396 ltnetworkgt397 ltentrygt398 ltentry name=untrustgt399 ltnetworkgt400 ltvirtual-wiregt401 ltmembergtethernet11ltmembergt402 ltvirtual-wiregt403 ltnetworkgt404 ltentrygt405 ltzonegt406 ltservice gt407 ltservice-group gt408 ltschedule gt409 ltrulebasegt410 ltsecuritygt411 ltrulesgt412 ltentry name=rule2 uuid=031613c5-a691-4887-b284-5af2915e7c36gt413 lttogt414 ltmembergtuntrustltmembergt415 lttogt416 ltfromgt417 ltmembergttrustltmembergt418 ltfromgt419 ltsourcegt420 ltmembergtanyltmembergt421 ltsourcegt422 ltsource-usergt423 ltmembergtanyltmembergt424 ltsource-usergt425 ltcategorygt426 ltmembergtanyltmembergt427 ltcategorygt428 ltapplicationgt429 ltmembergtanyltmembergt430 ltapplicationgt431 ltservicegt432 ltmembergtapplication-defaultltmembergt433 ltservicegt434 lthip-profilesgt435 ltmembergtanyltmembergt436 lthip-profilesgt

PAN-OS XML API Labs with pan-python

10

437 ltactiongtdenyltactiongt438 ltdestinationgt439 ltmembergtgroup2ltmembergt440 ltdestinationgt441 ltentrygt442 ltentry name=rule1 uuid=c678a3fb-0e9b-45b7-aa4f-66a3e8864339gt443 lttogt444 ltmembergtuntrustltmembergt445 lttogt446 ltfromgt447 ltmembergttrustltmembergt448 ltfromgt449 ltsourcegt450 ltmembergtanyltmembergt451 ltsourcegt452 ltdestinationgt453 ltmembergtanyltmembergt454 ltdestinationgt455 ltsource-usergt456 ltmembergtanyltmembergt457 ltsource-usergt458 ltcategorygt459 ltmembergtanyltmembergt460 ltcategorygt461 ltapplicationgt462 ltmembergtanyltmembergt463 ltapplicationgt464 ltservicegt465 ltmembergtanyltmembergt466 ltservicegt467 lthip-profilesgt468 ltmembergtanyltmembergt469 lthip-profilesgt470 ltactiongtallowltactiongt471 ltentrygt472 ltrulesgt473 ltsecuritygt474 ltrulebasegt475 ltimportgt476 ltnetworkgt477 ltinterfacegt478 ltmembergtethernet11ltmembergt479 ltmembergtethernet12ltmembergt480 ltinterfacegt481 ltnetworkgt482 ltimportgt483 ltaddressgt484 ltentry name=addr1gt485 ltip-netmaskgt10001ltip-netmaskgt486 ltentrygt487 ltentry name=addr2gt488 ltip-netmaskgt10002ltip-netmaskgt489 ltentrygt490 ltentry name=addr3gt491 ltip-netmaskgt10003ltip-netmaskgt492 ltentrygt493 ltentry name=addr4gt494 ltip-netmaskgt10004ltip-netmaskgt495 ltentrygt496 ltentry name=addr5gt

PAN-OS XML API Labs with pan-python

11

497 ltip-netmaskgt10005ltip-netmaskgt498 ltentrygt499 ltaddressgt500 ltaddress-groupgt501 ltentry name=group1gt502 ltstaticgt503 ltmembergtaddr1ltmembergt504 ltmembergtaddr2ltmembergt505 ltmembergtaddr3ltmembergt506 ltstaticgt507 ltentrygt508 ltentry name=group2gt509 ltdynamicgt510 ltfiltergttag01 or tag02ltfiltergt511 ltdynamicgt512 ltentrygt513 ltaddress-groupgt514 ltuser-id-collectorgt515 ltsettinggt516 ltenable-mapping-timeoutgtyesltenable-mapping-timeoutgt517 ltip-user-mapping-timeoutgt45ltip-user-mapping-timeoutgt518 ltsettinggt519 ltuser-id-collectorgt520 ltdynamic-user-groupgt521 ltentry name=dug1gt522 ltfiltergttag01 or tag02ltfiltergt523 ltentrygt524 ltdynamic-user-groupgt525 ltentrygt526 ltvsysgt527 ltentrygt528 ltdevicesgt529 ltconfiggt

Introduction to the PAN-OS API

About the API

APIrsquos are very important to Palo Alto Networks Security automation is key to the success of any organization inpreventing cyber attacks So Palo Alto Networks products have comprehensive APIs to enable automation

In this lab wersquoll focus on the PAN-OS API which is the API for the Palo Alto Networks Next-generation Firewall andPanorama Management Center

When connecting to the PAN-OS API

bull Access the API on the management interface using HTTPS just as you would connect to the GUI

bull Connections to the API are treated as general web admin access They create a session just like you wereaccessing the GUI

bull Authentication requires an API key which is generated through an API call

Introduction to the PAN-OS API

12

Some examples of how you might use the PAN-OS API include but are not limited to

bull Read write verify and commit configuration

bull Download reports in XML format

bull Execute operational commands to check health and status

bull Collect logs and pcaps

bull Update dynamic address groups

bull Update user-id mappings

bull And much more

The API BrowserThe Next-generation Firewall and Panorama have an API Browser built in which allows you to explore the API andtrigger simple API calls in the browser itself

You can access the API Browser by adding api to the URL after the IP address of the firewall For example if yourfirewall is at 10001 the URL of the API Browser is https10001api

Lab exercise Try connecting to the API Browser on the firewall in your lab Explore a little to get familiar thencontinue with the lab

API Command TypesThere are several API types as shown in the main page of the API browser

API Types

API Type Description

keygen Generate an API Key (not shown in API Browser)

config Retrieve or modify the configuration

commit Commit the configuration

export Export files packet captures and keys

import Import files certificates response pages and branding

op Operational commands (like lsquoshowrsquo commands)

report Retrieve predefined dynamic and custom reports

user-id UserIP mappings and Dynamic Address Groups

This lab focuses on the following 5 types but the concepts needed to understand these 5 types are the sameconcepts for all the other types

bull keygen

bull config

bull commit

bull op

bull user-id

Introduction to the PAN-OS API

13

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 8: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

77 ltbotnetgt 78 ltcontent-previewgt 79 ltapplication gt 80 ltapplication-typegt 81 ltcategory gt 82 lttechnology gt 83 ltapplication-typegt 84 ltcontent-previewgt 85 ltlocal-user-databasegt 86 ltuser-group gt 87 ltlocal-user-databasegt 88 ltsharedgt 89 ltdevicesgt 90 ltentry name=localhostlocaldomaingt 91 ltnetworkgt 92 ltinterfacegt 93 ltethernetgt 94 ltentry name=ethernet11gt 95 ltvirtual-wire gt 96 ltentrygt 97 ltentry name=ethernet12gt 98 ltvirtual-wire gt 99 ltentrygt100 ltethernetgt101 ltinterfacegt102 ltprofilesgt103 ltmonitor-profilegt104 ltentry name=defaultgt105 ltintervalgt3ltintervalgt106 ltthresholdgt5ltthresholdgt107 ltactiongtwait-recoverltactiongt108 ltentrygt109 ltmonitor-profilegt110 ltprofilesgt111 ltikegt112 ltcrypto-profilesgt113 ltike-crypto-profilesgt114 ltentry name=defaultgt115 ltencryptiongt116 ltmembergtaes-128-cbcltmembergt117 ltmembergt3desltmembergt118 ltencryptiongt119 lthashgt120 ltmembergtsha1ltmembergt121 lthashgt122 ltdh-groupgt123 ltmembergtgroup2ltmembergt124 ltdh-groupgt125 ltlifetimegt126 lthoursgt8lthoursgt127 ltlifetimegt128 ltentrygt129 ltentry name=Suite-B-GCM-128gt130 ltencryptiongt131 ltmembergtaes-128-cbcltmembergt132 ltencryptiongt133 lthashgt134 ltmembergtsha256ltmembergt135 lthashgt136 ltdh-groupgt

PAN-OS XML API Labs with pan-python

5

137 ltmembergtgroup19ltmembergt138 ltdh-groupgt139 ltlifetimegt140 lthoursgt8lthoursgt141 ltlifetimegt142 ltentrygt143 ltentry name=Suite-B-GCM-256gt144 ltencryptiongt145 ltmembergtaes-256-cbcltmembergt146 ltencryptiongt147 lthashgt148 ltmembergtsha384ltmembergt149 lthashgt150 ltdh-groupgt151 ltmembergtgroup20ltmembergt152 ltdh-groupgt153 ltlifetimegt154 lthoursgt8lthoursgt155 ltlifetimegt156 ltentrygt157 ltike-crypto-profilesgt158 ltipsec-crypto-profilesgt159 ltentry name=defaultgt160 ltespgt161 ltencryptiongt162 ltmembergtaes-128-cbcltmembergt163 ltmembergt3desltmembergt164 ltencryptiongt165 ltauthenticationgt166 ltmembergtsha1ltmembergt167 ltauthenticationgt168 ltespgt169 ltdh-groupgtgroup2ltdh-groupgt170 ltlifetimegt171 lthoursgt1lthoursgt172 ltlifetimegt173 ltentrygt174 ltentry name=Suite-B-GCM-128gt175 ltespgt176 ltencryptiongt177 ltmembergtaes-128-gcmltmembergt178 ltencryptiongt179 ltauthenticationgt180 ltmembergtnoneltmembergt181 ltauthenticationgt182 ltespgt183 ltdh-groupgtgroup19ltdh-groupgt184 ltlifetimegt185 lthoursgt1lthoursgt186 ltlifetimegt187 ltentrygt188 ltentry name=Suite-B-GCM-256gt189 ltespgt190 ltencryptiongt191 ltmembergtaes-256-gcmltmembergt192 ltencryptiongt193 ltauthenticationgt194 ltmembergtnoneltmembergt195 ltauthenticationgt196 ltespgt

PAN-OS XML API Labs with pan-python

6

197 ltdh-groupgtgroup20ltdh-groupgt198 ltlifetimegt199 lthoursgt1lthoursgt200 ltlifetimegt201 ltentrygt202 ltipsec-crypto-profilesgt203 ltglobal-protect-app-crypto-profilesgt204 ltentry name=defaultgt205 ltencryptiongt206 ltmembergtaes-128-cbcltmembergt207 ltencryptiongt208 ltauthenticationgt209 ltmembergtsha1ltmembergt210 ltauthenticationgt211 ltentrygt212 ltglobal-protect-app-crypto-profilesgt213 ltcrypto-profilesgt214 ltikegt215 ltqosgt216 ltprofilegt217 ltentry name=defaultgt218 ltclass-bandwidth-typegt219 ltmbpsgt220 ltclassgt221 ltentry name=class1gt222 ltprioritygtreal-timeltprioritygt223 ltentrygt224 ltentry name=class2gt225 ltprioritygthighltprioritygt226 ltentrygt227 ltentry name=class3gt228 ltprioritygthighltprioritygt229 ltentrygt230 ltentry name=class4gt231 ltprioritygtmediumltprioritygt232 ltentrygt233 ltentry name=class5gt234 ltprioritygtmediumltprioritygt235 ltentrygt236 ltentry name=class6gt237 ltprioritygtlowltprioritygt238 ltentrygt239 ltentry name=class7gt240 ltprioritygtlowltprioritygt241 ltentrygt242 ltentry name=class8gt243 ltprioritygtlowltprioritygt244 ltentrygt245 ltclassgt246 ltmbpsgt247 ltclass-bandwidth-typegt248 ltentrygt249 ltprofilegt250 ltqosgt251 ltvirtual-routergt252 ltentry name=defaultgt253 ltprotocolgt254 ltbgpgt255 ltenablegtnoltenablegt256 ltdampening-profilegt

PAN-OS XML API Labs with pan-python

7

257 ltentry name=defaultgt258 ltcutoffgt125ltcutoffgt259 ltreusegt05ltreusegt260 ltmax-hold-timegt900ltmax-hold-timegt261 ltdecay-half-life-reachablegt300ltdecay-half-life-reachablegt262 ltdecay-half-life-unreachablegt900ltdecay-half-life-unreachablegt263 ltenablegtyesltenablegt264 ltentrygt265 ltdampening-profilegt266 ltbgpgt267 ltprotocolgt268 ltentrygt269 ltvirtual-routergt270 ltvirtual-wiregt271 ltentry name=default-vwiregt272 ltinterface1gtethernet11ltinterface1gt273 ltinterface2gtethernet12ltinterface2gt274 ltentrygt275 ltvirtual-wiregt276 ltnetworkgt277 ltdeviceconfiggt278 ltsystemgt279 lttypegt280 ltstatic gt281 lttypegt282 ltupdate-servergtupdatespaloaltonetworkscomltupdate-servergt283 ltupdate-schedule gt284 lttimezonegtUSPacificlttimezonegt285 ltservicegt286 ltdisable-telnetgtyesltdisable-telnetgt287 ltdisable-httpgtyesltdisable-httpgt288 ltservicegt289 lthostnamegtPA-VMlthostnamegt290 ltip-addressgt1921681103ltip-addressgt291 ltnetmaskgt2552552550ltnetmaskgt292 ltdefault-gatewaygt1921681254ltdefault-gatewaygt293 ltdns-settinggt294 ltserversgt295 ltprimarygt8888ltprimarygt296 ltserversgt297 ltdns-settinggt298 ltntp-serversgt299 ltprimary-ntp-servergt300 ltntp-server-addressgtuspoolntporgltntp-server-addressgt301 ltauthentication-typegt302 ltnone gt303 ltauthentication-typegt304 ltprimary-ntp-servergt305 ltsecondary-ntp-servergt306 ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt307 ltauthentication-typegt308 ltnone gt309 ltauthentication-typegt310 ltsecondary-ntp-servergt311 ltntp-serversgt312 ltsystemgt313 ltsettinggt314 ltconfiggt315 ltrematchgtyesltrematchgt316 ltconfiggt

PAN-OS XML API Labs with pan-python

8

317 ltmanagementgt318 lthostname-type-in-sysloggtFQDNlthostname-type-in-sysloggt319 ltdisable-predefined-reportsgt320 ltmembergtspyware-infected-hostsltmembergt321 ltmembergttop-application-categoriesltmembergt322 ltmembergttop-technology-categoriesltmembergt323 ltmembergtbandwidth-trendltmembergt324 ltmembergtrisk-trendltmembergt325 ltmembergtthreat-trendltmembergt326 ltmembergttop-usersltmembergt327 ltmembergttop-attacker-sourcesltmembergt328 ltmembergttop-attacker-destinationsltmembergt329 ltmembergttop-victim-sourcesltmembergt330 ltmembergttop-victim-destinationsltmembergt331 ltmembergttop-attackers-by-source-countriesltmembergt332 ltmembergttop-attackers-by-destination-countriesltmembergt333 ltmembergttop-victims-by-source-countriesltmembergt334 ltmembergttop-victims-by-destination-countriesltmembergt335 ltmembergttop-sourcesltmembergt336 ltmembergttop-destinationsltmembergt337 ltmembergttop-destination-countriesltmembergt338 ltmembergttop-source-countriesltmembergt339 ltmembergttop-connectionsltmembergt340 ltmembergttop-ingress-interfacesltmembergt341 ltmembergttop-egress-interfacesltmembergt342 ltmembergttop-ingress-zonesltmembergt343 ltmembergttop-egress-zonesltmembergt344 ltmembergttop-applicationsltmembergt345 ltmembergttop-http-applicationsltmembergt346 ltmembergttop-rulesltmembergt347 ltmembergttop-attacksltmembergt348 ltmembergttop-spyware-threatsltmembergt349 ltmembergttop-virusesltmembergt350 ltmembergttop-vulnerabilitiesltmembergt351 ltmembergtwildfire-file-digestsltmembergt352 ltmembergttop-websitesltmembergt353 ltmembergttop-url-categoriesltmembergt354 ltmembergttop-url-usersltmembergt355 ltmembergttop-url-user-behaviorltmembergt356 ltmembergttop-blocked-websitesltmembergt357 ltmembergttop-blocked-url-categoriesltmembergt358 ltmembergttop-blocked-url-usersltmembergt359 ltmembergttop-blocked-url-user-behaviorltmembergt360 ltmembergtblocked-credential-postltmembergt361 ltmembergtunknown-tcp-connectionsltmembergt362 ltmembergtunknown-udp-connectionsltmembergt363 ltmembergttop-denied-sourcesltmembergt364 ltmembergttop-denied-destinationsltmembergt365 ltmembergttop-denied-applicationsltmembergt366 ltmembergtrisky-usersltmembergt367 ltmembergtSaaS Application Usageltmembergt368 ltmembergtgtp-events-summaryltmembergt369 ltmembergtgtp-malicious-wildfire-submissionsltmembergt370 ltmembergtgtp-security-eventsltmembergt371 ltmembergtgtp-v1-causesltmembergt372 ltmembergtgtp-v2-causesltmembergt373 ltmembergtgtp-users-visiting-malicious-urlltmembergt374 ltmembergttop-gtp-attacker-destinationsltmembergt375 ltmembergttop-gtp-attacker-sourcesltmembergt376 ltmembergttop-gtp-victim-destinationsltmembergt

PAN-OS XML API Labs with pan-python

9

377 ltmembergttop-gtp-victim-sourcesltmembergt378 ltmembergtsctp-error-causesltmembergt379 ltmembergtsctp-events-summaryltmembergt380 ltmembergtsctp-security-eventsltmembergt381 ltdisable-predefined-reportsgt382 ltmanagementgt383 ltauto-mac-detectgtyesltauto-mac-detectgt384 ltsettinggt385 ltdeviceconfiggt386 ltvsysgt387 ltentry name=vsys1gt388 ltapplication gt389 ltapplication-group gt390 ltzonegt391 ltentry name=trustgt392 ltnetworkgt393 ltvirtual-wiregt394 ltmembergtethernet12ltmembergt395 ltvirtual-wiregt396 ltnetworkgt397 ltentrygt398 ltentry name=untrustgt399 ltnetworkgt400 ltvirtual-wiregt401 ltmembergtethernet11ltmembergt402 ltvirtual-wiregt403 ltnetworkgt404 ltentrygt405 ltzonegt406 ltservice gt407 ltservice-group gt408 ltschedule gt409 ltrulebasegt410 ltsecuritygt411 ltrulesgt412 ltentry name=rule2 uuid=031613c5-a691-4887-b284-5af2915e7c36gt413 lttogt414 ltmembergtuntrustltmembergt415 lttogt416 ltfromgt417 ltmembergttrustltmembergt418 ltfromgt419 ltsourcegt420 ltmembergtanyltmembergt421 ltsourcegt422 ltsource-usergt423 ltmembergtanyltmembergt424 ltsource-usergt425 ltcategorygt426 ltmembergtanyltmembergt427 ltcategorygt428 ltapplicationgt429 ltmembergtanyltmembergt430 ltapplicationgt431 ltservicegt432 ltmembergtapplication-defaultltmembergt433 ltservicegt434 lthip-profilesgt435 ltmembergtanyltmembergt436 lthip-profilesgt

PAN-OS XML API Labs with pan-python

10

437 ltactiongtdenyltactiongt438 ltdestinationgt439 ltmembergtgroup2ltmembergt440 ltdestinationgt441 ltentrygt442 ltentry name=rule1 uuid=c678a3fb-0e9b-45b7-aa4f-66a3e8864339gt443 lttogt444 ltmembergtuntrustltmembergt445 lttogt446 ltfromgt447 ltmembergttrustltmembergt448 ltfromgt449 ltsourcegt450 ltmembergtanyltmembergt451 ltsourcegt452 ltdestinationgt453 ltmembergtanyltmembergt454 ltdestinationgt455 ltsource-usergt456 ltmembergtanyltmembergt457 ltsource-usergt458 ltcategorygt459 ltmembergtanyltmembergt460 ltcategorygt461 ltapplicationgt462 ltmembergtanyltmembergt463 ltapplicationgt464 ltservicegt465 ltmembergtanyltmembergt466 ltservicegt467 lthip-profilesgt468 ltmembergtanyltmembergt469 lthip-profilesgt470 ltactiongtallowltactiongt471 ltentrygt472 ltrulesgt473 ltsecuritygt474 ltrulebasegt475 ltimportgt476 ltnetworkgt477 ltinterfacegt478 ltmembergtethernet11ltmembergt479 ltmembergtethernet12ltmembergt480 ltinterfacegt481 ltnetworkgt482 ltimportgt483 ltaddressgt484 ltentry name=addr1gt485 ltip-netmaskgt10001ltip-netmaskgt486 ltentrygt487 ltentry name=addr2gt488 ltip-netmaskgt10002ltip-netmaskgt489 ltentrygt490 ltentry name=addr3gt491 ltip-netmaskgt10003ltip-netmaskgt492 ltentrygt493 ltentry name=addr4gt494 ltip-netmaskgt10004ltip-netmaskgt495 ltentrygt496 ltentry name=addr5gt

PAN-OS XML API Labs with pan-python

11

497 ltip-netmaskgt10005ltip-netmaskgt498 ltentrygt499 ltaddressgt500 ltaddress-groupgt501 ltentry name=group1gt502 ltstaticgt503 ltmembergtaddr1ltmembergt504 ltmembergtaddr2ltmembergt505 ltmembergtaddr3ltmembergt506 ltstaticgt507 ltentrygt508 ltentry name=group2gt509 ltdynamicgt510 ltfiltergttag01 or tag02ltfiltergt511 ltdynamicgt512 ltentrygt513 ltaddress-groupgt514 ltuser-id-collectorgt515 ltsettinggt516 ltenable-mapping-timeoutgtyesltenable-mapping-timeoutgt517 ltip-user-mapping-timeoutgt45ltip-user-mapping-timeoutgt518 ltsettinggt519 ltuser-id-collectorgt520 ltdynamic-user-groupgt521 ltentry name=dug1gt522 ltfiltergttag01 or tag02ltfiltergt523 ltentrygt524 ltdynamic-user-groupgt525 ltentrygt526 ltvsysgt527 ltentrygt528 ltdevicesgt529 ltconfiggt

Introduction to the PAN-OS API

About the API

APIrsquos are very important to Palo Alto Networks Security automation is key to the success of any organization inpreventing cyber attacks So Palo Alto Networks products have comprehensive APIs to enable automation

In this lab wersquoll focus on the PAN-OS API which is the API for the Palo Alto Networks Next-generation Firewall andPanorama Management Center

When connecting to the PAN-OS API

bull Access the API on the management interface using HTTPS just as you would connect to the GUI

bull Connections to the API are treated as general web admin access They create a session just like you wereaccessing the GUI

bull Authentication requires an API key which is generated through an API call

Introduction to the PAN-OS API

12

Some examples of how you might use the PAN-OS API include but are not limited to

bull Read write verify and commit configuration

bull Download reports in XML format

bull Execute operational commands to check health and status

bull Collect logs and pcaps

bull Update dynamic address groups

bull Update user-id mappings

bull And much more

The API BrowserThe Next-generation Firewall and Panorama have an API Browser built in which allows you to explore the API andtrigger simple API calls in the browser itself

You can access the API Browser by adding api to the URL after the IP address of the firewall For example if yourfirewall is at 10001 the URL of the API Browser is https10001api

Lab exercise Try connecting to the API Browser on the firewall in your lab Explore a little to get familiar thencontinue with the lab

API Command TypesThere are several API types as shown in the main page of the API browser

API Types

API Type Description

keygen Generate an API Key (not shown in API Browser)

config Retrieve or modify the configuration

commit Commit the configuration

export Export files packet captures and keys

import Import files certificates response pages and branding

op Operational commands (like lsquoshowrsquo commands)

report Retrieve predefined dynamic and custom reports

user-id UserIP mappings and Dynamic Address Groups

This lab focuses on the following 5 types but the concepts needed to understand these 5 types are the sameconcepts for all the other types

bull keygen

bull config

bull commit

bull op

bull user-id

Introduction to the PAN-OS API

13

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 9: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

137 ltmembergtgroup19ltmembergt138 ltdh-groupgt139 ltlifetimegt140 lthoursgt8lthoursgt141 ltlifetimegt142 ltentrygt143 ltentry name=Suite-B-GCM-256gt144 ltencryptiongt145 ltmembergtaes-256-cbcltmembergt146 ltencryptiongt147 lthashgt148 ltmembergtsha384ltmembergt149 lthashgt150 ltdh-groupgt151 ltmembergtgroup20ltmembergt152 ltdh-groupgt153 ltlifetimegt154 lthoursgt8lthoursgt155 ltlifetimegt156 ltentrygt157 ltike-crypto-profilesgt158 ltipsec-crypto-profilesgt159 ltentry name=defaultgt160 ltespgt161 ltencryptiongt162 ltmembergtaes-128-cbcltmembergt163 ltmembergt3desltmembergt164 ltencryptiongt165 ltauthenticationgt166 ltmembergtsha1ltmembergt167 ltauthenticationgt168 ltespgt169 ltdh-groupgtgroup2ltdh-groupgt170 ltlifetimegt171 lthoursgt1lthoursgt172 ltlifetimegt173 ltentrygt174 ltentry name=Suite-B-GCM-128gt175 ltespgt176 ltencryptiongt177 ltmembergtaes-128-gcmltmembergt178 ltencryptiongt179 ltauthenticationgt180 ltmembergtnoneltmembergt181 ltauthenticationgt182 ltespgt183 ltdh-groupgtgroup19ltdh-groupgt184 ltlifetimegt185 lthoursgt1lthoursgt186 ltlifetimegt187 ltentrygt188 ltentry name=Suite-B-GCM-256gt189 ltespgt190 ltencryptiongt191 ltmembergtaes-256-gcmltmembergt192 ltencryptiongt193 ltauthenticationgt194 ltmembergtnoneltmembergt195 ltauthenticationgt196 ltespgt

PAN-OS XML API Labs with pan-python

6

197 ltdh-groupgtgroup20ltdh-groupgt198 ltlifetimegt199 lthoursgt1lthoursgt200 ltlifetimegt201 ltentrygt202 ltipsec-crypto-profilesgt203 ltglobal-protect-app-crypto-profilesgt204 ltentry name=defaultgt205 ltencryptiongt206 ltmembergtaes-128-cbcltmembergt207 ltencryptiongt208 ltauthenticationgt209 ltmembergtsha1ltmembergt210 ltauthenticationgt211 ltentrygt212 ltglobal-protect-app-crypto-profilesgt213 ltcrypto-profilesgt214 ltikegt215 ltqosgt216 ltprofilegt217 ltentry name=defaultgt218 ltclass-bandwidth-typegt219 ltmbpsgt220 ltclassgt221 ltentry name=class1gt222 ltprioritygtreal-timeltprioritygt223 ltentrygt224 ltentry name=class2gt225 ltprioritygthighltprioritygt226 ltentrygt227 ltentry name=class3gt228 ltprioritygthighltprioritygt229 ltentrygt230 ltentry name=class4gt231 ltprioritygtmediumltprioritygt232 ltentrygt233 ltentry name=class5gt234 ltprioritygtmediumltprioritygt235 ltentrygt236 ltentry name=class6gt237 ltprioritygtlowltprioritygt238 ltentrygt239 ltentry name=class7gt240 ltprioritygtlowltprioritygt241 ltentrygt242 ltentry name=class8gt243 ltprioritygtlowltprioritygt244 ltentrygt245 ltclassgt246 ltmbpsgt247 ltclass-bandwidth-typegt248 ltentrygt249 ltprofilegt250 ltqosgt251 ltvirtual-routergt252 ltentry name=defaultgt253 ltprotocolgt254 ltbgpgt255 ltenablegtnoltenablegt256 ltdampening-profilegt

PAN-OS XML API Labs with pan-python

7

257 ltentry name=defaultgt258 ltcutoffgt125ltcutoffgt259 ltreusegt05ltreusegt260 ltmax-hold-timegt900ltmax-hold-timegt261 ltdecay-half-life-reachablegt300ltdecay-half-life-reachablegt262 ltdecay-half-life-unreachablegt900ltdecay-half-life-unreachablegt263 ltenablegtyesltenablegt264 ltentrygt265 ltdampening-profilegt266 ltbgpgt267 ltprotocolgt268 ltentrygt269 ltvirtual-routergt270 ltvirtual-wiregt271 ltentry name=default-vwiregt272 ltinterface1gtethernet11ltinterface1gt273 ltinterface2gtethernet12ltinterface2gt274 ltentrygt275 ltvirtual-wiregt276 ltnetworkgt277 ltdeviceconfiggt278 ltsystemgt279 lttypegt280 ltstatic gt281 lttypegt282 ltupdate-servergtupdatespaloaltonetworkscomltupdate-servergt283 ltupdate-schedule gt284 lttimezonegtUSPacificlttimezonegt285 ltservicegt286 ltdisable-telnetgtyesltdisable-telnetgt287 ltdisable-httpgtyesltdisable-httpgt288 ltservicegt289 lthostnamegtPA-VMlthostnamegt290 ltip-addressgt1921681103ltip-addressgt291 ltnetmaskgt2552552550ltnetmaskgt292 ltdefault-gatewaygt1921681254ltdefault-gatewaygt293 ltdns-settinggt294 ltserversgt295 ltprimarygt8888ltprimarygt296 ltserversgt297 ltdns-settinggt298 ltntp-serversgt299 ltprimary-ntp-servergt300 ltntp-server-addressgtuspoolntporgltntp-server-addressgt301 ltauthentication-typegt302 ltnone gt303 ltauthentication-typegt304 ltprimary-ntp-servergt305 ltsecondary-ntp-servergt306 ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt307 ltauthentication-typegt308 ltnone gt309 ltauthentication-typegt310 ltsecondary-ntp-servergt311 ltntp-serversgt312 ltsystemgt313 ltsettinggt314 ltconfiggt315 ltrematchgtyesltrematchgt316 ltconfiggt

PAN-OS XML API Labs with pan-python

8

317 ltmanagementgt318 lthostname-type-in-sysloggtFQDNlthostname-type-in-sysloggt319 ltdisable-predefined-reportsgt320 ltmembergtspyware-infected-hostsltmembergt321 ltmembergttop-application-categoriesltmembergt322 ltmembergttop-technology-categoriesltmembergt323 ltmembergtbandwidth-trendltmembergt324 ltmembergtrisk-trendltmembergt325 ltmembergtthreat-trendltmembergt326 ltmembergttop-usersltmembergt327 ltmembergttop-attacker-sourcesltmembergt328 ltmembergttop-attacker-destinationsltmembergt329 ltmembergttop-victim-sourcesltmembergt330 ltmembergttop-victim-destinationsltmembergt331 ltmembergttop-attackers-by-source-countriesltmembergt332 ltmembergttop-attackers-by-destination-countriesltmembergt333 ltmembergttop-victims-by-source-countriesltmembergt334 ltmembergttop-victims-by-destination-countriesltmembergt335 ltmembergttop-sourcesltmembergt336 ltmembergttop-destinationsltmembergt337 ltmembergttop-destination-countriesltmembergt338 ltmembergttop-source-countriesltmembergt339 ltmembergttop-connectionsltmembergt340 ltmembergttop-ingress-interfacesltmembergt341 ltmembergttop-egress-interfacesltmembergt342 ltmembergttop-ingress-zonesltmembergt343 ltmembergttop-egress-zonesltmembergt344 ltmembergttop-applicationsltmembergt345 ltmembergttop-http-applicationsltmembergt346 ltmembergttop-rulesltmembergt347 ltmembergttop-attacksltmembergt348 ltmembergttop-spyware-threatsltmembergt349 ltmembergttop-virusesltmembergt350 ltmembergttop-vulnerabilitiesltmembergt351 ltmembergtwildfire-file-digestsltmembergt352 ltmembergttop-websitesltmembergt353 ltmembergttop-url-categoriesltmembergt354 ltmembergttop-url-usersltmembergt355 ltmembergttop-url-user-behaviorltmembergt356 ltmembergttop-blocked-websitesltmembergt357 ltmembergttop-blocked-url-categoriesltmembergt358 ltmembergttop-blocked-url-usersltmembergt359 ltmembergttop-blocked-url-user-behaviorltmembergt360 ltmembergtblocked-credential-postltmembergt361 ltmembergtunknown-tcp-connectionsltmembergt362 ltmembergtunknown-udp-connectionsltmembergt363 ltmembergttop-denied-sourcesltmembergt364 ltmembergttop-denied-destinationsltmembergt365 ltmembergttop-denied-applicationsltmembergt366 ltmembergtrisky-usersltmembergt367 ltmembergtSaaS Application Usageltmembergt368 ltmembergtgtp-events-summaryltmembergt369 ltmembergtgtp-malicious-wildfire-submissionsltmembergt370 ltmembergtgtp-security-eventsltmembergt371 ltmembergtgtp-v1-causesltmembergt372 ltmembergtgtp-v2-causesltmembergt373 ltmembergtgtp-users-visiting-malicious-urlltmembergt374 ltmembergttop-gtp-attacker-destinationsltmembergt375 ltmembergttop-gtp-attacker-sourcesltmembergt376 ltmembergttop-gtp-victim-destinationsltmembergt

PAN-OS XML API Labs with pan-python

9

377 ltmembergttop-gtp-victim-sourcesltmembergt378 ltmembergtsctp-error-causesltmembergt379 ltmembergtsctp-events-summaryltmembergt380 ltmembergtsctp-security-eventsltmembergt381 ltdisable-predefined-reportsgt382 ltmanagementgt383 ltauto-mac-detectgtyesltauto-mac-detectgt384 ltsettinggt385 ltdeviceconfiggt386 ltvsysgt387 ltentry name=vsys1gt388 ltapplication gt389 ltapplication-group gt390 ltzonegt391 ltentry name=trustgt392 ltnetworkgt393 ltvirtual-wiregt394 ltmembergtethernet12ltmembergt395 ltvirtual-wiregt396 ltnetworkgt397 ltentrygt398 ltentry name=untrustgt399 ltnetworkgt400 ltvirtual-wiregt401 ltmembergtethernet11ltmembergt402 ltvirtual-wiregt403 ltnetworkgt404 ltentrygt405 ltzonegt406 ltservice gt407 ltservice-group gt408 ltschedule gt409 ltrulebasegt410 ltsecuritygt411 ltrulesgt412 ltentry name=rule2 uuid=031613c5-a691-4887-b284-5af2915e7c36gt413 lttogt414 ltmembergtuntrustltmembergt415 lttogt416 ltfromgt417 ltmembergttrustltmembergt418 ltfromgt419 ltsourcegt420 ltmembergtanyltmembergt421 ltsourcegt422 ltsource-usergt423 ltmembergtanyltmembergt424 ltsource-usergt425 ltcategorygt426 ltmembergtanyltmembergt427 ltcategorygt428 ltapplicationgt429 ltmembergtanyltmembergt430 ltapplicationgt431 ltservicegt432 ltmembergtapplication-defaultltmembergt433 ltservicegt434 lthip-profilesgt435 ltmembergtanyltmembergt436 lthip-profilesgt

PAN-OS XML API Labs with pan-python

10

437 ltactiongtdenyltactiongt438 ltdestinationgt439 ltmembergtgroup2ltmembergt440 ltdestinationgt441 ltentrygt442 ltentry name=rule1 uuid=c678a3fb-0e9b-45b7-aa4f-66a3e8864339gt443 lttogt444 ltmembergtuntrustltmembergt445 lttogt446 ltfromgt447 ltmembergttrustltmembergt448 ltfromgt449 ltsourcegt450 ltmembergtanyltmembergt451 ltsourcegt452 ltdestinationgt453 ltmembergtanyltmembergt454 ltdestinationgt455 ltsource-usergt456 ltmembergtanyltmembergt457 ltsource-usergt458 ltcategorygt459 ltmembergtanyltmembergt460 ltcategorygt461 ltapplicationgt462 ltmembergtanyltmembergt463 ltapplicationgt464 ltservicegt465 ltmembergtanyltmembergt466 ltservicegt467 lthip-profilesgt468 ltmembergtanyltmembergt469 lthip-profilesgt470 ltactiongtallowltactiongt471 ltentrygt472 ltrulesgt473 ltsecuritygt474 ltrulebasegt475 ltimportgt476 ltnetworkgt477 ltinterfacegt478 ltmembergtethernet11ltmembergt479 ltmembergtethernet12ltmembergt480 ltinterfacegt481 ltnetworkgt482 ltimportgt483 ltaddressgt484 ltentry name=addr1gt485 ltip-netmaskgt10001ltip-netmaskgt486 ltentrygt487 ltentry name=addr2gt488 ltip-netmaskgt10002ltip-netmaskgt489 ltentrygt490 ltentry name=addr3gt491 ltip-netmaskgt10003ltip-netmaskgt492 ltentrygt493 ltentry name=addr4gt494 ltip-netmaskgt10004ltip-netmaskgt495 ltentrygt496 ltentry name=addr5gt

PAN-OS XML API Labs with pan-python

11

497 ltip-netmaskgt10005ltip-netmaskgt498 ltentrygt499 ltaddressgt500 ltaddress-groupgt501 ltentry name=group1gt502 ltstaticgt503 ltmembergtaddr1ltmembergt504 ltmembergtaddr2ltmembergt505 ltmembergtaddr3ltmembergt506 ltstaticgt507 ltentrygt508 ltentry name=group2gt509 ltdynamicgt510 ltfiltergttag01 or tag02ltfiltergt511 ltdynamicgt512 ltentrygt513 ltaddress-groupgt514 ltuser-id-collectorgt515 ltsettinggt516 ltenable-mapping-timeoutgtyesltenable-mapping-timeoutgt517 ltip-user-mapping-timeoutgt45ltip-user-mapping-timeoutgt518 ltsettinggt519 ltuser-id-collectorgt520 ltdynamic-user-groupgt521 ltentry name=dug1gt522 ltfiltergttag01 or tag02ltfiltergt523 ltentrygt524 ltdynamic-user-groupgt525 ltentrygt526 ltvsysgt527 ltentrygt528 ltdevicesgt529 ltconfiggt

Introduction to the PAN-OS API

About the API

APIrsquos are very important to Palo Alto Networks Security automation is key to the success of any organization inpreventing cyber attacks So Palo Alto Networks products have comprehensive APIs to enable automation

In this lab wersquoll focus on the PAN-OS API which is the API for the Palo Alto Networks Next-generation Firewall andPanorama Management Center

When connecting to the PAN-OS API

bull Access the API on the management interface using HTTPS just as you would connect to the GUI

bull Connections to the API are treated as general web admin access They create a session just like you wereaccessing the GUI

bull Authentication requires an API key which is generated through an API call

Introduction to the PAN-OS API

12

Some examples of how you might use the PAN-OS API include but are not limited to

bull Read write verify and commit configuration

bull Download reports in XML format

bull Execute operational commands to check health and status

bull Collect logs and pcaps

bull Update dynamic address groups

bull Update user-id mappings

bull And much more

The API BrowserThe Next-generation Firewall and Panorama have an API Browser built in which allows you to explore the API andtrigger simple API calls in the browser itself

You can access the API Browser by adding api to the URL after the IP address of the firewall For example if yourfirewall is at 10001 the URL of the API Browser is https10001api

Lab exercise Try connecting to the API Browser on the firewall in your lab Explore a little to get familiar thencontinue with the lab

API Command TypesThere are several API types as shown in the main page of the API browser

API Types

API Type Description

keygen Generate an API Key (not shown in API Browser)

config Retrieve or modify the configuration

commit Commit the configuration

export Export files packet captures and keys

import Import files certificates response pages and branding

op Operational commands (like lsquoshowrsquo commands)

report Retrieve predefined dynamic and custom reports

user-id UserIP mappings and Dynamic Address Groups

This lab focuses on the following 5 types but the concepts needed to understand these 5 types are the sameconcepts for all the other types

bull keygen

bull config

bull commit

bull op

bull user-id

Introduction to the PAN-OS API

13

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 10: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

197 ltdh-groupgtgroup20ltdh-groupgt198 ltlifetimegt199 lthoursgt1lthoursgt200 ltlifetimegt201 ltentrygt202 ltipsec-crypto-profilesgt203 ltglobal-protect-app-crypto-profilesgt204 ltentry name=defaultgt205 ltencryptiongt206 ltmembergtaes-128-cbcltmembergt207 ltencryptiongt208 ltauthenticationgt209 ltmembergtsha1ltmembergt210 ltauthenticationgt211 ltentrygt212 ltglobal-protect-app-crypto-profilesgt213 ltcrypto-profilesgt214 ltikegt215 ltqosgt216 ltprofilegt217 ltentry name=defaultgt218 ltclass-bandwidth-typegt219 ltmbpsgt220 ltclassgt221 ltentry name=class1gt222 ltprioritygtreal-timeltprioritygt223 ltentrygt224 ltentry name=class2gt225 ltprioritygthighltprioritygt226 ltentrygt227 ltentry name=class3gt228 ltprioritygthighltprioritygt229 ltentrygt230 ltentry name=class4gt231 ltprioritygtmediumltprioritygt232 ltentrygt233 ltentry name=class5gt234 ltprioritygtmediumltprioritygt235 ltentrygt236 ltentry name=class6gt237 ltprioritygtlowltprioritygt238 ltentrygt239 ltentry name=class7gt240 ltprioritygtlowltprioritygt241 ltentrygt242 ltentry name=class8gt243 ltprioritygtlowltprioritygt244 ltentrygt245 ltclassgt246 ltmbpsgt247 ltclass-bandwidth-typegt248 ltentrygt249 ltprofilegt250 ltqosgt251 ltvirtual-routergt252 ltentry name=defaultgt253 ltprotocolgt254 ltbgpgt255 ltenablegtnoltenablegt256 ltdampening-profilegt

PAN-OS XML API Labs with pan-python

7

257 ltentry name=defaultgt258 ltcutoffgt125ltcutoffgt259 ltreusegt05ltreusegt260 ltmax-hold-timegt900ltmax-hold-timegt261 ltdecay-half-life-reachablegt300ltdecay-half-life-reachablegt262 ltdecay-half-life-unreachablegt900ltdecay-half-life-unreachablegt263 ltenablegtyesltenablegt264 ltentrygt265 ltdampening-profilegt266 ltbgpgt267 ltprotocolgt268 ltentrygt269 ltvirtual-routergt270 ltvirtual-wiregt271 ltentry name=default-vwiregt272 ltinterface1gtethernet11ltinterface1gt273 ltinterface2gtethernet12ltinterface2gt274 ltentrygt275 ltvirtual-wiregt276 ltnetworkgt277 ltdeviceconfiggt278 ltsystemgt279 lttypegt280 ltstatic gt281 lttypegt282 ltupdate-servergtupdatespaloaltonetworkscomltupdate-servergt283 ltupdate-schedule gt284 lttimezonegtUSPacificlttimezonegt285 ltservicegt286 ltdisable-telnetgtyesltdisable-telnetgt287 ltdisable-httpgtyesltdisable-httpgt288 ltservicegt289 lthostnamegtPA-VMlthostnamegt290 ltip-addressgt1921681103ltip-addressgt291 ltnetmaskgt2552552550ltnetmaskgt292 ltdefault-gatewaygt1921681254ltdefault-gatewaygt293 ltdns-settinggt294 ltserversgt295 ltprimarygt8888ltprimarygt296 ltserversgt297 ltdns-settinggt298 ltntp-serversgt299 ltprimary-ntp-servergt300 ltntp-server-addressgtuspoolntporgltntp-server-addressgt301 ltauthentication-typegt302 ltnone gt303 ltauthentication-typegt304 ltprimary-ntp-servergt305 ltsecondary-ntp-servergt306 ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt307 ltauthentication-typegt308 ltnone gt309 ltauthentication-typegt310 ltsecondary-ntp-servergt311 ltntp-serversgt312 ltsystemgt313 ltsettinggt314 ltconfiggt315 ltrematchgtyesltrematchgt316 ltconfiggt

PAN-OS XML API Labs with pan-python

8

317 ltmanagementgt318 lthostname-type-in-sysloggtFQDNlthostname-type-in-sysloggt319 ltdisable-predefined-reportsgt320 ltmembergtspyware-infected-hostsltmembergt321 ltmembergttop-application-categoriesltmembergt322 ltmembergttop-technology-categoriesltmembergt323 ltmembergtbandwidth-trendltmembergt324 ltmembergtrisk-trendltmembergt325 ltmembergtthreat-trendltmembergt326 ltmembergttop-usersltmembergt327 ltmembergttop-attacker-sourcesltmembergt328 ltmembergttop-attacker-destinationsltmembergt329 ltmembergttop-victim-sourcesltmembergt330 ltmembergttop-victim-destinationsltmembergt331 ltmembergttop-attackers-by-source-countriesltmembergt332 ltmembergttop-attackers-by-destination-countriesltmembergt333 ltmembergttop-victims-by-source-countriesltmembergt334 ltmembergttop-victims-by-destination-countriesltmembergt335 ltmembergttop-sourcesltmembergt336 ltmembergttop-destinationsltmembergt337 ltmembergttop-destination-countriesltmembergt338 ltmembergttop-source-countriesltmembergt339 ltmembergttop-connectionsltmembergt340 ltmembergttop-ingress-interfacesltmembergt341 ltmembergttop-egress-interfacesltmembergt342 ltmembergttop-ingress-zonesltmembergt343 ltmembergttop-egress-zonesltmembergt344 ltmembergttop-applicationsltmembergt345 ltmembergttop-http-applicationsltmembergt346 ltmembergttop-rulesltmembergt347 ltmembergttop-attacksltmembergt348 ltmembergttop-spyware-threatsltmembergt349 ltmembergttop-virusesltmembergt350 ltmembergttop-vulnerabilitiesltmembergt351 ltmembergtwildfire-file-digestsltmembergt352 ltmembergttop-websitesltmembergt353 ltmembergttop-url-categoriesltmembergt354 ltmembergttop-url-usersltmembergt355 ltmembergttop-url-user-behaviorltmembergt356 ltmembergttop-blocked-websitesltmembergt357 ltmembergttop-blocked-url-categoriesltmembergt358 ltmembergttop-blocked-url-usersltmembergt359 ltmembergttop-blocked-url-user-behaviorltmembergt360 ltmembergtblocked-credential-postltmembergt361 ltmembergtunknown-tcp-connectionsltmembergt362 ltmembergtunknown-udp-connectionsltmembergt363 ltmembergttop-denied-sourcesltmembergt364 ltmembergttop-denied-destinationsltmembergt365 ltmembergttop-denied-applicationsltmembergt366 ltmembergtrisky-usersltmembergt367 ltmembergtSaaS Application Usageltmembergt368 ltmembergtgtp-events-summaryltmembergt369 ltmembergtgtp-malicious-wildfire-submissionsltmembergt370 ltmembergtgtp-security-eventsltmembergt371 ltmembergtgtp-v1-causesltmembergt372 ltmembergtgtp-v2-causesltmembergt373 ltmembergtgtp-users-visiting-malicious-urlltmembergt374 ltmembergttop-gtp-attacker-destinationsltmembergt375 ltmembergttop-gtp-attacker-sourcesltmembergt376 ltmembergttop-gtp-victim-destinationsltmembergt

PAN-OS XML API Labs with pan-python

9

377 ltmembergttop-gtp-victim-sourcesltmembergt378 ltmembergtsctp-error-causesltmembergt379 ltmembergtsctp-events-summaryltmembergt380 ltmembergtsctp-security-eventsltmembergt381 ltdisable-predefined-reportsgt382 ltmanagementgt383 ltauto-mac-detectgtyesltauto-mac-detectgt384 ltsettinggt385 ltdeviceconfiggt386 ltvsysgt387 ltentry name=vsys1gt388 ltapplication gt389 ltapplication-group gt390 ltzonegt391 ltentry name=trustgt392 ltnetworkgt393 ltvirtual-wiregt394 ltmembergtethernet12ltmembergt395 ltvirtual-wiregt396 ltnetworkgt397 ltentrygt398 ltentry name=untrustgt399 ltnetworkgt400 ltvirtual-wiregt401 ltmembergtethernet11ltmembergt402 ltvirtual-wiregt403 ltnetworkgt404 ltentrygt405 ltzonegt406 ltservice gt407 ltservice-group gt408 ltschedule gt409 ltrulebasegt410 ltsecuritygt411 ltrulesgt412 ltentry name=rule2 uuid=031613c5-a691-4887-b284-5af2915e7c36gt413 lttogt414 ltmembergtuntrustltmembergt415 lttogt416 ltfromgt417 ltmembergttrustltmembergt418 ltfromgt419 ltsourcegt420 ltmembergtanyltmembergt421 ltsourcegt422 ltsource-usergt423 ltmembergtanyltmembergt424 ltsource-usergt425 ltcategorygt426 ltmembergtanyltmembergt427 ltcategorygt428 ltapplicationgt429 ltmembergtanyltmembergt430 ltapplicationgt431 ltservicegt432 ltmembergtapplication-defaultltmembergt433 ltservicegt434 lthip-profilesgt435 ltmembergtanyltmembergt436 lthip-profilesgt

PAN-OS XML API Labs with pan-python

10

437 ltactiongtdenyltactiongt438 ltdestinationgt439 ltmembergtgroup2ltmembergt440 ltdestinationgt441 ltentrygt442 ltentry name=rule1 uuid=c678a3fb-0e9b-45b7-aa4f-66a3e8864339gt443 lttogt444 ltmembergtuntrustltmembergt445 lttogt446 ltfromgt447 ltmembergttrustltmembergt448 ltfromgt449 ltsourcegt450 ltmembergtanyltmembergt451 ltsourcegt452 ltdestinationgt453 ltmembergtanyltmembergt454 ltdestinationgt455 ltsource-usergt456 ltmembergtanyltmembergt457 ltsource-usergt458 ltcategorygt459 ltmembergtanyltmembergt460 ltcategorygt461 ltapplicationgt462 ltmembergtanyltmembergt463 ltapplicationgt464 ltservicegt465 ltmembergtanyltmembergt466 ltservicegt467 lthip-profilesgt468 ltmembergtanyltmembergt469 lthip-profilesgt470 ltactiongtallowltactiongt471 ltentrygt472 ltrulesgt473 ltsecuritygt474 ltrulebasegt475 ltimportgt476 ltnetworkgt477 ltinterfacegt478 ltmembergtethernet11ltmembergt479 ltmembergtethernet12ltmembergt480 ltinterfacegt481 ltnetworkgt482 ltimportgt483 ltaddressgt484 ltentry name=addr1gt485 ltip-netmaskgt10001ltip-netmaskgt486 ltentrygt487 ltentry name=addr2gt488 ltip-netmaskgt10002ltip-netmaskgt489 ltentrygt490 ltentry name=addr3gt491 ltip-netmaskgt10003ltip-netmaskgt492 ltentrygt493 ltentry name=addr4gt494 ltip-netmaskgt10004ltip-netmaskgt495 ltentrygt496 ltentry name=addr5gt

PAN-OS XML API Labs with pan-python

11

497 ltip-netmaskgt10005ltip-netmaskgt498 ltentrygt499 ltaddressgt500 ltaddress-groupgt501 ltentry name=group1gt502 ltstaticgt503 ltmembergtaddr1ltmembergt504 ltmembergtaddr2ltmembergt505 ltmembergtaddr3ltmembergt506 ltstaticgt507 ltentrygt508 ltentry name=group2gt509 ltdynamicgt510 ltfiltergttag01 or tag02ltfiltergt511 ltdynamicgt512 ltentrygt513 ltaddress-groupgt514 ltuser-id-collectorgt515 ltsettinggt516 ltenable-mapping-timeoutgtyesltenable-mapping-timeoutgt517 ltip-user-mapping-timeoutgt45ltip-user-mapping-timeoutgt518 ltsettinggt519 ltuser-id-collectorgt520 ltdynamic-user-groupgt521 ltentry name=dug1gt522 ltfiltergttag01 or tag02ltfiltergt523 ltentrygt524 ltdynamic-user-groupgt525 ltentrygt526 ltvsysgt527 ltentrygt528 ltdevicesgt529 ltconfiggt

Introduction to the PAN-OS API

About the API

APIrsquos are very important to Palo Alto Networks Security automation is key to the success of any organization inpreventing cyber attacks So Palo Alto Networks products have comprehensive APIs to enable automation

In this lab wersquoll focus on the PAN-OS API which is the API for the Palo Alto Networks Next-generation Firewall andPanorama Management Center

When connecting to the PAN-OS API

bull Access the API on the management interface using HTTPS just as you would connect to the GUI

bull Connections to the API are treated as general web admin access They create a session just like you wereaccessing the GUI

bull Authentication requires an API key which is generated through an API call

Introduction to the PAN-OS API

12

Some examples of how you might use the PAN-OS API include but are not limited to

bull Read write verify and commit configuration

bull Download reports in XML format

bull Execute operational commands to check health and status

bull Collect logs and pcaps

bull Update dynamic address groups

bull Update user-id mappings

bull And much more

The API BrowserThe Next-generation Firewall and Panorama have an API Browser built in which allows you to explore the API andtrigger simple API calls in the browser itself

You can access the API Browser by adding api to the URL after the IP address of the firewall For example if yourfirewall is at 10001 the URL of the API Browser is https10001api

Lab exercise Try connecting to the API Browser on the firewall in your lab Explore a little to get familiar thencontinue with the lab

API Command TypesThere are several API types as shown in the main page of the API browser

API Types

API Type Description

keygen Generate an API Key (not shown in API Browser)

config Retrieve or modify the configuration

commit Commit the configuration

export Export files packet captures and keys

import Import files certificates response pages and branding

op Operational commands (like lsquoshowrsquo commands)

report Retrieve predefined dynamic and custom reports

user-id UserIP mappings and Dynamic Address Groups

This lab focuses on the following 5 types but the concepts needed to understand these 5 types are the sameconcepts for all the other types

bull keygen

bull config

bull commit

bull op

bull user-id

Introduction to the PAN-OS API

13

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 11: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

257 ltentry name=defaultgt258 ltcutoffgt125ltcutoffgt259 ltreusegt05ltreusegt260 ltmax-hold-timegt900ltmax-hold-timegt261 ltdecay-half-life-reachablegt300ltdecay-half-life-reachablegt262 ltdecay-half-life-unreachablegt900ltdecay-half-life-unreachablegt263 ltenablegtyesltenablegt264 ltentrygt265 ltdampening-profilegt266 ltbgpgt267 ltprotocolgt268 ltentrygt269 ltvirtual-routergt270 ltvirtual-wiregt271 ltentry name=default-vwiregt272 ltinterface1gtethernet11ltinterface1gt273 ltinterface2gtethernet12ltinterface2gt274 ltentrygt275 ltvirtual-wiregt276 ltnetworkgt277 ltdeviceconfiggt278 ltsystemgt279 lttypegt280 ltstatic gt281 lttypegt282 ltupdate-servergtupdatespaloaltonetworkscomltupdate-servergt283 ltupdate-schedule gt284 lttimezonegtUSPacificlttimezonegt285 ltservicegt286 ltdisable-telnetgtyesltdisable-telnetgt287 ltdisable-httpgtyesltdisable-httpgt288 ltservicegt289 lthostnamegtPA-VMlthostnamegt290 ltip-addressgt1921681103ltip-addressgt291 ltnetmaskgt2552552550ltnetmaskgt292 ltdefault-gatewaygt1921681254ltdefault-gatewaygt293 ltdns-settinggt294 ltserversgt295 ltprimarygt8888ltprimarygt296 ltserversgt297 ltdns-settinggt298 ltntp-serversgt299 ltprimary-ntp-servergt300 ltntp-server-addressgtuspoolntporgltntp-server-addressgt301 ltauthentication-typegt302 ltnone gt303 ltauthentication-typegt304 ltprimary-ntp-servergt305 ltsecondary-ntp-servergt306 ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt307 ltauthentication-typegt308 ltnone gt309 ltauthentication-typegt310 ltsecondary-ntp-servergt311 ltntp-serversgt312 ltsystemgt313 ltsettinggt314 ltconfiggt315 ltrematchgtyesltrematchgt316 ltconfiggt

PAN-OS XML API Labs with pan-python

8

317 ltmanagementgt318 lthostname-type-in-sysloggtFQDNlthostname-type-in-sysloggt319 ltdisable-predefined-reportsgt320 ltmembergtspyware-infected-hostsltmembergt321 ltmembergttop-application-categoriesltmembergt322 ltmembergttop-technology-categoriesltmembergt323 ltmembergtbandwidth-trendltmembergt324 ltmembergtrisk-trendltmembergt325 ltmembergtthreat-trendltmembergt326 ltmembergttop-usersltmembergt327 ltmembergttop-attacker-sourcesltmembergt328 ltmembergttop-attacker-destinationsltmembergt329 ltmembergttop-victim-sourcesltmembergt330 ltmembergttop-victim-destinationsltmembergt331 ltmembergttop-attackers-by-source-countriesltmembergt332 ltmembergttop-attackers-by-destination-countriesltmembergt333 ltmembergttop-victims-by-source-countriesltmembergt334 ltmembergttop-victims-by-destination-countriesltmembergt335 ltmembergttop-sourcesltmembergt336 ltmembergttop-destinationsltmembergt337 ltmembergttop-destination-countriesltmembergt338 ltmembergttop-source-countriesltmembergt339 ltmembergttop-connectionsltmembergt340 ltmembergttop-ingress-interfacesltmembergt341 ltmembergttop-egress-interfacesltmembergt342 ltmembergttop-ingress-zonesltmembergt343 ltmembergttop-egress-zonesltmembergt344 ltmembergttop-applicationsltmembergt345 ltmembergttop-http-applicationsltmembergt346 ltmembergttop-rulesltmembergt347 ltmembergttop-attacksltmembergt348 ltmembergttop-spyware-threatsltmembergt349 ltmembergttop-virusesltmembergt350 ltmembergttop-vulnerabilitiesltmembergt351 ltmembergtwildfire-file-digestsltmembergt352 ltmembergttop-websitesltmembergt353 ltmembergttop-url-categoriesltmembergt354 ltmembergttop-url-usersltmembergt355 ltmembergttop-url-user-behaviorltmembergt356 ltmembergttop-blocked-websitesltmembergt357 ltmembergttop-blocked-url-categoriesltmembergt358 ltmembergttop-blocked-url-usersltmembergt359 ltmembergttop-blocked-url-user-behaviorltmembergt360 ltmembergtblocked-credential-postltmembergt361 ltmembergtunknown-tcp-connectionsltmembergt362 ltmembergtunknown-udp-connectionsltmembergt363 ltmembergttop-denied-sourcesltmembergt364 ltmembergttop-denied-destinationsltmembergt365 ltmembergttop-denied-applicationsltmembergt366 ltmembergtrisky-usersltmembergt367 ltmembergtSaaS Application Usageltmembergt368 ltmembergtgtp-events-summaryltmembergt369 ltmembergtgtp-malicious-wildfire-submissionsltmembergt370 ltmembergtgtp-security-eventsltmembergt371 ltmembergtgtp-v1-causesltmembergt372 ltmembergtgtp-v2-causesltmembergt373 ltmembergtgtp-users-visiting-malicious-urlltmembergt374 ltmembergttop-gtp-attacker-destinationsltmembergt375 ltmembergttop-gtp-attacker-sourcesltmembergt376 ltmembergttop-gtp-victim-destinationsltmembergt

PAN-OS XML API Labs with pan-python

9

377 ltmembergttop-gtp-victim-sourcesltmembergt378 ltmembergtsctp-error-causesltmembergt379 ltmembergtsctp-events-summaryltmembergt380 ltmembergtsctp-security-eventsltmembergt381 ltdisable-predefined-reportsgt382 ltmanagementgt383 ltauto-mac-detectgtyesltauto-mac-detectgt384 ltsettinggt385 ltdeviceconfiggt386 ltvsysgt387 ltentry name=vsys1gt388 ltapplication gt389 ltapplication-group gt390 ltzonegt391 ltentry name=trustgt392 ltnetworkgt393 ltvirtual-wiregt394 ltmembergtethernet12ltmembergt395 ltvirtual-wiregt396 ltnetworkgt397 ltentrygt398 ltentry name=untrustgt399 ltnetworkgt400 ltvirtual-wiregt401 ltmembergtethernet11ltmembergt402 ltvirtual-wiregt403 ltnetworkgt404 ltentrygt405 ltzonegt406 ltservice gt407 ltservice-group gt408 ltschedule gt409 ltrulebasegt410 ltsecuritygt411 ltrulesgt412 ltentry name=rule2 uuid=031613c5-a691-4887-b284-5af2915e7c36gt413 lttogt414 ltmembergtuntrustltmembergt415 lttogt416 ltfromgt417 ltmembergttrustltmembergt418 ltfromgt419 ltsourcegt420 ltmembergtanyltmembergt421 ltsourcegt422 ltsource-usergt423 ltmembergtanyltmembergt424 ltsource-usergt425 ltcategorygt426 ltmembergtanyltmembergt427 ltcategorygt428 ltapplicationgt429 ltmembergtanyltmembergt430 ltapplicationgt431 ltservicegt432 ltmembergtapplication-defaultltmembergt433 ltservicegt434 lthip-profilesgt435 ltmembergtanyltmembergt436 lthip-profilesgt

PAN-OS XML API Labs with pan-python

10

437 ltactiongtdenyltactiongt438 ltdestinationgt439 ltmembergtgroup2ltmembergt440 ltdestinationgt441 ltentrygt442 ltentry name=rule1 uuid=c678a3fb-0e9b-45b7-aa4f-66a3e8864339gt443 lttogt444 ltmembergtuntrustltmembergt445 lttogt446 ltfromgt447 ltmembergttrustltmembergt448 ltfromgt449 ltsourcegt450 ltmembergtanyltmembergt451 ltsourcegt452 ltdestinationgt453 ltmembergtanyltmembergt454 ltdestinationgt455 ltsource-usergt456 ltmembergtanyltmembergt457 ltsource-usergt458 ltcategorygt459 ltmembergtanyltmembergt460 ltcategorygt461 ltapplicationgt462 ltmembergtanyltmembergt463 ltapplicationgt464 ltservicegt465 ltmembergtanyltmembergt466 ltservicegt467 lthip-profilesgt468 ltmembergtanyltmembergt469 lthip-profilesgt470 ltactiongtallowltactiongt471 ltentrygt472 ltrulesgt473 ltsecuritygt474 ltrulebasegt475 ltimportgt476 ltnetworkgt477 ltinterfacegt478 ltmembergtethernet11ltmembergt479 ltmembergtethernet12ltmembergt480 ltinterfacegt481 ltnetworkgt482 ltimportgt483 ltaddressgt484 ltentry name=addr1gt485 ltip-netmaskgt10001ltip-netmaskgt486 ltentrygt487 ltentry name=addr2gt488 ltip-netmaskgt10002ltip-netmaskgt489 ltentrygt490 ltentry name=addr3gt491 ltip-netmaskgt10003ltip-netmaskgt492 ltentrygt493 ltentry name=addr4gt494 ltip-netmaskgt10004ltip-netmaskgt495 ltentrygt496 ltentry name=addr5gt

PAN-OS XML API Labs with pan-python

11

497 ltip-netmaskgt10005ltip-netmaskgt498 ltentrygt499 ltaddressgt500 ltaddress-groupgt501 ltentry name=group1gt502 ltstaticgt503 ltmembergtaddr1ltmembergt504 ltmembergtaddr2ltmembergt505 ltmembergtaddr3ltmembergt506 ltstaticgt507 ltentrygt508 ltentry name=group2gt509 ltdynamicgt510 ltfiltergttag01 or tag02ltfiltergt511 ltdynamicgt512 ltentrygt513 ltaddress-groupgt514 ltuser-id-collectorgt515 ltsettinggt516 ltenable-mapping-timeoutgtyesltenable-mapping-timeoutgt517 ltip-user-mapping-timeoutgt45ltip-user-mapping-timeoutgt518 ltsettinggt519 ltuser-id-collectorgt520 ltdynamic-user-groupgt521 ltentry name=dug1gt522 ltfiltergttag01 or tag02ltfiltergt523 ltentrygt524 ltdynamic-user-groupgt525 ltentrygt526 ltvsysgt527 ltentrygt528 ltdevicesgt529 ltconfiggt

Introduction to the PAN-OS API

About the API

APIrsquos are very important to Palo Alto Networks Security automation is key to the success of any organization inpreventing cyber attacks So Palo Alto Networks products have comprehensive APIs to enable automation

In this lab wersquoll focus on the PAN-OS API which is the API for the Palo Alto Networks Next-generation Firewall andPanorama Management Center

When connecting to the PAN-OS API

bull Access the API on the management interface using HTTPS just as you would connect to the GUI

bull Connections to the API are treated as general web admin access They create a session just like you wereaccessing the GUI

bull Authentication requires an API key which is generated through an API call

Introduction to the PAN-OS API

12

Some examples of how you might use the PAN-OS API include but are not limited to

bull Read write verify and commit configuration

bull Download reports in XML format

bull Execute operational commands to check health and status

bull Collect logs and pcaps

bull Update dynamic address groups

bull Update user-id mappings

bull And much more

The API BrowserThe Next-generation Firewall and Panorama have an API Browser built in which allows you to explore the API andtrigger simple API calls in the browser itself

You can access the API Browser by adding api to the URL after the IP address of the firewall For example if yourfirewall is at 10001 the URL of the API Browser is https10001api

Lab exercise Try connecting to the API Browser on the firewall in your lab Explore a little to get familiar thencontinue with the lab

API Command TypesThere are several API types as shown in the main page of the API browser

API Types

API Type Description

keygen Generate an API Key (not shown in API Browser)

config Retrieve or modify the configuration

commit Commit the configuration

export Export files packet captures and keys

import Import files certificates response pages and branding

op Operational commands (like lsquoshowrsquo commands)

report Retrieve predefined dynamic and custom reports

user-id UserIP mappings and Dynamic Address Groups

This lab focuses on the following 5 types but the concepts needed to understand these 5 types are the sameconcepts for all the other types

bull keygen

bull config

bull commit

bull op

bull user-id

Introduction to the PAN-OS API

13

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 12: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

317 ltmanagementgt318 lthostname-type-in-sysloggtFQDNlthostname-type-in-sysloggt319 ltdisable-predefined-reportsgt320 ltmembergtspyware-infected-hostsltmembergt321 ltmembergttop-application-categoriesltmembergt322 ltmembergttop-technology-categoriesltmembergt323 ltmembergtbandwidth-trendltmembergt324 ltmembergtrisk-trendltmembergt325 ltmembergtthreat-trendltmembergt326 ltmembergttop-usersltmembergt327 ltmembergttop-attacker-sourcesltmembergt328 ltmembergttop-attacker-destinationsltmembergt329 ltmembergttop-victim-sourcesltmembergt330 ltmembergttop-victim-destinationsltmembergt331 ltmembergttop-attackers-by-source-countriesltmembergt332 ltmembergttop-attackers-by-destination-countriesltmembergt333 ltmembergttop-victims-by-source-countriesltmembergt334 ltmembergttop-victims-by-destination-countriesltmembergt335 ltmembergttop-sourcesltmembergt336 ltmembergttop-destinationsltmembergt337 ltmembergttop-destination-countriesltmembergt338 ltmembergttop-source-countriesltmembergt339 ltmembergttop-connectionsltmembergt340 ltmembergttop-ingress-interfacesltmembergt341 ltmembergttop-egress-interfacesltmembergt342 ltmembergttop-ingress-zonesltmembergt343 ltmembergttop-egress-zonesltmembergt344 ltmembergttop-applicationsltmembergt345 ltmembergttop-http-applicationsltmembergt346 ltmembergttop-rulesltmembergt347 ltmembergttop-attacksltmembergt348 ltmembergttop-spyware-threatsltmembergt349 ltmembergttop-virusesltmembergt350 ltmembergttop-vulnerabilitiesltmembergt351 ltmembergtwildfire-file-digestsltmembergt352 ltmembergttop-websitesltmembergt353 ltmembergttop-url-categoriesltmembergt354 ltmembergttop-url-usersltmembergt355 ltmembergttop-url-user-behaviorltmembergt356 ltmembergttop-blocked-websitesltmembergt357 ltmembergttop-blocked-url-categoriesltmembergt358 ltmembergttop-blocked-url-usersltmembergt359 ltmembergttop-blocked-url-user-behaviorltmembergt360 ltmembergtblocked-credential-postltmembergt361 ltmembergtunknown-tcp-connectionsltmembergt362 ltmembergtunknown-udp-connectionsltmembergt363 ltmembergttop-denied-sourcesltmembergt364 ltmembergttop-denied-destinationsltmembergt365 ltmembergttop-denied-applicationsltmembergt366 ltmembergtrisky-usersltmembergt367 ltmembergtSaaS Application Usageltmembergt368 ltmembergtgtp-events-summaryltmembergt369 ltmembergtgtp-malicious-wildfire-submissionsltmembergt370 ltmembergtgtp-security-eventsltmembergt371 ltmembergtgtp-v1-causesltmembergt372 ltmembergtgtp-v2-causesltmembergt373 ltmembergtgtp-users-visiting-malicious-urlltmembergt374 ltmembergttop-gtp-attacker-destinationsltmembergt375 ltmembergttop-gtp-attacker-sourcesltmembergt376 ltmembergttop-gtp-victim-destinationsltmembergt

PAN-OS XML API Labs with pan-python

9

377 ltmembergttop-gtp-victim-sourcesltmembergt378 ltmembergtsctp-error-causesltmembergt379 ltmembergtsctp-events-summaryltmembergt380 ltmembergtsctp-security-eventsltmembergt381 ltdisable-predefined-reportsgt382 ltmanagementgt383 ltauto-mac-detectgtyesltauto-mac-detectgt384 ltsettinggt385 ltdeviceconfiggt386 ltvsysgt387 ltentry name=vsys1gt388 ltapplication gt389 ltapplication-group gt390 ltzonegt391 ltentry name=trustgt392 ltnetworkgt393 ltvirtual-wiregt394 ltmembergtethernet12ltmembergt395 ltvirtual-wiregt396 ltnetworkgt397 ltentrygt398 ltentry name=untrustgt399 ltnetworkgt400 ltvirtual-wiregt401 ltmembergtethernet11ltmembergt402 ltvirtual-wiregt403 ltnetworkgt404 ltentrygt405 ltzonegt406 ltservice gt407 ltservice-group gt408 ltschedule gt409 ltrulebasegt410 ltsecuritygt411 ltrulesgt412 ltentry name=rule2 uuid=031613c5-a691-4887-b284-5af2915e7c36gt413 lttogt414 ltmembergtuntrustltmembergt415 lttogt416 ltfromgt417 ltmembergttrustltmembergt418 ltfromgt419 ltsourcegt420 ltmembergtanyltmembergt421 ltsourcegt422 ltsource-usergt423 ltmembergtanyltmembergt424 ltsource-usergt425 ltcategorygt426 ltmembergtanyltmembergt427 ltcategorygt428 ltapplicationgt429 ltmembergtanyltmembergt430 ltapplicationgt431 ltservicegt432 ltmembergtapplication-defaultltmembergt433 ltservicegt434 lthip-profilesgt435 ltmembergtanyltmembergt436 lthip-profilesgt

PAN-OS XML API Labs with pan-python

10

437 ltactiongtdenyltactiongt438 ltdestinationgt439 ltmembergtgroup2ltmembergt440 ltdestinationgt441 ltentrygt442 ltentry name=rule1 uuid=c678a3fb-0e9b-45b7-aa4f-66a3e8864339gt443 lttogt444 ltmembergtuntrustltmembergt445 lttogt446 ltfromgt447 ltmembergttrustltmembergt448 ltfromgt449 ltsourcegt450 ltmembergtanyltmembergt451 ltsourcegt452 ltdestinationgt453 ltmembergtanyltmembergt454 ltdestinationgt455 ltsource-usergt456 ltmembergtanyltmembergt457 ltsource-usergt458 ltcategorygt459 ltmembergtanyltmembergt460 ltcategorygt461 ltapplicationgt462 ltmembergtanyltmembergt463 ltapplicationgt464 ltservicegt465 ltmembergtanyltmembergt466 ltservicegt467 lthip-profilesgt468 ltmembergtanyltmembergt469 lthip-profilesgt470 ltactiongtallowltactiongt471 ltentrygt472 ltrulesgt473 ltsecuritygt474 ltrulebasegt475 ltimportgt476 ltnetworkgt477 ltinterfacegt478 ltmembergtethernet11ltmembergt479 ltmembergtethernet12ltmembergt480 ltinterfacegt481 ltnetworkgt482 ltimportgt483 ltaddressgt484 ltentry name=addr1gt485 ltip-netmaskgt10001ltip-netmaskgt486 ltentrygt487 ltentry name=addr2gt488 ltip-netmaskgt10002ltip-netmaskgt489 ltentrygt490 ltentry name=addr3gt491 ltip-netmaskgt10003ltip-netmaskgt492 ltentrygt493 ltentry name=addr4gt494 ltip-netmaskgt10004ltip-netmaskgt495 ltentrygt496 ltentry name=addr5gt

PAN-OS XML API Labs with pan-python

11

497 ltip-netmaskgt10005ltip-netmaskgt498 ltentrygt499 ltaddressgt500 ltaddress-groupgt501 ltentry name=group1gt502 ltstaticgt503 ltmembergtaddr1ltmembergt504 ltmembergtaddr2ltmembergt505 ltmembergtaddr3ltmembergt506 ltstaticgt507 ltentrygt508 ltentry name=group2gt509 ltdynamicgt510 ltfiltergttag01 or tag02ltfiltergt511 ltdynamicgt512 ltentrygt513 ltaddress-groupgt514 ltuser-id-collectorgt515 ltsettinggt516 ltenable-mapping-timeoutgtyesltenable-mapping-timeoutgt517 ltip-user-mapping-timeoutgt45ltip-user-mapping-timeoutgt518 ltsettinggt519 ltuser-id-collectorgt520 ltdynamic-user-groupgt521 ltentry name=dug1gt522 ltfiltergttag01 or tag02ltfiltergt523 ltentrygt524 ltdynamic-user-groupgt525 ltentrygt526 ltvsysgt527 ltentrygt528 ltdevicesgt529 ltconfiggt

Introduction to the PAN-OS API

About the API

APIrsquos are very important to Palo Alto Networks Security automation is key to the success of any organization inpreventing cyber attacks So Palo Alto Networks products have comprehensive APIs to enable automation

In this lab wersquoll focus on the PAN-OS API which is the API for the Palo Alto Networks Next-generation Firewall andPanorama Management Center

When connecting to the PAN-OS API

bull Access the API on the management interface using HTTPS just as you would connect to the GUI

bull Connections to the API are treated as general web admin access They create a session just like you wereaccessing the GUI

bull Authentication requires an API key which is generated through an API call

Introduction to the PAN-OS API

12

Some examples of how you might use the PAN-OS API include but are not limited to

bull Read write verify and commit configuration

bull Download reports in XML format

bull Execute operational commands to check health and status

bull Collect logs and pcaps

bull Update dynamic address groups

bull Update user-id mappings

bull And much more

The API BrowserThe Next-generation Firewall and Panorama have an API Browser built in which allows you to explore the API andtrigger simple API calls in the browser itself

You can access the API Browser by adding api to the URL after the IP address of the firewall For example if yourfirewall is at 10001 the URL of the API Browser is https10001api

Lab exercise Try connecting to the API Browser on the firewall in your lab Explore a little to get familiar thencontinue with the lab

API Command TypesThere are several API types as shown in the main page of the API browser

API Types

API Type Description

keygen Generate an API Key (not shown in API Browser)

config Retrieve or modify the configuration

commit Commit the configuration

export Export files packet captures and keys

import Import files certificates response pages and branding

op Operational commands (like lsquoshowrsquo commands)

report Retrieve predefined dynamic and custom reports

user-id UserIP mappings and Dynamic Address Groups

This lab focuses on the following 5 types but the concepts needed to understand these 5 types are the sameconcepts for all the other types

bull keygen

bull config

bull commit

bull op

bull user-id

Introduction to the PAN-OS API

13

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 13: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

377 ltmembergttop-gtp-victim-sourcesltmembergt378 ltmembergtsctp-error-causesltmembergt379 ltmembergtsctp-events-summaryltmembergt380 ltmembergtsctp-security-eventsltmembergt381 ltdisable-predefined-reportsgt382 ltmanagementgt383 ltauto-mac-detectgtyesltauto-mac-detectgt384 ltsettinggt385 ltdeviceconfiggt386 ltvsysgt387 ltentry name=vsys1gt388 ltapplication gt389 ltapplication-group gt390 ltzonegt391 ltentry name=trustgt392 ltnetworkgt393 ltvirtual-wiregt394 ltmembergtethernet12ltmembergt395 ltvirtual-wiregt396 ltnetworkgt397 ltentrygt398 ltentry name=untrustgt399 ltnetworkgt400 ltvirtual-wiregt401 ltmembergtethernet11ltmembergt402 ltvirtual-wiregt403 ltnetworkgt404 ltentrygt405 ltzonegt406 ltservice gt407 ltservice-group gt408 ltschedule gt409 ltrulebasegt410 ltsecuritygt411 ltrulesgt412 ltentry name=rule2 uuid=031613c5-a691-4887-b284-5af2915e7c36gt413 lttogt414 ltmembergtuntrustltmembergt415 lttogt416 ltfromgt417 ltmembergttrustltmembergt418 ltfromgt419 ltsourcegt420 ltmembergtanyltmembergt421 ltsourcegt422 ltsource-usergt423 ltmembergtanyltmembergt424 ltsource-usergt425 ltcategorygt426 ltmembergtanyltmembergt427 ltcategorygt428 ltapplicationgt429 ltmembergtanyltmembergt430 ltapplicationgt431 ltservicegt432 ltmembergtapplication-defaultltmembergt433 ltservicegt434 lthip-profilesgt435 ltmembergtanyltmembergt436 lthip-profilesgt

PAN-OS XML API Labs with pan-python

10

437 ltactiongtdenyltactiongt438 ltdestinationgt439 ltmembergtgroup2ltmembergt440 ltdestinationgt441 ltentrygt442 ltentry name=rule1 uuid=c678a3fb-0e9b-45b7-aa4f-66a3e8864339gt443 lttogt444 ltmembergtuntrustltmembergt445 lttogt446 ltfromgt447 ltmembergttrustltmembergt448 ltfromgt449 ltsourcegt450 ltmembergtanyltmembergt451 ltsourcegt452 ltdestinationgt453 ltmembergtanyltmembergt454 ltdestinationgt455 ltsource-usergt456 ltmembergtanyltmembergt457 ltsource-usergt458 ltcategorygt459 ltmembergtanyltmembergt460 ltcategorygt461 ltapplicationgt462 ltmembergtanyltmembergt463 ltapplicationgt464 ltservicegt465 ltmembergtanyltmembergt466 ltservicegt467 lthip-profilesgt468 ltmembergtanyltmembergt469 lthip-profilesgt470 ltactiongtallowltactiongt471 ltentrygt472 ltrulesgt473 ltsecuritygt474 ltrulebasegt475 ltimportgt476 ltnetworkgt477 ltinterfacegt478 ltmembergtethernet11ltmembergt479 ltmembergtethernet12ltmembergt480 ltinterfacegt481 ltnetworkgt482 ltimportgt483 ltaddressgt484 ltentry name=addr1gt485 ltip-netmaskgt10001ltip-netmaskgt486 ltentrygt487 ltentry name=addr2gt488 ltip-netmaskgt10002ltip-netmaskgt489 ltentrygt490 ltentry name=addr3gt491 ltip-netmaskgt10003ltip-netmaskgt492 ltentrygt493 ltentry name=addr4gt494 ltip-netmaskgt10004ltip-netmaskgt495 ltentrygt496 ltentry name=addr5gt

PAN-OS XML API Labs with pan-python

11

497 ltip-netmaskgt10005ltip-netmaskgt498 ltentrygt499 ltaddressgt500 ltaddress-groupgt501 ltentry name=group1gt502 ltstaticgt503 ltmembergtaddr1ltmembergt504 ltmembergtaddr2ltmembergt505 ltmembergtaddr3ltmembergt506 ltstaticgt507 ltentrygt508 ltentry name=group2gt509 ltdynamicgt510 ltfiltergttag01 or tag02ltfiltergt511 ltdynamicgt512 ltentrygt513 ltaddress-groupgt514 ltuser-id-collectorgt515 ltsettinggt516 ltenable-mapping-timeoutgtyesltenable-mapping-timeoutgt517 ltip-user-mapping-timeoutgt45ltip-user-mapping-timeoutgt518 ltsettinggt519 ltuser-id-collectorgt520 ltdynamic-user-groupgt521 ltentry name=dug1gt522 ltfiltergttag01 or tag02ltfiltergt523 ltentrygt524 ltdynamic-user-groupgt525 ltentrygt526 ltvsysgt527 ltentrygt528 ltdevicesgt529 ltconfiggt

Introduction to the PAN-OS API

About the API

APIrsquos are very important to Palo Alto Networks Security automation is key to the success of any organization inpreventing cyber attacks So Palo Alto Networks products have comprehensive APIs to enable automation

In this lab wersquoll focus on the PAN-OS API which is the API for the Palo Alto Networks Next-generation Firewall andPanorama Management Center

When connecting to the PAN-OS API

bull Access the API on the management interface using HTTPS just as you would connect to the GUI

bull Connections to the API are treated as general web admin access They create a session just like you wereaccessing the GUI

bull Authentication requires an API key which is generated through an API call

Introduction to the PAN-OS API

12

Some examples of how you might use the PAN-OS API include but are not limited to

bull Read write verify and commit configuration

bull Download reports in XML format

bull Execute operational commands to check health and status

bull Collect logs and pcaps

bull Update dynamic address groups

bull Update user-id mappings

bull And much more

The API BrowserThe Next-generation Firewall and Panorama have an API Browser built in which allows you to explore the API andtrigger simple API calls in the browser itself

You can access the API Browser by adding api to the URL after the IP address of the firewall For example if yourfirewall is at 10001 the URL of the API Browser is https10001api

Lab exercise Try connecting to the API Browser on the firewall in your lab Explore a little to get familiar thencontinue with the lab

API Command TypesThere are several API types as shown in the main page of the API browser

API Types

API Type Description

keygen Generate an API Key (not shown in API Browser)

config Retrieve or modify the configuration

commit Commit the configuration

export Export files packet captures and keys

import Import files certificates response pages and branding

op Operational commands (like lsquoshowrsquo commands)

report Retrieve predefined dynamic and custom reports

user-id UserIP mappings and Dynamic Address Groups

This lab focuses on the following 5 types but the concepts needed to understand these 5 types are the sameconcepts for all the other types

bull keygen

bull config

bull commit

bull op

bull user-id

Introduction to the PAN-OS API

13

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 14: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

437 ltactiongtdenyltactiongt438 ltdestinationgt439 ltmembergtgroup2ltmembergt440 ltdestinationgt441 ltentrygt442 ltentry name=rule1 uuid=c678a3fb-0e9b-45b7-aa4f-66a3e8864339gt443 lttogt444 ltmembergtuntrustltmembergt445 lttogt446 ltfromgt447 ltmembergttrustltmembergt448 ltfromgt449 ltsourcegt450 ltmembergtanyltmembergt451 ltsourcegt452 ltdestinationgt453 ltmembergtanyltmembergt454 ltdestinationgt455 ltsource-usergt456 ltmembergtanyltmembergt457 ltsource-usergt458 ltcategorygt459 ltmembergtanyltmembergt460 ltcategorygt461 ltapplicationgt462 ltmembergtanyltmembergt463 ltapplicationgt464 ltservicegt465 ltmembergtanyltmembergt466 ltservicegt467 lthip-profilesgt468 ltmembergtanyltmembergt469 lthip-profilesgt470 ltactiongtallowltactiongt471 ltentrygt472 ltrulesgt473 ltsecuritygt474 ltrulebasegt475 ltimportgt476 ltnetworkgt477 ltinterfacegt478 ltmembergtethernet11ltmembergt479 ltmembergtethernet12ltmembergt480 ltinterfacegt481 ltnetworkgt482 ltimportgt483 ltaddressgt484 ltentry name=addr1gt485 ltip-netmaskgt10001ltip-netmaskgt486 ltentrygt487 ltentry name=addr2gt488 ltip-netmaskgt10002ltip-netmaskgt489 ltentrygt490 ltentry name=addr3gt491 ltip-netmaskgt10003ltip-netmaskgt492 ltentrygt493 ltentry name=addr4gt494 ltip-netmaskgt10004ltip-netmaskgt495 ltentrygt496 ltentry name=addr5gt

PAN-OS XML API Labs with pan-python

11

497 ltip-netmaskgt10005ltip-netmaskgt498 ltentrygt499 ltaddressgt500 ltaddress-groupgt501 ltentry name=group1gt502 ltstaticgt503 ltmembergtaddr1ltmembergt504 ltmembergtaddr2ltmembergt505 ltmembergtaddr3ltmembergt506 ltstaticgt507 ltentrygt508 ltentry name=group2gt509 ltdynamicgt510 ltfiltergttag01 or tag02ltfiltergt511 ltdynamicgt512 ltentrygt513 ltaddress-groupgt514 ltuser-id-collectorgt515 ltsettinggt516 ltenable-mapping-timeoutgtyesltenable-mapping-timeoutgt517 ltip-user-mapping-timeoutgt45ltip-user-mapping-timeoutgt518 ltsettinggt519 ltuser-id-collectorgt520 ltdynamic-user-groupgt521 ltentry name=dug1gt522 ltfiltergttag01 or tag02ltfiltergt523 ltentrygt524 ltdynamic-user-groupgt525 ltentrygt526 ltvsysgt527 ltentrygt528 ltdevicesgt529 ltconfiggt

Introduction to the PAN-OS API

About the API

APIrsquos are very important to Palo Alto Networks Security automation is key to the success of any organization inpreventing cyber attacks So Palo Alto Networks products have comprehensive APIs to enable automation

In this lab wersquoll focus on the PAN-OS API which is the API for the Palo Alto Networks Next-generation Firewall andPanorama Management Center

When connecting to the PAN-OS API

bull Access the API on the management interface using HTTPS just as you would connect to the GUI

bull Connections to the API are treated as general web admin access They create a session just like you wereaccessing the GUI

bull Authentication requires an API key which is generated through an API call

Introduction to the PAN-OS API

12

Some examples of how you might use the PAN-OS API include but are not limited to

bull Read write verify and commit configuration

bull Download reports in XML format

bull Execute operational commands to check health and status

bull Collect logs and pcaps

bull Update dynamic address groups

bull Update user-id mappings

bull And much more

The API BrowserThe Next-generation Firewall and Panorama have an API Browser built in which allows you to explore the API andtrigger simple API calls in the browser itself

You can access the API Browser by adding api to the URL after the IP address of the firewall For example if yourfirewall is at 10001 the URL of the API Browser is https10001api

Lab exercise Try connecting to the API Browser on the firewall in your lab Explore a little to get familiar thencontinue with the lab

API Command TypesThere are several API types as shown in the main page of the API browser

API Types

API Type Description

keygen Generate an API Key (not shown in API Browser)

config Retrieve or modify the configuration

commit Commit the configuration

export Export files packet captures and keys

import Import files certificates response pages and branding

op Operational commands (like lsquoshowrsquo commands)

report Retrieve predefined dynamic and custom reports

user-id UserIP mappings and Dynamic Address Groups

This lab focuses on the following 5 types but the concepts needed to understand these 5 types are the sameconcepts for all the other types

bull keygen

bull config

bull commit

bull op

bull user-id

Introduction to the PAN-OS API

13

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 15: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

497 ltip-netmaskgt10005ltip-netmaskgt498 ltentrygt499 ltaddressgt500 ltaddress-groupgt501 ltentry name=group1gt502 ltstaticgt503 ltmembergtaddr1ltmembergt504 ltmembergtaddr2ltmembergt505 ltmembergtaddr3ltmembergt506 ltstaticgt507 ltentrygt508 ltentry name=group2gt509 ltdynamicgt510 ltfiltergttag01 or tag02ltfiltergt511 ltdynamicgt512 ltentrygt513 ltaddress-groupgt514 ltuser-id-collectorgt515 ltsettinggt516 ltenable-mapping-timeoutgtyesltenable-mapping-timeoutgt517 ltip-user-mapping-timeoutgt45ltip-user-mapping-timeoutgt518 ltsettinggt519 ltuser-id-collectorgt520 ltdynamic-user-groupgt521 ltentry name=dug1gt522 ltfiltergttag01 or tag02ltfiltergt523 ltentrygt524 ltdynamic-user-groupgt525 ltentrygt526 ltvsysgt527 ltentrygt528 ltdevicesgt529 ltconfiggt

Introduction to the PAN-OS API

About the API

APIrsquos are very important to Palo Alto Networks Security automation is key to the success of any organization inpreventing cyber attacks So Palo Alto Networks products have comprehensive APIs to enable automation

In this lab wersquoll focus on the PAN-OS API which is the API for the Palo Alto Networks Next-generation Firewall andPanorama Management Center

When connecting to the PAN-OS API

bull Access the API on the management interface using HTTPS just as you would connect to the GUI

bull Connections to the API are treated as general web admin access They create a session just like you wereaccessing the GUI

bull Authentication requires an API key which is generated through an API call

Introduction to the PAN-OS API

12

Some examples of how you might use the PAN-OS API include but are not limited to

bull Read write verify and commit configuration

bull Download reports in XML format

bull Execute operational commands to check health and status

bull Collect logs and pcaps

bull Update dynamic address groups

bull Update user-id mappings

bull And much more

The API BrowserThe Next-generation Firewall and Panorama have an API Browser built in which allows you to explore the API andtrigger simple API calls in the browser itself

You can access the API Browser by adding api to the URL after the IP address of the firewall For example if yourfirewall is at 10001 the URL of the API Browser is https10001api

Lab exercise Try connecting to the API Browser on the firewall in your lab Explore a little to get familiar thencontinue with the lab

API Command TypesThere are several API types as shown in the main page of the API browser

API Types

API Type Description

keygen Generate an API Key (not shown in API Browser)

config Retrieve or modify the configuration

commit Commit the configuration

export Export files packet captures and keys

import Import files certificates response pages and branding

op Operational commands (like lsquoshowrsquo commands)

report Retrieve predefined dynamic and custom reports

user-id UserIP mappings and Dynamic Address Groups

This lab focuses on the following 5 types but the concepts needed to understand these 5 types are the sameconcepts for all the other types

bull keygen

bull config

bull commit

bull op

bull user-id

Introduction to the PAN-OS API

13

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 16: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Some examples of how you might use the PAN-OS API include but are not limited to

bull Read write verify and commit configuration

bull Download reports in XML format

bull Execute operational commands to check health and status

bull Collect logs and pcaps

bull Update dynamic address groups

bull Update user-id mappings

bull And much more

The API BrowserThe Next-generation Firewall and Panorama have an API Browser built in which allows you to explore the API andtrigger simple API calls in the browser itself

You can access the API Browser by adding api to the URL after the IP address of the firewall For example if yourfirewall is at 10001 the URL of the API Browser is https10001api

Lab exercise Try connecting to the API Browser on the firewall in your lab Explore a little to get familiar thencontinue with the lab

API Command TypesThere are several API types as shown in the main page of the API browser

API Types

API Type Description

keygen Generate an API Key (not shown in API Browser)

config Retrieve or modify the configuration

commit Commit the configuration

export Export files packet captures and keys

import Import files certificates response pages and branding

op Operational commands (like lsquoshowrsquo commands)

report Retrieve predefined dynamic and custom reports

user-id UserIP mappings and Dynamic Address Groups

This lab focuses on the following 5 types but the concepts needed to understand these 5 types are the sameconcepts for all the other types

bull keygen

bull config

bull commit

bull op

bull user-id

Introduction to the PAN-OS API

13

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 17: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Continue to Introducing pan-python in Module 1 to begin the first lab

Module 1 Getting Started

Introducing pan-pythonpan-python is a multi-tool set for Palo Alto Networks PAN-OS Panorama WildFire and AutoFocus

The panxapipy command line program from pan-python will be used in the PAN-OS XML API labs to perform APIrequests

pan-python is available on GitHub at httpsgithubcomkevinstevespan-python as a package on PyPi (PythonPackage Index) or can be installed using pip on Python 27 or 3x pan-python has no dependencies

Documentation is available on GitHub and as HTML from the package doc directory

Example Install pan-python Using pip

$ pip install --user pan-pythonCollecting pan-python Downloading pan-python-0110targz (109kB) 100 | | 112kB 20MBsBuilding wheels for collected packages pan-python Running setuppy bdist_wheel for pan-python done Stored in directory homeubuntucachepipwheelsf44c3ef8d30075fc8084fd786f23f7751e98a9802759539d500b24deSuccessfully built pan-pythonInstalling collected packages pan-pythonSuccessfully installed pan-python-0110

$ panxapipy --versionpan-python 0110

Note

By default pip installs the latest version of the package

Lab 1

1 Install pan-python using pip and display its version

2 Run panxapipy with ndashhelp to display command line options

3 View panxapipy documentation on GitHub

API Key GenerationThe panxapipy -k option performs the type=keygen API request to generate the API key for an administratoraccount The -h and -l (ell) options specify the hostname or IP address of the firewall and username and passwordarguments for the API request

Example Generate API Key

$ panxapipy -h 103011101 -l adminadmin -kkeygen successAPI key LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Module 1 Getting Started

14

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 18: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Note

For brevity the labs use the superuser administrator account admin creating API administrator accounts using acustom admin role with the least privilege set of XML API types required for your usage is recommended

A panrc file contains hostname and API key variables optionally referenced by a tagname using the panxapipy -toption The panrc file is a convenient way to store API keys for all your firewalls in a file then reference those keysby tag when executing API calls Yoursquoll create a panrc file in lsquoLab 2rsquo at the bottom of this page and use it for allfollowing API calls

When -t is combined with -h -l and -k panxapipy writes panrc format lines with the hostname and api_keyvariables to stdout

Example Generate panrc Format Without tagname

Use a null string for the tagname to create tagless variables these are matched when -t is not specified

$ panxapipy -t -h 103011101 -l adminadmin -kkeygen success panxapipy generated 20170408 090542hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Example Generate panrc Format With tagname

$ panxapipy -t xapilab -h 103011101 -l admin -kPasswordkeygen success panxapipy generated 20170408 090847hostnamexapilab=103011101api_keyxapilab=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

Note

When the password is not specified on the command line the user is prompted for it This is useful to avoidleaving the password in the shell history

Example Create panrc File Using Shell Output Redirection

Shell output redirection can be used to create your panrc file

$ panxapipy -t xapilab -h 103011101 -l admin -k gtgt ~panrcPasswordkeygen success

$ chmod 600 ~panrc

Note

The panrc file contains authentication material it should have strict file permissions (readwrite for the ownerand not accessible by group or other)

The panrc file entries with your tagname are verified by performing an operational command API request with -ocmd

Module 1 Getting Started

15

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 19: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Example Verify panrc File

$ panxapipy -t xapilab -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 091444 PDT 2017ltresultgtltresponsegt

Note

-X converts a CLI command to XML which is required for the API request show clock is converted toltshowgtltclockgtltclockgtltshowgt

-x prints the XML response to stdout

Lab 2

1 Create a panrc file in your accountrsquos $HOME directory containing entries for your lab firewall api_key andhostname

Hint

Use the shell redirection method shown above

Create the panrc entries without a tagname because the lab examples do not specify a -t option

Note

Your lab environment administrator password may not be admin An invalid password for a type=keygenrequest will result in 403 Forbidden

2 Perform an operational command API request to verify your panrc file api_key and hostname entries

Solution

$ panxapipy -t -h 103011101 -l adminadmin -k gtgt ~panrckeygen success

$ panxapipy -Xxo show clockop successltresponse status=successgtltresultgtSat Apr 8 092936 PDT 2017ltresultgtltresponsegt

Execute Operational Commands

Note

Examples using panxapipy will not specify the -t option for brevity When -t is not specified panrc entries arematched using a null tagname

Module 1 Getting Started

16

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 20: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

hostname=103011101api_key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The panxapipy -o option performs the type=op API request to execute operational commands (CLI) Thecommand is specified with the cmd argument which is an XML representation of the command line The -X optionconverts a CLI-style cmd argument to XML (in some cases the expected XML document cannot be derived)

Module 1 Getting Started

17

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 21: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Example show system info

$ panxapipy -Xjro show system infoop success system app-release-date 20180320 155721 PDT app-version 793-4594 av-release-date 20180325 095822 PDT av-version 2560-3056 cloud-mode non-cloud default-gateway 1921681254 devicename PA-VM family vm global-protect-client-package-version 000 global-protect-clientless-vpn-release-date null global-protect-clientless-vpn-version 0 global-protect-datafile-release-date unknown global-protect-datafile-version unknown hostname PA-VM ip-address 1921681103 ipv6-address unknown ipv6-default-gateway null ipv6-link-local-address fe8020c29fffe10b6a64 is-dhcp false logdb-version 818 mac-address 000c29100b6a model PA-VM multi-vsys off netmask 2552552550 operational-mode normal platform-family vm public-ip-address unknown serial 015351000006388 sw-version 810 threat-release-date 20180320 155721 PDT threat-version 793-4594 time Thu Apr 5 172401 2018n uptime 29 days 201951 url-db paloaltonetworks url-filtering-version 2018040540003 vm-cpuid ESXE3060500FFFBAB1F vm-license VM-50 vm-mac-base E4A7490A1800 vm-mac-count 256 vm-mode VMWare ESXi vm-uuid 564DB8BD-3315-1119-5608-E36D8E100B6A vpn-disable-mode off wf-private-release-date unknown wf-private-version 0 wildfire-release-date 20180326 091506 PDT wildfire-version 229813-232248

Note

This example used -jr to select the result content of the response as JSON Response output options include(from panxapipy --help)

Module 1 Getting Started

18

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 22: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

-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

Note

Not all CLI commands are supported by type=op including

bull debug ping ftp traceroute netstat scp others

bull some show commands

bull show config

bull show log

Tip

debug cli on can be used to determine the XML representation of a CLI command

adminPA-VMgt debug cli onadminPA-VMgt show system info

ltrequest cmd=op cookie=7641443416872627 uid=500gtltoperationsgtltshowgtltsystemgtltinfogtltsystemgtltshowgtltoperationsgtltrequestgt

Lab 3

1 Identify several CLI commands to execute using the API

Some suggestions include

bull show ntp

bull show system info

bull show counter global

bull show session info

2 Use the panxapipy -o option to execute the commands and review the output

3 Perform commands using -x -j and -r

Solution

$ panxapipy -xo ltshowgtltntpgtltshowgtop successltresponse status=successgtltresultgt ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt

Module 1 Getting Started

19

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 23: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gtltresultgtltresponsegt

$ panxapipy -Xro show ntpop success ltsynchedgtuspoolntporgltsynchedgt ltntp-server-1gt ltstatusgtsynchedltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtuspoolntporgltnamegt ltntp-server-1gt ltntp-server-2gt ltstatusgtavailableltstatusgt ltauthentication-typegtnoneltauthentication-typegt ltreachablegtyesltreachablegt ltnamegtnorth-americapoolntporgltnamegt ltntp-server-2gt

$ panxapipy -Xjro show ntpop success ntp-server-1 authentication-type none name uspoolntporg reachable true status synched ntp-server-2 authentication-type none name north-americapoolntporg reachable true status available synched uspoolntporg

Module 2 Configuration

Configuration API Introduction

Actions

The introduction described the different API Command Types Within the config API type there are severalactions

Actions

Retrieve configuration

get Retrieve candidate configuration

show Retrieve running configuration

Module 2 Configuration

20

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 24: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Modify configuration

set Merge existing config with this config

edit Replace existing config with this config

delete Delete existing config

rename Rename entry in existing config

clone Clone existing config

move Change configuration entry order

override Override existing config from Panorama

In this lab you will learn the following actions but the concepts for these actions transfer to the others

bull get

bull show

bull set

bull edit

bull delete

Every action takes an xpath parameter which specifies where in the configuration that action should be takenActions like set and edit that modify configuration also require and element parameter that contains the XMLconfiguration to apply at the xpath

Parameters

bull xpath The location in the configuration to apply the lsquoactionrsquo Always required

bull element The XML configuration to apply at the specified xpath

XPath

An XPath is a representation of a specific place in an XML document The Firewall and Panorama store theirconfiguration internally as XML documents so to interact with pieces of the XML document (the configuration) youmust specify what part of the XML yoursquore interested in You do this with an XPath

Example XPath 1 Letrsquos say you have an XML document with this structure

ltconfiggt ltsharedgt ltaddressgt ltentry name=my-server gt ltaddressgt ltsharedgtltconfiggt

If you want to modify the ldquomy-serverrdquo address object you would use this XPath

configsharedaddressentry[name=my-server]

There are two things to take from this example about XPath

1 Each XML element is separated by a slash as we drill down the XML structure

2 XML Attributes like name can be specified with square brackets [] and an symbol

Example XPath 2 Here is a real Firewall configuration If you wanted to get or change the hostname of this firewallwhat XPath would you use Consider your answer before checking the answer below

Module 2 Configuration

21

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 25: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Answerconfigdevicesentry[name=localhostlocaldomain]deviceconfigsystemhostname

Find the right XPath

There are a 3 techniques you can use to find the XPath you need for a part of the configuration

Technique 1 API Browser

You can use the API Browser to figure out the XPath As you drill down in the browser it will build the XPath for youThe API Browser does not build an element for you but you can submit the API call in the browser to see existingXML in the configuration and derive the element from that

Access the API Browser at httpsltip-of-firewallgtapi

Technique 2 Debug CLI

For those who are familiar with the Firewall and Panorama Command Line you can get the XPath and Element forany CLI command to reproduce that CLI command on the API The CLI uses the API internally so this techniquesimply prints the internal API calls that are made when you run a command

Start by typing debug cli on on the command line

Now any command you type will display the action xpath and element necessary for you to use that commandvia the API

Example

Technique 3 Debug GUI

For those who are familiar with the Firewall and Panorama GUI you can get the XPath and Element for any actiontaken in the GUI to reproduce that action on the API The GUI uses the API internally so this technique simply printsthe internal API calls that are made when you take action in the GUI

1 Start by pointing your browser to httpsltip-of-firewallgtdebug

2 Check Debug and Minimize Javascript

3 In a separate browser tab navigate in the firewall GUI to where you want to make a change and capture theAPI call

4 In the debug tab click Clear debug

5 In the GUI tab take the action you want to capture

6 In the debug tab click Refresh

Module 2 Configuration

22

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 26: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

In the debug window you will see the action xpath and element necessary for you to reproduce that action onthe API There is a lot of output and the fields you need are not labeled so look for things that appear familiar Youknown the actions that are possible and what an xpath looks like The element is usually a block of XML

Example

Use these 3 techniques as you work on the lab modules Which technique you use depends on the situation andyour own familiarity with the firewall If you are more familiar with the CLI you probably know the command for whichyou want to make an API call and you can use debug cli on (Technique 2) If yoursquore more familiar with the firewallrsquosGUI then yoursquoll use Technique 3 If you only need to determine a simple XPath or want to see a range of availableoptions then the API Browser (Technique 1) might be appropriate Try each one during the lab to understand whenand how to use each

Continue to Retrieve Configuration - show and get

Retrieve Configuration - show and getThe panxapipy -s option performs the type=configampaction=show API request to get the active (also calledrunning) configuration The -g option performs the type=configampaction=get API request to get the candidateconfiguration xpath selects the parts of the configuration to return and is the last argument on the command line

Module 2 Configuration

23

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 27: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Example Retrieve Administrator Accounts using get and show

$ panxapipy -xs configmgt-configusersshow successltresponse status=successgtltresultgtltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygtltusersgtltresultgtltresponsegt

$ panxapipy -xg configmgt-configusersget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltusersgt ltentry name=admingt ltphashgt$1$fniyibcj$0tm9SixJwwOkFkDnEqVwltphashgt ltpermissionsgt ltrole-basedgt ltsuperusergtyesltsuperusergt ltrole-basedgt ltpermissionsgt ltentrygt ltentry name=adminrgt ltpermissionsgt ltrole-basedgt ltsuperreadergtyesltsuperreadergt ltrole-basedgt ltpermissionsgt ltphashgt$1$rhprpgfp$JiYMvTDuUUWW4F7ND06JI1ltphashgt ltentrygt ltusersgtltresultgtltresponsegt

Note

See the Abbreviated Syntax section of httpswwww3orgTR1999REC-xpath-19991116 for examples of pathselection

The get response contains additional XML attributes (eg code and count) in the response and resultnodes

Lab 4

1 Use panxapipy to perform a get (-g) request to display the XML output of the rule1 security policy

Module 2 Configuration

24

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 28: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

2 Use panxapipy to perform a show (-s) request to display the XML output of the rule1 security policy

3 Review the output and identify differences

Tip

SSH to your firewall and use gt debug cli on then gt configure and show rulebase security rules rule1 to determine the XPath to use in the request

You can use shell output redirection to redirect the output to a file (eg gt getxml) and compare using a utilitylike diff

Both get and show XML documents are in a pretty format however the indentation and format can vary Thediff -b option can be used to ignore changes in white space

Shell quoting for the XPath is important Using double outer quotes and single inner quotes for the XPath isrecommended for example

$ panxapipy -s configmgt-configusersentry[name=admin]show success

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM show rulebase security rules rule1

ltrequest cmd=get obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1]gtltrequestgt

$ panxapipy -sx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtshowxmlshow success

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule1] gtgetxmlget success [code=19]

$ diff -bu showxml getxml--- showxml Tue Apr 10 073316 2018+++ getxml Tue Apr 10 073329 2018 -14 +15 -ltresponse status=successgtltresultgtltentry name=rule1gt+ltresponse code=19 status=successgtltresult count=1 total-count=1gt+ ltentry name=rule1gt lttogt ltmembergtuntrustltmembergt lttogt -274 +285 ltmembergtanyltmembergt lthip-profilesgt ltactiongtallowltactiongt-ltentrygtltresultgtltresponsegt+ ltentrygt+ltresultgtltresponsegt

Lab 5

1 The panxapipy -r option removes the outer response and result nodes from the XML response Repeatthe get and show requests but this time add a -r (Note that -r implies -x so you can replace -x with -r)

Module 2 Configuration

25

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 29: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

2 The panxapipy -j option displays the XML response in JSON Repeat the get and show requests with -j and-jr

Modify Configuration - set and editThe panxapipy -S option performs the type=configampaction=set API request and the -e option performs thetype=configampaction=edit API request The element argument specifies the objectrsquos XML data and the xpathargument specifies the objectrsquos node in the configuration element can be an XML string a path to a file containingXML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Example Disable and Enable Security Rule Using set and edit

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]rulebasesecurityrulesentry[name=rule2]

$ panxapipy -S ltdisabledgtyesltdisabledgt $XPATHset success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083845gtyesltdisabledgtltresultgtltresponsegt

$ panxapipy -e ltdisabledgtnoltdisabledgt $XPATHdisablededit success [code=20] command succeeded

$ panxapipy -gx $XPATHdisabledget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltdisabled admin=admin dirtyId=4 time=20180414 083944gtnoltdisabledgtltresultgtltresponsegt

Difference between set and edit

set edit

merge at node specified by XPath replace at node specified by XPath

create update objects during merge create update delete objects during replace

non-overlapping element at XPath and XML overlapping element at XPath and XML

Lab Firewall address Objects

The lab firewall configuration contains 5 address objects a static address-group with 3 members and a dynamicaddress-group

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]addressshow successltaddressgt ltentry name=addr1gt ltip-netmaskgt10001ltip-netmaskgt ltentrygt ltentry name=addr2gt ltip-netmaskgt10002ltip-netmaskgt ltentrygt ltentry name=addr3gt ltip-netmaskgt10003ltip-netmaskgt ltentrygt ltentry name=addr4gt ltip-netmaskgt10004ltip-netmaskgt

Module 2 Configuration

26

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 30: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

ltentrygt ltentry name=addr5gt ltip-netmaskgt10005ltip-netmaskgt ltentrygtltaddressgt

$ panxapipy -sr configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupshow successltaddress-groupgt ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgt ltentrygt ltentry name=group2gt ltdynamicgt ltfiltergttag01 or tag02ltfiltergt ltdynamicgt ltentrygtltaddress-groupgt

Lab 6

1 Use panxapipy to add address addr4 to address-group group1

Note

This can be performed with a set or edit API request for this lab use set

2 Verify results using get (-g)

Solution

adminPA-VMgt debug cli onadminPA-VMgt configureadminPA-VM set address-group group1 static addr4

ltrequest cmd=set obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static cookie=5913639088473413gtltmembergtaddr4ltmembergtltrequestgt

adminPA-VM delete address-group group1 static addr4

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -S ltmembergtaddr4ltmembergt $XPATHset success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084600gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084600gtaddr4ltmembergt ltstaticgt

Module 2 Configuration

27

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 31: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Note

After the configuration mode set command to determine the XPath and XML for the API request deleteremoves the member before performing the API set request

Note

The new addr4 you created has a few extra attributes like admin dirtyId and time These show up onlyduring a get and indicate this part of the configuration is lsquodirtyrsquo meaning it has been changed This metadatatells you which administrator who made the change and when they made it It can be safely ignored and willdisappear after a commit

Lab 7

1 Use panxapipy to update address-group group1 to contain only the 2 members addr3 and addr4 (deletemembers addr1 and addr2)

Note

This can be performed with a delete API request for this lab use edit

2 Verify results using get (-g)

Tip

The configuration mode edit command does not perform the API edit request and cannot be used to determinethe XML and XPath for this lab (edit is used to change context to a lower level in the configuration hierarchy)

In this lab the XPath is the same as Lab 6 and you must change the XML to have an overlapping element withthe XPath and different members

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ panxapipy -e ltstaticgtltmembergtaddr3ltmembergtltmembergtaddr4ltmembergtltstaticgt $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 084849gt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 084849gtaddr4ltmembergt ltstaticgt

Note the overlapping ltstaticgt within the xpath and element arguments which is required for the edit request

Module 2 Configuration

28

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 32: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Lab 8

1 Use panxapipy to update address-group group1 to contain the 5 members addr1-addr5

Note

This can be performed using either set or edit

Hint

This XML document can be used for this lab as the argument to -e It can be retrieved using curl or wget

2 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]static

$ cat edit-group1xmlltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltstaticgt

$ panxapipy -e edit-group1xml $XPATHedit success [code=20] command succeeded

$ panxapipy -gr $XPATHget success [code=19] ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt

Commit ConfigurationThe panxapipy -C cmd option performs the type=commit API request to commit the candidate configuration Thecommit options are specified with the cmd argument which is an XML document (the default is ltcommitgt)

The commit operation is performed asynchronously (as a management server job) To simulate a synchronouscommit by waiting for job completion use the ndashsync option

Example Perform Synchronous commit

Module 2 Configuration

29

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 33: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Warning

Donrsquot execute the commit right now you will perform a commit in the lab below

$ panxapipy -C --synccommit success Configuration committed successfully

Note

When no cmd argument is used you must specify a null string

Lab 9

1 Compare the output of the get and show requests for group1 to confirm candidate and active configuration aredifferent

2 Use panxapipy to commit the candidate configuration with the changes from the previous labs

3 Compare the output of the get and show requests to confirm candidate and active configuration are the same

4 Attempt to commit again

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry admin=admin dirtyId=4 name=group1 time=20180414 085519gt ltstatic admin=admin dirtyId=4 time=20180414 085519gt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr1ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr2ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr3ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr4ltmembergt ltmember admin=admin dirtyId=4 time=20180414 085519gtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success Configuration committed successfully

$ panxapipy -sr $XPATHshow successltentry name=group1gt ltstaticgt

Module 2 Configuration

30

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 34: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgtltentrygt

$ panxapipy -gr $XPATHget success [code=19] ltentry name=group1gt ltstaticgt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr3ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygt

$ panxapipy -C --synccommit success [code=19] There are no changes to commit

Delete ConfigurationThe panxapipy -d option performs the type=configampaction=delete API request to delete objects in theconfiguration The xpath argument specifies the objectrsquos node in the configuration

Example Delete Secondary NTP Server

$ XPATH=configdevicesentry[name=localhostlocaldomain]deviceconfigsystemntp-serverssecondary-ntp-server

$ panxapipy -gr $XPATHget success [code=19] ltsecondary-ntp-servergt ltntp-server-addressgtnorth-americapoolntporgltntp-server-addressgt ltauthentication-typegt ltnone gt ltauthentication-typegt ltsecondary-ntp-servergt

$ panxapipy -dx $XPATHdelete success [code=20] command succeededltresponse code=20 status=successgtltmsggtcommand succeededltmsggtltresponsegt

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

Note

The status is success and the code is ldquo7rdquo which specifies the object does not exist

The codes are documented in the PAN-OS and Panorama API Guide

Module 2 Configuration

31

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 35: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Lab 10

1 Use panxapipy to delete the addr3 member from address-group group1

2 Verify results using get (-g)

Tip

SSH to your firewall and use gt debug cli on then gt configure and delete address-group group1 static addr3 to determine the XPath to use in the request

Use set address-group group1 static addr3 to restore the member before proceeding with thepanxapipy request

Solution

adminPA-VMgt debug cli onadminPA-VMgt configure

adminPA-VM delete address-group group1 static addr3

ltrequest cmd=delete obj=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3] cookie=2983986049480030gtltrequestgt

adminPA-VM set address-group group1 static addr3

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr3]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmemberget success [code=19]ltresponse code=19 status=successgtltresult count=4 total-count=4gt ltmembergtaddr1ltmembergt ltmembergtaddr2ltmembergt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergtltresultgtltresponsegt

Note

text() is an XPath node test matching text nodes only and is used to match the addr3 member node

The XPath for action=delete can specify a node-set (gt 1 node) to delete multiple objects with a single requestThe following XPath expression uses the or operator to match multiple address-group members

Example Get Multiple Objects

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr4 or text()=addr5]

$ panxapipy -gr $XPATHget success [code=19] ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt

Module 2 Configuration

32

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 36: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Lab 11

1 Use panxapipy to delete the addr1 and addr2 members from address-group group1

2 Verify results using get (-g)

3 Use panxapipy to delete the address-group group1

4 Verify results using get (-g)

Solution

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]staticmember[text()=addr1 or text()=addr2]

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ XPATH=configdevicesentry[name=localhostlocaldomain]vsysentry[name=vsys1]address-groupentry[name=group1]

$ panxapipy -gx $XPATHget success [code=19]ltresponse code=19 status=successgtltresult count=1 total-count=1gt ltentry admin=admin dirtyId=5 name=group1 time=20180414 092913gt ltstatic admin=admin dirtyId=5 time=20180414 092913gt ltmembergtaddr4ltmembergt ltmembergtaddr5ltmembergt ltstaticgt ltentrygtltresultgtltresponsegt

$ panxapipy -d $XPATHdelete success [code=20] command succeeded

$ panxapipy -gx $XPATHget success [code=7]ltresponse code=7 status=successgtltresult gtltresponsegt

XPath Behavioral Differences (Optional)XPath selection behavior is different for get and show requests

Action Element Attribute Text node gt1 node Non-

node node character absolute

data path

show Yes Yes Yes No Yes

get Yes Yes No Yes No

Lab 12

1 Use panxapipy to perform get and show requests on the XPath configmgt-configusersentry(matches gt 1 node)

2 Use panxapipy to perform get and show requests on the XPath configmgt-configusers (matches1 node)

3 Use panxapipy to perform get and show requests on the XPath mgt-config (relative location path)

Module 2 Configuration

33

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 37: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Best Practice

Always use absolute XPath (start with slash )

Solution

Matches gt 1 node

$ panxapipy -g configmgt-configusersentryget success [code=19]$ panxapipy -s configmgt-configusersentryshow error No such node

Matches 1 node

$ panxapipy -g configmgt-configusersget success [code=19]$ panxapipy -s configmgt-configusersshow success

Relative location path

$ panxapipy -g mgt-configget unauth [code=16] Unauthorized request$ panxapipy -s mgt-configshow success

Module 3 User-ID

User-ID API Introduction

Overview

The User-ID API is used for all dynamic changes to the firewall not just User to IP mappings A dynamic change isany change that doesnrsquot require a commit and includes the following

User-ID API

User Login Logout Creates and removes User to IP mappings

Module 3 User-ID

34

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 38: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

User Group Membership Often retrieved from AD you can supplement groupinfo with the API

Host Information Profile (HIP) Information about the OS disk encryption antivirusetc of a host

Dynamic Address Groups Tag IP addresses with metadata and enforce policy ontags

Dynamic User Groups Tag Users with metadata and enforce policy on tags

User and Server information is often collected natively from external systems without using the API Such externalsystems might include an Active Directory Server Wireless AP Controller Virtual Desktop Manager VirtualizationOrchestrator or AWS Public Cloud The API is used for systems that are not natively supported such as aproprietary app non-standard Radius server or VPN concentrator You can send updates to the firewall from thesesystem using the User-ID API

User-ID API Call Structure

The User-ID API is a little different than the other API types in that it always requires an XML document The XMLdocument is called a UID Message and is structured with 3 main parts

Within the payload section you include a command Each command has at least one entry

There are several commands but these are the most common

User-ID API Commands

login Create a user to ip mapping

logout Remove a user to ip mapping

register Create a tag to ip mapping

unregister Remove a tag to ip mapping

register-user Create a tag to user mapping

unregister-user Remove a tag to user mapping

For less common commands refer to the PAN-OS API Documentation

User-ID with pan-python

The panxapipy -U option performs the type=user-id API request to perform dynamic updates The cmdargument specifies the update message and is an XML document cmd can be an XML string a path to a filecontaining XML or the value ldquo-rdquo (single minus character) to specify the XML is on stdin

Module 3 User-ID

35

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 39: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

The user-id API uses the ltuid-messagegt XML document for several types of dynamic updates including

bull User to IP mapping (ip-user)

bull show user ip-user-mapping

bull User to group mapping

bull show user group

bull tag to IP mapping (registered-ip)

bull show object registered-ip

bull Used in Dynamic Address Groups (DAGs)

bull tag to user mapping (registered-user)

bull show object registered-user

bull Used in Dynamic User Groups (DUGs)

Login and Logoutlogin and logout messages manage user to IP mappings

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogingt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002 timeout=60gt7 ltlogingt8 ltpayloadgt9 ltuid-messagegt

1 ltuid-messagegt2 lttypegtupdatelttypegt3 ltpayloadgt4 ltlogoutgt5 ltentry name=user1 ip=10001gt6 ltentry name=domainuser2 ip=10002gt7 ltlogoutgt8 ltpayloadgt9 ltuid-messagegt

Login Timeout

timeout is optional and the unit is minutes a 0 timeout specifies no timeout (Never)

If not specified the timeout is determined according to the User Identification Timeout configuration on thefirewall the default settings are

set user-id-collector setting enable-mapping-timeout yesset user-id-collector setting ip-user-mapping-timeout 45

When enable-mapping-timeout is yes the default timeout is ip-user-mapping-timeout when it is nothe default is Never

Logout name

The logout name attribute is optional When not specified the single user to IP mapping for the ip specified isdeleted

Module 3 User-ID

36

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 40: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Note

A user can have multiple IPs and an IP can have one user

login and logout can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltlogingt 5 ltentry name=user3 ip=10003gt 6 ltlogingt 7 ltlogoutgt 8 ltentry name=domainuser2 ip=10002gt 9 ltlogoutgt10 ltpayloadgt11 ltuid-messagegt

Note

When login and logout are combined in a single document the entries are processed in the order login logoutonly a single ltlogingt and ltlogoutgt section should be specified

Example Add User to IP Mappings (login)

$ cat uid-loginxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltlogingt ltentry name=user1 ip=10001gt ltentry name=domainuser2 ip=10002 timeout=60gt ltlogingt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3597 359710001 vsys1 XMLAPI user1 2697 2697Total 2 users

Tip

The CLI operational command clear user-cache all removes all IP user mappings

Lab 13

Module 3 User-ID

37

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 41: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

1 Use panxapipy to perform a login request

2 Verify ip-user mappings using the CLI

3 Use panxapipy to perform login and logout requests in a single message

4 Verify mappings using panxapipy -o

5 View userid logs using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-loginxmldynamic-update success

adminPA-VMgt show user ip-user-mapping all

IP Vsys From User IdleTimeout(s) MaxTimeout(s)--------------- ------ ------- -------------------------------- -------------- -------------10002 vsys1 XMLAPI domainuser2 3594 359410001 vsys1 XMLAPI user1 2694 2694Total 2 users

$ panxapipy -U uid-login-logoutxmldynamic-update success

$ panxapipy -Xro show user ip-user-mapping allop successltentrygtltipgt10003ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser3ltusergtltidle_timeoutgt2690ltidle_timeoutgtlttimeoutgt2690lttimeoutgtltentrygtltentrygtltipgt10001ltipgtltvsysgtvsys1ltvsysgtlttypegtXMLAPIlttypegtltusergtuser1ltusergtltidle_timeoutgt2672ltidle_timeoutgtlttimeoutgt2672lttimeoutgtltentrygtltcountgt2ltcountgt

adminPA-VMgt show log userid receive_time in last-hourDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate Timedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice NameVirtual System IDVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypePaddingcpaddingFactor TypeFactor Completion TimeFactor Number120170515 095902015351000001428360x0USERIDlogin620170515 0959020000PA-VM1vsys110001user1XMLAPI01270000xml-api0020170515 0959021120170515 095902015351000001428370x0USERIDlogin620170515 0959020000PA-VM1vsys110002domainuser2XMLAPI01360000xml-api0020170515 0959021120170515 095919015351000001428380x0USERIDlogin620170515 0959190000PA-VM1vsys110003user3XMLAPI01270000xml-api0020170515 0959201120170515 095919015351000001428390x0USERIDlogout620170515 0959190000PA-VM1vsys110002domainuser2XMLAPI01000xml-api0020170515 0959201

User Groups (Optional)groups messages manage user to group mappings

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group1gt 6 ltmembersgt 7 ltentry name=user1gt 8 ltentry name=domainuser2gt 9 ltmembersgt10 ltentrygt11 ltentry name=group2gt

Module 3 User-ID

38

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 42: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

12 ltmembersgt13 ltentry name=user3gt14 ltmembersgt15 ltentrygt16 ltgroupsgt17 ltpayloadgt18 ltuid-messagegt

Groups Updates

Group members must be updated in their entirety it is not possible to add or delete individual members

Note

Register-user and Unregister-user - DUG Objects is the preferred method to perform user to groupmappings when using PAN-OS 91 or greater Dynamic User Groups can be updated incrementally

To delete (clear) a group perform an update with an empty ltmembersgt element node

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltgroupsgt 5 ltentry name=group2gt 6 ltmembersgt 7 ltentrygt 8 ltgroupsgt 9 ltpayloadgt10 ltuid-messagegt

Module 3 User-ID

39

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 43: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Example Add User to Group Mappings (groups)

$ cat uid-groupsxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltgroupsgt ltentry name=group1gt ltmembersgt ltentry name=user1gt ltentry name=domainuser2gt ltmembersgt ltentrygt ltentry name=group2gt ltmembersgt ltentry name=user3gt ltmembersgt ltentrygt ltgroupsgt ltpayloadgtltuid-messagegt

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group list

group1group2

Total 2 Custom Group

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

adminPA-VMgt show user group name group2

source type xmlapi

[1 ] user3

Tip

The CLI commands debug user-id clear group all and debug user-id clear group ltgroupgtcan be used to remove all user group mappings and a specific grouprsquos mappings

Lab 14

1 Use panxapipy to perform a groups request to create group members

Module 3 User-ID

40

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 44: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

2 Verify group membership using the CLI

3 Verify group membership using panxapipy -o

4 Use panxapipy to perform a groups request to remove a group

5 Verify group membership using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-groupsxmldynamic-update success

adminPA-VMgt show user group name group1

source type xmlapi

[1 ] user1[2 ] domainuser2

$ panxapipy -Xro show user group name group2op successsource type xmlapi

[1 ] user3

$ panxapipy -U uid-groups-clearxmldynamic-update success

adminPA-VMgt show user group name group2

adminPA-VMgt

Register-user and Unregister-user - DUG ObjectsPAN-OS 91 introduced the Dynamic User Groups (DUGs) feature A Dynamic User Groups object is createdcontaining match criteria to define the members in the user group using the and and or operators to matchregistered-user object tags and populate the DUG which can be used in the source user of a security policy

register-user and unregister-user messages manage tag to user mappings (registered-user objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry user=domainuser2gt

Module 3 User-ID

41

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 45: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregister-usergt18 ltpayloadgt19 ltuid-messagegt

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregister-usergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each user

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistency

A registered-user mapping is persistent the mappings are preserved across device reboots

Timeout Attribute

A tag can contain an optional timeout attribute in the ltmembergt element

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register-user and unregister-user can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregister-usergt 5 ltentry user=user1gt 6 lttaggt 7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt

Module 3 User-ID

42

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 46: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

11 ltunregister-usergt12 ltregister-usergt13 ltentry user=domainuser2gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry user=user3gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregister-usergt25 ltpayloadgt26 ltuid-messagegt

Note

When register-user and unregister-user are combined in a single document the entries are processed in theorder unregister-user register-user only a single ltregister-usergt and ltunregister-usergt sectionshould be specified

A clear registered-user message removes all user tag mappings This is equivalent to the CLI commanddebug object registered-user clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-usergt 6 ltallgt 7 ltregistered-usergt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic user group dug1 exists in the lab config with match criteria tag01 or tag02

The CLI command show user group list dynamic can be used to list all dynamic user groups configured

Module 3 User-ID

43

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 47: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Example Add Tag to User Mappings (register-user)

$ cat uid-register-userxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregister-usergt ltentry user=user1gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry user=domainuser2gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregister-usergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-register-userxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregister-usergt ltregister-usergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01 tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergt

Module 3 User-ID

44

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 48: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

ltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2

Lab 15

1 Clear all registered-user mappings using the CLI

2 Use panxapipy to perform a register-user request

3 Verify registered-user mappings using the CLI

4 Use panxapipy to perform unregister-user and register-user requests in a single message

5 Verify mappings using panxapipy -o

6 View dynamic user group members for group dug1 using the CLI

7 View userid logs using the CLI

8 Use panxapipy to perform a clear request to remove all user tag mappings

9 Verify registered-user mappings using the CLI

10 View dynamic user group members for group dug1 using the CLI

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

adminPA-VMgt debug object registered-user clear all

done

$ panxapipy -U uid-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01

user1 tag01

Module 3 User-ID

45

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 49: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

tag02 tag03

Total 2 registered users received from user-id agent

$ panxapipy -U uid-unregister-register-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

domainuser2 tag01 tag02

user1 tag01

user3 tag01 tag02

Total 3 registered users received from user-id agent

$ panxapipy -Xro show object registered-user allop successltentry user=domainuser2gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry user=user1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry user=user3gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

[1 ] user1[2 ] domainuser2[3 ] user3

Module 3 User-ID

46

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 50: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

adminPA-VMgt show log userid direction equal backward receive_time in last-hourDomainReceive TimeSerial TypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPUserData Source NameEvent IDRepeat CounttimeoutbeginportendportData SourceData Source TypeSequence NumberAction FlagsDG Hierarchy Level 1DG Hierarchy Level 2DG Hierarchy Level 3DG Hierarchy Level 4Virtual System NameDevice NameVirtual System IDFactor TypeFactor Completion TimeFactor Numberugflagsuserbysource120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6050x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000user301000xml-api6040x00000PA-VM119691231 16000000x0user3120200304 084947015351000006388USERIDregister-tag230520200304 084947vsys10000domainuser201000xml-api6030x00000PA-VM119691231 16000000x0domainuser2120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6020x00000PA-VM119691231 16000000x0user1120200304 084947015351000006388USERIDunregister-tag230520200304 084947vsys10000user101000xml-api6010x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000domainuser201000xml-api6000x00000PA-VM119691231 16000000x0domainuser2120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101360000xml-api5990x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5980x00000PA-VM119691231 16000000x0user1120200304 084920015351000006388USERIDregister-tag230520200304 084920vsys10000user101000xml-api5970x00000PA-VM119691231 16000000x0user1

$ panxapipy -U uid-clear-registered-userxmldynamic-update success

adminPA-VMgt show object registered-user all

Registered User Tags---------------------------------------- -----------------

Total 0 registered users received from user-id agent

adminPA-VMgt show user group name dug1

source type xmlapiGroup type Dynamic

Register and Unregister - DAG ObjectsDynamic Address Groups (DAGs) are an alternative to Static Address Groups An Address Groups object with typeDynamic is created containing match criteria to define the members in the address group using the and and oroperators to match registered-ip object tags and populate the DAG which can be used in the source anddestination address of a security policy

register and unregister messages manage tag to IP mappings (registered-ip objects)

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 ltmember timeout=0gttag02ltmembergt 9 ltmember timeout=3600gttag03ltmembergt10 lttaggt11 ltentrygt12 ltentry ip=10002 persistent=0gt13 lttaggt14 ltmembergttag01ltmembergt15 lttaggt16 ltentrygt17 ltregistergt18 ltpayloadgt19 ltuid-messagegt

Module 3 User-ID

47

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 51: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt 7 ltmembergttag01ltmembergt 8 lttaggt 9 ltentrygt10 ltunregistergt11 ltpayloadgt12 ltuid-messagegt13

Tags

Up to 32 tags can be specified for each IP

The maximum length of a tag is 127

The tag name cannot contain the following

1 single quote

2 double quote

3 greater than one consecutive space

And cannot be the case insensitive words

bull and or not

Persistent Attribute

A registered-ip mapping can be persistent or non-persistent Persistent means the mapping is preserved acrossdevice reboots

The persistent attribute is optional and can be 0 (non-persistent) or 1 (persistent) the default ispersistent

Note

When an existing registered-ip mapping is updated the persistence is updated according to thepersistent attribute in the update

Timeout Attribute

Starting with PAN-OS 90 a tag can contain an optional timeout attribute in the ltmembergt elementUnrecognized attributes are ignored so timeout can be specified in documents used on prior PAN-OSversions

The default is 0 (never expires) or a timeout value in seconds for the tag The maximum timeout is 2592000(30 days)

register and unregister can be combined in a single XML document

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltunregistergt 5 ltentry ip=10001gt 6 lttaggt

Module 3 User-ID

48

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 52: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

7 ltmembergttag02ltmembergt 8 ltmembergttag03ltmembergt 9 lttaggt10 ltentrygt11 ltunregistergt12 ltregistergt13 ltentry ip=10002gt14 lttaggt15 ltmembergttag02ltmembergt16 lttaggt17 ltentrygt18 ltentry ip=10003gt19 lttaggt20 ltmembergttag01ltmembergt21 ltmembergttag02ltmembergt22 lttaggt23 ltentrygt24 ltregistergt25 ltpayloadgt26 ltuid-messagegt

Note

When register and unregister are combined in a single document the entries are processed in the orderunregister register only a single ltregistergt and ltunregistergt section should be specified

A clear registered-ip message removes all IP tag mappings This is equivalent to the CLI commanddebug object registered-ip clear all

1 ltuid-messagegt 2 lttypegtupdatelttypegt 3 ltpayloadgt 4 ltcleargt 5 ltregistered-ipgt 6 ltallgt 7 ltregistered-ipgt 8 ltcleargt 9 ltpayloadgt10 ltuid-messagegt

Note

The dynamic address group group2 exists in the lab config with match criteria tag01 or tag02

Module 3 User-ID

49

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 53: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Example Add Tag to IP Mappings (register)

$ cat uid-registerxmlltuid-messagegt lttypegtupdatelttypegt ltpayloadgt ltregistergt ltentry ip=10001gt lttaggt ltmembergttag01ltmembergt ltmember timeout=0gttag02ltmembergt ltmember timeout=3600gttag03ltmembergt lttaggt ltentrygt ltentry ip=10002 persistent=0gt lttaggt ltmembergttag01ltmembergt lttaggt ltentrygt ltregistergt ltpayloadgtltuid-messagegt

$ panxapipy -xU uid-registerxmldynamic-update successltresponse status=successgtltresultgtltuid-responsegt ltversiongt20ltversiongt ltpayloadgt ltregistergt ltregistergt ltpayloadgtltuid-responsegtltresultgtltresponsegt

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 (never expire) tag02 (never expire) tag03 (expire in 3592 seconds)

10002 tag01 (never expire)

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtltmembergttag03ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=0gt

Module 3 User-ID

50

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 54: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

lttaggtltmembergttag01ltmembergtlttaggtltentrygtltcountgt2ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02

10001 (R) 10002 (R) members total 2O address object R registered ip D dynamic group S static group

Lab 16

1 Use panxapipy to perform a register request

2 Verify registered-ip mappings using the CLI

3 Use panxapipy to perform unregister and register requests in a single message

4 Verify mappings using panxapipy -o

5 View dynamic address group members for group group2 using the CLI

6 View iptag logs using the CLI

7 Use panxapipy to perform a clear request to remove all IP tag mappings

Hint

The links to the ltuid-messagegt XML documents above can be retrieved using curl or wget

Solution

$ panxapipy -U uid-registerxmldynamic-update success

adminPA-VMgt show object registered-ip all

registered IP Tags---------------------------------------- -----------------

10001 tag01 tag02 tag03

10002 tag01

Module 3 User-ID

51

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 55: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Total 2 registered addresses received from user-id agent persistent

$ panxapipy -U uid-unregister-registerxmldynamic-update success

$ panxapipy -Xro show object registered-ip allop successltentry from_agent=0 ip=10001 persistent=1gtlttaggtltmembergttag01ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10002 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltentry from_agent=0 ip=10003 persistent=1gtlttaggtltmembergttag01ltmembergtltmembergttag02ltmembergtlttaggtltentrygtltcountgt3ltcountgt

adminPA-VMgt show object dynamic-address-group name group2

Dynamic address groups in vsys vsys1----------------------------------------------------

----------------defined in vsys -------------------- group2 filter tag01 or tag02 members total 3 10001 (R) 10002 (R) 10003 (R)

O address object R registered ip D dynamic group S static group

adminPA-VMgt show log iptag receive_time in last-15-minutesDomainReceive TimeSerial Sequence NumberAction FlagsTypeThreatContent TypeConfig VersionGenerate TimeVirtual SystemSource IPtag_nameevent_idRepeat CounttimeoutData Source Namedatasource_typedatasource_subtypedg_hier_level_1dg_hier_level_2dg_hier_level_3dg_hier_level_4Virtual System NameDevice Name120170515 111306015351000001428380x0IPTAG0620170515 111306vsys110001tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428390x0IPTAG0620170515 111306vsys110001tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428400x0IPTAG0620170515 111306vsys110001tag03register10XMLAPIxml-apiunknown0000PA-VM120170515 111306015351000001428410x0IPTAG0620170515 111306vsys110002tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428420x0IPTAG0620170515 111412vsys110001tag02unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428430x0IPTAG0620170515 111412vsys110001tag03unregister10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428440x0IPTAG0620170515 111412vsys110002tag02register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428450x0IPTAG0620170515 111412vsys110003tag01register10XMLAPIxml-apiunknown0000PA-VM120170515 111412015351000001428460x0IPTAG0620170515 111412vsys110003tag02register10XMLAPIxml-apiunknown0000PA-VM

$ panxapipy -U uid-clear-registered-ipxmldynamic-update success

Module 3 User-ID

52

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources
Page 56: PAN-OS XML API Labs with pan-pythonapi-lab.paloaltonetworks.com/_static/panos-xml-api-rtd.pdf5 set deviceconfig system service disable-telnet yes 6 set deviceconfig system service

Resources

bull PDF Lab Document

bull PAN-OS and Panorama API Guide

bull pan-python

bull Palo Alto Networks Device Framework (pandevice)

bull Live Community - pandevice

Resources

53

  • PAN-OS XML API Labs with pan-python
    • Lab PAN-OS Configuration
      • set Format Configuration
      • XML Format Configuration
        • Introduction to the PAN-OS API
          • About the API
          • The API Browser
          • API Command Types
            • Module 1 Getting Started
              • Introducing pan-python
                • Example Install pan-python Using pip
                • Lab 1
                  • API Key Generation
                    • Example Generate API Key
                    • Example Generate panrc Format Without tagname
                    • Example Generate panrc Format With tagname
                    • Example Create panrc File Using Shell Output Redirection
                    • Example Verify panrc File
                    • Lab 2
                      • Execute Operational Commands
                        • Example show system info
                        • Lab 3
                            • Module 2 Configuration
                              • Configuration API Introduction
                                • Actions
                                • XPath
                                • Find the right XPath
                                  • Technique 1 API Browser
                                  • Technique 2 Debug CLI
                                  • Technique 3 Debug GUI
                                      • Retrieve Configuration - show and get
                                        • Example Retrieve Administrator Accounts using get and show
                                        • Lab 4
                                        • Lab 5
                                          • Modify Configuration - set and edit
                                            • Example Disable and Enable Security Rule Using set and edit
                                            • Difference between set and edit
                                            • Lab Firewall address Objects
                                            • Lab 6
                                            • Lab 7
                                            • Lab 8
                                              • Commit Configuration
                                                • Example Perform Synchronous commit
                                                • Lab 9
                                                  • Delete Configuration
                                                    • Example Delete Secondary NTP Server
                                                    • Lab 10
                                                    • Example Get Multiple Objects
                                                    • Lab 11
                                                      • XPath Behavioral Differences (Optional)
                                                        • Lab 12
                                                            • Module 3 User-ID
                                                              • User-ID API Introduction
                                                                • Overview
                                                                • User-ID API Call Structure
                                                                • User-ID with pan-python
                                                                  • Login and Logout
                                                                    • Login Timeout
                                                                    • Logout name
                                                                    • Example Add User to IP Mappings (login)
                                                                    • Lab 13
                                                                      • User Groups (Optional)
                                                                        • Groups Updates
                                                                        • Example Add User to Group Mappings (groups)
                                                                        • Lab 14
                                                                          • Register-user and Unregister-user - DUG Objects
                                                                            • Tags
                                                                            • Persistency
                                                                            • Timeout Attribute
                                                                            • Example Add Tag to User Mappings (register-user)
                                                                            • Lab 15
                                                                              • Register and Unregister - DAG Objects
                                                                                • Tags
                                                                                • Persistent Attribute
                                                                                • Timeout Attribute
                                                                                • Example Add Tag to IP Mappings (register)
                                                                                • Lab 16
                                                                                    • Resources