Terry McCorkle

QualysGuard® API Release Version 8.0 - 30 day notification

Blog Post created by Terry McCorkle on Mar 20, 2014

This update to QualysGuard 8.0 includes improvements to the QualysGuard API, allowing you to integrate your programs and API calls with QualysGuard Vulnerability Management (VM) and QualysGuard Policy Compliance (PC).

 

What’s New

VM - “Security Risk Score” summary added to XML and CSV reports

VM & PC - "Network Support API” Updates

 

QualysGuard API Server URL. The QualysGuard API documentation and sample code use the API server URL for QualysGuard US Platform 1. If your account is located on another platform, please replace this URL with the appropriate server URL for your account.

 

Account  Location

API  Server URL for login
QualysGuard  US Platform https://qualysapi.qualys.com

QualysGuard  US Platform 2

https://qualysapi.qg2.apps.qualys.com

QualysGuard  EU Platformhttps://qualysapi.qualys.eu
QualysGuard  @Customerhttps://qualysapi.<customer_base_url>

 

QualysGuard API Documentation. API user guides and other documentation are available in your account’s Resources section (Help > Resources > API). Note: The service enforces limits on the API calls users can make within a subscription. See “QualysGuard API Limits” for details.

 

VM - “Security Risk Score” summary added to  XML and CSV reports

With this release vulnerability scan reports include a security risk score summary for the report and per host, in all report formats - earlier this was not in XML or  CSV. As before the risk score summary appears when your report template is configured for host based findings (automatic data) and the Text Summary option is selected. The asset_data_report.dtd was updated - we’ll show you the changes.

 

Tell me about the Security Risk Score. The score for the overall report is the average security risk for all hosts in the report. The score for each host is the average severity level detected (the default) or the highest severity level detected. Managers can configure the calculation method for the subscription by going to Reports > Setup > Security Risk. Are you an Express Lite user? If yes the average severity level is always used.

 

Sample reports. These reports were created using a scan report template configured with host based findings and Text Summary is selected (under Display > Detailed Results).

 

CSV report:

New rows show you the security risk score summary for the report and per host.

8.0Image.png

 

XML report:

New XML elements show you the security risk summary for the report (see  <RISK_SCORE_SUMMARY>)  and per host <see RISK_SCORE_PER_HOST>.

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE ASSET_DATA_REPORT SYSTEM "https://qualysguard.qualys.com/asset_data_report.dtd">
<ASSET_DATA_REPORT>
  <HEADER>
    <COMPANY><![CDATA[Qualys, Inc.]]></COMPANY>
    <USERNAME>USERNAME</USERNAME>
    <GENERATION_DATETIME>2014-03-11T23:56:22Z</GENERATION_DATETIME>
    ...
    <RISK_SCORE_SUMMARY>
      <TOTAL_VULNERABILITIES>14</TOTAL_VULNERABILITIES>
      <AVG_SECURITY_RISK>2.6</AVG_SECURITY_RISK>
      <BUSINESS_RISK>13/100</BUSINESS_RISK>
    </RISK_SCORE_SUMMARY>
  </HEADER>
<RISK_SCORE_PER_HOST>
  <HOSTS>
    <IP_ADDRESS>10.10.24.104</IP_ADDRESS>
    <TOTAL_VULNERABILITIES>4</TOTAL_VULNERABILITIES>
    <SECURITY_RISK>2.5</SECURITY_RISK>
  </HOSTS>
  <HOSTS>
    <IP_ADDRESS>10.10.24.106</IP_ADDRESS>
    <TOTAL_VULNERABILITIES>10</TOTAL_VULNERABILITIES>
    <SECURITY_RISK>2.6</SECURITY_RISK>
  </HOSTS>
</RISK_SCORE_PER_HOST>
  <HOST_LIST>
    <HOST>
      <IP>10.10.24.104</IP>
      <TRACKING_METHOD>IP</TRACKING_METHOD>
...

 

DTD updates:

You’ll see the updated asset_data_report.dtd below. There’s  new elements RISK_SCORE_PER_HOST and RISK_SCORE_SUMMARY.

<!-- QUALYS ASSET DATA REPORT DTD -->

<!ELEMENT ASSET_DATA_REPORT (ERROR | (HEADER, RISK_SCORE_PER_HOST?, HOST_LIST?, GLOSSARY?, APPENDICES?))>


