VM Scan Summary

/api/2.0/fo/scan/vm/summary/?action=list

[GET]  [POST]

This API can be used as an alternative to the original Scan Summary API. It’s easier to use, has more filter options and enhanced output content.

This API helps you to identify hosts that were scanned or not scanned and why. You can choose to get a scan summary for a particular scan by specifying the scan reference ID or for all scans launched since a certain date/time or within a date range.

This API will return details for all scans. Note, however, that the output will not include the <SCAN_RESULTS> block if the scan did not return results for some reason.

Permissions - Manager role is required.

Input Parameters

Parameter

Description

action=list

(Required) The list action is required.

output_format=xml

(Optional) The only supported output format at this time is XML.

scan_reference={value}

(Optional) Specifies a unique scan reference ID. Use this option to include scan summary information for a single scan only. For VM scans, the scan reference has the format scan/987654321.98765.

One of these parameters must be specified in the request: scan_datetime_since or scan_reference. You cannot specify scan_reference in the same request as scan_datetime_since and scan_datetime_until.

scan_datetime_since={value}

(Optional) Include scans started since a certain date. The date must be less than or equal to today’s date. Specify the date in GMT timezone in RFC 3339 format: yyyy-mm-ddThh-mm-ssZ. Example: 2020-10-01T09:30:48Z

One of these parameters must be specified in the request: scan_datetime_since or scan_reference. You cannot specify scan_datetime_since in the same request as scan_reference.

scan_datetime_until={value}

(Optional) Include scans started up to a certain date. The date must be more than or equal to scan_datetime_since, and less than or equal to today’s date. Specify the date in GMT timezone in RFC 3339 format: yyyy-mm-ddThh-mm-ssZ. Example: 2020-10-01T09:30:48Z

The parameter scan_datetime_until can only be specified when scan_datetime_since is also specified. You cannot specify scan_datetime_until in the same request as scan_reference.

include_scan_input={0|1}

(Optional) By default, scan input information is included in the XML output in the <SCAN_INPUT> block. Specify include_scan_input=0 if you don’t want this entire block to appear in the output. Scan input information includes the scan title, user login (for user who launched the scan), whether or not the scan was scheduled, scan target, network, option profile, etc.

include_scan_details={0|1}

(Optional) By default, scan details are included in the XML output in the <SCAN_DETAILS> block. Specify include_scan_details=0 if you don’t want this entire block to appear in the output. Scan details include the scan status, launch date/time, and scan duration.

include_hosts_summary={0|1}

(Optional) By default, hosts summary information is included in the XML output in the <HOSTS> block under <SCAN_RESULTS>. Specify include_hosts_summary=0 if you don’t want the <HOSTS> block to appear in the output. The hosts summary shows the total number of hosts scanned, and lists the IP addresses, DNS hostnames and NetBIOS hostnames in the scan.

include_detections_summary={0|1}

(Optional) By default, detections summary information is included in the XML output in the <DETECTIONS> block under <SCAN_RESULTS>. Specify include_detections_summary=0 if you don’t want the <DETECTIONS> block to appear in the output. The detections summary includes the total number of detections, and the number of detections by severity for confirmed, potential and information gathered.

include_hosts_summary_categories={value}

(Optional) When unspecified, all categories are included in the XML output. To filter the categories, provide a comma-separated list of the categories to include in the output.

Possible values are: scanned, excluded, cancelled, unresolved, duplicate, not_vulnerable, dead, aborted, blocked, failed_slice, exceeded_scan_duration.

See "Host Summary Categories" below for more information on each category. Each category appears a block inside <SCAN_RESULTS> <HOSTS>. If a category is filtered out, the respective category block does not appear in the output.

Host Summary Categories

Category

Description

Scanned

The hosts were scanned successfully.

Excluded

The hosts were excluded. Hosts may be excluded on a per scan basis (by the user launching or scheduling the scan) or globally for all scans. Managers and Unit Managers have privileges to edit the global excluded hosts list for the subscription.

Cancelled

Hosts were not scanned because the scan was cancelled. Scans may be cancelled by a user, by an administrator or automatically by the service as specified in scheduled scan settings.

Unresolved

Hosts were scanned but they could not be reported because the NetBIOS or DNS hostname, whichever tracking method is specified for each host, could not be resolved.

Duplicate

The hosts were duplicated within a single segment/slice of the scan job. For example, two different hostnames resolving to the same IP with tracking by IP.

Not Vulnerable

