Host Detection List

/api/2.0/fo/asset/host/vm/detection/?action=list

[GET]  [POST]

Download a list of hosts with the hosts latest vulnerability data, based on the host based scan data available in the user’s account. This data brings a lot of value to customers because they provide the latest complete vulnerability status for the hosts (NEW, ACTIVE, FIXED, REOPENED) and history information.

The Host List VM Detection API also shows the Qualys Detection Score (QDS) for each detection record in the API output and allows users to filter the output based on the QDS.

The Qualys Detection Score (QDS) is assigned to vulnerabilities detected by Qualys. QDS is derived from multiple contributing factors, including vulnerability technical details (e.g. CVSS score), vulnerability temporal details (e.g. external threat intelligence like exploit code maturity), and remediation controls applied to mitigate the risk from the vulnerability.

QDS has a range from 1 to 100 with these severity levels:

- Critical (90-100)

- High (70-89)

- Medium (40-69)

- Low (1-39)

Permissions - Managers view all VM scanned hosts in subscription. Auditors have no permission to view VM scanned hosts. Unit Managers view VM scanned hosts in user’s business unit. Scanners and Readers view VM scanned hosts in user’s account.

Express Lite - This API is available to Express Lite users.

Input Parameters

The input parameter action=list is required. All other input parameters are optional. Several filtering parameters are provided for filtering hosts and QIDs. When multiple filter parameters are specified, the service combines the effects of all the parameters in a way that corresponds to a logical “AND”. So if two filter parameters are specified in the request, the service returns hosts that match both filters.

Quick Links: Detection Filters | Host Filters | QID Filters | Asset Tags | Qualys Detection Score (QDS) | AWS EC2/Azure/GCP Metadata

API Request

Parameter

Description

action=list

(Required)

echo_request={0|1}

(Optional) Specify 1 to view input parameters in the XML output. When unspecified, parameters are not included in the XML output.

show_asset_id={0|1}

(Optional) When specified, we show the asset ID of the scanned hosts in the output. The default value of this parameter is set to 0. When set to 0, we do not show the asset id information for the scanned hosts.

include_vuln_type={confirmed|potential}

Optional)Use to download vulnerability information based on their type, confirmed or potential. Specify:

include_vuln_type=confirmed to download only confirmed vulnerabilities.

include_vuln_type=potential to download only potential vulnerabilities.

 

Exceptional Scenarios

 • After passing the parameter value include_vuln_type=confirmed, some potential vulnerabilities may show up in the API response. This happens when the vulnerability type for the QID is modified in the Qualys KnowledgeBase.

 • After passing the parameter value include_vuln_type=potential, some confirmed vulnerabilities show up in the API response. • This happens with the vulnerabilities assigned with a half red/half yellow severity level.

• This happens when the vulnerability type for the QID is changed while running the authenticated scan. It is because of various factors affecting scan results.

Detection Filters

Parameter

Description

show_results={0|1}

(Optional) When not specified, results are included in the output. Specify show_results=0 to exclude the results. If you exclude the results, CSV will have an empty Results column, and XML will not contain the Results tag.

show_reopened_info={0|1}

(Optional) When not specified, reopened info for reopened vulnerabilities is not included in the output. Specify show_reopened_info=1 to include reopened info i.e. first/last reopened date, times reopened.

arf_kernel_filter=
{0|1|2|3|4}

(Optional) Identify vulnerabilities found on running or non-running Linux kernels.

Good to Know - It’s possible that multiple kernels are detected on a single Linux host. You’ll notice the scan results report the running kernel on each Linux host in Info Gathered QID 45097.

When unspecified, vulnerabilities are not filtered based on kernel activity. <AFFECT_RUNNING_KERNEL> does not appear in the output.

When set to 0, vulnerabilities are not filtered based on kernel activity. <AFFECT_RUNNING_KERNEL> appears in the output for kernel related vulnerabilities.

When set to 1, exclude kernel related vulnerabilities that are not exploitable (found on non-running kernels). <AFFECT_RUNNING_KERNEL> appears in the output for kernel related vulnerabilities.

When set to 2, only include kernel related vulnerabilities that are not exploitable (found on non-running kernels). <AFFECT_RUNNING_KERNEL> appears in the output with a value of 0 for each detection.

When set to 3, only include kernel related vulnerabilities that are exploitable (found on running kernels). <AFFECT_RUNNING_KERNEL> appears in the output with a value of 1 for each detection.

When set to 4, only include kernel related vulnerabilities. <AFFECT_RUNNING_KERNEL> appears in the output with a value of 0 or 1 for each detection.

Note that active_kernels_only is deprecated and will be removed in a future release. Please use arf_kernel_filter instead.

arf_service_filter=
{0|1|2|3|4}

(Optional) Identify vulnerabilities found on running or non-running ports/services.

When unspecified, vulnerabilities are not filtered based on running ports/services. <AFFECT_RUNNING_SERVICE> does not appear in the output.

When set to 0, vulnerabilities are not filtered based on running ports/services. <AFFECT_RUNNING_SERVICE> appears in the output for service related vulnerabilities.

When set to 1, exclude service related vulnerabilities that are exploitable (found on running ports/services). <AFFECT_RUNNING_SERVICE> appears in the output for service related vulnerabilities that have a value of 1.

When set to 2, only include service related vulnerabilities that are exploitable (found on running ports/services). <AFFECT_RUNNING_SERVICE> appears in the output with a value of 0 for each detection.

When set to 3, only include service related vulnerabilities that are not exploitable (found on non-running ports/services). <AFFECT_RUNNING_SERVICE> appears in the output with a value of 1 for each detection.

