Christophe Delaure

QualysGuard 7.12 API Notification

Blog Post created by Christophe Delaure on Oct 23, 2013

A new release of QualysGuard, Version 7.12, will be available in production in Nov 2013.

 

Enhancements include a set of new APIs and a report related change

  • API Support for QualysGuard Express Lite Users
  • “Compliance Posture Info” API v2 - Support for retrieving batches of compliance posture info records “Compliance Control” API v2
  • “Asset IP” API v2 Enhancements - Ability to add and update IP addresses (VM and PC)
  • PC Authentication Report - Host Technology Added

 

More information specific to this release, including the date of global availability, will be communicating 2 weeks before the release date via the Release Notification pages here:

 

API Support for QualysGuard Express Lite Users

QualysGuard API now support for Express Lite users. Express Lite users have the ability to use the QualysGuard API to manage scans, assets (IP addresses and domains) and user accounts. Several APIs are available:

 

“Compliance Posture Info” API v2 - Support for retrieving batches of compliance posture info records

 

The Compliance Posture Info API v2 (with the endpoint /api/2.0/fo/compliance/posture/info/) is used to return a list of compliance posture info records for a selected policy in the user’s account.

 

The output of the Compliance Posture Info API is paginated. By default, a maximum of 5,000 posture info records are returned per request. You can customize the page size (i.e. the number of posture info records) by using the parameter:

  • “truncation_limit=10000” will be return with pages of 10,000 records.
  • “truncation_limit=0” will be return in a single page with all the records.

 

WARNING: “truncation_limit=0” can generate very large output and processing large XML files can consume a lot of resources on the client side. In this case it is recommended to use the pagination logic and parallel processing. The previous page can be processed while the next page is being downloaded.

 

API request:

 

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST" -d "action=list&echo_request=1&policy_id=13906&truncation_limit=1000"

"https://qualysapi.qualys.com//api/2.0/fo/compliance/posture/info/"

 

XML output:

 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE POSTURE_INFO_LIST_OUTPUT SYSTEM
"https://qualysapi.qualys.com/api/2.0/fo/compliance/posture/info/posture_info_list_output.dtd">
<POSTURE_INFO_LIST_OUTPUT>
<REQUEST>
...
<RESPONSE>
  <DATETIME>2013-08-06T12:28:16Z</DATETIME>
  <INFO_LIST>
