Configuring DAST scans with OpenAPI definitions using REST APIs

Overview

This section explains how to use the REST APIs to configure Dynamic Application Security Testing (DAST) scans using OpenAPI definitions. You can provide these definitions either as a publicly accessible URL or by directly uploading an OpenAPI specification file in JSON, YAML, or YML format. This API-driven approach provides automation for your API security testing workflows directly within AppScan Enterprise, replacing manual configuration steps that previously often involved AppScan Standard. This topic covers the two API endpoints dedicated to OpenAPI-based scan configurations.
Note:
  • These APIs are specifically for DASTConfig jobs and cannot be used with Content-Scan jobs.
  • If a DASTConfig job already has an OpenAPI configuration (from a URL or a file), using these APIs will replace the existing one.

API endpoints for OpenAPI-based configuration

  • POST /jobs/{jobId}/dastconfig/openapi/url/add – Add a public OpenAPI URL to a DASTConfig job.
  • POST /jobs/{jobId}/dastconfig/openapi/add – Upload an OpenAPI file to a DASTConfig job.

Prerequisites

  • You will need an existing DASTConfig job. You can create DASTConfig jobs using any of the following existing APIs:
    • POST/jobs/{templateId}/dastconfig/createjob
    • POST/jobs/createjobBasedOnTemplateFile
    • POST/jobs
  • The jobId of the DASTConfig job is required. This can be retrieved using the GET /folders/{folderId}/jobs API endpoint.
  • A valid asc_xsrf_token is required for API request authentication and can be obtained from the POST /login API endpoint. This token should be sent as a request header.
  • We recommend using the 'Regular scan' template for the DASTConfig job to avoid any performance issues.

API reference: POST /jobs/{jobId}/dastconfig/openapi/url/add

Purpose: This API endpoint allows you to configure an existing DASTConfig job in AppScan Enterprise to use an OpenAPI definition provided via a publicly accessible URL.

HTTP method and endpoint: POST /jobs/{jobId}/dastconfig/openapi/url/add

Path parameters:

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

Request body parameters (JSON): The request must contain a JSON body with the following parameters:

  • openApiUrl (String, Required): The publicly accessible URL pointing to the OpenAPI specification document (e.g., http://example.com/openapi.json).
  • baseUrl (String, Required): The root URL prefix for all API endpoints defined in the OpenAPI document (e.g., https://demo.testfire.net/api/).
  • additionalDomains (String, Optional): A comma-separated list of other domains to be included in the scan's scope apart from the domain included in the baseUrl (e.g., api.example.org, static.example.com).
Note:
  • Ensure your OpenAPI document correctly specifies any authentication needed for the API being scanned, as AppScan Enterprise will rely on the definition for security requirements.
  • Configure API authentication if required. Based on your specification file, configure authentication through Login Management (record login or use automatic login) to ensure better scan coverage, covering most endpoints and avoiding request failures.
  • Configuring API key authentication is not supported by AppScan Enterprise.

Response:

  • On success, the API returns an HTTP status code 200 OK.
  • For error details, refer to the API's Swagger documentation.

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

Purpose: This API endpoint allows you to upload an OpenAPI specification file directly to an existing DASTConfig job in AppScan Enterprise.

HTTP method and endpoint: POST /jobs/{jobId}/dastconfig/openapi/add

Path parameters:

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

Request parameters (multipart/form-data): This API expects a multipart/form-data request with the following parts:

  • openAPIDescriptionFile (File, Required): The OpenAPI specification file.
    • Supported formats: .json, .yaml, or .yml.
    • Maximum file size: 90 MB.
  • baseUrl (String, Required): The root URL prefix for all API endpoints defined in the OpenAPI file (e.g., https://demo.testfire.net/api/). (Likely sent as a form field with this name).
  • additionalDomains (String, Optional): A comma-separated list of other domains to be included in the scan's scope apart from the domain included in the baseUrl (e.g., api.example.org, static.example.com). (Likely sent as a form field with this name).
Note:
  • Confirm the exact form field names for baseUrl and additionalDomains from the API's Swagger documentation if needed.
  • The uploaded OpenAPI file should define any necessary API security schemes for authentication.
  • Configure API authentication if required. Based on your specification file, configure authentication through Login Management (record login or use automatic login) to ensure better scan coverage, covering most endpoints and avoiding request failures.
  • Configuring the API key authentication is not supported in AppScan Enterprise.
  • 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.

Response:

  • On success, the API returns an HTTP status code 200 OK.
  • For error details, refer to the API's Swagger documentation.