WillB

QualysGuard WAS 3.1 API Notification

Blog Post created by WillB on Oct 12, 2013

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

Outcomes