Skip to main content

Configure an analysis for an API

In the Veracode Platform, configure specific scan 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 created an analysis for the API you want to 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.1 or 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 options:

    • 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 scanner variables that you can reference in a 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. To save the configuration, select Save. A prescan or full Dynamic Analysis runs on the configured schedule.

After the analysis completes, we recommend linking the results to the related application profile. With the results linked, you can access results from multiple scan types for the same application, and review aggregated results from all scans in the Dynamic Analysis Coverage Report If you ran a prescan, learn more about prescan results for API scans.

Authentication​

This section explains the following authentication methods you can use when configuring an analysis.

Client Certificate​

Use for authenticating with servers configured with TLS authentication. The scanners respond 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 that decrypts 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 HTTP Header​

Common type of authentication for scanning APIs. 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.

The following 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

The following 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. Dynamic Analysis 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, we recommend running a prescan to ensure that:

  • Your script is free of errors. The Veracode Platform alerts you to any errors in your script.
  • Your authentication credentials are valid.
  • The Veracode Platform can use the script to successfully make requests to the target host.

We provide example scripts for modifying request authentication.

Add one or more HTTP cookies that the scanner can use to authenticate with the target server. For Cookie, enter the cookie data. For example, mycookie=chocolate; domain=veracode.com. To add additional cookies, select Add Another.

Scanner Variables​

Configure scanner variables in the Veracode Platform to define information that you can reference in your login scripts for web application scans. The variables consist of a reference key and value. You typically create scanner variables that define sign in credentials you want to keep safe and reuse in multiple scripts.

To indicate that the variable defines a time-based one-time password (TOTP) secret for multifactor authentication, select TOTP seed.

Internal Scanning​

If scanning an internal web application behind a firewall, select the ISM gateway and the associated endpoint that can access the URL.

If you select a gateway that is not associated with an accessible ISM endpoint, or the endpoint isn't ready for scanning, or you select an endpoint that is not reachable by the URL, the Dynamic Analysis fails.

Endpoints are identified as Ready, Pending, or Offline.

Gateway​

Select the gateway associated with an endpoint that can access the URL. If you select a gateway that is not associated with an accessible endpoint or is not ready for scanning, the Dynamic Analysis fails.

Endpoint​

Select an endpoint that can access the URL. If you select an endpoint that is not reachable by the URL or is not ready for scanning, the Dynamic Analysis fails. The scan identifies the endpoints as Ready, Pending, or Offline.

note

All of your configured gateways and endpoints are available for selection. If you do not know which gateways and endpoints are reachable by the URL, work with your ISM administrators to identify them.

Advanced Options​

Expand Advanced Options to configure the following settings.

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.

Last updated on