PAN-OS® and Panorama™API Usage Guide
    : Quarantine Compromised Devices (API)
    Focus
    Download PDF
    Focus
    1. Home
    2. PAN-OS
    3. PAN-OS® and Panorama™API Usage Guide
    4. PAN-OS XML API Use Cases
    5. Quarantine Compromised Devices (API)
    Download PDF

    PAN-OS® and Panorama™API Usage Guide

    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.
    TagDescriptionNotes
    <iot-message>Denotes message
    <version>XML versionContent is "1.0"
    <type>Indicates a request to updateContent is “update”
    <vsys>vsys of the firewall that has the quarantine listContent 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 quarantinedAttribute hostid is required
    <serialno>Serial number of the device to be quarantinedContent optional
    <reason>Reason for quarantineContent required. No spaces allowed in content
    <source>Source device or application from which this quarantine device was added to the quarantine listContent 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
    1. 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.
      1. 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>&lt;iot-message&gt;&lt;version&gt;1.0&lt;/version&gt;&lt;type&gt;update&lt;/type&gt;&lt;vsys&gt;vsys1&lt;/vsys&gt;&lt;payload&gt;&lt;quarantine-add&gt;&lt;entry hostid=&quot;host3&quot;&gt;&gt;&lt;serialno&gt;serial1&lt;/serialno&gt;&lt;reason&gt;admin1&lt;/reason&gt;&lt;source&gt;test1&lt;/source&gt;&lt;quarantine-ts&gt;1234&lt;/quarantine-ts&gt;&lt;/entry&gt;&lt;/quarantine-add&gt;&lt;/payload&gt;&lt;/iot-message&gt;</data></quarantine></set></operations></request>
      2. URL encode the HTML encoded data content.
        The example below shows the data content that we HTML encoded and now want to URL encode.
        &lt;iot-message&gt;&lt;version&gt;1.0&lt;/version&gt;&lt;type&gt;update&lt;/type&gt;&lt;vsys&gt;vsys1&lt;/vsys&gt;&lt;payload&gt;&lt;quarantine-add&gt;&lt;entry hostid=&quot;host3&quot;&gt;&lt;serialno&gt;serial1&lt;/serialno&gt;&lt;reason&gt;admin1&lt;/reason&gt;&lt;source&gt;test1&lt;/source&gt;&lt;quarantine-ts&gt;1234&lt;/quarantine-ts&gt;&lt;/entry&gt;&lt;/quarantine-add&gt;&lt;/payload&gt;&lt;/iot-message&gt;
        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%3B
    2. Make 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.
    1. 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.
    1. 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>

    © 2024 Palo Alto Networks, Inc. All rights reserved.