REST APIs quickstart
This quickstart steps you through accessing the Veracode REST APIs using Postman. For more advanced setup instructions for Java or Python, see Enabling HMAC for Veracode APIs
To access the REST APIs with Postman, complete the following tasks:
- Obtain a Veracode account.
- Enable access to the APIs.
- Sign in to the Veracode Platform.
- Use the Veracode Platform to generate API credentials.
- Set up Postman and import an example collection of requests.
- Send your first request to authenticate with Veracode.
- Optionally, send requests to retrieve scan results.
Obtain a Veracode account
To access the Veracode APIs, you must have a Veracode human user account. To complete this quickstart, your account does not require specific roles.
If you need an account, contact the Veracode Administrator for your organization.
Enable API access
For this quickstart, the Veracode APIs require access to analysiscenter.veracode.com and api.veracode.com, which are both in the Commercial Region. Contact your IT team to ensure both domains are on the allowlist for your organization and that there is one-way communication on port 443 to api.veracode.com. If your account is in the European Region or the US Federal Region, these regions use specific domains that must be on your allowlist. Refer to the complete list of domains and IP addresses to add to your allowlist.
Sign in to the Veracode Platform
Sign in to the Veracode Platform domain for your region using one of the following methods. Each region has a unique URL. This quickstart uses the Commercial Region domain: https://analysiscenter.veracode.com/. Your account might be in a different domain, such as the European Region: https://analysiscenter.veracode.eu/
- If you have a new Veracode account, you received a welcome email that provides a link for activating your account in the Veracode Platform. If you did not receive the welcome email, contact your Veracode Administrator.
- If you have an active Veracode account, you can sign in to the Veracode Platform using the domain for your region. If your organization uses a Single Sign-On (SSO) portal such as Okta, you can also access the Veracode Platform with SSO.
Generate API credentials
You must have Veracode API credentials to access and use the Veracode APIs.
To complete this task:
- In the Veracode Platform, from the user account dropdown menu, select API Credentials.
- Select Generate API Credentials.
- Copy the ID and secret key to a secure place. You provide these credentials when you set up Postman.
Though not required for this quickstart, Veracode recommends that you store your credentials in an API credentials file.
Set up Postman
Install Postman, download and configure a Veracode example Postman Collection from GitHub, and add your API credentials to a new environment.
To complete this task:
-
Install the latest version of Postman.
-
Download the collection
Veracode Example.postman_collection.jsonfrom this repo veracode-postman. -
Open Postman and import the collection
Veracode Example.postman_collection.jsoninto a new or existing workspace. -
Select New > Environment.
-
Enter a name, such as
Veracode, for the environment and press Enter. -
Add the following variables (case-sensitive) to the environment:
api_id: For Type, select secret. For Current value, enter your Veracode API ID.api_key: For Type, select secret. For Current value, enter your Veracode API key.
noteIf your account is in the European Region, you must delete
vera01ei-andvera01es-from the API ID and key values. -
If your account is not in the Commercial Region, change the values for the
base_urlvariable to the domain for your region. -
Select Save to save your environment.
Send your first request
Use Postman to send your first request to the Identity API and authenticate with Veracode.
To complete this task:
-
In Postman, select Collections, then expand the Veracode Example collection.
-
In the Veracode Example collection, select GET Self.
-
From the dropdown menu at the top-right, ensure the environment that contains your Veracode API credentials is selected. For example, if No Environment is selected, change it to the appropriate environment.
-
Select Send. If the request is successful, the response Status shows a green
200 OK. The Body tab shows details about your account, such as your username, organization, and any assigned roles. If you encounter errors, see troubleshooting.
-
To improve the security of your requests, in the environment that contains your Veracode API credentials, locate the
hmacAuthHeadervariable and set Type to secret. Then, select Save.
You can now use the REST APIs in Postman!
Optional: Retrieve scan results
This section is optional because your Veracode account must have the Reviewer role for you to review results. To add this role to your account, contact the administrator for your organization.
The requests in this section use scan results from the demo application verademo.war, which is covered in the Static Analysis Quickstart. The Static Analysis results contain both static flaws and Software Composition Analysis (SCA) vulnerabilities. You use the REST APIs to retrieve and review the results of verademo.war in Postman.
Retrieve the application profile ID
You need to obtain the GUID of the application profile that is linked to the scan results.
To complete this task:
-
In the Veracode Example collection, select the GET Applications request.
-
Select Send to send a request to the Applications API.
To return a list of application profiles by name, append the
?name=query parameter to the request URL:{{base_url}}/appsec/v1/applications/?name=verademoThe following example shows the response for a Static Analysis of
verademo.war. Under theprofileproperty, notice thenameproperty containsverademo. The GUID for the application profile isa99686b7-b54a-4fc4-abf5-cac0315fc041.{
"id": 1571531,
"oid": 72529,
"last_completed_scan_date": "2022-10-31T13:41:35.000Z",
"guid": "a99686b7-b54a-4fc4-abf5-cac0315fc041",
"created": "2022-10-31T13:13:49.000Z",
"modified": "2022-10-31T13:41:35.000Z",
"app_profile_url": "HomeAppProfile:72529:1571531",
"scans": [
{
"scan_type": "STATIC",
"status": "PUBLISHED",
"modified_date": "2022-10-31T13:41:35.000Z",
"scan_url": "StaticOverview:72529:1571531:21801526:21772979:21788629",
"internal_status": "resultsready",
"links": [],
"fallback_type": null,
"full_type": null
}
],
"last_policy_compliance_check_date": "2022-10-31T13:43:13.000Z",
"profile": {
"name": "Verademo",
"tags": null,
"business_unit": {
"id": 76248,
"name": "Not Specified",
"guid": "677a8473-a5f9-4a00-9275-072005a7f488"
},
"business_owners": [],
"archer_app_name": null,
"policies": [
{
"guid": "1300d04a-05fb-4f85-ba88-9bd664443725",
"name": "Veracode Recommended Very Low",
"is_default": true,
"policy_compliance_status": "PASSED"
}
],
"teams": [
{
"team_id": 136485,
"team_name": "Demo Team",
"guid": "3b6ee442-8ac3-46c7-9a53-fb003322508f"
}
],
"custom_fields": null,
"description": null,
"settings": {
"nextday_consultation_allowed": false,
"static_scan_xpa_or_dpa": true,
"dynamic_scan_approval_not_required": false,
"sca_enabled": false
},
"business_criticality": "VERY_LOW"
},
"results_url": "ViewReportsResultSummary:72529:1571531:21801526",
"_links": {
"self": {
"href": "https://api.veracode.com/appsec/v1/applications/a99686b7-b54a-4fc4-abf5-cac0315fc041"
},
"sandboxes": {
"href": "https://api.veracode.com/appsec/v1/applications/a99686b7-b54a-4fc4-abf5-cac0315fc041/sandboxes{?page,size}",
"templated": true
},
"policy": {
"href": "https://api.veracode.com/appsec/v1/policies/1300d04a-05fb-4f85-ba88-9bd664443725"
}
}
},
Retrieve example results
You can now retrieve all Static Analysis and SCA results for verademo.war.
To complete this task:
-
In the Veracode Example collection, add the following HTTP request to the Findings API as a
GET:{{base_url}}/appsec/v2/applications/{{application_guid}}/findings?scan_type=STATIC -
Save the request with the name
All Findings. -
Select the Headers tab and add the following header:
- For Key, enter
Authorization. - For Value, enter
{{hmacAuthHeader}}.
- For Key, enter
-
Select Save.
-
In the Collection window, select the name of the collection Veracode Example.
-
Select the Variables tab and add the following variable to the collection:
- For Variable, enter
application_guid. - For Current value, enter the GUID for your application profile for
verademo.war. For example, in Retrieve the Application Profile ID, the GUID isa99686b7-b54a-4fc4-abf5-cac0315fc041, but you need to use the GUID specific to your application profile.
- For Variable, enter
-
Select Save, then select Send.
The following example response shows a single flaw (finding) in the Static Analysis results for application profile GUID
a99686b7-b54a-4fc4-abf5-cac0315fc041."findings": [
{
"issue_id": 4,
"scan_type": "STATIC",
"description": "<span>This database query contains a SQL injection flaw. The call to java.sql.Statement.execute() constructs a dynamic SQL query using a variable derived from untrusted input. An attacker could exploit this flaw to execute arbitrary SQL queries against the database. The first argument to execute() contains tainted data from the variable sqlQuery. The tainted data originated from earlier calls to AnnotationVirtualController.vc_annotation_entry, and java.sql.Statement.executeQuery.</span> <span>Avoid dynamically constructing SQL queries. Instead, use parameterized prepared statements to prevent the database from interpreting the contents of bind variables as part of the query. Always validate untrusted input to ensure that it conforms to the expected format, using centralized data validation routines when possible.</span> <span>References: <a href=\"https://cwe.mitre.org/data/definitions/89.html\">CWE</a> <a href=\"https://owasp.org/www-community/attacks/SQL_Injection\">OWASP</a></span>",
"count": 1,
"context_type": "APPLICATION",
"context_guid": "a99686b7-b54a-4fc4-abf5-cac0315fc041",
"violates_policy": false,
"finding_status": {
"first_found_date": "2022-10-31T13:14:10.788Z",
"status": "OPEN",
"resolution": "UNRESOLVED",
"mitigation_review_status": "NONE",
"new": true,
"resolution_status": "NONE",
"last_seen_date": "2022-10-31T13:41:34.620Z"
},
"finding_details": {
"severity": 4,
"cwe": {
"id": 89,
"name": "Improper Neutralization of Special Elements used in an SQL Command ('SQL Injection')",
"href": "https://api.veracode.com/appsec/v1/cwes/89"
},
"file_path": "com/veracode/verademo/commands/RemoveAccountCommand.java",
"file_name": "RemoveAccountCommand.java",
"module": "verademo.war",
"relative_location": 75,
"finding_category": {
"id": 19,
"name": "SQL Injection",
"href": "https://api.veracode.com/appsec/v1/categories/19"
},
"procedure": "com.veracode.verademo.commands.RemoveAccountCommand.execute",
"exploitability": 0,
"attack_vector": "java.sql.Statement.execute",
"file_line_number": 49
},
"build_id": 21801526
}, -
To retrieve the SCA results for the same application profile, in the request URL, change
scan_type=STATICtoscan_type=SCA.{{base_url}}/appsec/v2/applications/{{application_guid}}/findings?scan_type=SCA -
Select Save, then select Send.
The following example response shows a single vulnerability (finding) in the SCA results for application profile GUID
a99686b7-b54a-4fc4-abf5-cac0315fc041."findings": [
{
"scan_type": "SCA",
"description": "junit is vulnerable to information disclosure. The vulnerability exists through the behaviour of `TemporaryFolder` on UNIX-like systems, where the system's temporary directory is shared between all users on that system by default.",
"count": 1,
"context_type": "APPLICATION",
"context_guid": "a99686b7-b54a-4fc4-abf5-cac0315fc041",
"violates_policy": false,
"finding_status": {
"first_found_date": "2022-10-31T13:29:48.882Z",
"status": "OPEN",
"resolution": "UNRESOLVED",
"new": false,
"resolution_status": "NONE",
"last_seen_date": "2022-10-31T13:30:08.255Z"
},
"finding_details": {
"severity": 1,
"cwe": {
"id": 732,
"name": "Incorrect Permission Assignment for Critical Resource",
"href": "https://api.veracode.com/appsec/v1/cwes/732"
},
"component_id": "4ebeadf3-e305-4520-8e20-f7b2b15141c4",
"licenses": [
{
"license_id": "epl-1.0",
"risk_rating": "3"
}
],
"metadata": {
"sca_scan_mode": "UPLOAD",
"sca_dep_mode": "UNKNOWN"
},
"cve": {
"name": "CVE-2020-15250",
"cvss": 1.9,
"href": "http://nvd.nist.gov/vuln/detail/CVE-2020-15250",
"severity": "Very Low",
"vector": "AV:L/AC:M/Au:N/C:P/I:N/A:N",
"cvss3": {
"score": 5.5,
"severity": "Medium",
"vector": "AV:L/AC:L/PR:N/UI:R/S:U/C:H/I:N/A:N"
}
},
"product_id": "f60afc17-560b-4caf-817f-5233bfd5ccc7",
"component_filename": "junit-4.13.jar",
"language": "JAVA",
"component_path": [
{
"path": "verademo.war#zip:WEB-INF/lib/junit-4.13.jar"
}
],
"version": "4.13"
}
},
Next steps
- Try other example requests for the Identity API.
- Try other example requests for the Applications API.
- Try other example requests for the Findings API.
- Read the best practices for using the Veracode APIs.
- Review the usage guidelines for the Veracode APIs.