Create an API Specification Scan

Getting Started with Veracode API Scanning

You can create an API specification scan in the Veracode Platform to perform a Dynamic Analysis of all endpoints in one or more API specifications.

Before You Begin

  • You have a Dynamic Analysis license.
  • 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.
  • An API specification file that you want to scan, permissions to scan the file, any required authentication information, and the base URL at which the API is hosted. The specification file must be either OpenAPI format in well-formed, uncompressed, YAML or JSON or an HTTP Archive (HAR). For more information, see About API Scanning and API Specifications.
  • 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, flaw 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: The Veracode Platform only allows a single application profile to be linked to a single API specification scan or web application scan. Also, you cannot scan both API specifications and web applications using the same analysis.

Steps

  1. Log in to the Veracode Platform.
  2. Select Scans and Analysis > Dynamic Analysis.
  3. Click Scan API Specifications to open the Create page. API Scanning Prescan Results
  4. In the Dynamic Analysis Information section, enter a name for the Dynamic Analysis. Ensure the name is unique to your organization and provides a human-readable description of the analysis.
  5. From the Options dropdown menu, select to upload a new API specification to scan or select an existing API specification. Upload 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. You can use the API Specification Management tab to upload and manage specifications, including renaming, reviewing configuration settings, and deleting a specification from Veracode. You can only delete specifications that are not referenced in a scan. You can also use this tab to configure visibility settings, which specify the user roles and teams that can access the specification and scan results.
  6. For a new API specification, in the Upload API Specification window, click Choose File, then 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.

  7. After the upload is complete, click Add to Analysis to add the specification to your new analysis. The new analysis is listed in the API Specifications to Scan table. To add additional specifications to the same analysis, repeat steps 5-7.

Column Descriptions for API Specifications to Scan

Column Description
Server Fully-qualified base URL for the specification.
API Specification Name Specification name you entered when uploading the specification.
File Type File type of your API specification: OpenAPI 2.0, OpenAPI 3.0, or HTTP Archive (HAR).
Uploaded Timestamp and Veracode username of the user that uploaded the specification.
Application Name Name of the Veracode application profile to which this scan is linked, if configured.
Internal Scanning Name of the Internal Scanning Management (ISM) gateway, if configured. Veracode uses ISM to scan private APIs behind a firewall.
Actions Options for configuring the specification scan, linking it to an application profile, or removing it from the current analysis. Because more than one analysis can reference the same specification, removing the specification from this table does not delete it from Veracode. To delete a specification from Veracode, in the Veracode Platform, go to Scans and Analysis > Dynamic Analysis > API Specification Management tab and use the actions in the API Specification Management table.
  1. Optionally, to link the analysis and the scan results to an application profile, in the API Specifications to Scan table, in the Actions column, click Link (link icon). Then, select an application profile and click Link.
  2. Optionally, in the Visibility Settings section, select which user roles or teams can access this analysis and the scan results.
  3. Optionally, in the Organization Information section, enter information specific to your organization.
  4. In the Scanning Certification section, select the checkbox to confirm that your organization has the required permissions to scan the specifications referenced in this analysis.
  5. Click Schedule to specify when you want the analysis to run, including whether to run a prescan, or click Review and Submit and Save. A prescan scans each API to verify that Veracode can successfully reach and, if required, authenticate with the target API server.
  6. Configure the API specification scan.