Launch Scans (Single)

[POST] /qps/rest/3.0/launch/was/wasscan/

We've enhanced the ability to support large web application scanning programs by adding the ability to scan any number of web applications as a Multi-Scan through API. This feature enables you to scan hundreds or even thousands of web applications you may have in your organization with granular insight into what scans are running and which ones are complete.

Permissions required - User must have WAS module enabled. User account must have these permissions: Access Permission “API Access” and "Launch WAS Scan". The output includes scan targets in the user's scope.

Input ParametersInput Parameters

These elements are optional and act as filters. When multiple elements are specified, parameters are combined using a logical AND. The special field=attributes attribute for the Criteria element is used to search custom attributes (see sample below).

Click here for available operators

Parameter	Mandatory /Optional	Data Type	Description
name	Optional	text	The scan name.
webApps.id or tags.id1	Optional	integer	The web applications to be scanned. webApps.id: Specify the web application ID to include it in the scan. tags.id: Specify the tag ID associated with the web applications to be scanned.
type	Optional	keyword	The scan type: VULNERABILITY or DISCOVERY.
profile.id2	Optional	integer	The name of the option profile that includes scan settings. The service provides the profile “Initial WAS Options” and we recommend this to get started. Example: <profile> <name>Initial WAS Options</name> </profile>
target.scannerAppliance.type	Optional	keyword	The type of scanner appliance used for the scan: EXTERNAL or INTERNAL or scannerTags.
target.scannerAppliance. friendlyName	Optional	text	Name of the scanner appliance used for the scan.
target.scannerTags.set.Tag.id	Optional	integer	The scanner associated with the tag (identified by the specified tag ID) is picked for the scan.
target.webAppAuthRecord.id or target.webAppAuthRecord.isDefault	Optional	boolean	Decides the authentication record to be used for the scan. target.webAppAuthRecord.id (integer): Specify the web application's authentication record ID to use the specific authentication record. target.webAppAuthRecord.isDefault (boolean): Set to true to use the default web application's authentication record for the scan.
proxy.id	Optional	integer	The proxy for scanning the target web application. Example: <proxy> <id>12345</id> </proxy>
dnsOverride.id	Optional	integer	The DNS override record for scanning the target web application. Example: <dnsOverride> <id>67890</id> </dnsOverride>
sendMail	Optional	boolean	Set to false to disable scan complete email notifications. Example:<sendMail>false</sendMail>

1 The element target must have at least tags or web applications specified

2 The element profile (Text) is required unless the target has a default option profile.

Sample - Launch a new scan - basic elementsSample - Launch a new scan - basic elements

Launch a new discovery scan on the web application ID 323126 using the option profile ID 1021.

API request

curl -u "USERNAME:PASSWORD" -H "content-type: text/xml" -X "POST" --data-binary @- "<qualys_base_url>/qps/rest/3.0/launch/was/wasscan" < file.xml
Note: “file.xml” contains the request POST data.

Request POST data

<ServiceRequest>
    <data>
        <WasScan>
            <name>New WAS Discovery Scan launched from API</name>
            <type>DISCOVERY</type>
            <target>
                <webApp>
                    <id>323126</id>
                </webApp>
                <webAppAuthRecord>
                    <isDefault>true</isDefault>
                </webAppAuthRecord>
                <scannerAppliance>
                    <type>EXTERNAL</type>
                </scannerAppliance>
            </target>
            <profile>
                <id>1021</id>
            </profile>
        </WasScan>
    </data>
</ServiceRequest>

XML response

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="<qualys_base_url>/qps/xsd/3.0/was/wasscan.xsd">
    <responseCode>SUCCESS</responseCode>
    <count>1</count>
    <data>
        <WasScan>
            <id>16954</id>
        </WasScan>
    </data>
</ServiceResponse>

Sample - Launch a new scan - use proxySample - Launch a new scan - use proxy

Type your dropdown text here

Launch a new vulnerability scan using proxy ID 12345.

API request

