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.

Using an API service account for automations

Veracode strongly recommends that you use an API service account, which is also called an API user, when configuring automations, such as scripts in cron.

For example, if you use a user account and the user assigned to that account leaves your organization, after your Veracode administrator deactivates the account, the user credentials are no longer valid and your automation can no longer authenticate with Veracode. Running automations using an API service account avoids this scenario and also allows a team to get notifications from the Veracode Platform if these events occur. You can create an API service 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 the requests fail, ensure your pipeline successfully 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 errors. 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 an error code of any value other than 0.

Safely storing and managing your Veracode credentials

Never store your API credentials in public locations, such as GitHub repositories, in a shell script, or other code, for example. Exposing your credentials to the public invites anyone to access data about the flaws in your software.

After configuring API credentials, Veracode strongly recommends 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 that you store separately from your code and appropriately secure on your host computer.

If your credentials become compromised, you can use the Identity API to quickly 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 reminder emails from Veracode. Veracode sends these emails seven days and one day before the credentials expire.

Example code for printing credentials expiration warning

This Python code example checks for the expiration date for your API credentials and prints a warning to the console if the credentials are close to expiring:

def creds_expire_days_warning():
    # the get_creds() method calls 
    # https://api.veracode.com/api/authn/v2/api_credentials
    creds = api.VeracodeAPI().get_creds()
    exp = datetime.datetime.strptime(creds['expiration_ts'], "%Y-%m-%dT%H:%M:%S.%f%z")
    delta = exp - datetime.datetime.now().astimezone() #we get a datetime with timezone...
    if (delta.days < 7):
        print('These API credentials expire ', creds['expiration_ts'])

Checking the status of Veracode services

If you need to check the status of various Veracode services, such as the current state of the Veracode Platform or an in-progress scan, Veracode recommends that you use the Veracode Status page or lightweight API calls. Ensure you design these API calls to perform a status check rather than repeatedly calling API endpoints that return more information than you might need. For example:

• To check when scan results are ready, rather than using detailedreport.do, call getbuildinfo.do.
• To check for a detailed report of all scan results related to the specified build, only call detailedreport.do.
• To check the status of the Veracode Platform, use the Veracode Status page or the lightweight Healthcheck 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.

Veracode recommends 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, Veracode recommends 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 for reports

You might need to import Veracode data, such as findings 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.

Veracode recommends 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 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, Veracode recommends the following practices:

• Fetch data for all applications that match your filters. While there is a filter field for app_id, Veracode recommends 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.

Fetching findings 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 access to near real-time findings data, you can use the Findings API.

To simplify the process of identifying which applications have changed since you last retrieved findings data, you can 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.