List Scanner Appliances
Click to view navigation pane

List Scanner Appliances

GET POST/api/2.0/fo/appliance/?action=list

List scanner appliances (all types such as physical, virtual, offline, etc) in the user's account. This API is available to Express Lite users when Internal Scanning is enabled in the user's account.

Input ParametersInput Parameters

Parameter

Required/Optional

Data Type

Description

action=list

Required

 String 

Specify action to list scanner appliances.

echo_request={0|1}

Optional

 Integer

Specify 1 to view (echo) input parameters in the XML output. By default these are not included.

output_mode={brief|full}

Optional

 Boolean 

The amount of detail provided for each scanner appliance in the output: brief (default) or full.

The "brief" output includes this information for each appliance: appliance ID, friendly name, software version, the number of running scans, and heartbeat check status (online or offline).

The "full" output includes the full appliance information, including the same details available in the Qualys user interface.

scan_detail={0|1}

Optional

 Integer 

Set to 1 to include scan details for scans currently running on the scanner appliance. Set to 0 (default) to not include scan details. Scan detail includes scan ID, title, scan reference, scan type and scan date.

include_cloud_info={0|1}

Optional

 Integer 

When specified output_mode=full is required) Set to 1 to include cloud information in the output for virtual scanner appliances deployed on cloud platforms e.g. Amazon EC2, Microsoft Azure Cloud Platform and Google Cloud Platform. Set to 0 (default) to not include cloud info.

busy={0|1}

Optional

 Integer 

By default all scanner appliances in the user account are shown. Set to 0 to show only appliances which are not currently running scans. Set to 1 (default) to show only appliances which are currently running scans.

scan_ref={value}

Optional

 String 

Specify a scan reference code to show only the scanner appliances running a particular scan. You may enter a valid scan reference code for a currently running scan.

The scan reference code starts with a string that identifies the scan type: "scan/" for a vulnerability scan, "compliance/" for a compliance scan, "was/" for a web application scan, "qscap/" for an FDCC scan, or "map/" for a network map.

name={string}

Optional

 String 

List only scanner appliances (physical and virtual) that have names matching the string provided. Tip - Substring match is supported. For example, if you have 2 appliances named "myscanner" and "anotherscanner" and you supply the string "name=scan" both appliance both appliances will be returned in the XML output.

ids={id1,id2,...}

Optional

 Integer 

List only scanner appliances (physical and virtual) that have certain IDs. Multiple IDs are comma separated.

include_license_info={0|1}

Optional

  

Set to 1 to return virtual scanner license information in the XML output. This tells you the number of licenses you have and the number used. This information is not returned by default. When specified the XML output will include the LICENSE_INFO element.

type={physical|virtual|offline}

Optional

 Boolean 

Type of scanner appliances: physical, virtual, offline. Type appears when output_mode=full is specified in API request.

platform_provider

Optional

 String 

Specify a platform to show scanners deployed on that platform. The valid values are: ec2, ec2_compat, gce, azure, vCenter.

ec2 - Amazon EC2, ec2_compat - OpenStack, gce - Google Cloud Platform, azure - Microsoft Azure Cloud Platform, vCenter - VMware vCenter

Sample - Brief Details With License InfoSample - Brief Details With License Info

API Request

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -d"action=list&echo_request=1&ids=777,1127,1131&include_license_info=1""https://<qualys_base_url>/api/2.0/fo/appliance/"

XML Output

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE APPLIANCE_LIST_OUTPUT SYSTEM
"https://<qualys_base_url>/api/2.0/fo/appliance/appliance_list_output.dtd">
<APPLIANCE_LIST_OUTPUT>
    <RESPONSE>
        <DATETIME>2018-05-02T09:26:01Z</DATETIME>
        <APPLIANCE_LIST>
            <APPLIANCE>
                <ID>777</ID>
                <NAME>scanner1</NAME>
                <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>
                <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>
                <STATUS>Online</STATUS>
            </APPLIANCE>
            <APPLIANCE>
                <ID>1127</ID>
                <NAME>scanner2</NAME>
                <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>
                <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>
                <STATUS>Online</STATUS>
            </APPLIANCE>
            <APPLIANCE>
                <ID>1131</ID>
                <NAME>scanner3</NAME>
                <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>
                <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>
                <STATUS>Offline</STATUS>
            </APPLIANCE>
        </APPLIANCE_LIST>
        <LICENSE_INFO>
            <QVSA_LICENSES_COUNT>10</QVSA_LICENSES_COUNT>
            <QVSA_LICENSES_USED>3</QVSA_LICENSES_USED>
        </LICENSE_INFO>
    </RESPONSE>