curl -u "USERNAME:PASSWORD" -H "content-type: text/xml" -X "POST" --data-binary @- "<qualys_base_url>/qps/rest/3.0/launch/was/wasscan" < file.xml
Note: “file.xml” contains the request POST data.

Request POST data

<?xml version="1.0" encoding="UTF-8"?>
<ServiceRequest>
    <data>
        <WasScan>
            <name>New WAS Vulnerability Scan launched from API</name>
            <type>VULNERABILITY</type>
            <target>
                <webApp>
                    <id>323126</id>
                </webApp>
                <scannerAppliance>
                    <type>INTERNAL</type>
                    <friendlyName>dp_scanner</friendlyName>
                </scannerAppliance>
                <proxy>
                    <id>12345</id>
                </proxy>
            </target>
            <profile>
                <id>1021</id>
            </profile>
        </WasScan>
    </data>
</ServiceRequest>

XML response

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="<qualys_base_url>/qps/xsd/3.0/was/wasscan.xsd">
    <responseCode>SUCCESS</responseCode>
    <count>1</count>
    <data>
        <WasScan>
            <id>16954</id>
        </WasScan>
    </data>
</ServiceResponse>

Sample - Launch a new scan - assign multiple scanner appliancesSample - Launch a new scan - assign multiple scanner appliances

Let us launch a new discovery scan on the web application ID 522066 and assign the pool of scanners using asset tag.

API request

curl -u "USERNAME:PASSWORD" -H "content-type: text/xml" -X "POST" --data-binary @- "<qualys_base_url>/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[Scan With Pool of Internal Scanners]>
            </name>
            <type>DISCOVERY</type>
            <target>
                <webApp>
                    <id>522066</id>
                </webApp>
                <scannerTags>
                    <set>
                        <Tag>
                            <id>15415353311147</id>
                        </Tag>
                    </set>
                </scannerTags>
            </target>
        </WasScan>
    </data>
</ServiceRequest>

