Uninstall Multiple Agents

[POST] /qps/rest/2.0/uninstall/am/asset

Bulk uninstall cloud agents matching the specified filter criteria, and remove associated agent hosts from your subscription.

Filter criteria required - For a bulk request it is mandatory to add this filter criteria in <ServiceRequest>:

<Criteria field="tagName" operator="EQUALS">Cloud Agent</Criteria>

 Providing at least one criterion in the Service Request is mandatory for bulk uninstallation of agents.

Good to Know - A request to uninstall agents makes a call to the Qualys Cloud Platform to purge the host scan data (findings) for the agent hosts and remove the agent hosts from your subscription

Permissions required - Managers with full scope. Other users must have these permissions: Access Permission “API Access” and CA Agent Permission “Uninstall Agent”.

Input ParametersInput Parameters

To uninstall all agents, nothing other than the filter tagName EQUALS Cloud Agent is recommended. The more filters added to the request we’ll uninstall a more refined list of agents.

Use the following <ServiceRequest> parameters to select agents you want to uninstall. These parameters act as filters. When multiple filters are specified, parameters are combined using a logical AND.

Filter operators are available for use with <ServiceRequest> parameters.

Use of NOT EQUALS operator is now disabled during agent uninstall. This is to avoid unintended consequences of Tags or Assets being deleted or updated. The service response includes an error message if you use the NOT EQUALS operator while uninstalling an agent.

Supported filter operators

Parameter

Mandatory

/Optional

Data Type

Description

id 

Optional

integer

Asset ID of the agent host.

name 

Optional

string

Asset name of the agent host.

created 

Optional

date

Date when the agent host was added to your asset inventory (i.e. when the agent was provisioned). Date is specified in UTC/GMT format, i.e. YYYY-MM-DD[THH:MM:SSZ]

updated 

Optional

date

Date when the agent was last updated, such as activation, host name change, etc. Date is specified in UTC/GMT format.

tagName 

Mandatory

string

Asset tag name assigned to the agent host. All agent hosts are assigned the tag Cloud Agent.

agentUuid 

Optional

string

Agent ID (UUID) of the Agent host.

Sample - Uninstall agents in bulkSample - Uninstall agents in bulk

API request

Curl request:
curl --location '<qualys_base_url>/qps/rest/2.0/uninstall/am/asset/' \
--header 'Content-Type: application/xml' \
--header 'Authorization: Basic <Authorization_Token>' \
--data '
<?xml version="1.0" encoding="UTF-8" ?>    
    

Contents of uninstall_all_agents.xml

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <filters>
        <Criteria field="tagName" operator="EQUALS">Cloud Agent</Criteria>
    </filters>
</ServiceRequest>      
    

Response


<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="<qualys_base_url>/qps/xsd/2.0/am/asset.xsd">
    <responseCode>SUCCESS</responseCode>
    <count>4</count>
    <data>
        <Asset>
            <id>59284297</id>
        </Asset>
        <Asset>
            <id>60423255</id>
        </Asset>
        <Asset>
            <id>60451458</id>
        </Asset>
        <Asset>
            <id>61527815</id>
        </Asset>
    </data>
</ServiceResponse>
    

Sample: Uninstall agents using UUIDSample: Uninstall agents using UUID

In case of agent UUID, use the EQUALS operator for uninstalling a single agent or use the IN operator with comma separated UUID values for bulk uninstall.

Sample API Request

curl -u fo_username:password -X POST -H "Content-Type: text/xml" -H "Cache-Control: no-cache" --data-binary @uninstall_all_agents.xml "<qualys_base_url>/qps/rest/2.0/uninstall/am/asset/"

“file.xml” contains the request POST data.

Input Data

  
Request POST data: (Contents of file.xml)
<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <filters>
        <Criteria field="agentUuid" operator="IN">1d71c07e-f1b0-42df-918b-01b231489b86,0285fead-0014-465e-8840-6457ad482bb3</Criteria>
    </filters>
</ServiceRequest>
    

Use the EQUALS operator for uninstalling a single agent or use the IN operator with comma separated UUID values for bulk uninstall.

Response

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="<qualys_base_url>/qps/xsd/2.0/am/asset.xsd">
    <responseCode>SUCCESS</responseCode>
    <count>2</count>
    <data>
        <Asset>
            <id>712038</id>
        </Asset>
        <Asset>
            <id>2532638</id>
        </Asset>
    </data>
</ServiceResponse>      
    

XSD

<platform API server>/qps/xsd/2.0/am/asset.xsd