Skip navigation

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>

...           

A new release of QualysGuard WAS, Version 3.1, will be available in production in mid-November 2013. The exact date depends on the platform and this release contains changes to the APIs that requires a 30-day notification. APIs will be updated for each platform on the same day version 3.1 is released. 

 

 

More information on specific release dates that correspond to the platforms can be found here:

 

 

 

This API notification provides an early preview into the coming API changes in QualysGuard WAS 3.1, allowing you to proactively identify any changes that might be required for your automated scripts or programs that utilize the API methods described below.  There are 2 primary API changes in this release:

 

  • New API for Managing Authentication Records
  • WAS Reports in XML – Findings are now Base64 Encoded

 

Full release notes will be available to customers on the day of the release.

 

New API for Managing Authentication Records

With WAS 3.1 we’re introducing a new API for managing authentication records called WebAppAuthRecord. This new API allows you to:

  • Manage authentication records independently from web application settings
  • Easily create an authentication record once and associate it with multiple web applications
  • Perform all authentication record operations – create, update, delete, get details, search and count

 

The new WebAppAuthRecord resource is located at this URL:

  • https://qualysapi.qualys.com/qps/rest/3.0/<operation>/was/webappauthrecord
    (where “qualysapi.qualys.com” is the QualysGuard API server URL for your QualysGuard platform, in this case US Platform 1. )

Supported Operations

 

  • Count authentication records
    <base URL for platform>/qps/3.0/count/was/webappauthrecord
  • Search authentication records
    <base URL for platform>/qps/3.0/search/was/webappauthrecord
  • Get authentication record details
    <base URL for platform>/qps/3.0/get/was/webappauthrecord
  • Create a new authentication record
    <base URL for platform>/qps/3.0/create/was/webappauthrecord
  • Update an authentication record
    <base URL for platform>/qps/3.0/update/was/webappauthrecord
  • Delete an authentication record
    <base URL for platform>/qps/3.0/delete/was/webappauthrecord

 

New XSD - The WebAppAuthRecord object is independent from the WebApp object. There’s a new webappauthrecord.xsd (…/qps/xsd/3.0/was/webappauthrecord.xsd). WebAppAuthRecord object has these new attributes:

 

<xs:complexType name="WebAppAuthRecord">
 <xs:all>
  <xs:element name="id" type="xs:long" minOccurs="0"/>
  <xs:element name="name" type="Cdata" minOccurs="0"/>
  <xs:element name="owner" type="User" minOccurs="0"/>
  <xs:element name="formRecord" type="WebAppAuthFormRecord" minOccurs="0"/>
  <xs:element name="serverRecord" type="WebAppAuthServerRecord" minOccurs="0"/>
  <xs:element name="tags" type="TagList" minOccurs="0"/>
  <xs:element name="comments" type="CommentList" minOccurs="0"/>
  <xs:element name="createdDate" type="xs:dateTime" />
  <xs:element name="createdBy" type="User" />
  <xs:element name="updatedDate" type="xs:dateTime" />
  <xs:element name="updatedBy" type="User" />
 </xs:all>
</xs:complexType>

 

Changes to the Web Application API

The WebApp API has been updated for this release.  Supported Operations – Please note these 2 changes:

  1. You will associate an authentication record with the web application using the CREATE and UPDATE operations (you can’t create the record within the web application settings as before). Just provide the id element as input with your API request.
  2. An API request to view web applications and get details (SEARCH and GET operations) returns only the ID and name for the web application.

 

 

XSD updates - The webapp.xsd has been updated (…/qps/xsd/3.0/was/webapp.xsd). Please note these changes:

1) The WebApp object still contains a list of WebAppAuthRecord elements (no changes):

 

<xs:complexType name="WebApp"> 
  <xs:all> 
     ... 
     <xs:element name="authRecords" type="WebAppAuthRecordList" minOccurs="0"/> 
     ... 
  </xs:all> 
</xs:complexType>

 