When set to 4, only include service related vulnerabilities. <AFFECT_RUNNING_SERVICE> appears in the output with a value of 0 or 1 for each detection.

arf_config_filter=
{0|1|2|3|4}

(Optional) Identify vulnerabilities that may or may not be exploitable due to the current host configuration.

When unspecified, vulnerabilities are not filtered based on host configuration. <AFFECT_EXPLOITABLE_CONFIG> does not appear in the output.

When set to 0, vulnerabilities are not filtered based on host configuration. <AFFECT_EXPLOITABLE_CONFIG> appears in the output for config related vulnerabilities.

When set to 1, exclude vulnerabilities that are exploitable due to host configuration. <AFFECT_EXPLOITABLE_CONFIG> appears in the output for config related detections that have a value of 1.

When set to 2, only include config related vulnerabilities that are exploitable. <AFFECT_EXPLOITABLE_CONFIG> appears in the output with a value of 0 for each detection.

When set to 3, only include config related vulnerabilities that are not exploitable. <AFFECT_EXPLOITABLE_CONFIG> appears in the output with a value of 1 for each detection.

When set to 4, only include config related vulnerabilities. <AFFECT_EXPLOITABLE_CONFIG> appears in the output with a value of 0 or 1 for each detection.

active_kernels_only=
{0|1|2|3}

(Optional) Identify vulnerabilities related to running and non-running kernels in the output in the tag <AFFECT_RUNNING_KERNEL>.

Good to Know - It’s possible that multiple kernels are detected on a single Linux host. You’ll notice the scan results report the running kernel on each Linux host in Information Gathered QID 45097.

When unspecified, vulnerabilities are not filtered based on kernel activity. <AFFECT_RUNNING_KERNEL> does not appear in the output for kernel related vulnerabilities.

When set to 0, vulnerabilities are not filtered based on kernel activity. <AFFECT_RUNNING_KERNEL> appears in the output for kernel related vulnerabilities.

When set to 1, exclude vulnerabilities found on non-running Linux kernels. <AFFECT_RUNNING_KERNEL> appears in the output for kernel related vulnerabilities.

When set to 2, only include vulnerabilities found on non-running Linux kernels. <AFFECT_RUNNING_KERNEL> appears in the output with a value of 0 for all vulnerabilities.

When set to 3, only include vulnerabilities found on running Linux kernels. <AFFECT_RUNNING_KERNEL> appears in the output with a value of 1 for all vulnerabilities.

Note that active_kernels_only is deprecated and will be removed in a future release. Please use arf_kernel_filter instead.

output_format={value}

 

(Optional)  Specifies the format of the host detection list output. When not specified, the output format is XML. Valid values are: XML, CSV or CSV_NO_METADATA, CSV_NO_METADATA_MS_EXCEL and CSV_MS_EXCEL

XML (default) - Specifies XML format for the output.

CSV - Specifies CSV format for the output. The output is structured in these sections: HEADER_CSV (lists input parameters specified during the list request if echo_request=1 is also specified), BODY_CSV (lists host records matching filters) and FOOTER_CSV (lists status messages and truncation details, if applicable).

CSV_NO_METADATA - Specifies CSV format for the output with no metadata. In this case, the output will not be structured with header, body and footer sections, and will not indicate whether the list is truncated.

CSV_NO_METADATA_MS_EXCEL - When specified we will use CSV format for the output with no metadata with MS Excel restrictions on the maximum length allowed for a string value in the output.

CSV_MS_EXCEL - When specified we will use CSV format for the output with MS Excel restriction on the maximum length allowed for a string value in the output. A value in the output will be truncated if the length of the value exceeds the maximum length supported in MS Excel.

suppress_duplicated_
data_from_csv={0|1}

(Optional) By default or when set to 0, host details will be repeated in each line of detection information in the CSV output. When set to 1, host details will not be repeated (suppressed) in each detection line.

This parameter must be specified with: output_format=CSV or output_format=CSV_NO_METADATA.

truncation_limit={value}

(Optional)  Specifies the maximum number of host records processed per request. When not specified, the truncation limit is set to 1000 host records. You may specify a value less than the default (1-999) or greater than the default (1001-1000000). Specify 0 for no truncation limit.

If the requested list identifies more host records than the truncation limit and output_format=XML, then the XML output includes the <WARNING> element and the URL for making another request for the next batch of host records.

If the requested list identifies more host records than the truncation limit and output_format=CSV, then the CSV output includes “Truncated” in the FOOTER_CSV section and the URL for making another request for the next batch of host records.

Check API samples (2, 4, 16)

Qualys API - Host List Detection API samples (GitHub)

max_days_since_
detection_updated={value}

(Optional) Show only detections whose detection status changed since some maximum number of days you specify. For detections that have never changed the maximum number of days is applied to the last detection date.

One of these parameters may be specified in the same request: detection_updated_since, max_days_since_detection_updated

detection_updated_
since={value}

(Optional) Show only detections whose detection status changed after a certain date and time. For detections that have never changed the date is applied to the last detection date. Valid date format is: YYYY-MMDD[THH:MM:SSZ] format (UTC/GMT), like “2017-02-15” or “2017-02-15T23:15:00Z”.

Tip: You can use this parameter in conjunction with the detection_updated_before parameter to limit the detections shown to a specific date range.

One of these parameters may be specified in the same request: detection_updated_since, max_days_since_detection_updated

detection_updated_
before={value}

(Optional) Show only detections whose detection status changed before a certain date and time. Valid date format is: YYYY-MMDD[THH:MM:SSZ] format (UTC/GMT), like “2017-02-15” or “2017-02-15T23:15:00Z”.

Tip: You can use this parameter in conjunction with the detection_updated_since parameter to limit the detections shown to a specific date range.

One of these parameters may be specified in the same request: detection_updated_since, max_days_since_detection_updated

detection_processed_
before={date}

(Optional) Show detections with vulnerability scan results rocessed before a certain date and time. Specify the date in YYY-MMDD[THH:MM:SSZ] format (UTC/GMT), like “2016-09-12” or “2016-09-12T23:15:00Z”.

detection_processed_
after={date}

(Optional) Show detections with vulnerability scan results processed after a certain date and time. Specify the date in YYYY-MMDD[ THH:MM:SSZ] format (UTC/GMT), like “2016-09-12” or “2016-09-12T23:15:00Z”.

detection_last_
tested_since={date}

(Optional) Show only detections that were last tested on or after a certain date and time. Valid date format is: YYYY-MM-DD[THH:MM:SSZ] format (UTC/GMT), like

“2018-07-01” or “2018-01-25T23:12:00Z”.

You can use this parameter in conjunction with detection_last_tested_before or detection_last_tested_before_days to limit the detections shown to a date range.

This parameter cannot be specified in the same request as detection_last_tested_since_days.

detection_last_
tested_since_days={value}

(Optional) Show only detections that were last tested within the number of days you specify. For example, show detections last tested in the past 10 days.

You can use this parameter in conjunction with detection_last_tested_before or detection_last_tested_before_days to limit the detections shown to a specific date range.

This parameter cannot be specified in the same request as detection_last_tested_since.

detection_last_
tested_before={date}

(Optional) Show only detections that were last tested before a certain date and time. Valid date format is: YYYY-MM-DD[THH:MM:SSZ] format (UTC/GMT), like

“2018-07-01” or “2018-01-25T23:12:00Z”.

You can use this parameter in conjunction with detection_last_tested_since or detection_last_tested_since_days to limit the detections shown to a specific date range.

This parameter cannot be specified in the same request as detection_last_tested_before_days.

detection_last_
tested_before_days={value}

(Optional) Show only detections that were last tested before the number of days you specify. For example, show detections last tested more than 30 days ago.

You can use this parameter in conjunction with detection_last_tested_since or detection_last_tested_since_days to limit the detections shown to a specific date range.

This parameter cannot be specified in the same request as detection_last_tested_before.

Host Filters

Parameter

Description

ids={value}

(Optional) Show only 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.

id_min={value}

(Optional) Show only hosts which have a minimum host ID value.

id_max={value}

(Optional) Show only hosts which have a maximum host ID value. A valid host ID is required.

ips={value}

(Optional) Show only 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).

ipv6={value}

(Optional) A valid IPv6 address. Multiple entries are comma separated.

If ipv6 is used as filter parameter then other target input filter parameters are not accepted.

ag_ids={value}

(Optional) Show only 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.

The ag_ids and ag_titles parameters are mutually exclusive and cannot be specified together in the same request.

ag_titles={value}

(Optional) Show only 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).

The ag_ids and ag_titles parameters are mutually exclusive and cannot be specified together in the same request.

network_ids={value}

(Optional, and valid only when the Network Support feature is enabled for the user’s account)

Restrict the request to certain custom network IDs. Multiple network IDs are comma separated.

vm_scan_since={date}

(Optional)  Show hosts scanned and processed 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”.

This parameter cannot be specified with max_days_since_vm_scan in the same request.

no_vm_scan_since=
{date}

(Optional) Show hosts not scanned and processed 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”.

This parameter cannot be specified with max_days_since_vm_scan in the same request.

max_days_since_last_
vm_scan={value}

(Optional) Show only hosts scanned and processed in the past number of days, where the value is a number of days.

This parameter cannot be specified with any of these parameters in the same request: vm_scan_since and no_vm_scan_since.

vm_processed_
before={date}

(Optional) Show hosts with vulnerability scan results processed before a certain date and time. Specify the date in YYYY-MM-DD[THH:MM:SSZ] format (UTC/GMT), like “2016-09-12” or “2016-09-12T23:15:00Z”.

vm_processed_
after={date}

(Optional) Show hosts with vulnerability scan results processed after a certain date and time. Specify the date in YYYY-MM-DD[THH:MM:SSZ] format (UTC/GMT), like “2016-09-12” or “2016-09-12T23:15:00Z”.

vm_scan_date_
before={date}

(Optional) Show hosts with a vulnerability scan end date before a certain date and time. Specify the date in YYYY-MM-DD[THH:MM:SSZ] format (UTC/GMT), like “2016-09-12” or “2016-09-12T23:15:00Z”.

vm_scan_date_after={date}

(Optional) Show hosts with a vulnerability scan end date after a certain date and time. Specify the date in YYYY-MM-DD[THH:MM:SSZ] format (UTC/GMT), like “2016-09-12” or “2016-09-12T23:15:00Z”.

vm_auth_scan_
date_before={date}

(Optional) Show hosts with a successful authenticated vulnerability scan end date before a certain date and time. Specify the date in YYYY-MM-DD[THH:MM:SSZ] format (UTC/GMT), like “2016-09-12” or “2016-09-12T23:15:00Z”.

vm_auth_scan_
date_after={date}

(Optional) Show hosts with a successful authenticated vulnerability scan end date after a certain date and time. Specify the date in YYYY-MM-DD[THH:MM:SSZ] format (UTC/GMT), like “2016-09-12” or “2016-09-12T23:15:00Z”.

status={value}

(Optional) Show only hosts with one or more of these status values: New, Active, Re-Opened, Fixed. Multiple status values are entered as a comma-separated list.

If this parameter is not passed to the API, by default, the output contains detections with New, Active or Re-Opened <STATUS> only.

To get hosts with Fixed status, check this API sample