Hosts were found to be not vulnerable during host discovery without having to run a full scan. This could happen for example if the list of QIDs to be scanned are limited to certain ports and those ports are found to be closed.

Dead

The hosts were not “alive” at the time of the scan, meaning that they did not respond to probes sent by the scanning engine, and the option to Scan Dead Hosts was not enabled.

Aborted

The scan was abruptly discontinued. This is a rare occurrence that may be caused for different reasons. For example, it's possible that a connection timed out or there were connection errors on a particular port or the scan time elapsed.

Blocked

Hosts were blocked from scanning for some reason. For example, user provided blacklisted IPs to scan and after the scan was launched it was blocked due to improper configuration.

Failed Slice Hosts

The scan failed for these hosts.

Exceeded Scan Duration

Applicable when the Maximum Scan Duration per Asset feature is enabled and a maximum scan duration is specified in the option profile used for the scan. This setting determines how long a scan can run on a single asset. The scan on these hosts exceeded the scan duration allowed so the scan on these hosts was aborted.

Sample 1 - Get scan summary by scan reference

API request

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

"http://qualysapi.qualys.com/api/2.0/fo/scan/vm/summary/?action=list&include_scan_input=1&include_hosts_summary=1&output_format=xml&include_detections_summary=1&scan_reference=scan/9876543210.12345"

XML output

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

<!DOCTYPE SCAN_SUMMARY_OUTPUT SYSTEM "http://qualysapi.qualys.com/api/2.0/fo/scan/vm/summary/output.dtd">

