Create an API Specification Scan
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.
You can also scan APIs with the Dynamic Analysis REST API
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, for JSON and YAML files only, 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.
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.
To complete this task:
Log in to the Veracode Platform.
Select Scans and Analysis > Dynamic Analysis.
Click Scan API Specifications to open the Create page.
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.
From the Options dropdown menu, 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.
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.
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.
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.
Optionally, in the Visibility Settings section, select which user roles or teams can access this analysis and the scan results.
Optionally, in the Organization Information section, enter information specific to your organization.
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.
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.
Column Descriptions for API Specifications to Scan
|Server||Fully-qualified base URL for the specification. Does not apply to HAR files.|
|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, use the options on the API Specification Management tab.|