Qualys API - Host List Detection API samples (GitHub, sample 11)

compliance_enabled={0|1}

(Optional) This parameter is valid only when the policy compliance module is enabled for the user account. This parameter is invalid for an Express Lite user.

Specify 1 to list compliance hosts in the user’s account that have been scanned and processed. These hosts are assigned to the policy compliance module. Specify 0 to list scanned hosts which are not assigned to the policy compliance module.

os_pattern={expression}

(Optional) Show 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:

Qualys API - Host List Detection API samples (GitHub, see sample 17)

Click here for info on PCRE format.

qids={value}

(Optional) Show only detection records with certain QIDs. One or more QIDs may be specified. A range is specified with a dash (for example: 68518-68522). Multiple entries are comma separated. Valid QIDs are required.

severities={value}

(Optional) Show only detection records which have certain severities. One or more levels may be specified. A range is specified with a dash (for example: 1-3). Multiple entries are comma separated.

show_igs={0|1}

(Optional except as noted) Specify 1 to show detection records with information gathered along with confirmed vulnerabilities and potential vulnerabilities. Specify 0 (default) to hide information gathered.

The show_igs parameter is required in one use case. The parameter show_igs=1 must be specified if both these conditions are met: 1) search lists are included using the parameter include_search_list_titles or include_search_list_ids, and 2) if the included search lists contain only information gathered.

include_search_list_
titles={value}

(Optional) Show detection records only when a record’s QID is INCLUDED IN in one or more of the specified search list titles. One or more titles may be specified. Multiple titles are comma separated.

This parameter cannot be specified with any of these parameters in the same request: qids, severities or include_search_list_ids.

exclude_search_list_
titles={value}

(Optional) Show detection records only when a record’s QID is IS EXCLUDED from one or more of the specified search list titles. One or more titles may be specified. Multiple titles are comma separated.

This parameter cannot be specified with any of these parameters in the same request: qids, severities or exclude_search_list_ids.

include_search_list_
ids={value,value...}

(Optional) Show detection records only when a record’s QID IS INCLUDED in one or more of the specified search list titles. One or more IDs may be specified. A range is specified with a dash (for example: 10-15). Multiple entries are comma separated.

This parameter cannot be specified with any of these parameters in the same request: qids, severities or include_search_list_titles.

exclude_search_list_
ids={value,value...}

(Optional) Show detection records only when a record’s QID IS EXCLUDED from one or more of the specified search list titles. One or more IDs may be specified. A range is specified with a dash (for example: 40-42). Multiple entries are comma separated.

This parameter cannot be specified with any of these parameters in the same request: qids, severities or exclude_search_list_titles.

QID Filters

Parameter

Description

qids={value}

(Optional) Show only detection records with certain QIDs. One or more QIDs may be specified. A range is specified with a dash (for example: 68518-68522). Multiple entries are comma separated. Valid QIDs are required.

severities={value}

(Optional) Show only detection records which have certain severities. One or more levels may be specified. A range is specified with a dash (for example: 1-3). Multiple entries are comma separated.

show_igs={0|1}

(Optional except as noted) Specify 1 to show detection records with information gathered along with confirmed vulnerabilities and potential vulnerabilities. Specify 0 (default) to hide information gathered.

The show_igs parameter is required in one use case. The parameter show_igs=1 must be specified if both these conditions are met: 1) search lists are included using the parameter include_search_list_titles or include_search_list_ids, and 2) if the included search lists contain only information gathered.

include_search_list_titles={value}

(Optional) Show detection records only when a record’s QID is INCLUDED IN in one or more of the specified search list titles. One or more titles may be specified. Multiple titles are comma separated.

This parameter cannot be specified with any of these parameters in the same request: qids, severities or include_search_list_ids.

exclude_search_list_titles={value}

(Optional) Show detection records only when a record’s QID is IS EXCLUDED from one or more of the specified search list titles. One or more titles may be specified. Multiple titles are comma separated.

This parameter cannot be specified with any of these parameters in the same request: qids, severities or exclude_search_list_ids.

include_search_list_ids={value,value...}

(Optional) Show detection records only when a record’s QID IS INCLUDED in one or more of the specified search list titles. One or more IDs may be specified. A range is specified with a dash (for example: 10-15). Multiple entries are comma separated.

This parameter cannot be specified with any of these parameters in the same request: qids, severities or include_search_list_titles.

exclude_search_list_ids={value,value...}

(Optional) Show detection records only when a record’s QID IS EXCLUDED from one or more of the specified search list titles. One or more IDs may be specified. A range is specified with a dash (for example: 40-42). Multiple entries are comma separated.

This parameter cannot be specified with any of these parameters in the same request: qids, severities or exclude_search_list_titles.

filter_superseded_qids={0|1}

(Optional) When unspecified or set to 0, the XML output includes all QIDs even if they’ve been superseded. Specify 1 to filter out QIDs that have been superseded by another QID in the results.

Asset Tags

Parameter

Description

use_tags={0|1}

(Optional) Specify 0 (the default) if you want to select hosts based on IP addresses/ranges and/or asset groups. Specify 1 if you want to select hosts based on asset tags.

tag_set_by={id|name}

(Optional when use_tags=1) Specify “id” (the default) to select a tag set by providing tag IDs. Specify “name” to select a tag set by providing tag names.

tag_include_selector=

{any|all}

(Optional when use_tags=1) Select “any” (the default) to include hosts that match at least one of the selected tags. Select “all” to include hosts that match all of the selected tags.

tag_exclude_selector=

{any|all}

(Optional when use_tags=1) Select “any” (the default) to exclude hosts that match at least one of the selected tags. Select “all” to exclude hosts that match all of the selected tags.

tag_set_include={value}