<SCAN_SUMMARY_OUTPUT>

    <RESPONSE>

        <DATETIME>2020-09-15T09:09:36Z</DATETIME>

        <SCAN_SUMMARY_LIST>

            <SCAN_SUMMARY>

                <SCAN_REFERENCE>scan/9876543210.12345</SCAN_REFERENCE>

                <SCAN_INPUT>

                    <TITLE>CustomAgScan</TITLE>

                    <USER>

                        <USERNAME>qualys_joe</USERNAME>

                    </USER>

                    <SCHEDULED>0</SCHEDULED>

                    <SCAN_DATETIME>2020-04-01 06:55:55</SCAN_DATETIME>

                    <NETWORK>

                        <ID>63010</ID>

                        <NAME>Custom Network</NAME>

                    </NETWORK>

                    <OPTION_PROFILE>

                        <ID>86395</ID>

                        <NAME>Initial Options</NAME>

                    </OPTION_PROFILE>

                    <TARGETS>

                        <IP_LIST>

                            <COUNT>256</COUNT>

                            <IP_DATA>

                                <RANGES>

                                    <RANGE>11.1.1.0-11.1.1.255</RANGE>

                                </RANGES>

                            </IP_DATA>

                        </IP_LIST>

                        <DNS_LIST>

                            <COUNT>3</COUNT>

                            <DNS_DATA>

                                <DNS_CSV>sample2.com,sample3.com,sample1.com</DNS_CSV>

                            </DNS_DATA>

                        </DNS_LIST>

                        <NETBIOS_LIST>

                            <COUNT>3</COUNT>

                            <NETBIOS_DATA>

                                <NETBIOS_CSV>NB1.COM,NB3.COM,NB2.COM</NETBIOS_CSV>

                            </NETBIOS_DATA>

                        </NETBIOS_LIST>

                        <ASSET_GROUP_LIST>

                            <COUNT>1</COUNT>

                            <ASSET_GROUP_DATA>

                                <ASSET_GROUP>

                                    <ID>206216</ID>

                                    <NAME>Custom Network Asset Group</NAME>

                                </ASSET_GROUP>

                            </ASSET_GROUP_DATA>

                        </ASSET_GROUP_LIST>

                    </TARGETS>

                </SCAN_INPUT>

                <SCAN_DETAILS>

                    <STATUS>ERROR</STATUS>

                    <LAUNCH_DATETIME>2020-04-01 06:55:55</LAUNCH_DATETIME>

                    <DURATION>1261</DURATION>

                </SCAN_DETAILS>

                <SCAN_RESULTS>

                    <HOSTS>

                        <COUNT>262</COUNT>

                        <HOSTS_DATA>

                            <SCANNED>

                                 <IP_LIST>

                                    <COUNT>9</COUNT>

                                    <IP_DATA>

                                        <RANGES>

                                            <RANGE>43.56.78.111-43.56.78.119</RANGE>

                                        </RANGES>

                                    </IP_DATA>

                                </IP_LIST>

                            </SCANNED>

                            <FAILED_SLICE_HOSTS>

                                <IPV4_LIST>

                                    <COUNT>8</COUNT>

                                    <IPV4_DATA>

                                        <IPV4_CSV>10.10.10.1,10.20.10.10-10.20.10.13,10.10.10.3,10.20.10.7,10.10.10.8,10.20.10.11</IPV4_CSV>

                                    </IPV4_DATA>

                                </IPV4_LIST>

                                <IPV6_LIST>

                                    <COUNT>2</COUNT>

                                    <IPV6_DATA>

                                        <IPV6_CSV>::ff01,::ff02,::ff02</IPV6_CSV>

                                    </IPV6_DATA>

                                </IPV6_LIST>

                                <DNS_LIST>

                                    <COUNT>4</COUNT>

                                    <DNS_DATA>

                                        <DNS_CSV>sample4.com, sample5.com, sample6.com, sample7.com</DNS_CSV>

                                    </DNS_DATA>

                                </DNS_LIST>

                                <NETBIOS_LIST>

                                    <COUNT>4</COUNT>

                                    <NETBIOS_DATA>

                                        <NETBIOS_CSV>WIN2KB, SATEELITE,WIN4KB, KRWSDG</NETBIOS_CSV>

                                    </NETBIOS_DATA>

                                </NETBIOS_LIST>

                            </FAILED_SLICE_HOSTS>                        </HOSTS_DATA>

                    </HOSTS>

                    <DETECTIONS>

                        <IG>

                            <TOTAL_COUNT>7216</TOTAL_COUNT>

                            <COUNT_BY_SEVERITY>

                                <SEVERITY_1>4467</SEVERITY_1>

                                <SEVERITY_2>2232</SEVERITY_2>

                                <SEVERITY_3>517</SEVERITY_3>

                                <SEVERITY_4>0</SEVERITY_4>

                                <SEVERITY_5>0</SEVERITY_5>

                            </COUNT_BY_SEVERITY>

                        </IG>

                        <VULN>

                            <CONFIRMED>

                                <TOTAL_COUNT>8054</TOTAL_COUNT>

                                <COUNT_BY_SEVERITY>

                                    <SEVERITY_1>238</SEVERITY_1>

                                    <SEVERITY_2>985</SEVERITY_2>

                                    <SEVERITY_3>2124</SEVERITY_3>

                                    <SEVERITY_4>2546</SEVERITY_4>

                                    <SEVERITY_5>2161</SEVERITY_5>

                                </COUNT_BY_SEVERITY>

                            </CONFIRMED>

                            <POTENTIAL>

                                <TOTAL_COUNT>1497</TOTAL_COUNT>

                                <COUNT_BY_SEVERITY>

                                    <SEVERITY_1>17</SEVERITY_1>

                                    <SEVERITY_2>420</SEVERITY_2>

                                    <SEVERITY_3>579</SEVERITY_3>

                                    <SEVERITY_4>304</SEVERITY_4>

                                    <SEVERITY_5>177</SEVERITY_5>

                                </COUNT_BY_SEVERITY>

                            </POTENTIAL>

                        </VULN>

                    </DETECTIONS>

                </SCAN_RESULTS>

            </SCAN_SUMMARY>

        </SCAN_SUMMARY_LIST>

    </RESPONSE>

</SCAN_SUMMARY_OUTPUT>

Sample 2 - Get scan summary by scan date

API request

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

"https://qualysapi.qualys.com/api/2.0/fo/scan/vm/summary/?action=list&output_format=xml&scan_datetime_since=2020-04-06T02:30:00Z&scan_datetime_until=2020-04-06T02:30:00Z"

XML output

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

<!DOCTYPE SCAN_SUMMARY_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/scan/vm/summary/output.dtd">

<SCAN_SUMMARY_OUTPUT>

  <RESPONSE>

    <DATETIME>2020-09-22T05:02:40Z</DATETIME>

    <SCAN_SUMMARY_LIST>

      <SCAN_SUMMARY>

        <SCAN_REFERENCE>scan/1234567890.12345</SCAN_REFERENCE>

        <SCAN_INPUT>

          <TITLE>My-Scan</TITLE>

          <USER>

            <USERNAME>qualys_joe</USERNAME>

          </USER>

          <SCHEDULED>0</SCHEDULED>

          <SCAN_DATETIME>2020-04-06 07:17:45</SCAN_DATETIME>

          <NETWORK>

            <ID>0</ID>

            <NAME>Global Default Network</NAME>

          </NETWORK>

          <OPTION_PROFILE>

            <ID>2171</ID>

            <NAME>Initial Options</NAME>

          </OPTION_PROFILE>

          <TARGETS>

            <IP_LIST>

              <COUNT>3</COUNT>

              <IP_DATA>

                <RANGES>

                  <RANGE>10.10.30.10-10.10.30.12</RANGE>

                </RANGES>

              </IP_DATA>

            </IP_LIST>

          </TARGETS>

        </SCAN_INPUT>

        <SCAN_DETAILS>

          <STATUS>FINISHED</STATUS>

          <LAUNCH_DATETIME>2020-04-06 07:17:45</LAUNCH_DATETIME>

          <DURATION>21656</DURATION>

        </SCAN_DETAILS>

        <SCAN_RESULTS>

          <HOSTS>

            <COUNT>3</COUNT>

            <HOSTS_DATA>

              <SCANNED>

                <IP_LIST>

                  <COUNT>2</COUNT>

                  <IP_DATA>

                    <RANGES>

                      <RANGE>10.10.30.10-10.10.30.11</RANGE>

                    </RANGES>

                  </IP_DATA>

                </IP_LIST>

              </SCANNED>

              <DEAD>

                <IP_LIST>

                  <COUNT>1</COUNT>

                  <IP_DATA>

                    <IP_CSV>10.10.30.12</IP_CSV>

                  </IP_DATA>

                </IP_LIST>

              </DEAD>

              <FAILED_SLICE_HOSTS>

               <IPV4_LIST>

                 <COUNT>8</COUNT>

                 <IPV4_DATA>

                   <IPV4_CSV>10.10.10.1,10.20.10.10-10.20.10.13,10.10.10.3,10.20.10.7,10.10.10.8,10.20.10.11</IPV4_CSV>

                 </IPV4_DATA>

              </IPV4_LIST>

              <IPV6_LIST>

                <COUNT>2</COUNT>

                <IPV6_DATA>

                <IPV6_CSV>::ff01,::ff02,::ff02</IPV6_CSV>

              </IPV6_DATA>

              </IPV6_LIST>

              <DNS_LIST>

                <COUNT>4</COUNT>

              <DNS_DATA>

                 <DNS_CSV>sample1.com, sample2.com, sample3.com, sample4.com</DNS_CSV>

              </DNS_DATA>

              </DNS_LIST>

              <NETBIOS_LIST>

                <COUNT>4</COUNT>

              <NETBIOS_DATA>

              <NETBIOS_CSV>SAMPLE1, SAMPLE2, SAMPLE3, SAMPLE4</NETBIOS_CSV>

               </NETBIOS_DATA>

               </NETBIOS_LIST>

              </FAILED_SLICE_HOSTS>

            </HOSTS_DATA>

          </HOSTS>

          <DETECTIONS>

            <IG>

              <TOTAL_COUNT>77</TOTAL_COUNT>

              <COUNT_BY_SEVERITY>

                <SEVERITY_1>52</SEVERITY_1>

                <SEVERITY_2>12</SEVERITY_2>

                <SEVERITY_3>5</SEVERITY_3>

                <SEVERITY_4>2</SEVERITY_4>

                <SEVERITY_5>6</SEVERITY_5>

              </COUNT_BY_SEVERITY>

            </IG>

            <VULN>

              <CONFIRMED>

                <TOTAL_COUNT>17</TOTAL_COUNT>

                <COUNT_BY_SEVERITY>

                  <SEVERITY_1>0</SEVERITY_1>

                  <SEVERITY_2>3</SEVERITY_2>

                  <SEVERITY_3>10</SEVERITY_3>

                  <SEVERITY_4>0</SEVERITY_4>

                  <SEVERITY_5>4</SEVERITY_5>

                </COUNT_BY_SEVERITY>

              </CONFIRMED>

              <POTENTIAL>

                <TOTAL_COUNT>18</TOTAL_COUNT>

                <COUNT_BY_SEVERITY>

                  <SEVERITY_1>2</SEVERITY_1>

                  <SEVERITY_2>4</SEVERITY_2>

                  <SEVERITY_3>10</SEVERITY_3>

                  <SEVERITY_4>1</SEVERITY_4>

                  <SEVERITY_5>1</SEVERITY_5>

                </COUNT_BY_SEVERITY>

              </POTENTIAL>

            </VULN>

          </DETECTIONS>

        </SCAN_RESULTS>

      </SCAN_SUMMARY>

