Skip to main content

Create an API specification scan

You can create an API specification scan in the Veracode Platform to perform a Dynamic Analysis of the following:

  • Endpoints in one or more API specifications.
  • Requests in one or more Postman Collections.

You can also scan APIs with the REST API.

Before you begin:

Before you begin, you must have:

  • A Dynamic Analysis license.
  • A Veracode account. Any member of the team associated with the Dynamic Analysis is able to view the analysis and its results.
  • An API specification file that you want to scan, permissions to scan the file, and any required authentication information. API specifications must be either OpenAPI format in well-formed and uncompressed YAML or JSON, an HTTP Archive (HAR), or a Postman Collection. You can upload a new file or use an existing file uploaded previously.
  • For OpenAPI specifications and Postman Collections, the base URL where the API for your specification is hosted. All scans of the specification will use this URL as an allowed host and ignore requests to other hosts. For more information, see About API specification scans.
  • For Postman Collections, if you have defined variables in Postman environments, you have manually added the variables from the environment files to the variable field in your Postman Collections.
  • If you want to link the API scan and its scan results to an application profile, you have created the application profile. An application profile provides scan history, vulnerability history, reports, policy, and analytics for a linked application. You cannot start the scan from the linked application profile, only from the Dynamic Analysis page in the Veracode Platform.
note

You can only link one application profile to an API scan or web application scan. Also, you cannot use the same analysis for both API and web application scans.

To complete this task:

  1. Sign in to the Veracode Platform.

  2. Select Scans and Analysis > Dynamic Analysis.

  3. Select Scan API Specifications. The Create page opens.

  4. For Dynamic Analysis Name, enter a name for this analysis. Ensure the name is unique to your organization and provides a human-readable description of the analysis.

  5. For API Specifications, select Options. Then, select to upload a new API specification to scan or select an existing API specification. You only need to upload a new specification one time, and it remains available to other analyses. The specification is also available on the API Specification Management tab on the Dynamic Analysis page.

  6. For a new API specification, in the Upload API Specification window, select Choose File.

  7. Locate and select a valid API specification file.

    If you do not enter a name for the API specification, by default, the Veracode Platform uses the filename of the uploaded specification. Depending on the size of your specification file, the upload might take several seconds to complete. Also, the Veracode Platform shows messages about any issues with the specification, such as unsupported file format, invalid syntax, or an issue with the relative URL.

  8. To add the specification to your analysis, select Add to Analysis. Your analysis is listed in the API Specifications to Scan table.

  9. To add additional specifications to the same analysis, repeat steps 5-8.

  10. To link the analysis and the scan results to an application profile, in the API Specifications to Scan table, in the Actions column, select Link link_icon.png. Then, select an application profile and select Link. The name of the linked application profile appears in the Application Name column.

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

    • API Scan Default: accept the default string. Veracode identifies as the originator of the scan 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.

  1. Optionally, under Visibility Settings, select which user roles or teams can access this analysis and the scan results.

  2. Optionally, under Organization Information, enter information specific to your organization.

  3. To certify that your organization has the required permissions to scan the specifications added to this analysis, under Scanning Certification, select the checkbox.

  4. To schedule the analysis, including whether to run a prescan, select Schedule. To verify that Veracode can successfully reach and, if required, authenticate with the target API server, a prescan scans all endpoints or requests in the specification. If you do not want to schedule the analysis, select Review and Submit and Save.

    note

    Because API Scanning scans API specifications quickly, Veracode recommends that you do not schedule the analysis to automatically pause and resume.

  5. Configure the API specification scan.

Last updated on