Skip to main content

API best practices

The Veracode APIs allow you to perform and automate security testing tasks you perform in the Veracode Platform and with Veracode integrations. The best practices in this section help you avoid performance issues for your automations.

note

Veracode APIs and integrations require access to specific region domains, depending on the region for your Veracode account. Contact your IT team to ensure the correct domains for your region are on the allowlist for your organization. Also ensure that your organization allows outbound communication on port 443 to the domain for the REST APIs.

General usage guidelines​

The REST APIs, XML APIs, and API wrappers have specific prerequisites, but there are general guidelines that apply to all APIs.

note

You can use OAuth Client Credentials to authenticate with the REST APIs and XML APIs, but not the API wrappers.

Using an API user account for automations​

We recommend using an API user account, also called an API user, when configuring automations such as cron scripts.

For example, if you use a UI user account for an automation and that user leaves your organization, the credentials are no longer valid after a Veracode administrator deactivates the account. As a result, the automation can no longer authenticate with Veracode. Using an API user account for automations avoids this scenario and allows your team to receive notifications when the API credentials are scheduled to expire. You can create an API user account in the Veracode Platform or with the Identity API.

Ensuring API requests succeed before adding them to a production pipeline​

Before adding Veracode APIs to your production pipelines or other build jobs, send a few API requests from a test pipeline to ensure the requests succeed. If a request fails, ensure the pipeline also fails the build.

For example, if your pipeline sends a request to start a Static Analysis and the request fails, your team might not see the error and the same request continues to fail during subsequent pipeline runs. If the same job also creates a sandbox with every scan, you could be creating a large number of sandboxes with incomplete scans.

By default, the Java API wrapper automatically fails a pipeline if a Veracode scan returns an error. If you write your own scan logic with the Veracode APIs, or if your pipeline automation sends a different API call, you must check for errors and configure your script to return a nonzero exit code.

Safely storing and managing your Veracode credentials​

Never store your API credentials in publicly accessible locations, shell scripts, or other code, including public GitHub repositories. Exposing your credentials could allow unauthorized users to access information about flaws in your software.

After configuring API credentials, we recommend you use one or more of these options to protect them:

  • Pipeline secrets. See the documentation for your pipeline vendor.
  • Pipeline environment variables. See the documentation for your pipeline vendor.
  • API credentials file. Store the file separately from your code and secure it appropriately on your host computer.

If your credentials become compromised, you can use the Identity API to revoke them.

Ensuring Veracode credentials are valid​

You must not let your API credentials expire. By default, API credentials expire 1 year (365 days) after you generate or renew them. If you do not renew credentials before they expire, any automations that use them will fail.

You can generate API credentials in the Veracode Platform or with the Identity API.

After generating your API credentials:

  • Make a note of the expiration date and set a reminder to renew the credentials.
  • Check the expiration date in your automation scripts and print a warning to notify your team when the credentials are scheduled to expire.
  • Monitor your email inbox for reminders from Veracode. Veracode sends these emails seven days and one day before the credentials expire.

Checking the status of Veracode services​

To check the status of Veracode services, such as the Veracode Platform or a scan in progress, use the Veracode Status page or lightweight API calls. Design these API calls to perform status checks rather than repeatedly calling endpoints that return more information than you need. For example:

  • To check when scan results are ready, rather than using detailedreport.do, call getbuildinfo.do.
  • Call detailedreport.do only when you need a detailed report of all scan results for a specific build.
  • To check the status of the Veracode Platform, use the Veracode Status page or send the lightweight GET principal request to the Identity API.

Allowing sufficient time between polling calls​

You might need to make one API call to initiate a long-running action, then make a second call to check whether that action has completed. For example:

  • Submitting a static scan, then checking scan status
  • Requesting a flaw report, then attempting to download it

If your automation checks for updates on these actions every ten seconds, for example, this excessive polling can degrade performance for your account and Veracode might begin to throttle your API calls.

We recommend that you wait at least two minutes between API calls that check for the status of a scan or report. For static scans, consider using Pipeline Scan, which typically executes faster than an equivalent static policy scan or sandbox scan.

Retrying API calls​

It is a best practice to check for errors when making API calls and retry when certain errors are observed. To avoid unnecessary retries, follow the guidance below.

Retrying with rate limits​

Veracode practices API rate limiting to ensure optimal performance and availability for all users. If a Veracode API call returns an HTTP 429 error code, check the value of the retry-after header and retry after that number of seconds has passed.

Retrying failed actions to resolve transient network issues​

When using Veracode APIs in your pipeline, if network problems or other issues cause your pipeline to fail, your application build could be in a bad state. These issues might be unrelated to a network communication failure, particularly when checking for status, between Veracode APIs and Veracode services.

To ensure your API integration is more resilient to transient network failures, we recommend that you retry the failed actions no more than five times.

Using the Veracode API wrappers for static uploads​

Veracode integrations are built on the API wrappers. These wrappers simplify accessing and using the XML APIs from the command line or functions. You can use them for common workflows, such as uploading application code to a new or existing application profile. For static upload scenarios, the uploadandscan action can replace three or more separate API calls for creating an application profile, creating a sandbox, uploading files and starting a prescan and scan. The uploadandscan action also includes guidance mentioned in this section, such as automatic retries on network errors and waiting between status calls.

Fetching findings and scans for reports​

You might need to import Veracode data, such as findings or scan information for the applications you are scanning, to an external vulnerability management system, dashboard, or business intelligence (BI) tool. If you have custom integrations that routinely fetch data for several, or all, of your applications, these requests can degrade the performance of your Veracode account.

We recommend using the Reporting API to fetch data for large volumes of applications for reporting use cases. The Reporting API allows making a single API call to retrieve findings or scan data across many applications, greatly reducing API traffic and avoiding API use patterns that might lead to rate limiting. The Reporting API also allows reporting on closed findings, which is often necessary for reporting use cases.

When using the Reporting API, we recommend the following practices:

  • Fetch data for all applications that match your filters. While there is a filter field for app_id, we recommend not using this except for debugging purposes. It is more efficient to call the Reporting API for all findings that changed in a certain period than to make multiple calls to the Reporting API for each application in your account.
  • Apply other filters to restrict the data retrieved. For instance, if you do not need to report on sandbox scans, set the policy_sandbox filter to policy.
  • Use the SCANS report type to fetch large volumes of static, dynamic, and manual scan information. That information includes scans from SCA Upload and Scan, which occur simultaneously with static scans, but does not include SCA agent-based scans.

Fetching findings and scans for near real-time information​

The Reporting API uses Veracode Analytics as its data source, and therefore does not have real-time data. If you need near real-time information for a single or small number of applications, we recommend:

For findings or scans for a large number of applications, we recommend using the Reporting API.

To simplify the process of identifying which applications have changed since you last retrieved findings or scans data, use the last_policy_compliance_check_date property of the Applications API.

Each time Veracode evaluates the policy for an application, it updates the value for this property based on these events:

  • Publishing a new policy scan
  • Approving a mitigation
  • Assigning a different policy to the application

To get only the applications that have had a policy check since the last time you retrieved data, you can use the policy_compliance_checked_after query filter with the Applications API. This allows you to process only changed applications, which significantly decreases total processing time and reduces the number of required API calls.

Last updated on