The Power of XML API!

by on ‎02-28-2018 06:59 AM - last edited on ‎05-06-2018 08:19 AM by (21,942 Views)

You can do a lot of cool things with the API. One of the more common tasks an administrator can perform is accessing, updating and changing the firewall's configuration through some creative scripting while leveraging the ease of use of the API.

 

Just like the GUI and the CLI, accessing the API requires authentication. An authentication token can be generated and the resulting token can then be injected into any API command.

 

Let's see how we can use the above to get the configuration logs from a firewall using XML API.

 

First, you'll want to get the authentication token I talked about above. To get the token, simply open a browser and go to your firewall's address with the URL you see below.  Change <hostname> with your firewall's IP address or actual hostname and change <username> and <password> with the actual username/password:

 

 

 

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

 

 

For example, your query will look like this if your hostname is 10.192.16.170 and if you're still using the default username/password which is NOT RECOMMENDED, of course!!!

 

 

https://10.192.16.170/api/?type=keygen&user=admin&password=admin

 

 

This query will return the authentication key I talked about earlier ... the result will look like this:

 

 

<response status="success">
<result>
<key>LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09
</key>
</result>
</response>

 

This long ORANGE string is the authentication key you will be using to perform the following API calls.

 

Let's see how you can use this key and get the config log at the same time.

 

You can use the API browse function to look through all the possible options, but just trust me when I tell you that for the config logs, the following query is the one you need (notice how I added the authentication key to the query):

 

 

https://10.192.16.170/api/?type=log&log-type=config&key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

 

 

You'll get a job-id in return ... it will look something like this:

 

 

<response status="success" code="19">
<result>
<msg>
<line>query job enqueued with jobid 2145</line>
</msg>
<job>2145</job>
</result>
</response>

 

Now you can use this job-id to get the actual log output.  Just use the following syntax and notice how I use the job-id parameter in the query and also how I used the authentication key in the same query:

 

 

https://10.192.16.170/api/?type=log&action=get&job-id=2145&key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

 

This output will return the last 20 config logs. 

20 being the default number but this can be edited in your query.  The output will look as displayed below (truncated for obvious reasons):

 

 