<INFO> ...
  </INFO_LIST>
  <WARNING_LIST>
    <WARNING>
      <CODE>1980</CODE>
      <TEXT>1000 record limit exceeded. Use URL to get next batch of results.</TEXT>
       <URL><![CDATAhttps://qualysapi.qualys.com/api/2.0/fo/compliance/posture/info/action=list&echo_request=1&policy_id=13906&truncation_limit=1000&id_min=1958791]>          
       </URL>
  </WARNING>
</WARNING_LIST>

 

“Compliance Control” API v2 - Support for retrieving batches of compliance controls

The Compliance Control API v2 (with the endpoint /api/2.0/fo/compliance/control/) is used to return a list of compliance controls in the user’s account.

 

Customize the Page Size using “truncation_limit” parameter

The output of the Compliance Control API is paginated. By default, a maximum of 1,000 control records are returned per request. You can customize the page size (i.e. the number of control records) by using the parameter:

  • “truncation_limit=10000” will be return with pages of 10,000 records.
  • “truncation_limit=0” will be return in a single page with all the records.

 

API request:


curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST" -d "action=list&echo_request=1&truncation_limit=200&details=Basic" "https://qualysapi.qualys.com//api/2.0/fo/compliance/control/"

 

XML output:

 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE CONTROL_LIST_OUTPUT SYSTEM
"https://qualysapi.qualys.com/api/2.0/fo/compliance/control/control_list_output.dtd">
<CONTROL_LIST_OUTPUT>
  <REQUEST>
 ...
  <RESPONSE>
    <DATETIME>2013-09-09T05:57:25Z</DATETIME>
    <CONTROL_LIST>
      <CONTROL>
        <ID>1044</ID>
        <UPDATE_DATE>2012-06-08T00:00:00Z</UPDATE_DATE>
        <CREATED_DATE>2007-10-12T00:00:00Z</CREATED_DATE>
...
    </CONTROL_LIST>
    <WARNING>
      <CODE>1980</CODE>
      <TEXT>200 record limit exceeded. Use URL to get next batch of
results.</TEXT>
<URL><![CDATA[https://qualysapi.qualys.com/api/2.0/fo/compliance/control/
?action=list&echo_request=1&truncation_limit=200&details=Basic&id_min=104
6]]></URL>
    </WARNING>
  </RESPONSE>
</CONTROL_LIST_OUTPUT>

 

“Asset IP” API v2 Enhancements - Ability to add and update IP addresses

 

The “Asset IP” API v2 (with the endpoint /api/2.0/fo/asset/ip/) now gives you the ability to add IP addresses for scanning to the subscription, and update them. You can choose to add IP addresses to VM and/or PC, depending on your license.

 

For additional information on the parameters available and additional examples, please refer to the release notes or documentations.

 

Add IP(s) Example

 

API request (POSTED raw data in CSV format):

curl -H "X-Requested-With: Curl" -H "Content-Type:text/csv" -u "USERNAME:PASSWORD" --data-binary @ips_list.csv "https://qualysapi.qualys.com/api/2.0/fo/asset/ip/?action=add&enable_vm=1&enable_pc=1&tracking_method=IP&owner=quays_es1"

 

API request (“ips” parameter):

curl -H "X-Requested-With: demo" -u "USERNAME:PASSWORD" -X "POST" -d "action=add&enable_vm=1&enable_pc=1&ips=10.10.10.1,10.10.10.10-

10.10.10.20,10.10.10.200" "https://qualysapi.qualys.com/api/2.0/fo/asset/ip/"

 

XML output:

 

<?xml version="1.0" encoding="UTF-8" ?>
  <!DOCTYPE SIMPLE_RETURN SYSTEM
"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">
 <SIMPLE_RETURN>
    <RESPONSE>
      <DATETIME>2013-08-07T01:21:03Z</DATETIME>
<TEXT>IPs successfully added to Vulnerability Management/Compliance Management</TEXT>
    </RESPONSE>

 

PC Authentication Report - Host Technology Added

The Policy Compliance (PC) Authentication Report tells you whether hosts scanned for compliance passed authentication. If authentication failed, we give you the reason so you can look into it.

With this release, the PC Authentication Report includes the host technology associated with each host instance - this is the compliance technology the host’s operating system is mapped to. We added a new element <HOST_TECHNOLOGY> to the XML output and updated the report DTD.

 

Updated Report DTD

The report DTD can be found at the following URL (where qualysapi.qualys.com is the API server URL where your account is located):

       https://qualysapi.qualys.com/compliance_authentication_report.dtd

The new <HOST_TECHNOLOGY> appears under the <HOST> element.

 

...

<!ELEMENT TECHNOLOGY_LIST (TECHNOLOGY*)>

<!ELEMENT TECHNOLOGY (NAME, HOST_LIST)>

<!ELEMENT HOST_LIST (HOST*)>

<!ELEMENT HOST (TRACKING_METHOD, IP, DNS?, NETBIOS?, HOST_TECHNOLOGY?,

                INSTANCE?, STATUS, CAUSE?)>

<!ELEMENT TRACKING_METHOD (#PCDATA)>

<!ELEMENT IP (#PCDATA)>

<!ELEMENT DNS (#PCDATA)>

<!ELEMENT HOST_TECHNOLOGY (#PCDATA)> <!ELEMENT NETBIOS (#PCDATA)> <!ELEMENT INSTANCE (#PCDATA)>

...

 

Sample Report XML


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

<!DOCTYPE COMPLIANCE_AUTHENTICATION_REPORT SYSTEM

"https://qualysapi.qualys.com/compliance_authentication_report.dtd">

<COMPLIANCE_AUTHENTICATION_REPORT>

...

<TECHNOLOGY_LIST>

      <TECHNOLOGY>

        <NAME><![CDATA[Unix/Cisco IOS]]></NAME>

        <HOST_LIST>

          <HOST>

            <TRACKING_METHOD><![CDATA[IP]]></TRACKING_METHOD>

            <IP><![CDATA[10.10.24.12]]></IP>

            <DNS><![CDATA[]]></DNS>

            <NETBIOS><![CDATA[]]></NETBIOS>

            <HOST_TECHNOLOGY><![CDATA[Solaris 9.x]]></HOST_TECHNOLOGY>

            <STATUS><![CDATA[Passed]]></STATUS>

           </HOST>

...           

Outcomes