2) The WebAppAuthRecord elements allow only the id and name attributes (other attributes are no longer supported).

 

<xs:complexType name="WebAppAuthRecord">
  <xs:all>
    <xs:element name="id" type="xs:long" minOccurs="0"/>
    <xs:element name="name" type="Cdata" minOccurs="0"/>
  </xs:all>
</xs:complexType>

 

 

Creating Authentication Records and Apply them to Web Applications

Using the WAS API Version 3.1 you’ll first create independent authentication record(s) and link them to your web application. Then you’re ready to launch authenticated scans against your web application.

 

Step 1: Create Authentication Record(s)

Create new authentication record(s) and tell us how to authenticate to your web application. The sample request below indicates form authentication will be used. You can create multiple authentication records as needed for your various web applications. (You must have the new Create authentication record permission enabled under Web Application authentication record permissions.)

 

Request:

curl -u "USERNAME:PASSWORD" -H "Content-type: text/xml" -X "POST" --data-binary @-
"https://qualysapi.qualys.com/qps/rest/3.0/create/was/webappauthrecord/" < file.xml

Note: “file.xml” contains the request POST data.

 

Request POST Data:

<?xml version="1.0" encoding="UTF-8"?>
<ServiceRequest>
 <data>
  <WebAppAuthRecord>
   <name><![CDATA[From API - Form]]></name>
   <formRecord>
    <type>STANDARD</type>
    <sslOnly>true</sslOnly>
    <fields>
     <set>
      <WebAppAuthFormRecordField>
       <name><![CDATA[password]]></name>
       <value><![CDATA[12345]]></value>
      </WebAppAuthFormRecordField>
      <WebAppAuthFormRecordField>
       <name><![CDATA[username]]></name>
       <value><![CDATA[user]]></value>
      </WebAppAuthFormRecordField>
     </set>
    </fields>
   </formRecord>
   <comments>
    <set>
     <Comment>
      <contents><![CDATA[This is a comment]]></contents>
     </Comment>
    </set>
   </comments>
   <tags>
    <set>
     <Tag>
      <id>102609</id>
     </Tag>
    </set>
   </tags>
  </WebAppAuthRecord>
 </data>
</ServiceRequest>

 

Step 2: Add Authentication Record(s) to web application settings

Add authentication record(s) to web application settings by creating or updating each web application you want to authenticate to. You just need to add the authentication record ID. Note the same authentication record can be linked to multiple web applications. (As long as you have permission to create/update web applications under WAS Asset Permissions, you can add authentication records to web app settings.)

 

Request:

curl -u "USERNAME:PASSWORD" -H "Content-type: text/xml" -X "POST" --data-binary @-
"https://qualysapi.qualys.com/qps/rest/3.0/update/was/webapp/324539" < file.xml

Note: “file.xml” contains the request POST data.

 

Request POST Data:

<ServiceRequest>
 <data>
  <WebApp>
   <authRecords>
    <add>
      <WebAppAuthRecord><id>1688</id></WebAppAuthRecord>
      <WebAppAuthRecord><id>1689</id></WebAppAuthRecord>
      <WebAppAuthRecord><id>1690</id></WebAppAuthRecord>
      <WebAppAuthRecord><id>1691</id></WebAppAuthRecord>
    </add>
   </authRecords>
  </WebApp>
 </data>
</ServiceRequest>

 

Step 3: Check web application details

The web application details will include all web application settings and the authentication record(s) you’ve added. At scan time we’ll attempt authentication using all of the web application’s records.

 

Request:

curl -u "USERNAME:PASSWORD" -H "Content-type: text/xml" -X "POST" --data-binary @-
"https://qualysapi.qualys.com/qps/rest/3.0/get/was/webapp/324539"

 

Step 4: Start your scan

Launch a scan using the WasScan API at this URL:  https://qualysapi.qualys.com/qps/rest/3.0/launch/was/wascan

Filter Blog

By date: By tag: