Use Host Asset API to Uninstall Agents in Bulk
If you want to filter using more parameters, you can use the Host Asset API to 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>
Proving at least one criteria in 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 |
|---|---|---|---|
|
qwebHostId |
Optional |
integer | |
|
lastVulnScan |
Optional |
date |
|
|
lastComplianceScan |
Optional |
date |
|
|
informationGatheredUpdated |
Optional |
date |
|
|
os |
Optional |
text | |
|
dnsHostName |
Optional |
text | |
|
address |
Optional |
text | |
|
vulnsUpdated |
Optional |
date | |
|
id |
Optional |
integer | |
|
name |
Optional |
text | |
|
created |
Optional |
date | |
|
type |
Optional |
text | |
|
netbiosName |
Optional |
string | |
|
netbiosNetworkID |
Optional |
text | |
|
networdGuid |
Optional |
text | |
|
trackingMethod |
Optional |
keyword |
NONE, IP, DNSNAME, NETBIOS, INSTANCE_ID, QAGENT |
|
port |
Optional |
integer | |
|
installedSoftware |
Optional | text | |
|
tagName |
Mandatory | text | |
|
tagId |
Optional |
integer | |
|
update |
Optional |
date | |
|
Assets with cloud agents |
|
|
|
|
activationKey |
Optional |
string |
Allowed operator: EQUALS |
|
agentConfigurationName |
Optional |
string |
Allowed operators: EQUALS, CONTAINS |
|
agentConfigurationId |
Optional |
integer |
Allowed operator: EQUALS |
|
agentVersion |
Optional | string |
Allowed operators: EQUALS, LESSER, GREATER |
|
lastCheckedIn |
Optional | date |
Allowed operators: EQUALS, LESSER, GREATER |
|
agentUuid |
Optional | string |
Agent ID (UUID) of the Agent host. |
Sample - Uninstall agents in bulkSample - Uninstall agents in bulk
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/hostasset/"
Contents of uninstall_all_agents.xml
<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
<filters>
<Criteria field="trackingMethod"
operator="EQUALS">QAGENT</Criteria>
<Criteria field="type" operator="EQUALS">HOST</Criteria>
<Criteria field="tagName" operator="EQUALS">Cloud
Agent</Criteria>
<Criteria field="lastVulnScan" operator="GREATER">2018-03-
08T05:16:56Z</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/hostasset.xsd">
<responseCode>SUCCESS</responseCode>
<count>1</count>
<hasMoreRecords>false</hasMoreRecords>
<data>
<HostAsset>
<id>6851120</id>
<name>shwetas-Mac-mini.local</name>
<created>2018-03-07T11:43:26Z</created>
<modified>2018-03-08T06:49:56Z</modified>
<type>HOST</type>
<tags>
<list>
<TagSimple>
<id>8652821</id>
<name>Cloud Agent</name>
</TagSimple>
<TagSimple>
<id>8654616</id>
<name>DT_Port</name>
</TagSimple>
</list>
</tags>
<sourceInfo>
<list>
<AssetSource/>
</list>
</sourceInfo>
<qwebHostId>672160</qwebHostId>
<lastComplianceScan>2018-03-
08T01:20:28Z</lastComplianceScan>
<lastVulnScan>2018-03-08T06:20:10Z</lastVulnScan>
<lastSystemBoot>2018-02-06T06:00:24Z</lastSystemBoot>
<lastLoggedOnUser>root</lastLoggedOnUser>
<os>Mac OS X 10.11.6</os>
<dnsHostName>shwetas-Mac-mini.local</dnsHostName>
<agentInfo>
<agentVersion>1.7.0.64</agentVersion>
<agentId>2b79e576-201b-49b9-9d2a-
8e5cb70bfdcd</agentId>
<status>STATUS_ACTIVE</status>
<lastCheckedIn>2018-03-08T06:49:55Z</lastCheckedIn>
<connectedFrom>10.113.196.203</connectedFrom>
<chirpStatus>Inventory Scan Complete</chirpStatus>
<platform>MACOSX</platform>
<activatedModule>AGENT_VM,AGENT_PC</activatedModule>
<manifestVersion>VULNSIGS-2.4.281.2-
1</manifestVersion>
<agentConfiguration>
<id>432001</id>
<name>Test_abc</name>
</agentConfiguration>
<activationKey>
<activationId>fc8aa44e-6e6d-492d-ae06-
08e1676901ff</activationId>
<title>Test_abc</title>
</activationKey>
</agentInfo>
<netbiosName>MACMINI-3BFD26</netbiosName>
<address>10.113.196.203</address>
<trackingMethod>QAGENT</trackingMethod>
<manufacturer>Apple Inc.</manufacturer>
<model>Macmini7,1</model>
<totalMemory>8192</totalMemory>
<timezone>+05:30</timezone>
<biosDescription>Macmini7,1, MM71.0224.B00,
2.24f32</biosDescription>
<openPort>
<list>
<HostAssetOpenPort>
<port>49558</port>
<protocol>TCP</protocol>
</HostAssetOpenPort>
<HostAssetOpenPort>
<port>22</port>
<protocol>TCP</protocol>
</HostAssetOpenPort>
...
</list>
</software>
<vuln>
<list>
<HostAssetVuln>
<qid>105145</qid>
<hostInstanceVulnId>139552720</hostInstanceVulnId>
<firstFound>2018-03-
07T12:18:20Z</firstFound>
<lastFound>2018-03-08T06:20:10Z</lastFound>
</HostAssetVuln>
<HostAssetVuln>
<qid>124557</qid>
<hostInstanceVulnId>139552721</hostInstanceVulnId>
<firstFound>2018-03-
07T12:18:20Z</firstFound>
<lastFound>2018-03-08T06:20:10Z</lastFound>
</HostAssetVuln>
...
</list>
</vuln>
<processor>
<list>
<HostAssetProcessor>
<name>Intel Core i5</name>
<speed>2600</speed>
</HostAssetProcessor>
</list>
</processor>
<volume>
<list>
<HostAssetVolume>
<name>/</name>
<size>975312896</size>
<free>104348560</free>
</HostAssetVolume>
</list>
</volume>
<account>
<list>
<HostAssetAccount>
<username>_mbsetupuser</username>
</HostAssetAccount>
<HostAssetAccount>
<username>_uucp</username>
</HostAssetAccount>
...
</list>
</account>
<networkInterface>
<list>
<HostAssetInterface>
<interfaceName>en0</interfaceName>
<macAddress>38:c9:86:3b:fd:26</macAddress>
<type>LOCAL</type>
<address>fe80:0:0:0:0:0:0:1</address>
<gatewayAddress>10.113.196.1</gatewayAddress>
</HostAssetInterface>
<HostAssetInterface>
<hostname>shwetas-Mac-mini.local</hostname>
<interfaceName>en0</interfaceName>
<macAddress>38:c9:86:3b:fd:26</macAddress>
<type>LOCAL</type>
<address>10.113.196.203</address>
<gatewayAddress>10.113.196.1</gatewayAddress>
</HostAssetInterface>
...
</list>
</networkInterface>
</HostAsset>
</data>
</ServiceResponse>
XSD
<platform API server>/qps/xsd/2.0/am/hostasset.xsd