Uninstall Multiple Agents
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.
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