XML response

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="<qualys_base_url>/qps/xsd/3.0/was/scan.xsd">
    <responseCode>SUCCESS</responseCode>
    <count>1</count>
    <data>
        <WasScan>
            <id>1731352</id>
            <name>
                <![CDATA[Scan With Pool of Internal Scanners]]>
            </name>
            <reference>was/1484222839357.1955345</reference>
            <type>DISCOVERY</type>
            <mode>ONDEMAND</mode>
            <progressiveScanning>ENABLED</progressiveScanning>
            <multi>true</multi>
            <target>
                <webApps>
                    <list>
                        <WebApp>
                            <id>522066</id>
                            <name>
                                <![CDATA[My Web Application]>
                            </name>
                            <url>
                                <![CDATA[http://mywebapp.com]]>
                            </url>
                        </WebApp>
                    </list>
                </webApps>
                <scannerTags>
                    <set>
                        <Tag>
                            <id>8461819</id>
                            <name>
                                <![CDATA[TagForScanner]]>
                            </name>
                        </Tag>
                    </set>
                </scannerTags>
                <cancelOption>DEFAULT</cancelOption>
            </target>
            <profile>
                <id>194283</id>
                <name>
                    <![CDATA[Initial WAS Options]]>
                </name>
            </profile>
            <options>
                <count>14</count>
                <list>
                    <WasScanOption>
                        <name>Web Application Authentication Record Name</name>
                        <value>
                            <![CDATA[None]]>
                        </value>
                    </WasScanOption>
                    <WasScanOption>
                        <name>Unexpected Error Threshold</name>
                        <value>
                            <![CDATA[300]]>
                        </value>
                    </WasScanOption>
                    <WasScanOption>
                        <name>Sensitive Content: Credit Card Numbers</name>
                        <value>
                            <![CDATA[false]]>
                        </value>
                    </WasScanOption>
                    <WasScanOption>
                        <name>Performance Settings</name>
                        <value>
                            <![CDATA[LOW]]>
                        </value>
                    </WasScanOption>
                    <WasScanOption>
                        <name>Detection Scope</name>
                        <value>
                            <![CDATA[COMPLETE]]>
                        </value>
                    </WasScanOption>
                    <WasScanOption>
                        <name>Crawling Form Submissions</name>
                        <value>
                            <![CDATA[BOTH]]>
                        </value>
                    </WasScanOption>
                    <WasScanOption>
                        <name>Bruteforce Settings</name>
                        <value>
                            <![CDATA[DISABLED]]>
                        </value>
                    </WasScanOption>
                    <WasScanOption>
                        <name>Option Profile Name</name>
                        <value>
                            <![CDATA[Initial WAS Options]]>
                        </value>
                    </WasScanOption>
                    <WasScanOption>
                        <name>Maximum Crawling Links</name>
                        <value>
                            <![CDATA[300]]>
                        </value>
                    </WasScanOption>
                    <WasScanOption>
                        <name>Timeout Error Threshold</name>
                        <value>
                            <![CDATA[100]]>
                        </value>
                    </WasScanOption>
                    <WasScanOption>
                        <name>Web Application Name</name>
                        <value>
                            <![CDATA[My Web Application]]>
                        </value>
                    </WasScanOption>
                    <WasScanOption>
                        <name>Request Parameter Set</name>
                        <value>
                            <![CDATA[Initial Parameters]]>
                        </value>
                    </WasScanOption>
                    <WasScanOption>
                        <name>Sensitive Content: Social Security Numbers (US)</name>
                        <value>
                            <![CDATA[false]]>
                        </value>
                    </WasScanOption>
                    <WasScanOption>
                        <name>Target URL</name>
                        <value>
                            <![CDATA[http://mywebapp.com]]>
                        </value>
                    </WasScanOption>
                </list>
            </options>
            <launchedDate>2017-01-12T12:07:19Z</launchedDate>
            <launchedBy>
                <id>1056860</id>
                <username>user_john</username>
                <firstName>
                    <![CDATA[John]]>
                </firstName>
                <lastName>
                    <![CDATA[Doe]]>
                </lastName>
            </launchedBy>
            <status>SUBMITTED</status>
            <sendMail>true</sendMail>
        </WasScan>
    </data>
</ServiceResponse>

Sample - Launch a new scan - progressive scanningSample - Launch a new scan - progressive scanning

The user can set the progressiveScanning option to true or false for the vulnerability scan, if Progressive Scanning is enabled for the subscription. If the option is not set for a scan, the Progressive Scanning setting for the web application is used. Note this option is not supported for a discovery scan.

API request

curl -u "USERNAME:PASSWORD" -H "content-type: text/xml" -X "POST" --data-binary @- "<qualys_base_url>/qps/rest/3.0/launch/was/wasscan" < file.xml
Note: “file.xml” contains the request POST data.

Request POST data

<ServiceRequest>
    <data>
        <WasScan>
            <name>New WAS Vulnerability Scan launched from API</name>
            <type>VULNERABILITY</type>
            <target>
                <webApp>
                    <id>323126</id>
                </webApp>
                <scannerAppliance>
                    <type>EXTERNAL</type>
                </scannerAppliance>
            </target>
            <profile>
                <id>1021</id>
            </profile>
            <cancelAfterNHours>5</cancelAfterNHours>
            <progressiveScanning>DISABLED</progressiveScanning>
        </WasScan>
    </data>
</ServiceRequest>

XML response

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="<qualys_base_url>/qps/xsd/3.0/was/wasscan.xsd">
    <responseCode>SUCCESS</responseCode>
    <count>1</count>
    <data>
        <WasScan>
            <id>16954</id>
        </WasScan>
    </data>
</ServiceResponse>

If Progressive Scanning is not enabled for the subscription, the progressiveScanning element cannot be provided, otherwise an error will be returned.

XML response (error)

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="<qualys_base_url>/qps/xsd/3.0/was/wasscan.xsd">
    <responseCode>INVALID_REQUEST</responseCode>
    <responseErrorDetails>
        <errorMessage>Progressive scanning is not enabled in your subscription.</errorMessage>
        <errorResolution>Please check with your account manager to enable this option.</errorResolution>
    </responseErrorDetails>
</ServiceResponse>

XSD

<platform API server>/qps/xsd/3.0/was/wasscan.xsd