Configuring DAST scans with OpenAPI definitions using REST APIs

Overview

This section explains how you can use the REST APIs to configure Dynamic Application Security Testing (DAST) scans using OpenAPI definitions.

This method supports both file-based (JSON, YAML, YML) and URL-based OpenAPI definitions, and adds new support for configuring authorization and additional parameters for your API scans.

You will follow a two-step process:

Step 1: Use POST /jobs/{jobId}/dastconfig/openapi/specification/process to upload an OpenAPI file or process an OpenAPI URL. This API extracts and returns the file path and a list of available parameters from the definition.
Step 2: Use POST /jobs/{jobId}/dastconfig/openapi/configure to apply the configuration. You pass the location of the file/URL along with the baseUrl and any optional authorization or parameter values.

Note:

You can only use these APIs for DASTConfig jobs. You can't use them with Content-Scan jobs.
If a DASTConfig job already has an OpenAPI configuration, using the .../configure API replaces the existing one.

API endpoints for OpenAPI-based configuration

POST /jobs/{jobId}/dastconfig/openapi/specification/process – Uploads an OpenAPI description file or processes a URL for later use in configuration and parameter retrieval.
POST /jobs/{jobId}/dastconfig/openapi/configure – Creates or updates the DAST configuration using an OpenAPI definition.

Prerequisites

You need an existing DASTConfig job. We recommend that you use the 'Regular scan' template to avoid performance issues. You can create a DASTConfig job using any of the following APIs:
- POST/jobs/{templateId}/dastconfig/createjob
- POST/jobs/createjobBasedOnTemplateFile
- POST/jobs
You need the jobId of the DASTConfig job. You can get this by using the GET /folders/{folderId}/jobs API endpoint.
You need a valid asc_xsrf_token for API request authentication. You can get this from the POST /login API endpoint. You must send this token as a request header.

API reference: POST /jobs/{jobId}/dastconfig/openapi/specification/process

Purpose: Use this API to upload an OpenAPI Description file or OpenAPI URL, which you can then reference with the .../configure API. This API also extracts and returns a list of additional parameters available in the uploaded file or from a provided URL.

HTTPS method and endpoint: POST /jobs/{jobId}/dastconfig/openapi/specification/process

Path parameters:

jobId (Integer, Required): The unique identifier of the DASTConfig job.

Request parameters (multipart/form-data):

openApiDescriptionFile (File, Optional): The OpenAPI specification file in .json, .yaml, or .yml format.
openApiUrl (String, Optional): A publicly accessible URL pointing to an OpenAPI document in .json, .yaml, or .yml format.

Note:

For file-based OpenAPI configuration, you must use this API to upload the file before you call .../configure.
For URL-based configuration, using this API is optional. You can use it to preview and retrieve available parameters from the URL before configuration.

Success response (200 OK):

The API returns a 200 OK on success, with the file path (if uploaded) or URL (if provided), and the extracted parameters from the OpenAPI specification.

Response class (model):

OpenApiProcessResponse {
  openApiFileLocation (string): The location (URL or path) of the generated OpenAPI file,
 
  parameters (array[OpenApiAdditionalParameters], optional): A list of API parameters extracted from the OpenAPI specification
}

OpenApiAdditionalParameters {
  path (string, optional):
      The API endpoint path (e.g., /login, /account/{accountNo}),
 
  name (string, optional):
      The name of the parameter (e.g., username, password, accountNo),
 
  location (string, optional):
      The location of the parameter (e.g., body, path, query)
}

See Response Messages for error codes.

API reference: POST /jobs/{jobId}/dastconfig/openapi/configure

Purpose: Use this API to configure a DAST job for OpenAPI. You cannot add this configuration to a Content-Scan job. If an existing configuration is present, this API call replaces it.

HTTPS method and endpoint: POST /jobs/{jobId}/dastconfig/openapi/configure

Path parameters:

jobId (Integer, Required): The path parameter for the DASTConfig job to which you are applying the configuration.

Request body parameters (JSON):

openApiFileLocation (String, Required): Provide either a publicly accessible URI pointing to a standardized OpenAPI document (.json, .yaml, .yml), or the file path returned by the .../openapi/specification/process API for file-based configuration.
baseUrl (String, Required): Specify the root URL that defines the common path prefix for all API endpoints in the OpenAPI description.
additionalDomains (String, Optional): Specify other domains to be tested, as comma-separated values.
authorization (Object, Optional): Provide a key-value pair for API authorization. These values are updated in the DAST config job and used for authenticated API requests.
```
{ "key": "string", "value": "string" }
```

parameters (Array[Object], Optional): Provide a list of additional parameters to set in the DAST config job. You can retrieve additional parameters by using the .../openapi/specification/process API.


                                [
                                {
                                "path": "string",
                                "name": "string",
                                "location": "string",
                                "value": "string"
                                }
                                ]

Request body example (JSON):


                        {
                        "openApiFileLocation": "string",
                        "baseUrl": "string",
                        "additionalDomains": "string",
                        "authorization": {
                        "key": "string",
                        "value": "string"
                        },
                        "parameters": [
                        {
                        "path": "string",
                        "name": "string",
                        "location": "string",
                        "value": "string"
                        }
                        ]
                        }

Note:

If you add a local JSON or YAML description file instead of a URL to a configuration, you cannot export it as a SCANT (template) file, as the specification file cannot be included in a template. You must either remove the specification file or save it as a SCAN file.

Success response (200 OK):

On success, the API returns an HTTP status code 200 OK.

Error response class (model):


                        ErrorMessage {
                        errorMessage (string)
                        }

See Response Messages for other error codes.