Purge hosts in your account to remove the assessment data associated with them.
Purging hosts will remove host based data in the user’s account (scan results will not be removed). Purged host information will not appear in new reports generated by users. One or both types of host data is removed, based on the user’s API request: vulnerability data and compliance data.
Managers can purge assessment data for all hosts in the subscription, including vulnerability data and/or compliance data.
Auditors can purge compliance data only for all compliance hosts in the subscription (vulnerability data will not be removed).
Unit Managers, Scanners, and Readers can purge vulnerability data and/or compliance data in their user account if granted the permission “Purge host information/history”. The permission “Manage compliance” is required to purge compliance data.
Express Lite - This API is available to Express Lite users.
The input parameter “data_scope” allows you to specify the type of data to purge from a host. Specify “vm” to purge vulnerability data, “pc” to purge compliance data, or “vm,pc” (irrespective of order) to purge both types of data.
You can also use the input parameter “compliance_enabled” to purge compliance data along with vulnerability data or vulnerability data only. This option does not allow you to purge compliance data only.
You can combine compliance_enabled and data_scope in the same request. Note, however, that anytime compliance_enabled=1 is specified, then both vulnerability and compliance data is purged regardless of the data_scope value. See the table below to understand the different combinations and the type of data purged.
|
compliance_enabled value |
data_scope value |
type of data purged |
|---|---|---|
|
1 |
unspecified |
vulnerability + compliance data |
|
0 |
unspecified |
vulnerability data only |
|
unspecified or 0 |
vm |
vulnerability data only |
|
unspecified or 0 |
pc |
compliance data only |
|
unspecified or 0 |
vm,pc |
vulnerability + compliance data |
|
1 |
vm |
vulnerability + compliance data |
|
1 |
pc |
vulnerability + compliance data |
|
1 |
vm,pc |
vulnerability + compliance data |
|
Parameter |
Required/Optional |
Data Type |
Description |
|---|---|---|---|
|
action=purge |
Required | String |
The POST method should be used to purge the assets. |
|
echo_request={0|1} |
Optional | Integer |
Specify 1 to view input parameters in the XML output. When unspecified, parameters are not included in the XML output. |
|
ids={value} |
Optional | Integer |
Purge host information for certain host IDs/ranges. One or more host IDs/ranges may be specified. Multiple entries are comma separated. A host ID range is specified with a hyphen (for example, 190-400).Valid host IDs are required. One of these host selection parameters must be specified in an API request: ids, ips, ag_ids or ag_titles. Multiple host selection parameters may be specified together in the same request. |
|
ips={value} |
Optional | Integer |
Purge host information certain IP addresses/ranges. One or more IPs/ranges may be specified. Multiple entries are comma separated. An IP range is specified with a hyphen (for example, 10.10.10.1-10.10.10.100). One of these host selection parameters must be specified in an API request: ids, ips, ag_ids or ag_titles. Multiple host selection parameters may be specified together in the same request. |
|
ag_ids={value} |
Optional | Integer |
Purge hosts belonging to asset groups with certain IDs. One or more asset group IDs and/or ranges may be specified. Multiple entries are comma separated. A range is specified with a dash (for example, 386941-386945). Valid asset group IDs are required. One of these host selection parameters must be specified in an API request: ids, ips, ag_ids or ag_titles. Multiple host selection parameters may be specified together in the same request. These parameters are mutually exclusive and cannot be specified together: ag_ids and ag_titles. |
|
ag_titles={value} |
Optional | String |
Purge hosts belonging to asset groups with certain strings in the asset group title. One or more asset group titles may be specified. Multiple entries are comma separated (for example, My+First+Asset+Group,Another+Asset+Group). One of these parameters must be specified in an API request: ids, ips, ag_ids or ag_titles. Multiple host selection parameters may be specified together in the same request. These parameters are mutually exclusive and cannot be specified together: ag_ids and ag_titles. |
|
network_ids={value} |
Optional, and valid only when the Network Support feature is enabled for the user’s account | Integer |
Restrict the request to certain custom network IDs. Multiple network IDs are comma separated. |
|
no_vm_scan_since={date} |
Optional | Integer |
Purge hosts not scanned since a certain date and time (optional). The date/time is specified in YYYY-MM-DD[THH:MM:SSZ] format (UTC/GMT), like “2007-07-01” or “2007-01-25T23:12:00Z”. User Permissions: An Auditor cannot specify this parameter. |
|
no_compliance_scan_since={date} |
Optional | Integer |
Purge compliance hosts not scanned since a certain date and time (optional). This parameter is invalid for an Express Lite user. The date/time is specified in YYYY-MM-DD[THH:MM:SSZ] format (UTC/GMT), like “2007-07-01” or “2007-01-25T23:12:00Z”. User Permissions: A sub-account (Unit Manager, Scanner or Reader) can specify this parameter only when the user account is granted certain permissions to purge compliance information. |
|
data_scope={value} |
Optional | Boolean |
The type of data to purge. Specify “vm” to purge vulnerability data, specify “pc” to purge compliance data, or specify both as a comma separated list to purge both types of data. If compliance_enabled=1 is specified in the same request, then vulnerability and compliance data will both be purged regardless of the data_scope value. |
|
compliance_enabled={0|1} |
Optional | Integer |
This parameter is valid only when the policy compliance module is enabled for the user account. Specify 1 to purge compliance hosts in the user’s account. These hosts are assigned to the PC module. When selected, the service will remove vulnerability data and compliance data associated with the selected hosts. Specify 0 to purge hosts which are not assigned to the PC module. When specified (without data_scope), the service will remove only vulnerability information associated with the selected hosts. Note: A sub-account (Unit Manager, Scanner or Reader) can specify this parameter only when the user account is granted permissions to purge compliance information. An Auditor does not have permission to set compliance_enabled=0. |
|
os_pattern={expression} |
Optional | String |
Purge only hosts which have an operating system matching a certain regular expression. An empty value cannot be specified. Use “%5E%24” to match empty string. Important: The regular expression string you enter must follow the PCRE standard and it must be URL encoded. Sample regular expression strings for matching OS names: Check API Sample 17 Qualys API - Host List Detection API samples (GitHub) Click here for info on PCRE format. |
API Request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With: curl" -X "POST" -d "action=purge&ips=10.20.32.152&data_scope=pc" "https://<qualys_base_url>/api/2.0/fo/asset/host/"XML Output
<!DOCTYPE BATCH_RETURN SYSTEM "https://<qualys_base_url>/api/2.0/batch_return.dtd">
<BATCH_RETURN>
<RESPONSE>
<DATETIME>2020-11-19T10:51:57Z</DATETIME>
<BATCH_LIST>
<BATCH>
<TEXT>Hosts Queued (compliance data) for Purging</TEXT>
<ID_SET>
<ID>3971339</ID>
</ID_SET>
</BATCH>
</BATCH_LIST>
</RESPONSE>
</BATCH_RETURN>API Request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With: curl" -X "POST" -d "action=purge&ips=10.20.32.152&data_scope=vm" "https://<qualys_base_url>/api/2.0/fo/asset/host/"XML Output
<!DOCTYPE BATCH_RETURN SYSTEM "https://<qualys_base_url>/api/2.0/batch_return.dtd">
<BATCH_RETURN>
<RESPONSE>
<DATETIME>2020-11-19T10:51:45Z</DATETIME>
<BATCH_LIST>
<BATCH>
<TEXT>Hosts Queued (vulnerability data) for Purging</TEXT>
<ID_SET>
<ID>3971339</ID>
</ID_SET>
</BATCH>
</BATCH_LIST>
</RESPONSE>
</BATCH_RETURN>API Request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With: curl" -X "POST" -d "action=purge&ips=10.20.32.152&data_scope=pc,vm" "https://<qualys_base_url>/api/2.0/fo/asset/host/"XML Output
<!DOCTYPE BATCH_RETURN SYSTEM "https://<qualys_base_url>/api/2.0/batch_return.dtd">
<BATCH_RETURN>
<RESPONSE>
<DATETIME>2020-11-19T10:52:12Z</DATETIME>
<BATCH_LIST>
<BATCH>
<TEXT>Hosts Queued (vulnerability + compliance data) for Purging</TEXT>
<ID_SET>
<ID>3971339</ID>
</ID_SET>
</BATCH>
</BATCH_LIST>
</RESPONSE>
</BATCH_RETURN>In this example, compliance_enabled=1 and data_scope=pc. Both vulnerability and compliance data will be purged for the host since compliance_enabled=1 takes precedence.
API Request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With: curl" -X "POST" -d "action=purge&ips=10.20.32.154&compliance_enabled=1&data_scope=vm" "https://<qualys_base_url>/api/2.0/fo/asset/host/"XML Output
<!DOCTYPE BATCH_RETURN SYSTEM
"https://<qualys_base_url>/api/2.0/batch_return.dtd">
<BATCH_RETURN>
<RESPONSE>
<DATETIME>2020-11-19T11:25:12Z</DATETIME>
<BATCH_LIST>
<BATCH>
<TEXT>Hosts Queued (vulnerability + compliance data) for
Purging</TEXT>
<ID_SET>
<ID>3971340</ID>
</ID_SET>
</BATCH>
</BATCH_LIST>
</RESPONSE>
</BATCH_RETURN>In this example, compliance_enabled=0 and data_scope=vm so only vulnerability data will be purged.
API Request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With: curl" -X "POST" -d "action=purge&ips=10.20.32.154&compliance_enabled=0&data_scope=vm" "https://<qualys_base_url>/api/2.0/fo/asset/host/" XML Output
<!DOCTYPE BATCH_RETURN SYSTEM
"https://<qualys_base_url>/api/2.0/batch_return.dtd">
<BATCH_RETURN>
<RESPONSE>
<DATETIME>2020-11-19T11:25:12Z</DATETIME>
<BATCH_LIST>
<BATCH>
<TEXT>Hosts Queued (vulnerability data) for Purging</TEXT>
<ID_SET>
<ID>3971340</ID>
</ID_SET>
</BATCH>
</BATCH_LIST>
</RESPONSE>
</BATCH_RETURN><platform API server>/api/2.0/fo/asset/host/dtd/purge/output.dtd