<response status="success">
<result>
<job>
<tenq>20:30:15</tenq>
<tdeq>20:30:15</tdeq>
<tlast>20:30:15</tlast>
<status>FIN</status>
<id>2145</id>
</job>
<log>
<logs count="20" progress="100">
<entry logid="6521450854455705600">
<domain>1</domain>
<receive_time>2018/02/11 20:27:46</receive_time>
<serial>007000001728</serial>
<seqno>1717</seqno>
<actionflags>0x8000000000000000</actionflags>
<type>CONFIG</type>
<subtype>0</subtype>
<config_ver>0</config_ver>
<time_generated>2018/02/11 20:27:46</time_generated>
<dg_hier_level_1>0</dg_hier_level_1>
<dg_hier_level_2>0</dg_hier_level_2>
<dg_hier_level_3>0</dg_hier_level_3>
<dg_hier_level_4>0</dg_hier_level_4>
<device_name>PA-VM</device_name>
<vsys_id>0</vsys_id>
<host>10.192.7.140</host>
<cmd>edit</cmd>
<admin>admin</admin>
<client>Web</client>
<result>Succeeded</result>
<path> vsys vsys1 rulebase dos rules TEST</path>
<before-change-preview>
TEST { protection { classified { classification-criteria { addre
</before-change-preview>
<after-change-preview>TEST { } </after-change-preview>
</entry>

 

In your query, you can add different parameters.  Using the API browser you can look at what these are exactly but being the good guy that I am I'll list them here :

 

query : You can use this parameter to define your query, similar to the Log Filter in the GUI

dir : You can choose the direction with this parameter.  The direction can be forward or backward

skip : You can define the number of log records to skip with this parameter

nlogs : You can define the number of log records to fetch.  As I said earlier in this blog, the default is 20 but you can define up to a maximum of 5000!

 

An example using some of the parameters discussed here:

 

https://10.192.16.170/api/?type=log&log-type=config&direction=backward&nlogs=25&query=(receive_time geq '2012/06/22 08:00:00')&key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

 

This will result in a job-id:

 

<response status="success" code="19">
<result>
<msg>
<line>query job enqueued with jobid 2162</line>
</msg>
<job>2162</job>
</result>
</response>

Use this job-id in your query to receive the report in XML format:

 

https://10.192.16.170/api/?type=log&action=get&job-id=2162&key=LUFRPT14MW5xOEo1R09KVlBZNnpnemh0VHRBOWl6TGM9bXcwM3JHUGVhRlNiY0dCR0srNERUQT09

The output will be your report based on the parameters you defined, in XML format as shown below (truncated, of course):

 

<response status="success">
  <result>
<job>
<tenq>21:49:29</tenq>
<tdeq>21:49:29</tdeq>
<tlast>21:49:29</tlast>
<status>FIN</status>
<id>2162</id>
</job>
<log>
<logs count="25" progress="100">
<entry logid="6521450854455705600">
<domain>1</domain>
<receive_time>2018/02/11 20:27:46</receive_time>
<serial>007000001728</serial>
<seqno>1717</seqno>
<actionflags>0x8000000000000000</actionflags>
<type>CONFIG</type>
<subtype>0</subtype>
<config_ver>0</config_ver>
<time_generated>2018/02/11 20:27:46</time_generated>
<dg_hier_level_1>0</dg_hier_level_1>
<dg_hier_level_2>0</dg_hier_level_2>
<dg_hier_level_3>0</dg_hier_level_3>
<dg_hier_level_4>0</dg_hier_level_4>
<device_name>PA-VM</device_name>
<vsys_id>0</vsys_id>
<host>10.192.7.140</host>
<cmd>edit</cmd>
<admin>admin</admin>
<client>Web</client>
<result>Succeeded</result>
<path> vsys vsys1 rulebase dos rules TEST</path>
<before-change-preview>
TEST { protection { classified { classification-criteria { addre
</before-change-preview>
<after-change-preview>TEST { } </after-change-preview>
</entry>

Now it's up to you to use and adapt this XML example and experiment with it. 

I'm positive this powerful tool can be used in your environment as well.

 

There are plenty of XML API resources available on Live for you to get started!

Feel free to ask questions or share your XML API examples in the comments section below!

 

-Kiwi out!

Comments
by dgaur
on ‎03-02-2018 06:28 AM

Thanks for this interesting article. It is highly useful for XML starters.

Would be useful if you can also highlight some GUI based tools/screenshots which may be used to test out the scripts above.

by psouthwick
on ‎04-02-2018 01:03 PM

Great article, question though; is it possible to then run another query on the 'entry logid' so that you can get the full 'before-change-preview> and <after-change-preview>?  As this view appears to restrict the total characters so you aren't able to use this query to see what was changed in its entirety.

by
on ‎04-03-2018 01:02 AM

@psouthwick : Good point.  I was unable to get the full preview with the tests I've did.  I've tried by adding the 'entry logid' using the XPATH method explained in one of my other XML blog articles but I was unable to get the desired result.  It seems that it keeps returning that values as shown in the GUI columns (not the full details).

 

I've illustrated it below :

#1 is returned

#2 is what you would like to see instead

 

2018-04-03_09-55-37.jpg

 

 

Maybe check with TAC to see if this is at all possible ... if not then a feature request might be a good idea.

by iseekSupport
‎07-02-2018 06:57 PM - edited ‎07-03-2018 03:21 PM

Looks impressive!

 

I noticed a couple of gotchas on my trials.

 

a) For passwords with special characters, use ASCII encoding. For Eg:. palo&alto can be represented as palo%26alto.

b) When you create a separate admin role for xml access, with just xml only rights and apply it for a user and try to pull configuration out of the box it hides the passwords, which makes sense

Ask Questions Get Answers Join the Live Community
Labels