About API specification scans
Use DAST to scan APIs in the Veracode Platform or using the REST API. To assess the security posture of your APIs, the scans crawl and analyze the endpoints defined in specification files or Postman Collections. The results identify vulnerabilities that might require remediation.
In the Veracode Platform, create a target for DAST and upload or select the API specification or Postman Collection you want to analyze. An analysis can contain a maximum of 250 specifications.
To try scanning an API without an OpenAPI or Postman specification, create an HTTP Archive (HAR) file using a free tool such as Chrome Developer Tools. To reduce extraneous traffic—such as third-party requests—apply filtering by selecting Fetch/XHR before exporting the HAR.
Learn more about API scanning.
License to scan APIs
DAST requires a license to scan APIs. Veracode calculates the number of API specifications or Postman Collections you can scan based on the number of target URLs included in your license. Each target URL represents a unique API server defined in your specifications. When you upload a specification in the Veracode Platform, it imports the URLs of the defined API servers. When you upload a Postman Collection, you must specify a custom base URL. Veracode uses this base URL as the target and only scans requests that reference it.
During a specification scan, Veracode detects the target API server and deducts it from the number of target URLs available in your license. If a specification has multiple servers defined, you can select the server you want to use when configuring the scan. If you scan a specification using a defined server and then scan that same specification using a different server, Veracode treats both servers as separate target URLs and deducts both target URLs from your license.
Ensure your DAST license includes a sufficient number of target URLs for the API specifications you plan to scan. To obtain or modify a license, contact your Veracode sales representative.
How the scan engine processes API specifications
When you upload an API specification as an OpenAPI or HAR file, the scan engine performs the following to prepare the file for analysis:
- Converts OpenAPI files to HAR files.
- Parses the HAR files to extract the list of endpoints and the URLs of the target API servers.
- Generates the API call requests.
If you upload a HAR file, it skips the conversion step. When configuring an analysis, you can select which endpoints from this list to include or exclude during scanning. The scan engine does not convert Postman Collections to HAR files.
The scan engine periodically reprocesses the API specifications to ensure that they are up-to-date. We recommend that you periodically review recurring scans to ensure that all endpoints or requests are accurate. If the server-side logic for detecting eligible endpoints or requests changes, you might need to update your scan configurations to include or exclude these rules.
After scheduling the analysis, you can download the HAR file of each scanned API specification from the Veracode Platform. You can also re-upload a downloaded HAR file for scanning.
OpenAPI 2.0 conversion to HAR
When converting OpenAPI 2.0 specification files to HAR format, the scan engine first converts them to OpenAPI 3.0 using the official OpenAPI Swagger Parser. Because OpenAPI 3.0 supports multiple servers, if an OpenAPI 2.0 file specifies the API server array with the host/basepath property, during conversion, the scan engine treats this value as a single entry in the server array.
OpenAPI 3.1 or 3.0 conversion to HAR
When converting OpenAPI 3.1 or 3.0 specification files to HAR format, the scan engine enumerates the API endpoints and generates values for all associated properties. While generating these values, the scan engine retains relevant schema data from the specification to ensure the values are valid. Veracode strongly recommends that all properties in a specification include a detailed schema.
The scan engine uses the endpoints and properties to form HTTP requests, which it also stores in the HAR format. For certain values, particularly URL properties, the HAR files contain URLs that include the property names, typically enclosed in curly brackets ({,}). Corresponding values are encoded within the open-ended comment property present on the request within the HAR file. Other structures within the HAR format might use the comment property to encode schema information and other metadata that the scan engine can use during scanning. Because of these dependencies, prior to re-uploading a downloaded HAR file, Veracode highly recommends that you do not modify the comment property or any of the structures within the HAR file.
HAR conversion and processing
Before scanning HAR files, the scan engine converts the HAR format to internal data structures. During the conversion, the scan engine resolves any URL properties to generate the final, fully-qualified URLs for each request, and then applies all property values.
If an API specification contains combinations of path tokens and hosts for the target API servers, these values can result in double-slashes (//) rather than single slashes during an API request. During conversion, the scan engine changes multiple repeating slashes into single slashes when generating the request URLs. To avoid potential errors during scanning, before uploading your specification, ensure all paths use the correct path format.
API server URLs
You can only scan the absolute, or base, URL of the server that is hosting the API you want to scan. The scan checks for this URL when you upload an API specification or Postman Collection to the Veracode Platform. If the scan can't determine this URL from the uploaded specification or Postman Collection, you see an error with a field to enter the fully-qualified URL. Enter the base URL for your API. For OpenAPI specifications, you can add a custom base URL. By default, when you configure a scan, Veracode automatically selects the base URL from the list of available servers. This base URL replaces any relative URLs in your specification. For Postman Collections, a base URL is required because the URL defines an allowed host that the scanners can attack to find vulnerabilities in requests. HAR files do not support base URLs. If you do not know the base URL for your API, contact the development team that provided the specification file.
After you add a base URL, the scanners treat the value as a url entry in the OpenAPI servers list, as explained in the OpenAPI 3 Documentation. Ensure your value includes any base path. For example, if an API has entry points under /v1/pets, the absolute URL must also have that path: https://api.example/com/v1/pets.