<!ELEMENT ERROR (#PCDATA)*>
<!ATTLIST ERROR number CDATA #IMPLIED>




<!-- HEADER -->


<!ELEMENT HEADER (COMPANY, USERNAME, GENERATION_DATETIME, TEMPLATE,
                  TARGET, RISK_SCORE_SUMMARY?)>


<!ELEMENT COMPANY (#PCDATA)>
<!ELEMENT USERNAME (#PCDATA)>
<!ELEMENT GENERATION_DATETIME (#PCDATA)>
<!ELEMENT TEMPLATE (#PCDATA)>
<!ELEMENT TARGET (USER_ASSET_GROUPS?, USER_IP_LIST?, COMBINED_IP_LIST?, 
                  ASSET_TAG_LIST?)>


<!ELEMENT USER_ASSET_GROUPS (ASSET_GROUP_TITLE+)>
<!ELEMENT ASSET_GROUP_TITLE (#PCDATA)>


<!ELEMENT USER_IP_LIST (RANGE*)>
<!ELEMENT RANGE (START, END)>
<!ELEMENT START (#PCDATA)>
<!ELEMENT END (#PCDATA)>


<!ELEMENT COMBINED_IP_LIST (RANGE*)>


<!ELEMENT ASSET_TAG_LIST (INCLUDED_TAGS, EXCLUDED_TAGS?)>


<!ELEMENT INCLUDED_TAGS (ASSET_TAG*)>
<!ATTLIST INCLUDED_TAGS scope CDATA #IMPLIED>


<!ELEMENT EXCLUDED_TAGS (ASSET_TAG*)>
<!ATTLIST EXCLUDED_TAGS scope CDATA #IMPLIED>


<!-- AVERAGE RISK_SCORE_SUMMARY -->
<!ELEMENT RISK_SCORE_SUMMARY (TOTAL_VULNERABILITIES, AVG_SECURITY_RISK,
                              BUSINESS_RISK)>
<!ELEMENT TOTAL_VULNERABILITIES (#PCDATA)>
<!ELEMENT AVG_SECURITY_RISK (#PCDATA)>
<!ELEMENT BUSINESS_RISK (#PCDATA)>


<!-- RISK_SCORE_PER_HOST -->
<!ELEMENT RISK_SCORE_PER_HOST (HOSTS+)>
<!ELEMENT HOSTS (IP_ADDRESS, TOTAL_VULNERABILITIES, SECURITY_RISK)>
<!ELEMENT IP_ADDRESS (#PCDATA)>
<!ELEMENT SECURITY_RISK (#PCDATA)>


<!-- HOST_LIST -->


<!ELEMENT HOST_LIST (HOST+)>
...

 

VM & PC - Network Support API Updates

 

We made some updates to the Network Support API for QualysGuard 8.0. You’ll find the latest information integrated into this user guide. You might like to review the latest changes below.

 

Set Up Networks

 

Scanner Appliance List API v2 - filter by network ID

The Scanner Appliance List API v2 (resource /api/2.0/fo/appliance/ with action=list) returns scanner appliances in your account. Now you can use the new input parameter “network_id” (optional) to return a list of scanner appliances for a certain network. Specify 0 for the Global Default Network or a custom network ID.

 

For example:

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

"https://qualysapi.qualys.com/api/2.0/fo/appliance/?action=list&network_id=1002"

 

Organize Assets by Network

 

Asset Group List API v1 - network ID added to group’s IPs

The Asset Group List API v1 (/msp/asset_group_list.php) is used to retrieve a list of asset groups in your account. We added a new attribute “network_id” to the subelement /SCANIPS/IP in the XML output (asset_group_list.dtd). This appears for an All asset group that is not the same as the subscription’s All asset group.

 

Have multiple All asset groups? Yes you might. There is always 1 All asset group for the subscription - this includes all assets, visible to Managers. If you have business units, there is 1 unique All asset group for each business unit. If you have Scanners and/or Readers, there is 1 unique All asset group for each Scanner/Reader account. (There is no All asset group for a network.)

 

Sample XML output:

Sample XML output showing an All asset group that is not the subscription’s All asset group:

...
<ASSET_GROUP>
  <ID>5010</ID>
  <TITLE><![CDATA[All]]></TITLE>
  <SCANIPS>
    <IP network_id="0"> 10.0.0.0-10.10.10.11</IP>
    <IP network_id="0"> 10.10.10.13-10.10.10.247</IP>
    <IP network_id="1193"> 10.0.0.0-10.10.10.11</IP>
    <IP network_id="1193"> 10.10.10.13-10.10.10.247</IP>
...

 

DTD update:

New “network_id” attribute added to the subelement /IP.

...
<!ELEMENT IP (#PCDATA)>
<!ATTLIST IP network_id CDATA "0">
...

 

Asset Management

Support for IP List API v2

The IP List API v2 (resource /api/2.0/fo/asset/ip/ with action=list) is used to retrieve a list of IP addresses in your account. The XML output now lists the network ID for each IP address/range when the request is made by a sub-user with access to multiple networks. We added a new attribute “network_id” to the subelements /IP_SET/IP and /IP_SET/IP_RANGE in the XML output (ip_list_output.dtd).

 

Good to know:

 

  • Managers will not see the “network_id” attribute for any IP or IP_RANGE elements in the output since Managers can see all IPs for all networks.
  • Any sub-user with access to only a single network (the Global Default Network or a custom network) will not see the “network_id” attribute either. This is for consistency with the UI, where these users do not see the network workflows.

 

Sample XML output:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE IP_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/asset/ip/ip_list_output.dtd">
<IP_LIST_OUTPUT>
  <RESPONSE>
    <DATETIME>2014-02-14T22:47:32Z</DATETIME>
    <IP_SET>
      <IP_RANGE network_id="0">1.0.0.0-10.10.10.14</IP_RANGE>
      <IP_RANGE network_id="0">10.10.10.17-10.10.10.29</IP_RANGE>
      <IP network_id="0">10.10.10.32</IP>
    </IP_SET>
  </RESPONSE>
</IP_LIST_OUTPUT>

 

 

DTD updates:

New “network_id” attribute added to the subelements /IP_SET/IP and /IP_SET/IP_RANGE.

...
<!ELEMENT IP_SET ((IP|IP_RANGE)+)>
<!ELEMENT IP (#PCDATA)>
<!ATTLIST IP
  network_id  CDATA  "0"
>
<!ELEMENT IP_RANGE (#PCDATA)>
<!ATTLIST IP_RANGE
  network_id  CDATA  "0"
>
...

 

Support for Excluded IP List API v2

The Excluded IP List API v2 (/api/2.0/fo/asset/excluded_ip/ with action=list) returns a list of excluded hosts.

 

Use the new input parameter “network_id” (optional) to return a list of excluded IPs for a certain network.

 

The XML output now identifies the network ID for each IP address/range when your subscription has at least 1 network defined. We added a new attribute “network_id” to the subelements /IP_SET/IP and /IP_SET/IP_RANGE in the XML output (ip_list_output.dtd).

 

Sample XML output:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE IP_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/asset/excluded_ip/ip_list_output.dtd">
<IP_LIST_OUTPUT>
  <RESPONSE>
    <DATETIME>2014-03-20T20:49:19Z</DATETIME>
    <IP_SET>
      <IP network_id="0">10.10.10.19</IP>
      <IP_RANGE network_id="1275">10.10.50.6-10.10.50.10</IP_RANGE>
    </IP_SET>
  </RESPONSE>
</IP_LIST_OUTPUT>

 

DTD updates:

New “network_id” attribute added to the subelements /IP_SET/IP and /IP_SET/IP_RANGE.

...
<!ELEMENT IP_SET ((IP|IP_RANGE)+)>
<!ELEMENT IP (#PCDATA)>
<!ATTLIST IP
  network_id  CDATA  "0"
>
<!ELEMENT IP_RANGE (#PCDATA)>
<!ATTLIST IP_RANGE
  network_id  CDATA  "0"
>
...

 

Support for Excluded IP Change History API v2

The excluded IP change history V2 API (/api/2.0/fo/asset/excluded_ip/history/ with action=list) returns a change history for excluded hosts.

 

Use the new input parameter “network_id” (optional) to return a list of excluded IPs for a certain network.

 

The XML output now identifies the network ID for each IP address/range when your subscription has at least 1 network defined. We added a new attribute “network_id” to the subelements /IP_SET/IP and /IP_SET/IP_RANGE in the XML output (history_list_output.dtd).

 

Sample XML output:

...
 <HISTORY_LIST>
      <HISTORY>
        <ID>1441</ID>
        <IP_SET>
          <IP_RANGE network_id="0">10.10.10.234-10.10.10.235</IP_RANGE>
        </IP_SET>
        <ACTION>Added</ACTION>
...

 

DTD updates:

New “network_id” attribute added to the subelements /IP_SET/IP and /IP_SET/IP_RANGE.

...
<!ELEMENT IP_SET ((IP|IP_RANGE)+)>
<!ELEMENT IP (#PCDATA)>
<!ATTLIST IP
    network_id  CDATA  "0"
>           
<!ELEMENT IP_RANGE (#PCDATA)>
<!ATTLIST IP_RANGE
    network_id  CDATA  "0"
>
...

Outcomes