</APPLIANCE_LIST_OUTPUT>

Sample - Full Details and Cloud Info for Amazon EC2Sample - Full Details and Cloud Info for Amazon EC2

API Request

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -d"action=list&include_cloud_info=1&output_mode=full""https://<qualys_base_url>/api/2.0/fo/appliance/"

XML Output

...
        <IS_CLOUD_DEPLOYED>1</IS_CLOUD_DEPLOYED>
        <CLOUD_INFO>
          <PLATFORM_PROVIDER>ec2</PLATFORM_PROVIDER>
          <EC2_INFO>
            <INSTANCE_ID>i-02441120f4e14e32c</INSTANCE_ID>
            <INSTANCE_TYPE>m3.medium</INSTANCE_TYPE>
            <AMI_ID>ami-2d4ed53a</AMI_ID>
            <ACCOUNT_ID>205767712438</ACCOUNT_ID>
            <INSTANCE_REGION>US East (N. Virginia)</INSTANCE_REGION>
            <INSTANCE_AVAILABILITY_ZONE>us-east-1c</INSTANCE_AVAILABILITY_ZONE>
            <INSTANCE_ZONE_TYPE>Classic</INSTANCE_ZONE_TYPE>
            <IP_ADDRESS_PRIVATE>10.181.43.219</IP_ADDRESS_PRIVATE>
            <HOSTNAME_PRIVATE>ip-10-181-43-219.ec2.internal</HOSTNAME_PRIVATE>
            <API_PROXY_SETTINGS>
              <SETTING>Enabled</SETTING>
              <PROXY>
                <PROTOCOL>http</PROTOCOL>
                <IP_ADDRESS>1.1.1.1</IP_ADDRESS>
                <HOSTNAME>test_hostname.com</HOSTNAME>
                <PORT>234</PORT>
                <USER>*****</USER>
              </PROXY>
            </API_PROXY_SETTINGS>
          </EC2_INFO>
        </CLOUD_INFO>
...

Sample - Full Details Showing the Appliance Type and the Specifications Regarding CPU, Memory, and RegionSample - Full Details Showing the Appliance Type and the Specifications Regarding CPU, Memory, and Region

To access the CPU, memory, and region information for a scanner appliance, you need to contact your Technical Account Manager or Qualys support and get this feature enabled for your subscription.

API Request

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -d"action=list&output_mode=full""https://<qualys_base_url>/api/2.0/fo/appliance/"

XML Output

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE APPLIANCE_LIST_OUTPUT SYSTEM "https://<qualys_base_url>/api/2.0/fo/appliance/appliance_list_output.dtd">
<APPLIANCE_LIST_OUTPUT>
    <RESPONSE>
        <DATETIME>2017-08-31T09:14:49Z</DATETIME>
        <APPLIANCE_LIST>
            <APPLIANCE>
                <ID>132455</ID>
                <UUID>6ae4efce-0c5e-e227-82e0-1b7f55f1b98b</UUID>
                <NAME>VS_ND_1</NAME>
                <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>
                <RUNNING_SLICES_COUNT>0</RUNNING_SLICES_COUNT>
                <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>
                <STATUS>Offline</STATUS>
                <MODEL_NUMBER>cvscanner</MODEL_NUMBER>
                <TYPE>Virtual</TYPE>
                <SERIAL_NUMBER>0</SERIAL_NUMBER>
                <ACTIVATION_CODE>15440265032293</ACTIVATION_CODE>
                <INTERFACE_SETTINGS>
                    <INTERFACE>lan</INTERFACE>
                    <IP_ADDRESS>1.1.1.1</IP_ADDRESS>
                    <NETMASK>128.0.0.0</NETMASK>
                    <GATEWAY>128.0.0.0</GATEWAY>
                    <LEASE>Static</LEASE>
                    <IPV6_ADDRESS></IPV6_ADDRESS>
                    <SPEED></SPEED>
                    <DUPLEX>Unknown</DUPLEX>
                    <DNS>
                        <DOMAIN></DOMAIN>
                        <PRIMARY>128.0.0.0</PRIMARY>
                        <SECONDARY>128.0.0.0</SECONDARY>
                    </DNS>
                </INTERFACE_SETTINGS>
