Skip navigation

A new release of Qualys Cloud Suite, Version 8.6, includes an API update which is targeted for release in November 2015.

 

This API notification provides an early preview into the upcoming API features and enhancements in Qualys Cloud Suite 8.6, allowing you to proactively identify new opportunities to automate your Qualys service or to integrate with other applications.

 

This 15-day notification describes new API features that do not impact existing API implementations. API changes in the 8.6 release that may impact existing API implementations were already announced in the 30-day notification: Qualys Cloud Suite 8.6 API Release Notification

 

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

 

Qualys API Enhancements

 

Select Scanner Appliances using Asset Tags

 

The Scan API v2 (/api/2.0/fo/scan/) has been updated to support the selection of a scanner appliance via tags.  The parameter “scanners_in_tagset” can be used when launching or scheduling a scan using tags via the API.  The Appliance API v2 (/api/2.0/fo/appliance/) parameter "output_mode" can be used to list the asset tags for each scanner.


For more details on the new feature, please review <Qualys Cloud Suite 8.6 New Features blog entry>.

 


Appliance List Output - Running Slices Count

 

We’ve updated the Appliance API v2 (/api/2.0/fo/appliance/) appliance list output to tell you if an appliance is available or busy.  You'll see the new RUNNING_SLICES_COUNT element in the output, a 0 value indicates the appliance is not busy and available.

 


User List Output - Timezone Code

 

The User List v1 API (/msp/user_list.php) user list output now includes the timezone code selected for each user - either the browser’s timezone (Auto) or a user-selected timezone (e.g., US-NY).

 


Scan List Output - Target No Longer Truncated

 

We will now show the full list of target IPs in the output when you make a scan list request. In previous releases, we would truncate the target list after a set number of

characters and show [...] to indicate that it was truncated.

 


VM - Download the KnowledgeBase to CSV, XML

 

You can download the KnowledgeBase in the same way you download other data lists from the UI. Simply choose Download from the New menu when you’re on the KnowledgeBase tab. Then select a file format (CSV or XML). Only the records and columns shown in the UI will be included in the downloaded report.

 


VM - View multiple Oracle instances on a port

 

You’ll see scanned Oracle instances listed separately in scan results, scan reports, host detection results and ticket list output. Note you’ll need to create a separate Oracle authentication record for each of the instances you want to scan.


There are no changes made to API calls or DTDs.

 


VM - Create static search lists

 

Our new Static Search List API (/api/2.0/fo/qid/search_list/static/) lets you create, update, list, and delete static search lists and get detailed information about them.

 


VM - Create dynamic search lists

 

Our new Dynamic Search List API (/api/2.0/fo/qid/search_list/dynamic/) lets you create, update, list, and delete dynamic search lists and get detailed information about them.

 


VM - Vendor IDs and references PC

 

Our new Vendor API (/api/2.0/fo/vendor/) lists vendor IDs and names. This vendor information may be defined as part of dynamic search list query criteria.

 


VM - Display Host Identification Information in Scan Reports

 

When you have cloud agents they’re collecting additional host information. Now you can include more host identification information in your scan reports like IP addresses (IPv4 and IPv6) and the asset ID for each host. This option is available for scan reports in all formats, including XML. The Asset Data Report DTD has been updated. (This information is only available when VM agents are licensed in your account.)

 


PC - Display reference information in reports

With this release you can view the Reference information for controls in Policy Compliance and Compliance Interactive reports. We’ve updated DTDs for Individual Host Compliance Report (individual_host_compliance_report.dtd) and Control Pass/Fail Report (control_pass_fail_report.dtd).

 


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>

Filter Blog

By date: By tag: