Configure an API Specification Scan

Getting Started with Veracode API Scanning

Publication
Getting Started with Veracode API Scanning
Edition date
2023-01-23
Last publication
2023-01-23T19:14:28.364564

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 Scan Management (ISM) gateway.

Before you begin:

To complete this task:

  1. Log 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, click 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. Under Additional Authentication Options, select the checkbox for one or more authentication options you want to use. See the table at the end of this topic for a description of each option.

    Client Certificate

    Use for authenticating with servers configured with TLS authentication. API Scanning responds to any client certificate requests for certificates from a matching issuer with the configured certificate. Ensure the file format of the certificate is PKCS#12, which usually has a .pfx or .p12 extension. Also, you must specify a passphrase for decrypting the private key in the .p12 file.

    Basic Authentication

    Use basic and NTLMv2 authentication for authenticating with internal servers. API specifications that use basic authentication typically have scheme: basic defined in their OpenAPI definitions. For example, in OpenAPI 3.0:

    components:
    securitySchemes:
      basicAuth:
      type: http
      scheme: basic   # specifies to use basic authentication.
    

    Custom Headers

    Common type of authentication for use with Veracode API Scanning. You can define one or more name/value pairs. When defining the name, do not add any trailing colons. Values typically do not include a colon, but this is legal according to the RFC. You cannot use these reserved header names:

    Accept-Charset

    Accept-Encoding

    Access-Control-Request-Headers

    Access-Control-Request-Method

    Connection

    Content-Length

    Cookie

    Cookie2

    Date

    DNT

    Expect

    Host

    Keep-Alive

    Origin

    Referer

    TE

    Trailer

    Transfer-Encoding

    Upgrading

    Via

    Custom headers in OpenAPI specifications use apiKey or bearerAuth security scheme types. Because authentication might occur at a different layer of the solution, such as through an API gateway, you might not need to add it to the API specification. Ensure you check with the development team that created the specification to confirm the authentication solution.

    This example shows a custom header with the name X-API-KEY:

    openapi: 3.0.0
    ...
    components:
    securitySchemes:
       ApiKeyAuth:      # arbitrary name for the security scheme
       type: apiKey
       in: header       # can be "header" or "cookie"
       name: X-API-KEY  # name of the header, query parameter, or cookie
    

    This example shows a JWT bearer token:

    openapi: 3.0.0
    ...
    components:
    securitySchemes:
       bearerAuth:  # arbitrary name for the security scheme
       type: http
       scheme: bearer
       bearerFormat: JWT 
    

    You can configure this token as a custom header with name Authorization and value Bearer $JWT_CONTENT, where $JWT_CONTENT is a series of period-delimited, base64-encoded JSON fragments.

    OAuth 2.0

    Authenticate with servers that require the OAuth 2.0 protocol. API Scanning supports both the Client Credentials and Password Credentials grant types, which you can select from the Grant Types dropdown menu. For both grant types, a scope is optional. If you need to enter multiple scope values, separate each value with a space. Veracode sends all authorization data as an HTTP Authorization Header.

    If you select the Client Credentials grant type, you can select the Use OpenID Connect checkbox to use OAuth 2.0 with OpenID Connect. After selecting the checkbox, enter the URL for the authentication server in the OpenID Connect URL field.

    Scriptable Request Modification

    Use a plain text JavaScript file to provide logic that can modify an HTTP request at runtime. Example modifications include changing the request URI, HTTP headers, or the request body. After uploading your JavaScript file to the Veracode Platform, Veracode recommends running a prescan to ensure the script is free of any errors, your authentication credentials are valid, and Veracode can use it to successfully make requests to the target host. The Veracode Platform alerts you to any errors in your script. Veracode provides an example script that you can use as a starting point.

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

  12. 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/[email protected].

    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.

  13. Under Requests Per Second, select to allow an unlimited number of API requests or enter a limit.

  14. Click 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: