fmc

Qualys WAS 4.3 API Release Notification 2

Blog Post created by fmc on Oct 13, 2015

A new release of Qualys WAS, Version 4.3 which includes API updates, is targeted for release in October. The specific day will differ depending on the platform.  See platform release dates for more information.  The updated APIs for WAS 4.3 enhance the ability to fully automate and integrate the Qualys WAS solution with other customer applications.  WAS APIs enable customers to perform all the major functions within WAS including creating web applications to scan, launching and scheduling scans, and running and retrieving reports.  The APIs enable custom integrations with GRC tools, bug tracking systems and web application firewalls (WAFs) just to name a few.

 

This API notification provides an early preview into the coming API changes in Qualys WAS 4.3, allowing you to proactively identify any changes that might be required for your automated scripts or programs that utilize the API methods.

 

Please refer to attached document ( WAS 4.3 API Release Notification.pdf ) for full details and examples with full XML output.

 

API Enhancements

 

  • Option Profile API - Update Owner
  • DNS Override Settings
  • Disable Scan Complete Notification
  • Custom Attributes for Web Apps

 

Option Profile API - Update Owner

 

The Option Profile API has been updated to allow users to update the option profile owner. A new owner / id element has been added.

 

API Request:

 

curl -u "USERNAME:PASSWORD" -H "content-type: text/xml" -X "POST"

--data-binary @-

"https://qualysapi.qualys.com/qps/rest/3.0/update/was/optionprofil

e/123456" < file.xml

 

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

 

Request POST Data:

 

<ServiceRequest>

   <data>

      <OptionProfile>

         <owner><id>123456</id></owner>

      </OptionProfile>

   </data>

</ServiceRequest>

 

DNS Override Settings

 

For this release users can define DNS override settings and apply them to scans. We’ve made updates to multiple WAS APIs to support this capability. DNS override settings are defined using the WAS user interface. The mappings you define will override the DNS associated with the target web application URL.

 

WebApp API

 

Updated XSD: webapp.xsd

 

New section for WebApp CREATE and UPDATE

 

Assign DNS override settings, one or more records, to a web application when making requests to create and update web applications. Records are specified in the dnsOverrides section.

 

API request (CREATE):

 

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

 

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

 

Request POST data:

 

<ServiceRequest>

   <data>

      <WebApp>

         <name><![CDATA[My Web App]]></name>

         <url><![CDATA[http://test.com]]></url>

         <scope>ALL</scope>

         <defaultScanner>

            <type>EXTERNAL</type>

            </defaultScanner>

            <scannerLocked>false</scannerLocked>

      <dnsOverrides>

         <set>

            <DnsOverride>

               <id>2022</id>

            </DnsOverride>

         </set>

      </dnsOverrides>

      <useRobots>IGNORE</useRobots>

      <useSitemap>false</useSitemap>

      <malwareMonitoring>false</malwareMonitoring>

   </WebApp>

</data>

</ServiceRequest>

 

Updated response from WebApp GET


When a web application has default DNS override settings defined, the new dnsOverrides element lists the record(s) containing the DNS override settings.


API request:

 

curl -u "USERNAME:PASSWORD" "https://qualysapi.qualys.com/qps/rest/3.0/get/was/webapp/2508873"

 

Scan API

 

Updated XSD: scan.xsd, wasscan.xsd

 

New attribute for Scan LAUNCH

 

Use the new dnsOverride element to specify DNS override settings, one or more records.

 

API request:

 

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

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

 

Request POST data:

 

<ServiceRequest>

   <data>

      <WasScan>

         <name><![CDATA[Launch Scan from API with DNS Override)]]></name>

         <type>VULNERABILITY</type>

         <target>

            <webApp>

               <id>2461682</id>

            </webApp>

            <scannerAppliance>

               <type>EXTERNAL</type>

            </scannerAppliance>

            <dnsOverride><id>3220</id></dnsOverride>

         </target>

         <profile><id>395933</id></profile>

      </WasScan>

   </data>

</ServiceRequest>

 

Updated response from Scan GET

 

When a scan has DNS override settings defined, the dnsOverride element lists DNS override settings (record) to be used for scanning.

 

API request:

 

curl -u "USERNAME:PASSWORD" "https://qualysapi.qualys.com/qps/rest/3.0/get/was/wasscan/1381602"

 

Scan Schedule API

 

Updated XSD: schedule.xsd, wasscanschedule.xsd

 

New attribute for Schedule CREATE and UPDATE


Use the new dnsOverride element to specify DNS override settings.

 

API request (CREATE):

 

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

 

Request POST data:

 

<ServiceRequest>

<data>

   <WasScanSchedule>

     <name><![CDATA[My Scan Schedule]]></name>

     <type>VULNERABILITY</type>

     <active>false</active>   

     <scheduling>

        <!--<cancelTime>15:00</cancelTime> -->

        <cancelAfterNHours>7</cancelAfterNHours>

       <startDate>2013-09-30T13:11:00Z</startDate>

       <timeZone>

         <code>America/Dawson</code>

       </timeZone>

       <occurrenceType>ONCE</occurrenceType>

     </scheduling>

     <target>

            <webApp>

               <id>2461682</id>

            </webApp>

       <scannerAppliance>

         <type>EXTERNAL</type>

       </scannerAppliance>

       <cancelOption>DEFAULT</cancelOption>

       <dnsOverride><id>3220</id></dnsOverride>

     </target>

     <profile>

        <id>395933</id>

     </profile>

   </WasScanSchedule>

</data>

</ServiceRequest>

 

API request (UPDATE):

 

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

 

Request POST data:

 

<ServiceRequest>

<data>

   <WasScanSchedule>

       <target>

         <dnsOverride><id>3220</id></dnsOverride>

     </target>

   </WasScanSchedule>

</data>

</ServiceRequest>

 

Updated response from Schedule GET


When a scan schedule has DNS override settings defined, the dnsOverride element lists the DNS override settings to be used for scanning.

 

API request:

 

curl -u "USERNAME:PASSWORD" "https://qualysapi.qualys.com/qps/rest/3.0/get/was/wasscanschedule/340194" < file.xml

 

Request POST data:

 

<ServiceRequest>

<data>

   <WasScanSchedule>

       <target>

         <dnsOverride><id>3220</id></dnsOverride>

     </target>

   </WasScanSchedule>

</data>

</ServiceRequest>

 

Disable Scan Complete Notification

 

By default we’ll send email notifications to users when a scan completes. Now you can disable this notification when making a request to launch a scan or schedule a scan. The Using the WAS API just specify <sendMail>false</sendMail> as shown below for your scan or schedule request.

 

Scan API Update

 

Updated XSD: scan.xsd, wasscan.xsd

 

New attribute for Scan LAUNCH

 

Use new sendMail attribute to disable scan complete email notifications.

 

API request:

 

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

 

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

 

Request POST data:

 

<ServiceRequest>

  <data>

    <WasScan>

      <name><![CDATA[My Vulnerability Scan]]></name>

      <type>VULNERABILITY</type>

      <target>

        <webApp>

          <id>2376280</id>

        </webApp>

        <scannerAppliance>

          <type>EXTERNAL</type>

        </scannerAppliance>

        <cancelOption>DEFAULT</cancelOption>

      </target>

       <sendMail>false</sendMail>

    </WasScan>

  </data>

</ServiceRequest>

 

Update to Scan GET

 

New sendMail element in the XML output.

 

API request:

 

curl -u "USERNAME:PASSWORD" "https://qualysapi.qualys.com/qps/rest/3.0/get/was/wasscan/1382978"

 

Scan Schedule API

 

Updated XSD: schedule.xsd, wasscanschedule.xsd

 

New attribute for Schedule CREATE and UPDATE


Use new sendMail attribute to disable scan complete email notifications.

 

API request (UPDATE):

 

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

 

Request POST data:

 

<ServiceRequest>

  <data>

    <WasScanSchedule>

      <notification>

        <active>true</active>

        <delay>

          <nb>4</nb>

          <scale>DAY</scale>

        </delay>

        <recipients>

          <set>         <EmailAddress><![CDATA[name1@company.com]]></EmailAddress>         <EmailAddress><![CDATA[name2@company.com]]></EmailAddress>                 <EmailAddress><![CDATA[name3@company.com]]></EmailAddress>          

          </set>

        </recipients>

        <message><![CDATA[The schedule notification message]]></message>      

      </notification>

       <sendMail>false</sendMail>

    </WasScanSchedule>

  </data>

</ServiceRequest>

 

Update to Schedule GET

 

New sendMail element in the XML output.

 

API request:

 

curl -u "USERNAME:PASSWORD" -H "content-type: text/xml" -X "POST" --data-binary @- "https://qualysapi.qualys.com/qps/rest/3.0/get/was/wasscanschedule/1688” < file.xml

 

Custom Attributes for Web Apps


WAS 4.3 gives you the ability to assign custom attributes to your web applications. Using the WebApp API you can add, update and search custom attributes.

 

Web App API

 

Updated XSD: webapp.xsd

 

Web App SEARCH supports searching custom attributes

 

Search custom attributes using the new field attribute for the Criteria element.

 

API request:

 

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

 

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

 

Request POST data (CONTAINS):

 

Find web applications that have a custom attribute name “Function” and this attribute has a value that contains “web” (case insensitive search).

 

<ServiceRequest>

       <filters>

         <Criteria field="attributes" name="Function"  operator="CONTAINS">web</Criteria>

       </filters>

</ServiceRequest>

 

Request POST data (EQUALS):

 

Find web applications that have a custom attribute name “Function” and this attribute has a value that is equal to “web”.

 

<ServiceRequest>

       <filters>

         <Criteria field="attributes" name="Function" operator="EQUALS">web</Criteria>

       </filters>

</ServiceRequest>

 

Request POST data (NOT EQUALS):

 

Find web applications that have a custom attribute name “Function” and this attribute has a value not equal to “web”.

 

<ServiceRequest>

       <filters>

         <Criteria field="attributes" name="Function" operator="NOT EQUALS">web</Criteria>

       </filters>

</ServiceRequest>

 

New section for WebApp CREATE

 

When custom attributes are defined they appear in the XML output in the new attributes element.

 

API request (CREATE):

 

Create a new web app with custom attributes.

 

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

 

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

 

Request POST data:

 

<ServiceRequest>

  <data>

    <WebApp>

        <name><![CDATA[Custom Attribute via API]]></name> <url><![CDATA[http://funkytown.vuln.qa.qualys.com:80/updated_web_app_name/]]></url>

        <attributes>

            <set>

            <Attribute>

             <name>Custom key 1</name>

             <value><![CDATA[Custom value 1]]></value>

            </Attribute>

            </set>

        </attributes>

    </WebApp>

   </data>

</ServiceRequest>


New section for WebApp UPDATE

 

Add, update and remove attribute names and values using the new input attribute “attributes”.

 

API request (UDATE sample 1):

 

Modify existing custom attribute value.

 

curl -u "USERNAME:PASSWORD" -H "Content-type: text/xml" -X "POST"

--data-binary @- "https://qualysapi.qualys.com/qps/rest/3.0/update/was/webapp/2514679" < file.xml

 

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

 

Request POST data:

 

ServiceRequest>

  <data>

        <WebApp>

            <attributes>

                <update>

                    <Attribute>

                     <name>Custom key 1</name>

                     <value><![CDATA[Custom value 2]]></value>

                    </Attribute>

                </update>

            </attributes>

        </WebApp>

  </data>

</ServiceRequest>

 

API request (UDATE sample 2):

 

Add new custom attribute value.

 

curl -u "USERNAME:PASSWORD" -H "Content-type: text/xml" -X "POST"

--data-binary @- "https://qualysapi.qualys.com/qps/rest/3.0/update/was/webapp/2514679" < file.xml

 

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

 

Request POST data:

 

<ServiceRequest>

  <data>

        <WebApp>

            <attributes>

                <add>

                    <Attribute>

                     <name>Custom key 3</name>

                     <value><![CDATA[Custom value 3]]></value>

                    </Attribute>

                </add>

            </attributes>

        </WebApp>

  </data>

</ServiceRequest>

 

API request (UDATE sample 3):


Remove existing custom attribute value.

 

curl -u "USERNAME:PASSWORD" -H "Content-type: text/xml" -X "POST"

--data-binary @- "https://qualysapi.qualys.com/qps/rest/3.0/update/was/webapp/2514679" < file.xml

 

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

 

Request POST data:

 

<ServiceRequest>

  <data>

        <WebApp>

            <attributes>

                <remove>

                    <Attribute>

                     <name>Custom key 3</name>

                    </Attribute>

                </remove>

            </attributes>

        </WebApp>

  </data>

</ServiceRequest>

Outcomes