Skip to main content

Configure and run an API specification scan

After you create 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 and endpoint.

Before you begin:

Before you begin, you must 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.
  • 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 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 specification you want to configure.

  6. In the Actions column, select Configure. The Configure window opens.

  7. Under API Specification Information, for Server, select the URL of the server you want to use with this specification.

    OpenAPI 2.0 specifications and Postman Collections only support a single server, while OpenAPI 3.0 specifications and HAR files support multiple servers. If you are scanning a HAR file that you captured using a browser, but you have not filtered the HAR file, ensure that the correct server is selected. The scanners attempt to select the correct server by analyzing network traffic in the HAR file.

  8. To open the Endpoints (OpenAPI or HAR) or Requests (Postman Collections) table, select the server name in bold. The table lists all endpoints or requests in the specification.

  9. In the Endpoints or Requests table, under Scope, select from the following:

    • Include: include the endpoint or request in the scan. By default, all endpoints or requests are included.
    • Exclude: exclude the endpoint or request from the scan. The scanners do not send requests to excluded endpoints or requests.
    • Ignore: for Postman Collections only, send the request during the scan, but do not detect vulnerabilities for it. The scanners only send the request and run any pre- or post-processing in the Postman Collection. For example, you might want to ignore a request that you do not want to scan, but that request is a dependency of another request that you do want to scan.

  10. To configure authentication methods that the scanners use to access the selected server, under Authentication, for Authentication required, select Required.

  11. Optionally, to define variables that you can reference in a login script, select Scanner Variables. Then, add a reference key and value for a variable. If a variable is for multifactor authentication (MFA), select TOTP seed and ensure the reference key value matches the reference key in your login script. You can also configure this setting with the REST API.

  12. Optionally, for Postman Collections, to block or exclude requests to target URLs, select URL-Specific Blocklist and Ignorelist. The scanners send requests to these URLs, but the URLs are not included in the scan. Then, select from the following:

    • BLOCKLIST: to send all requests to any URLs, select Do not exclude any specific URLs (the default). To block requests to a URL, select Exclude the following URLs and enter the URL. To add additional URLs, select Add URL.
    • IGNORELIST: to send all requests to any URLs, but not include the requests in the scan, select Do not ignore any specific URLs. To ignore a request based on a target URL, select Ignore the following URLs and enter the URL. To add additional URLs, select Add URL.

    Any requests that are blocked in the Requests table take precedence over the blocklist and ignorelist. For example, if you block a request in the Requests table and add a target URL for that request to an ignorelist, or you don't block any target URLs, that request is blocked and excluded from the scan. Conversely, if you include or ignore a request in the Requests table and add a target URL for that request to a blocklist, that request is blocked and excluded from the scan.

  13. To select an Internal Scanning Management (ISM) gateway and endpoint, select Internal Scanning. Then, select a gateway and endpoint. The scanners use ISM to access internal servers that are behind a firewall or not exposed to the public internet.

  14. Optionally, select Advanced Options and configure the following:

    • User Agent: configure a user agent string that the scanners add as a header to each API request. For Browser, select one of the following:

      • API Scan Default: accept the default string. Veracode identifies as the originator of the request with Veracode Security Scan/[email protected].
      • Custom: add your custom string to User Agent.

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

    • Requests Per Second: enter the maximum number of requests the scanners send to the selected server every second. For Request Limit, select Unlimited or select Limit to and enter the number of requests.

  15. To save the configuration, select Save. A prescan or full Dynamic Analysis runs on the configured schedule.

Next steps:

Last updated on