Reference: WebApp

The <WebApp> element includes sub elements used to define a web application. A reference of these elements is provided below. An asterisk * indicates a complex element.

Parameter

Mandatory

/Optional

Data Type

Description

id

  integer

Web application ID. This element is assigned by the service and required for an update request.

removeFrom

Subscription

  boolean

When set to true, deletes the web application asset from your subscription if the web application is not shared with other modules such as WAF. The “removeFromSubscription” flag is ignored if the web application that you want to remove from the subscription is shared with other modules. In that case, the Delete Web application API request with this flag set to true will only delete the web application from WAS and not from your subscription.

reactivateIf

Exists

  boolean

Set this parameter to “true” to create a web application with the same name and URL. In such a case, all the data of the old web application such as findings, detections, scans will be deleted. The new web application will have the same web application asset ID as the old web application.

But if you try to create a web application with different URL but with a name that already exists in your subscription, then the API will return an error “Webapp with same name exists” in the response. The flag "reactivateIfExists" will be ignored even if it is set to true".

If this flag is not set to true and if you try to create a web application with the same name and URL, then we show this error message in the response: “We found in your subscription an existing asset that already uses the same name and URL. The asset is currently being used by the modules: Was, Waf. Please set flag reactivateIfExists to true to use that existing asset. If not, you will need to change the name of the one you are trying to create.”

name

 

text

The web application name (maximum 256 characters). This element is required to create a web application.

type

  keyword

Type of the finding: VULNERABILITY, SENSITIVE_CONTENT, or INFORMATION_GATHERED.

url

  text

The URL of the web application maximum 2048 characters). This element is required to create a web application.

os

  text

The operating system of the web application.

owner

  text

This element is assigned by the service and may be specified for an update request only.

config*

   

 Configure the cancel scan option. Specify “cancel after” time or “cancel at” time. Only one of <cancelScansAfterNHours> or <cancelScanstAt> is allowed in one config section.

Example for “cancel after” time:

<config>
   <cancelScansAfterNHours>3 </cancelScansAfterNHours>
</config>

 Example for “cancel at” time:

<config>
   <cancelScansAt>2017-06-10T12:00:00Z </cancelScansAt>
</config>

 Notes about updating web applications:
- If none of the above elements are specified in the config section, the default cancel option is removed from the web app settings.

- If the config section is not specified, no changes are made to the web app settings.

You can set one of the DNS override records that you assigned to your web application as the default record for the web application. The default DNS override setting is useful when you want to scan multiple web applications using the DNS override option. We will use the default DNS override record that you have set for your web applications to launch scan on them.

The parameter for setting the default DNS override is config.defaultDnsOverride.id. This parameter takes the ID of the DNS override record that you want to set as the default record.

This is an optional parameter.

Example:

<config>
   <defaultDnsOverride>
      <id>14620</id>
   <defaultDnsOverride>
</config>

attributes*

   

Custom web application attributes.

Example:

<attributes>
  <set>
      <Attribute>
         <name>Custom key 1</name>
         <value><![CDATA[Custom value 1]]></value>
      </Attribute>
      <Attribute>
         <name>Custom key 2</category>
         <value><![CDATA[Custom value 2]]></value>
      </Attribute>
   </set>
</attributes>

tags*

   

Tags assigned to the web application.

Example:

<tags>
   <set>
      <Tag>
         <id>12345</id>
      </Tag>
      <Tag>
         <id>12345678</id>
      </Tag>
   </set>
</tags>

comments

  text

Comments on the web application.

scope

  keyword

The scanning scope for the web application: ALL (default), LIMIT, SUBDOMAIN or DOMAINS.

 - If set to ALL, the scan will crawl all directories and sub-directories of the starting URL.

 - If set to LIMIT, crawling will be limited to the starting URI’s initial path and sub-directories.  

 - If set to SUBDOMAINS, any sub-domain that is in the same domain as the specified domain name will be crawled.  

 - If set to DOMAINS, only the specified domains will be crawled.

uris

  text

Additional URLs to crawl. Each must be a valid HTTP or HTTPS URL consistent with the web application scope.

swaggerFile

   

Swagger-based REST API file that you want to scan for vulnerabilities. To scan the API, you need to specify the content of the Swagger/OpenAPI file in YAML or XML format. Note that we support scanning single API at a time. For scanning Swagger-based REST APIs, the web application URL should point to the Swagger file host or OpenAPI server URL as per the API definition. Before adding the file content, you must encode the file content into base64 format. It is your responsibility to verify that you have permission to scan APIs that you specify as scan targets.

To remove the API file that you added to the web application, add a blank “swaggerFile” tag in the update web application request.

We currently only support Swagger API file version 2.0 and 3.0 in YAML or XML format. The size of the file you upload should not exceed 5 MB.

Example:

<WebApp>
  <id>87452</id>
  ...
  <swaggerFile>
    <name>ajax.yml</name>
    <content>LS0tDQpzd2FnZ2
    VyOiAnMi4wJw0KaW5mbzoN...</content>
   </swaggerFile>

Note that the swaggerFile and postmanCollection tags are mutually exclusive and cannot be specified together in the request.

postman

Collection

   

Postman collection files that you want to scan for vulnerabilities. postmanCollection has 3 tags for specifying Postman Collection File content: “collection” for specifying Postman Collection File content, “environmentVariable” for specifying Postman Environment Variables File, and “globalVariable” for specifying Global Variables File. All these 3 tags are part of the “postmanCollection” tag. While creating the web application, the Postman Collection File is a mandatory parameter whereas specifying the Postman Environmental Variables and Postman Global Variables files is optional.

Note that before adding the file content, you must encode the file content into base64 format.

You can remove the files by sending blank tags in the update request. To remove,

- Postman Environment Variables File, send a blank “environmentVariable” tag.

- Postman Global Variables File, send a blank “globalVariable” tag.

- Postman Collection File, send either a blank "postmanCollection" or “collection” tag. This will also remove the variables file if added.

We currently only support v2.0.0 and v2.1.0. for Postman Collection. The size of the file you upload should not exceed 5 MB.

<WebApp>
<id>87452</id>
...
<postmanCollection>
  <collection>
   <name>Mycollection.XML</name>
   <content>ewoJInZhcmlhYmx
   lcydLAoJImlu...</content>
  </collection>
 <environmentVariable>
   <name>Myenvvariables</name>
   <content>ewoJImlkIjogIjcxN
   TBhYjIyLWE1MDQtNGEz...</content>
 </environmentVariable>
 <globalVariable>
   <name>myglobal.XML</name>
   <content>ewogICJpZIwNTY5Yzkz
   YS02YzRjLWFkMDIt...</content>
 </globalVariable>
</postmanCollection>

Note that the swaggerFile and postmanCollection tags are mutually exclusive and cannot be specified together in the request..

malware

Monitoring

  boolean

A flag indicating whether Malware Monitoring is enabled for the web application.

Example:<malwareMonitoring>true</malwareMonitoring>

malware

Notification

  boolean

A flag indicating whether email notification is enabled for Malware Monitoring scans.

Example:<malwareNotification>true</malwareNotification>

malware

Scheduling*

   

Schedule Malware Monitoring scans for your web application with various scheduling options.

<occurrenceType> can be set to one of: ONCE, HOURLY, DAILY, WEEKLY, MONTHLY.

Scan Settings

defaultProfile*

   

The default option profile for scanning the web application. When unspecified, an option profile must be specified by the user for each scan.

<defaultProfile>

   <id>139359</id>

   <name><![CDATA[10 Links edit]]></name>

</defaultProfile>

defaultScanner*

   

The default scanner for the web application. A default scanner is optional.

For type (keyword) specify INTERNAL for a scanner appliance. If type is INTERNAL, specify friendlyName (text).

EXTERNAL for the external scanners or scannerTags for assigning multiple scanner appliances grouped by asset tag.

Example:

<defaultScanner>
   <type>INTERNAL</type>
   <friendlyName>dp_scanner</friendlyName>
</defaultScanner>

proxy.id

  integer

The default proxy for scanning the web application.

Example:

<proxy>
   <id>12345</id>
</proxy>

scannerLocked

  boolean

A flag indicating whether the default scanner appliance is locked for the web application.

Example:

<scannerLocked>false</scannerLocked>

dnsOverrides*

   

Assign DNS override settings, one or more records, to a web application.

Example:

<dnsOverrides>
    <set>
       <DnsOverride>
          <id>2022</id>
       </DnsOverride>
   </set>
 </dnsOverrides>

useRobots 

  keyword

A flag indicating whether to observe the Robots.txt file and its directives if found when scanning the web application.

If set to IGNORE (default) the Robots.txt file is ignANDed.

If set to ADD_PATHS, the “disallow” and “allow” directives in the Robots.txt file will be observed; this means these directives will be added as link hints for the crawler.

If set to BLACKLIST the “disallow” directives in the Robots.txt file will be observed; this means scans will not crawl matching links.

useSitemap 

  boolean

A flag indicating whether to adhere to a sitemap.xml file if present in the web application: true or false (default).

headers*

 

   

The headers that need to be injected by the scanning engine to scan the web application for complex authentication schemes or to impersonate a web browser.

urlBlacklist*

 

   

The URLs for the black list. These are web application links (URLs) that you do not want scanned. For each URL, specify UrlEntry (text). If the attribute regex (Boolean) is set to “true” the service performs a regular expression match.

urlWhitelist*

 

   

The URLs for the white list. These are web application links (URLs) that you want to be scanned.

For each URL, specify UrlEntry (text). If the attribute regex (Boolean) is set to "true" the service performs a regular expression match.

postData

Blacklist*

 

   

The web application URLs for which you want to block form submission (POST data), as this could have unwanted side effects.

For each URL, specify UrlEntry (text). The attribute regex (Boolean) can be set to “true” for a regular expression match.

authRecords*

 

   

The web application authentication records. The WebAppAuthRecords element identifies a set of authentication instances (combination of form and types).

WebApp

AuthRecord*

 

   

Under <authRecords>, this element identifies an authentication record assigned to the web application. Prior to WAS 3.1, authentication records and their settings were defined here using the Web Applicatin API.  Now you can manage authentication records using the Authentication API.

CrawlingScript

 

   

The selenium crawl script for your web application. The SeleniumScript element tells the selenium script details.

SeleniumScript

 

  text

Under <CrawlingScript>, this element provides more information such as name of the script (text), start point of the crawl, if authentication is required or not, and such other details about the selenium script associated with the web application.

Example:

<crawlingScripts>

              <count>1</count>

                 <list>

                  <SeleniumScript>

                   <id>2500</id>

                                <name><![CDATA[name of the Script]]></name>

               <data>                 .....

             <requiresAuthentication>

                true

              </requiresAuthentication>

             <startingUrl>URL</startingUrl>

              <startingUrlRegex>

                 true

              </startingUrlRegex>

          </SeleniumScript>

       </list> </crawlingScripts>

Elements Assigned by the Service

id

  integer

The web application ID.

owner

  text

The user login ID of the web application owner.

isScheduled

  boolean

Is a scan-scheduled for the web application? (true or false).

createdBy

  text

The user who created the web application.

createdDate

  date

The date when the web application was created in WAS, in UTC date/time format.

updatedBy

  text

The user who last updated the web application.

updatedDate

  date

The date when the web application was last updated in WAS, in UTC date/time format.

lastScan

  text

The scan ID of the last scan run on the web application.

lastScan.status

  keyword

Scan status reported by last web application scan: SUBMITTED, RUNNING, FINISHED, TIME_LIMIT_EXCEEDED, SCAN_NOT_LAUNCHED, SCANNER_NOT_AVAILABLE, ERROR or CANCELED