...
   <MAX_CAPACITY_UNITS></MAX_CAPACITY_UNITS>
   <CPU_INFO>Intel(R) Xeon(R) CPU E5-2699 v3 @2.30GHz</CPU_INFO>
   <MEMORY_INFO>2,070,484 MB</MEMORY_INFO>
   <REGION_INFO></REGION_INFO>
...

Sample - Full Details With IPv6 VLANs, Static RoutesSample - Full Details With IPv6 VLANs, Static Routes

<IPV6_SLAAC /> indicates that ipv6_auto was specified for auto-configuring IPv6 using SLAAC on the VLAN.

API Request

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -d "action=list&echo_request=1&output_mode=full&ids=126209" "https://<qualys_base_url>/api/2.0/fo/appliance/"

XML Output

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE APPLIANCE_LIST_OUTPUT SYSTEM "https://<qualys_base_url>/api/2.0/fo/appliance/appliance_list_output.dtd">
<APPLIANCE_LIST_OUTPUT>
  <REQUEST>
    <DATETIME>2018-07-20T12:10:48Z</DATETIME>
...
  <RESPONSE>
    <DATETIME>2018-07-20T12:10:48Z</DATETIME>
    <APPLIANCE_LIST>
      <APPLIANCE>
        <ID>126209</ID>
...
        <VLANS>
          <SETTING>Enabled</SETTING>
          <VLAN>
            <ID>3456</ID>
            <NAME>Name3456</NAME>
            <IP_ADDRESS>12.12.12.12</IP_ADDRESS>
            <NETMASK>255.255.255.0</NETMASK>
            <IPV6_ADDRESS>fdd1:0:1:107::500</IPV6_ADDRESS>
          </VLAN>
          <VLAN>
            <ID>9012</ID>
            <NAME>Name9012</NAME>
            <IP_ADDRESS>244.244.244.244</IP_ADDRESS>
            <NETMASK>255.255.255.0</NETMASK>
            <IPV6_SLAAC />
          </VLAN>
          <VLAN>
            <ID>5678</ID>
            <NAME>Name5678</NAME>
            <IP_ADDRESS>123.123.123.123</IP_ADDRESS>
            <NETMASK>255.255.255.255</NETMASK>
          </VLAN>
          <VLAN>
            <ID>1234</ID>
            <NAME>Name1234</NAME>
            <IPV6_ADDRESS>fdd1:0:1:108::500</IPV6_ADDRESS>
          </VLAN>
        </VLANS>
        <STATIC_ROUTES>
          <ROUTE>
            <NAME>Name1</NAME>
            <IPV6_GATEWAY>2001:470:8418:280d::1</IPV6_GATEWAY>
            <IPV6_ADDRESS>fdd1:0:1:107::500</IPV6_ADDRESS>
            <IPV6_NETWORK>fdd1:0:1:107::/64</IPV6_NETWORK>
          </ROUTE>
          <ROUTE>
            <NAME>Name5</NAME>
            <IPV6_GATEWAY>2001:470:8418:280d::1</IPV6_GATEWAY>
            <IPV6_ADDRESS>fdd1:0:1:107::500</IPV6_ADDRESS>
          </ROUTE>
        </STATIC_ROUTES>
        ...
      </APPLIANCE>
    </APPLIANCE_LIST>
  </RESPONSE>
</APPLIANCE_LIST_OUTPUT>

DTD

<platform API server>/api/2.0/fo/appliance/appliance_list_output.dtd