Skip to main content

Configure and run an API specification scan

After creating an API specification scan in the Veracode Platform, you need to configure the scan with specific settings, such as the target API server, the server authentication method, and, if the server is behind a firewall, an Internal Scanning Management (ISM) gateway.

Before you begin:

  • You have a Veracode account with the Creator, Submitter, or Security Lead role. Any member of the team associated with the Dynamic Analysis is able to view the analysis and its results.
  • You have created an API specification scan.

To complete this task:

  1. Sign in to the Veracode Platform.

  2. Select Scans and Analysis > Dynamic Analysis.

  3. In the All Dynamic Analyses table, locate the row for the analysis that references the API specification you want to configure.

  4. In the Actions column, select Configure Analysis.

  5. In the API Specifications to Scan table, locate the row for the specification you want to configure.

  6. In the Actions column, select Configure (pencil icon) to open the Configure window.
    Upload API Specification

  7. In the API Specification Information section, from the Server dropdown menu, select the URL of the server you want to use with this specification.

    OpenAPI 2.0 only supports a single server, while OpenAPI 3.0 and HAR files support multiple servers. You typically use these servers to select different environments, such as a production instance and a staging environment, or multiple production instances located in different regions.

  8. Optionally, under the selected server URL, select the endpoints to include or exclude during scanning.

    If you uploaded a HAR file that you captured using a browser, but have not filtered the HAR file, ensure that the server hosting your APIs is selected. API Scanning attempts to select the correct server based on traffic analysis, but you must confirm that the correct server is selected.

  9. In the Authentication section, select Required to select and configure an authentication method for accessing the selected server.

  10. Optionally, under Scanner Variables, configure variables that the scanners can use when scanning the API. Add a reference key and value for the variable. If the variable is for multi-factor authentication (MFA), select the TOTP seed checkbox and ensure the reference key value matches the reference key in your login script. You can also configure this setting with the REST API.

  11. Under Additional Authentication Options, select the checkbox for one or more authentication methods.

  12. In the Internal Scanning section, if your scan uses an internal server that is not exposed to the public internet, you can configure Internal Scanning Management (ISM) to enable access to that server. Select a configured ISM gateway and endpoint for accessing the server.

  13. In the Advanced Options section, you can configure a custom user agent that API Scanning sends with each API request. By default, API Scanning identifies as the originator of the scan with Veracode Security Scan/support@veracode.com.

Compared to the substring for web application scanning, this substring does not include browser information. You can also use this substring to exempt Web Application Firewall (WAF) blocking or suppress pager notifications in an Intrusion Prevention System (IPS). See your vendor documentation for information about the solution for your organization.

  1. Under Requests Per Second, select to allow an unlimited number of API requests or enter a limit.
  2. Select Save to save the configuration. Depending on your scan configuration, a full Dynamic Analysis or prescan runs on the specified schedule.
note

Because API Scanning scans each API specification quickly, Veracode does not recommend pausing and resuming the analysis.

Next steps: