Quarantine Compromised Devices (API)
Table of Contents
Quarantine Compromised Devices (API)
XML API examples of adding devices to the firewall quarantine list.
You can use this XML API to identify compromised
devices by adding them to a quarantine list, which you can then
use to block GlobalProtect users from connecting those devices to
a gateway. See the following for examples of XML API requests to
manage device quarantine.
Add a Device to a Quarantine List
You can use the XML API to write one or more
compromised devices to the quarantine list on the firewall.
The
following example shows the basic syntax of the XML API request
path to add one or more identified devices to the quarantine list
on the firewall.
https://<firewall>/api/?type=op&cmd=<set><quarantine><data></data></quarantine></set>
The <data></data> content identifies the
device(s) to be quarantined and the following table lists the tags
in the content. All tags listed in the table are required.
| Tag | Description | Notes |
|---|---|---|
| <iot-message> | Denotes message | |
| <version> | XML version | Content is "1.0" |
| <type> | Indicates a request to update | Content is “update” |
| <vsys> | vsys of the firewall that has the quarantine list | Content is the vsys |
| <payload> | Denotes payload | |
| <quarantine-add> | Identifies action to add quarantine device | |
| <entry hostid=""> | Attribute hostid is the compromised device ID. Can have multiple entries. Include one entry per device to be quarantined | Attribute hostid is required |
| <serialno> | Serial number of the device to be quarantined | Content optional |
| <reason> | Reason for quarantine | Content required. No spaces allowed in content |
| <source> | Source device or application from which this quarantine device was added to the quarantine list | Content required |
| <quarantine-ts> | Quarantine timestamp. Time when device was added to quarantine list. | Content required |
The following is an example of <data></data>
content to add one device to the quarantine list.
<iot-message><version>1.0</version><type>update</type><vsys>vsys1</vsys><payload><quarantine-add><entry
hostid="host3"><serialno>serial1</serialno><reason>admin1</reason><source>litest1</source><quarantine-ts>1234</quarantine-ts></entry></quarantine-add></payload></iot-message>The
following is an example of the <data></data> content to add
more than one device to the quarantine list.
<iot-message><version>1.0</version><type>update</type><vsys>vsys1</vsys><payload><quarantine-add><entry hostid="host9"><serialno>123uabcd2</serialno><reason>Magnifier</reason><source>Magnifier</source><quarantine-ts>7890</quarantine-ts>&</entry><entry hostid="host8"><serialno>309ufwi88</serialno><reason>Cortex</reason><source>Cortex</source><quarantine-ts>4567</quarantine-ts></entry></quarantine-add></payload></iot-message- Encode the data content.You must encode the data content twice before you submit it with the XML API request. First HTML encode the content and then URL encode the HTML encoded content.
- HTML encode the content.One approach is to use the CLI. See Use the CLI to Find XML API Syntax for details about how to use the CLI to determine the syntax of this request. The following command outputs an HTML encoded string.
set quarantine data '<iot-message><version>1.0</version><type>update</type><vsys>vsys1</vsys><payload><quarantine-add><entry hostid="host3"><serialno>serial1</serialno><reason>admin1</reason><source>test1</source><quarantine-ts>1234</quarantine-ts></entry></quarantine-add></payload></iot-message>'The output from this command includes the following. The <data></data> content is the HTML encoded version of your original data content.<request cmd="op" cookie="3515166656333795" uid="10.2"><operations><set><quarantine><data><iot-message><version>1.0</version><type>update</type><vsys>vsys1</vsys><payload><quarantine-add><entry hostid="host3">><serialno>serial1</serialno><reason>admin1</reason><source>test1</source><quarantine-ts>1234</quarantine-ts></entry></quarantine-add></payload></iot-message></data></quarantine></set></operations></request>URL encode the HTML encoded data content.The example below shows the data content that we HTML encoded and now want to URL encode.<iot-message><version>1.0</version><type>update</type><vsys>vsys1</vsys><payload><quarantine-add><entry hostid="host3"><serialno>serial1</serialno><reason>admin1</reason><source>test1</source><quarantine-ts>1234</quarantine-ts></entry></quarantine-add></payload></iot-message>The URL encoded content for the data content shown above is as follows.%26lt%3Biot-message%26gt%3B%26lt%3Bversion%26gt%3B1.0%26lt%3B%2Fversion%26gt%3B%26lt%3Btype%26gt%3Bupdate%26lt%3B%2Ftype%26gt%3B%26lt%3Bvsys%26gt%3Bvsys1%26lt%3B%2Fvsys%26gt%3B%26lt%3Bpayload%26gt%3B%26lt%3Bquarantine-add%26gt%3B%26lt%3Bentry%20hostid%3D%26quot%3Bhost3%26quot%3B%26gt%3B%26gt%3B%26lt%3Bserialno%26gt%3Bserial1%26lt%3B%2Fserialno%26gt%3B%26lt%3Breason%26gt%3Badmin1%26lt%3B%2Freason%26gt%3B%26lt%3Bsource%26gt%3Btest1%26lt%3B%2Fsource%26gt%3B%26lt%3Bquarantine-ts%26gt%3B1234%26lt%3B%2Fquarantine-ts%26gt%3B%26lt%3B%2Fentry%26gt%3B%26lt%3B%2Fquarantine-add%26gt%3B%26lt%3B%2Fpayload%26gt%3B%26lt%3B%2Fiot-message%26gt%3BMake a request to add your device to the quarantine list on the firewall.The following example shows a cURL request to add a single compromised device to the quarantine list.curl -X POST 'https://<firewall>/api?key=<api key>&type=op&cmd=<set><quarantine><data>%26lt%3Biot-message%26gt%3B%26lt%3Bversion%26gt%3B1.0%26lt%3B%2Fversion%26gt%3B%26lt%3Btype%26gt%3Bupdate%26lt%3B%2Ftype%26gt%3B%26lt%3Bvsys%26gt%3Bvsys1%26lt%3B%2Fvsys%26gt%3B%26lt%3Bpayload%26gt%3B%26lt%3Bquarantine-add%26gt%3B%26lt%3Bentry%20hostid%3D%26quot%3Bhost3%26quot%3B%26gt%3B%26lt%3Bserialno%26gt%3Bserial1%26lt%3B%2Fserialno%26gt%3B%26lt%3Breason%26gt%3Badmin1%26lt%3B%2Freason%26gt%3B%26lt%3Bsource%26gt%3Btest1%26lt%3B%2Fsource%26gt%3B%26lt%3Bquarantine-ts%26gt%3B1234%26lt%3B%2Fquarantine-ts%26gt%3B%26lt%3B%2Fentry%26gt%3B%26lt%3B%2Fquarantine-add%26gt%3B%26lt%3B%2Fpayload%26gt%3B%26lt%3B%2Fiot-message%26gt%3B</data></quarantine></set>'An example of a successful response is shown below.<response status="success"><result><iot-response> <version>2.0</version> <payload> <quarantine-add> </quarantine-add> </payload> </iot-response> </result></response>List Quarantined Devices
Once you’ve added a device to the quarantine list on a firewall, you can use another XML API to access the updated list.- Make a request to get the list of quarantined devices from the firewall.The following is an example of a curl command that requests a list of all the quarantined devices from a firewall.curl -X POST 'https://<firewall>/api?key=<api key>&type=op&cmd=<request><device-quarantine-list><show></show></device-quarantine-list></request>'The following example shows the result format of the request.
<response status="success"> <result> <entry name="12345abcde"> <start>0</start> <hostid>12345abcde</hostid> <reason>Admin</reason> <source></source> <vsys_id>1</vsys_id> <serialno></serialno> <user></user> <timestamp>Tue Feb 4 15:48:32 2020</timestamp> </entry> <entry name="host3"> <start>0</start> <hostid>host3</hostid> <reason>admin1</reason> <source>litest1</source> <vsys_id>1</vsys_id> <serialno>serial1</serialno> <user></user> <timestamp>Mon Apr 13 12:10:55 2020</timestamp> </entry> <total>2</total> </result> </response>Delete a Device From the Quarantine List
Management of the quarantine list on a firewall includes the ability to remove a device that is no longer compromised from the list.- Make an API request to delete a device from the quarantine list.The following example shows a request to to delete a devicehost3 from a firewall quarantine list.curl -X POST 'https://<firewall>/api?key=<api key>&type=op&cmd=<request><device-quarantine-list><delete><host>host3</host></delete></device-quarantine-list></request>'An example of a successful response is as follows.<response status="success"> <result> <status>success</status> <msg>Device is deleted from quarantine list</msg> </result> </response>
