Reporting REST API

The Reporting API enables you to access Veracode Analytics in your own tools. It generates the Findings report, which can return open, closed, and mitigated findings.

This API supports data from the following scan types:

• Static Analysis
• Dynamic Analysis
• Software Composition Analysis (SCA) upload scans
• SCA agent-based scans linked to applications

The Reporting API can return a maximum of six months of data. Veracode recommends using the Reporting API incrementally to reduce the impact of this limit.

The Reporting API enables reporting scenarios, such as the analysis of trends in departmental security development or the production of recurring executive dashboards.

Permissions and authentication

To enable the Reporting API for your account, send a request to support@veracode.com.

Before you can use all the endpoints of the Reporting API, you must have one of these accounts with the required roles:

• An API service account with the Reporting API role.
• A user account with the Executive or Security Lead role.

This API uses API ID/key credentials and HMAC authentication to provide improved security. Before you can send requests, you must complete these configurations:

• API credentials
• HMAC authentication

Ensure you access the APIs with the domain for your region.

Reporting API specification

The Reporting API specification is available from SwaggerHub.

Examples

The following examples demonstrate how to filter the Veracode Analytics data sets when generating reports with the Reporting API.

You can use any combination of request body filters to narrow down your result set. Exclude parameters to return all findings for that filter.

Generate a report with the REST API

1. To generate a report, send the following request:

   http --auth-type=veracode_hmac POST "https://api.veracode.com/appsec/v1/analytics/report" < input.json

   To request all findings that have been updated from a given date until now, include the minimum required payload. For example:

   {
     "report_type": "findings",
     "last_updated_start_date": "YYYY-MM-DD HH:MM:ss"
   }

   To apply every possible filter to your request, include all valid parameters in the payload. For example:

   {
   "app_id": {numerical application id},
   "scan_type": ["Static Analysis", "Dynamic Analysis", "Manual Analysis", "SCA"],
   "policy_sandbox": "Policy",
   "policy_rule_passed": "no",
   "status": "open",
   "severity" : [1, 2, 3, 4, 5],
   "report_type": "findings",
   "last_updated_start_date": "YYYY-MM-DD HH:MM:ss",
   "last_updated_end_date": "YYYY-MM-DD HH:MM:ss"
   }

   Note the id value in the JSON response.

2. Send a GET request that appends the id from the response to the end of the URL. For example:

   http --auth-type=veracode_hmac GET "https://api.veracode.com/appsec/v1/analytics/report/{id}

Request findings updated since a given date for a specific application profile

This example requires the GUID of a target an application profile.

1. Send the following request to generate a report:

   http --auth-type=veracode_hmac POST "https://api.veracode.com/appsec/v1/analytics/report" < input.json

   Include a payload that specifies the GUID of the target Veracode application. You can use the Applications API to get the GUID for an application profile. For example:

   {
   "app_id": {numerical application id},
   "report_type": "findings",
   "last_updated_start_date": "YYYY-MM-DD HH:MM:ss"
   }

   Note the id value in the JSON response.

2. Send a GET request that appends the id from the response to the end of the URL. For example:

   http --auth-type=veracode_hmac GET "https://api.veracode.com/appsec/v1/analytics/report/{id}

Request findings updated since a given date for specific scan types

1. Send the following request to generate a report:

   http --auth-type=veracode_hmac POST "https://api.veracode.com/appsec/v1/analytics/report" < input.json

   Include a payload that specifies the scan types for which you want to view findings data. For example:

   {
   "scan_type": ["Static Analysis", "Dynamic Analysis", "Manual Analysis", "SCA"],
   "report_type": "findings",
   "last_updated_start_date": "YYYY-MM-DD HH:MM:ss"
   }

   Note the id value in the JSON response.

2. Send a GET request that appends the id from the response to the end of the URL. For example:

   http --auth-type=veracode_hmac GET "https://api.veracode.com/appsec/v1/analytics/report/{id}

Request findings updated since a given date from policy scans

1. Send the following request to generate a report:

   http --auth-type=veracode_hmac POST "https://api.veracode.com/appsec/v1/analytics/report" < input.json

   Include a payload that requests policy findings. For example:

   {
   "policy_sandbox": "Policy",
   "report_type": "findings",
   "last_updated_start_date": "YYYY-MM-DD HH:MM:ss"
   }

   Note the id value in the JSON response.

2. Send a GET request that appends the id from the response to the end of the URL. For example:

   http --auth-type=veracode_hmac GET "https://api.veracode.com/appsec/v1/analytics/report/{id}

Request findings updated since a given date that did not pass policy

1. Send the following request to generate a report:

   http --auth-type=veracode_hmac POST "https://api.veracode.com/appsec/v1/analytics/report" < input.json

   Include a payload that requests findings that did not pass policy. For example:

   {
   "policy_rule_passed": "no",
   "report_type": "findings",
   "last_updated_start_date": "YYYY-MM-DD HH:MM:ss"
   }

   Note the id value in the JSON response.

2. Send a GET request that appends the id from the response to the end of the URL. For example:

   http --auth-type=veracode_hmac GET "https://api.veracode.com/appsec/v1/analytics/report/{id}

Request open findings updated since a given date

1. Send the following request to generate a report:

   http --auth-type=veracode_hmac POST "https://api.veracode.com/appsec/v1/analytics/report" < input.json

   Include a payload that requests open findings. For example:

   {
   "status": "open",
   "report_type": "findings",
   "last_updated_start_date": "YYYY-MM-DD HH:MM:ss"
   }

   Note the id value in the JSON response.

2. Send a GET request that appends the id from the response to the end of the URL. For example:

   http --auth-type=veracode_hmac GET "https://api.veracode.com/appsec/v1/analytics/report/{id}

Request findings updated between a given start date and end date

1. Send the following request to generate a report:

   http --auth-type=veracode_hmac POST "https://api.veracode.com/appsec/v1/analytics/report" < input.json

   Include a payload that specifies the start date and end date for the requested findings. For example:

   {
   "report_type": "findings",
   "last_updated_start_date": "YYYY-MM-DD HH:MM:ss",
   "last_updated_end_date": "YYYY-MM-DD HH:MM:ss"
   }

   Note the id value in the JSON response.

2. Send a GET request that appends the id from the response to the end of the URL. For example:

   http --auth-type=veracode_hmac GET "https://api.veracode.com/appsec/v1/analytics/report/{id}

Request findings updated since a given date with specified severities

1. Send the following request to generate a report:

   http --auth-type=veracode_hmac POST "https://api.veracode.com/appsec/v1/analytics/report" < input.json

   Include a payload that specifies the severities of the requested findings. For example:

   {
   "report_type": "findings",
   "severity": [1,2,3,4,5],
   "last_updated_start_date": "YYYY-MM-DD HH:MM:ss"
   }

   Note the id value in the JSON response.

2. Send a GET request that appends the id from the response to the end of the URL. For example:

   http --auth-type=veracode_hmac GET "https://api.veracode.com/appsec/v1/analytics/report/{id}