(Optional when use_tags=1) Specify a tag set to include. Hosts that match these tags will be included. You identify the tag set by providing tag name or IDs. Multiple entries are comma separated.

tag_set_exclude={value}

(Optional when use_tags=1) Specify a tag set to exclude. Hosts that match these tags will be excluded. You identify the tag set by providing tag name or IDs. Multiple entries are comma separated.

show_tags={0|1}

(Optional) Specify 1 to display asset tags associated with each host in the XML output.

Qualys Detection Score (QDS)

Parameter

Description

show_qds={0|1}

(Optional) Specify 1 to show the QDS value in the output for each detection record. Specify 0 if you do not want to show the QDS value.

qds_min={value}

(Optional) Show only detection records with a QDS value greater than or equal to the QDS min value specified. qds_min can only be specified when show_qds=1. When qds_min and qds_max are specified in the same request, the qds_min value must be less than the qds_max value.

qds_max={value}

(Optional) Show only detection records with a QDS value less than or equal to the QDS max value specified. qds_max can only be specified when show_qds=1. When qds_min and qds_max are specified in the same request, the qds_min value must be less than the qds_max value.

show_qds_factors={0|1}

(Optional) Specify 1 to show QDS contributing factors associated with each detection record in the output. Specify 0 if you do not want to show QDS contributing factors.

 

AWS EC2/Azure/GCP Metadata

Parameter

Description

host_metadata={value}

(Optional) Specify the name of a cloud provider to show metadata of assets managed by that cloud provider. To view metadata for assets from all cloud providers, specify "all".

Valid values: all, ec2, google, azure

Note: This parameter pertains to only metadata and does not affect the inclusion or exclusion of assets.

host_metadata_fields= {value1,value2}

(Optional when host_metadata is specified) Specify metadata fields to only return data for certain attributes.

To retrieve information about the host instance type, use the metadata field, "instance-type".

show_cloud_tags={0|1}

(Optional) Specify 1 to display cloud provider tags for each scanned host asset in the output. The default value of the parameter is set to 0. When set to 0, we will not show the cloud provider tags for the scanned assets.

cloud_tag_fields={value1,value2}

(Optional when show_cloud_tags is specified) Specify cloud tags or cloud tag and name combinations to only return information for specified cloud tags. A cloud tag name and value combination is specified with a colon (for example:SomeTag6:AY_ec2). For each cloud tag, we show the cloud tag’s name, its value, and last success date (the tag last success date/time, fetched from instance).

If this parameter is not specified and "show_cloud_tags" is set to 1, we will show all the cloud provider tags for the assets.

Sample 1 - List VM scanned hosts

API request

curl -u "username:password" -H "X-Requested-With: curl" "https://qualysapi.qualys.com/api/2.0/fo/asset/host/vm/detection/?action=list"

XML output

<HOST_LIST_VM_DETECTION_OUTPUT>

  <RESPONSE>

    <DATETIME>2018-04-26T11:25:58Z</DATETIME>

    <HOST_LIST>

      <HOST>

        <ID>6506432</ID>

        <IP>10.10.10.11</IP>

        <TRACKING_METHOD>IP</TRACKING_METHOD>

        <OS><![CDATA[Windows 2008 R2 Enterprise Service Pack 1]]></OS>

        <DNS><![CDATA[2k8r2-u-10-11.sample.qualys.com]]></DNS>

        <DNS_DATA>

           <HOSTNAME><![CDATA[2k8r2-u-10-11]]></HOSTNAME>

           <DOMAIN><![CDATA[sample.qualys.com]]></DOMAIN>

           <FQDN><![CDATA[2k8r2-u-10-11.sample.qualys.com]]></FQDN>

        </DNS_DATA>

        <NETBIOS><![CDATA[2K8R2-U-10-11]]></NETBIOS>

        <LAST_SCAN_DATETIME>2018-04-13T03:49:05Z</LAST_SCAN_DATETIME>

        <LAST_VM_SCANNED_DATE>2018-04-13T03:48:50Z</LAST_VM_SCANNED_DATE>

        <LAST_VM_SCANNED_DURATION>352</LAST_VM_SCANNED_DURATION>

        <DETECTION_LIST>

          <DETECTION>

            <UNIQUE_VULN_ID>52664</UNIQUE_VULN_ID>

            <QID>38170</QID>

            <TYPE>Confirmed</TYPE>

            <SEVERITY>2</SEVERITY>

            <PORT>3389</PORT>

            <PROTOCOL>tcp</PROTOCOL>

            <SSL>1</SSL>

            <RESULTS><![CDATA[Certificate #0 CN=2k8r2-u-10-11 (2k8r2-u-10-11) doesn&apos;t resolve]]></RESULTS>

            <STATUS>Active</STATUS>

            <FIRST_FOUND_DATETIME>2018-01-26T04:45:50Z</FIRST_FOUND_DATETIME>

            <LAST_FOUND_DATETIME>2018-04-13T03:48:50Z</LAST_FOUND_DATETIME>

            <TIMES_FOUND>111</TIMES_FOUND>

            <LAST_TEST_DATETIME>2018-04-13T03:48:50Z</LAST_TEST_DATETIME>

            <LAST_UPDATE_DATETIME>2018-04-13T03:49:05Z</LAST_UPDATE_DATETIME>

            <IS_IGNORED>0</IS_IGNORED>

            <IS_DISABLED>0</IS_DISABLED>

            <LAST_PROCESSED_DATETIME>2018-04-13T03:49:05Z</LAST_PROCESSED_DATETIME>

          </DETECTION>

          <DETECTION>

            <UNIQUE_VULN_ID>52666</UNIQUE_VULN_ID>

            <QID>38173</QID>

            <TYPE>Confirmed</TYPE>

            <SEVERITY>2</SEVERITY>

            <PORT>3389</PORT>

            <PROTOCOL>tcp</PROTOCOL>

            <SSL>1</SSL>

            <RESULTS><![CDATA[Certificate #0 CN=2k8r2-u-10-11 unable to get local issuer certificate]]></RESULTS>

            <STATUS>Active</STATUS>

            <FIRST_FOUND_DATETIME>2018-01-26T04:45:50Z</FIRST_FOUND_DATETIME>

            <LAST_FOUND_DATETIME>2018-04-13T03:48:50Z</LAST_FOUND_DATETIME>

            <TIMES_FOUND>111</TIMES_FOUND>

            <LAST_TEST_DATETIME>2018-04-13T03:48:50Z</LAST_TEST_DATETIME>

            <LAST_UPDATE_DATETIME>2018-04-13T03:49:05Z</LAST_UPDATE_DATETIME>

            <IS_IGNORED>0</IS_IGNORED>

            <IS_DISABLED>0</IS_DISABLED>

            <LAST_PROCESSED_DATETIME>2018-04-13T03:49:05Z</LAST_PROCESSED_DATETIME>

          </DETECTION>

          <DETECTION>

            <UNIQUE_VULN_ID>52645</UNIQUE_VULN_ID>

            <QID>38601</QID>

            <TYPE>Confirmed</TYPE>

            <SEVERITY>2</SEVERITY>

            <PORT>3389</PORT>

            <PROTOCOL>tcp</PROTOCOL>

            <SSL>1</SSL>

            <RESULTS><![CDATA[CIPHER KEY-EXCHANGE AUTHENTICATION MAC ENCRYPTION(KEY-STRENGTH) GRADE

TLSv1 WITH RC4 CIPHERs IS SUPPORTED      

RC4-SHA RSA RSA SHA1 RC4(128) MEDIUM

RC4-MD5 RSA RSA MD5 RC4(128) MEDIUM]]></RESULTS>

            <STATUS>Active</STATUS>

            <FIRST_FOUND_DATETIME>2018-01-26T04:45:50Z</FIRST_FOUND_DATETIME>

            <LAST_FOUND_DATETIME>2018-04-13T03:48:50Z</LAST_FOUND_DATETIME>

            <TIMES_FOUND>111</TIMES_FOUND>

            <LAST_TEST_DATETIME>2018-04-13T03:48:50Z</LAST_TEST_DATETIME>

            <LAST_UPDATE_DATETIME>2018-04-13T03:49:05Z</LAST_UPDATE_DATETIME>

            <IS_IGNORED>0</IS_IGNORED>

            <IS_DISABLED>0</IS_DISABLED>

            <LAST_PROCESSED_DATETIME>2018-04-13T03:49:05Z</LAST_PROCESSED_DATETIME>

          </DETECTION>

          ...

        </DETECTION_LIST>

      </HOST>

    </HOST_LIST>

  </RESPONSE>

</HOST_LIST_VM_DETECTION_OUTPUT>

Sample 2 - Host Detection XML Output with Truncation

A truncated response is returned when the API request returns more host records than the truncation limit. In this sample, the truncation limit is set to 100 host records.

API request

curl -u "username:password" -H "X-Requested-With: curl" "https://qualysapi.qualys.com/api/2.0/fo/asset/host/vm/detection/?action=list&truncation_limit=100"

 

The Warning message in the XML output (shown below) indicates the URL you need to use to request the next 100 host records.

XML output

...

          </DETECTION>

        </DETECTION_LIST>

      </HOST>

    </HOST_LIST>

    <WARNING>

      <CODE>1980</CODE>

      <TEXT>100 record limit exceeded. Use URL to get next batch of results.</TEXT>

      <URL><![CDATA[https://qualysapi.qualys.com/api/2.0/fo/asset/host/vm/detection/?action=list&truncation_limit=100&id_min=5641289]]></URL>

    </WARNING>

  </RESPONSE>

</HOST_LIST_VM_DETECTION_OUTPUT>

Sample 3 - List assets with Qualys Detection Score (QDS)

API request

curl -u "USERNAME:PASSWORD" -H "X-Requested-With:curl"

"https://qualysapi.qualys.com/api/2.0/fo/asset/host/vm/detection/?action=list&ips=10.20.30.40,10.11.12.13&show_qds=1&qds_min=1&qds_max=20&show_ qds_factors=1"

XML output

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE HOST_LIST_VM_DETECTION_OUTPUT SYSTEM

"https://qualysapi.qualys.com/api/2.0/fo/asset/host/vm/detection/dtd/output.dtd">

<HOST_LIST_VM_DETECTION_OUTPUT>

  <RESPONSE>

    <DATETIME>2022-01-31T12:10:01Z</DATETIME>

    <HOST_LIST>       <HOST> ...

          <DETECTION>

            <UNIQUE_VULN_ID>52664</UNIQUE_VULN_ID>

            <QID>38170</QID>

            <TYPE>Confirmed</TYPE>

            <SEVERITY>2</SEVERITY>

            <PORT>443</PORT>

            <PROTOCOL>TCP</PROTOCOL

            <SSL>1</SSL>

            <RESULTS>

               <![CDATA[CCertificate #0

CN=IPMI,OU=Software,O=Super_Micro_Computer,ST=California,C=US (IPMI) doesn&apos;t resolve]]>

            </RESULTS>

            <STATUS>ACTIVE</STATUS>

            <FIRST_FOUND_DATETIME>2021-12-

29T14:09:58Z</FIRST_FOUND_DATETIME>

            <LAST_FOUND_DATETIME>2022-01-

11T13:11:20Z</LAST_FOUND_DATETIME>

            <QDS severity="LOW">5</QDS>

            <QDS_FACTORS>

                <QDS_FACTOR name="RTI">

                    <![CDATA[[No_Patch]]>

                </QDS_FACTOR>

                <QDS_FACTOR name="TEMPORAL_SCORE">

                    <![CDATA[2.1]]>

                </QDS_FACTOR>

                <QDS_FACTOR name="BASE_SCORE">

                    <![CDATA[2.6]]>

                </QDS_FACTOR>

                <QDS_FACTOR name="SEVERITY">

                    <![CDATA[2]]>

                <QDS_FACTOR name="EXPLOIT_MATURITY">

                    <![CDATA[null]]>

                </QDS_FACTOR>

                <QDS_FACTOR name="EXPLOIT_AVAILABLE">

                    <![CDATA[[poc]]]>

                </QDS_FACTOR>

                <QDS_FACTOR name="TRENDING">

                    <![CDATA[null]]>

                </QDS_FACTOR>

                <QDS_FACTOR name="MITIGATION_CONTROLS">

                    <![CDATA[null]]>

                </QDS_FACTOR>

                <QDS_FACTOR name="MALWARE_NAME">

                    <![CDATA[null]]>

                </QDS_FACTOR>

                <QDS_FACTOR name="MALWARE_HASH">

                    <![CDATA[null]]>

                </QDS_FACTOR>

                <QDS_FACTOR name="RTI">

                    <![CDATA[null]]>

                </QDS_FACTOR>

            </QDS_FACTORS>

            <TIMES_FOUND>1</TIMES_FOUND>

            <LAST_TEST_DATETIME>2021-06-03T11:18:57Z</LAST_TEST_DATETIME>

            <LAST_UPDATE_DATETIME>2021-06-

05T03:12:47Z</LAST_UPDATE_DATETIME>

            <IS_IGNORED>0</IS_IGNORED>

            <IS_DISABLED>0</IS_DISABLED>

            <LAST_PROCESSED_DATETIME>2021-06-

05T03:12:47Z</LAST_PROCESSED_DATETIME>           </DETECTION>

...

        </DETECTION_LIST>

      </HOST>

    </HOST_LIST>

  </RESPONSE>

</HOST_LIST_VM_DETECTION_OUTPUT>

Sample 4 - Download a list of hosts with the latest vulnerability data, based on vulnerability type, potential

API request

curl --location '<qualys_base_url>/api/2.0/fo/asset/host/vm/detection/?action=list&ips=11.110.11.111&include_vuln_type=potential' \

--header 'X-Requested-With: curl'

--header 'Authorization: Basic <encoded username:password string>'

XML output

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE HOST_LIST_VM_DETECTION_OUTPUT SYSTEM "<qualys_base_url>/api/2.0/fo/asset/host/vm/detection/dtd/output.dtd">

<HOST_LIST_VM_DETECTION_OUTPUT>

    <RESPONSE>

        <DATETIME>2023-08-16T11:51:13Z</DATETIME>

        <HOST_LIST>

            <HOST>

                <ID>524323</ID>

                <IP>11.110.11.111</IP>

                <TRACKING_METHOD>IP</TRACKING_METHOD>

                <OS>

                    <![CDATA[Linux 2.4-2.6 / Embedded Device / F5 Networks Big-IP]]>

                </OS>

                <LAST_SCAN_DATETIME>2019-11-08T09:15:14Z</LAST_SCAN_DATETIME>

                <LAST_VM_SCANNED_DATE>2019-11-08T06:37:29Z</LAST_VM_SCANNED_DATE>

                <DETECTION_LIST>

                    <DETECTION>

                        <UNIQUE_VULN_ID>3978356</UNIQUE_VULN_ID>

                        <QID>38469</QID>

                        <TYPE>Potential</TYPE>

                        <SEVERITY>2</SEVERITY>

                        <SSL>0</SSL>

                        <RESULTS>

                            <![CDATA[SSH-2.0-OpenSSH_3.9p1-AuthSelect-SecurID-log]]>

                        </RESULTS>

                        <STATUS>New</STATUS>

                        <FIRST_FOUND_DATETIME>2019-11-08T06:37:29Z</FIRST_FOUND_DATETIME>

                        <LAST_FOUND_DATETIME>2019-11-08T06:37:29Z</LAST_FOUND_DATETIME>

                        <TIMES_FOUND>1</TIMES_FOUND>

                        <LAST_TEST_DATETIME>2019-11-08T06:37:29Z</LAST_TEST_DATETIME>

                        <LAST_UPDATE_DATETIME>2019-11-08T09:15:14Z</LAST_UPDATE_DATETIME>

                        <IS_IGNORED>0</IS_IGNORED>

                        <IS_DISABLED>0</IS_DISABLED>

                        <LAST_PROCESSED_DATETIME>2019-11-08T09:15:14Z</LAST_PROCESSED_DATETIME>

                    </DETECTION>

                    <DETECTION>

                        <UNIQUE_VULN_ID>3978354</UNIQUE_VULN_ID>

                        <QID>38560</QID>

                        <TYPE>Potential</TYPE>

                        <SEVERITY>4</SEVERITY>

                        <SSL>0</SSL>

                        <RESULTS>

                            <![CDATA[SSH-2.0-OpenSSH_3.9p1-AuthSelect-SecurID-log]]>

                        </RESULTS>

                        <STATUS>New</STATUS>

                        <FIRST_FOUND_DATETIME>2019-11-08T06:37:29Z</FIRST_FOUND_DATETIME>

                        <LAST_FOUND_DATETIME>2019-11-08T06:37:29Z</LAST_FOUND_DATETIME>

                        <TIMES_FOUND>1</TIMES_FOUND>

                        <LAST_TEST_DATETIME>2019-11-08T06:37:29Z</LAST_TEST_DATETIME>

                        <LAST_UPDATE_DATETIME>2019-11-08T09:15:14Z</LAST_UPDATE_DATETIME>

                        <IS_IGNORED>0</IS_IGNORED>

                        <IS_DISABLED>0</IS_DISABLED>

                        <LAST_PROCESSED_DATETIME>2019-11-08T09:15:14Z</LAST_PROCESSED_DATETIME>

                    </DETECTION>

                    <DETECTION>

                        <UNIQUE_VULN_ID>3978353</UNIQUE_VULN_ID>

                        <QID>115317</QID>

                        <TYPE>Potential</TYPE>

                        <SEVERITY>3</SEVERITY>

                        <SSL>0</SSL>

                        <RESULTS>

                            <![CDATA[SSH-2.0-OpenSSH_3.9p1-AuthSelect-SecurID-log]]>

                        </RESULTS>

                        <STATUS>New</STATUS>

                        <FIRST_FOUND_DATETIME>2019-11-08T06:37:29Z</FIRST_FOUND_DATETIME>

                        <LAST_FOUND_DATETIME>2019-11-08T06:37:29Z</LAST_FOUND_DATETIME>

                        <TIMES_FOUND>1</TIMES_FOUND>

                        <LAST_TEST_DATETIME>2019-11-08T06:37:29Z</LAST_TEST_DATETIME>

                        <LAST_UPDATE_DATETIME>2019-11-08T09:15:14Z</LAST_UPDATE_DATETIME>

                        <IS_IGNORED>0</IS_IGNORED>

                        <IS_DISABLED>0</IS_DISABLED>

                        <LAST_PROCESSED_DATETIME>2019-11-08T09:15:14Z</LAST_PROCESSED_DATETIME>

                    </DETECTION>

                </DETECTION_LIST>

            </HOST>

        </HOST_LIST>

    </RESPONSE>

</HOST_LIST_VM_DETECTION_OUTPUT>

Sample 5 - Download a list of hosts with the latest vulnerability data, based on vulnerability type, confirmed

API request

curl --location '<qualys_base_url>/api/2.0/fo/asset/host/vm/detection/?action=list&ips=11 .111.11.111&include_vuln_type=confirmed' \--header 'X-Requested-With: curl'--header 'Authorization: Basic <encoded username:password string>'

XML output

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE HOST_LIST_VM_DETECTION_OUTPUT SYSTEM "<qualys_base_url>/api/2.0/fo/asset/host/vm/detection/dtd/output.dtd">

<HOST_LIST_VM_DETECTION_OUTPUT>

    <RESPONSE>

        <DATETIME>2023-08-16T13:34:18Z</DATETIME>

        <HOST_LIST>

            <HOST>

                <ID>524323</ID>

                <IP>11.111.11.111</IP>

                <TRACKING_METHOD>IP</TRACKING_METHOD>

                <OS>

                    <![CDATA[Linux 2.4-2.6 / Embedded Device / F5 Networks Big-IP]]>

                </OS>

                <LAST_SCAN_DATETIME>2019-11-08T09:15:14Z</LAST_SCAN_DATETIME>

                <LAST_VM_SCANNED_DATE>2019-11-08T06:37:29Z</LAST_VM_SCANNED_DATE>

                <DETECTION_LIST>

                    <DETECTION>

                        <UNIQUE_VULN_ID>3978355</UNIQUE_VULN_ID>

                        <QID>82054</QID>

                        <TYPE>Confirmed</TYPE>

                        <SEVERITY>2</SEVERITY>

                        <SSL>0</SSL>

                        <RESULTS>

                            <![CDATA[Tested on port 2222 with an injected SYN/RST offset by 16 bytes.]]>

                        </RESULTS>

                        <STATUS>New</STATUS>

                        <FIRST_FOUND_DATETIME>2019-11-08T06:37:29Z</FIRST_FOUND_DATETIME>

                        <LAST_FOUND_DATETIME>2019-11-08T06:37:29Z</LAST_FOUND_DATETIME>

                        <TIMES_FOUND>1</TIMES_FOUND>

                        <LAST_TEST_DATETIME>2019-11-08T06:37:29Z</LAST_TEST_DATETIME>

                        <LAST_UPDATE_DATETIME>2019-11-08T09:15:14Z</LAST_UPDATE_DATETIME>

                        <IS_IGNORED>0</IS_IGNORED>

                        <IS_DISABLED>0</IS_DISABLED>

                        <LAST_PROCESSED_DATETIME>2019-11-08T09:15:14Z</LAST_PROCESSED_DATETIME>

                    </DETECTION>

                </DETECTION_LIST>

            </HOST>

        </HOST_LIST>

    </RESPONSE>

</HOST_LIST_VM_DETECTION_OUTPUT>

More Samples

Qualys API - Host List Detection API samples  (GitHub)

Keep Alive mechanism

The service uses a “keep alive” mechanism to maintain an open connection to the Qualys server for the duration of the host detection list API request. To keep the connection alive, the service sends some “dummy” data back to the client every 30 to 40 seconds if no “real” data has been sent already by the API during that time.

In XML output, this “dummy” data appears as a “<!-- keep-alive -->” line (since comments should be safely ignored by downstream XML parsers).

In CSV and CSV_NO_METADATA output, this “dummy” data appears as a <CR><LF> (carriage return, linefeed) pair (since empty lines clearly do not contain any CSV data).

DTD

<platform API server>/api/2.0/fo/asset/host/vm/detection/dtd/output.dtd