...

Sample 3 - Filter list of categories in output

API request

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

"https://qualysapi.qualys.com/api/2.0/fo/scan/vm/summary/?action=list&output_format=xml&scan_reference=scan/1234567890.12345&include_hosts_summary_categories=cancelled"

XML output

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

<!DOCTYPE SCAN_SUMMARY_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/scan/vm/summary/output.dtd">

<SCAN_SUMMARY_OUTPUT>

  <RESPONSE>

    <DATETIME>2020-09-22T05:07:05Z</DATETIME>

    <SCAN_SUMMARY_LIST>

      <SCAN_SUMMARY>

        <SCAN_REFERENCE>scan/1234567890.12345</SCAN_REFERENCE>

        <SCAN_INPUT>

          <TITLE>My-Scan-2</TITLE>

          <USER>

            <USERNAME>qualys_joe</USERNAME>

          </USER>

          <SCHEDULED>0</SCHEDULED>

          <SCAN_DATETIME>2020-08-06 03:52:30</SCAN_DATETIME>

          <NETWORK>

            <ID>1000</ID>

            <NAME>My-Custom-Network</NAME>

          </NETWORK>

          <OPTION_PROFILE>

            <ID>2134</ID>

            <NAME>Initial Options</NAME>

          </OPTION_PROFILE>

          <TARGETS>

          </TARGETS>

        </SCAN_INPUT>

        <SCAN_DETAILS>

          <STATUS>CANCELED</STATUS>

          <LAUNCH_DATETIME>2020-08-06 03:52:30</LAUNCH_DATETIME>

          <DURATION>10</DURATION>

        </SCAN_DETAILS>

        <SCAN_RESULTS>

          <HOSTS>

            <COUNT>4</COUNT>

            <HOSTS_DATA>

              <CANCELLED>

                <IP_LIST>

                  <COUNT>2</COUNT>

                  <IP_DATA>

                    <IP_CSV>10.10.25.232, 10.10.25.240</IP_CSV>

                  </IP_DATA>

                </IP_LIST>

                <DNS_LIST>

                  <COUNT>2</COUNT>

                  <DNS_DATA>

                    <DNS_CSV>dns1.qualys.com,dns2.qualys.com</DNS_CSV>

                  </DNS_DATA>

                </DNS_LIST>

              </CANCELLED>

            </HOSTS_DATA>

          </HOSTS>

          <DETECTIONS>

            <IG>

              <TOTAL_COUNT>0</TOTAL_COUNT>

              <COUNT_BY_SEVERITY>

                <SEVERITY_1>0</SEVERITY_1>

                <SEVERITY_2>0</SEVERITY_2>

                <SEVERITY_3>0</SEVERITY_3>

                <SEVERITY_4>0</SEVERITY_4>

                <SEVERITY_5>0</SEVERITY_5>

              </COUNT_BY_SEVERITY>

            </IG>

            <VULN>

              <CONFIRMED>

                <TOTAL_COUNT>0</TOTAL_COUNT>

                <COUNT_BY_SEVERITY>

                  <SEVERITY_1>0</SEVERITY_1>

                  <SEVERITY_2>0</SEVERITY_2>

                  <SEVERITY_3>0</SEVERITY_3>

                  <SEVERITY_4>0</SEVERITY_4>

                  <SEVERITY_5>0</SEVERITY_5>

                </COUNT_BY_SEVERITY>

              </CONFIRMED>

              <POTENTIAL>

                <TOTAL_COUNT>0</TOTAL_COUNT>

                <COUNT_BY_SEVERITY>

                  <SEVERITY_1>0</SEVERITY_1>

                  <SEVERITY_2>0</SEVERITY_2>

                  <SEVERITY_3>0</SEVERITY_3>

                  <SEVERITY_4>0</SEVERITY_4>

                  <SEVERITY_5>0</SEVERITY_5>

                </COUNT_BY_SEVERITY>

              </POTENTIAL>

            </VULN>

          </DETECTIONS>

        </SCAN_RESULTS>

      </SCAN_SUMMARY>

    </SCAN_SUMMARY_LIST>

  </RESPONSE>

</SCAN_SUMMARY_OUTPUT>

DTD

<platform API server>/api/2.0/fo/scan/vm/summary/output.dtd