Configuring DAST scans with a Postman collection URL using REST APIs

Overview

This section explains how to use the REST API in AppScan Enterprise to configure Dynamic Application Security Testing (DAST) scans by providing a URL to a Postman collection. This feature allows for the automation of scan configurations using your existing Postman collections, which can be particularly useful when setting up AppScan Dynamic Analysis Client (ADAC) jobs or other dynamic scans. This API-driven method provides a way to perform this configuration directly within AppScan Enterprise, replacing manual steps previously often managed via AppScan Standard.

Note:
  • This API is specifically for DASTConfig jobs and cannot be used with Content-Scan jobs.
  • If a DASTConfig job already has a Postman collection URL configured, using this API will replace the existing one.

API endpoint for Postman URL configuration

  • POST /jobs/{jobId}/dastconfig/postman/url/add – Add a Postman collection URL 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 (Integer) 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, typically named asc_xsrf_token or similar, with its corresponding value.
  • We recommend using the ‘Regular scan’ template to avoid any performance issues.
    Note:
    If the web API requires authorization, the authorization request must include valid credentials (API Key, Basic Auth., or other fixed tokens and passwords). The authorization request must be one of the first requests in the collection. By default, AppScan Enterprise examines the first seven requests for the authorization request, but if needed, this can be increased in the ADAC client in Advanced Configuration > Postman: Login analysis sample size.

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

Purpose: This API endpoint allows you to configure an existing DASTConfig job in AppScan Enterprise to use a Postman collection, provided via a URL, for defining the scan scope and API interactions.

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

Path parameters:

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

Request parameters:

  • postmanCollectionUrl (String, Required): The URL to the Postman collection (e.g., http://example.com/collection.json).
  • envVariablesUrl (String, Optional): The URL to a Postman environment JSON file.
  • globalVariablesUrl (String, Optional): The URL to a Postman global variables JSON file.
  • postmanAdditionalFiles (File, Optional): A zip archive containing any external files required by the Postman collection (e.g., data.zip). Maximum size: 80 MB.
  • domainsToBeTested (String, Required): A comma-separated list of domains that will be scanned based on the collection (e.g., api.example.com, auth.example.com).

Request headers (Example):

  • asc_xsrf_token: {your_obtained_token_value}
  • Content-Type: multipart/form-data (if postmanAdditionalFiles is included) or application/json (if only URLs are sent, though form-data is generally recommended by feedback for this API).
Note:
  • Use form-data option to configure the API, especially when including postmanAdditionalFiles. The parameter names listed above are the keys (names) for the form fields, and the URLs, file uploads, and domain lists are their respective values.
  • Ensure that any authentication required by the target APIs within the Postman collection is appropriately handled (as mentioned in prerequisites or within the collection/environment variables).
  • Postman collection version 2.0 and later is supported.
  • The Postman collection URL extension should be .json.
  • Domains not included in domainsToBeTested will not be scanned.
  • When you add a Postman collection URL to a DAST job, the URLs are saved in the template file. However, additional files aren’t included in the template. To access them, download the SCAN file.
  • Only one Postman Collection URL can be added per scan. To scan a second collection URL, create a new scan for that collection.

Response:

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