GraphQL API

The Veracode Risk Manager (VRM) GraphQL API allows you to programmatically interact with VRM to gather data on findings, issues, assets, applications, and solutions so that you can use that data in other products or generate your own reports using the raw data.

The GraphQL API is compliant with the GraphQL standard and organized in a way that aligns with VRM’s common data model. VRM provides an API Explorer tool directly in the VRM console to make it as easy as possible to get familiar with the the GraphQL API and even execute queries without having to write an external script.

Authentication

Generate API credentials

If you are writing scripts that connect programmatically to the API, you need to create and store API credentials so that your script can securely connect to Veracode.

Enable HMAC authentication

For increased security, your tool for accessing the VRM API must support HMAC authentication.

For example, see these sample instructions for quick configuration guidance.

Set authorization for your requests

If your pre-request script does not automatically add HMAC authentication, manually add a header to authorize the requests.

To add a header in Postman:

1. Select the Headers tab below the request URL field.
2. In Key, enter Authorization.
3. In Value, enter a placeholder variable defined in your script, such as {hmacAuthHeader}.

API Explorer

You access the API Explorer from the My Account menu at the bottom left of the VRM platform. This utility shows all available GraphQL commands, lets you execute GraphQL queries, and includes an internal reference documenting the GraphQL query commands.

Explorer

The Explorer tab lists all the available GraphQL commands.

Commands that retrieve data on an individual object follow the convention of starting with get, as in getAsset or getIssue. Commands that retrieve a list of objects start with list, such as listFindings or listIntegrations.

To perform a query on an object type, use the commands such as applications, assets, issues, or solutions.

History

The History tab allows you to see a list of all of our recent queries. This list persists if you log out of the console but is lost if you clear your browser cache. To set queries in this History list as favorites, select the star icon that appears when hovering over the query name.

Docs

Select Docs in the far right of the API explorer menu to open the Docs panel. This panel lets you see the structure of the GraphQL schema and allows you to click on each object name to drill down into the details of that object.

Building queries

To start exploring with the GraphQL API, you can expand the endpoints in the Explorer and start building queries by selecting the parameters and filters available in that list. As you expand and select items in the API list, the query will be entered automatically into the playground section.

If you are familiar with GraphQL already, you can simply start writing queries in the playground section on your own without using the Explorer. You can also paste in GraphQL queries from other sources.

To execute a query, click the play (triangle) button. If you have pasted multiple queries into the playground, the play button shows a drop-down menu, so you can select which query you want to run.

You can set Query Variables in the section below the query playground. This is especially useful if you are copying queries and variables from an external source where the variables have already been separated from the base query.

Query results

When you execute a query, the results appear on the right side of the playground in JSON format. You can browse through this data in the API Explorer, or copy it to a text editor or code editor. To search the query results, use Ctrl+F on Windows or Command+F on macOS.

Example queries

The examples in this section show a request built in the API Explorer and the corresponding request in curl, in addition to the JSON response.

GraphQL body request

query MyQuery {
  assets(pageSize: 10) {
   pageData {
    assetTypeLabel
    issueCount
    name
    uri
    }
  }
}

curl request

curl --location 'https://api.veracode.com/risk-manager/api-server/v1/graphql' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: ••••••' \
--data 'query MyQuery { assets(pageSize: 10) { pageData { assetTypeLabel issueCount name uri } } }'

To retrieve data on assets, issues, solutions, findings, and applications, use the /graphql endpoint in the query. If your organization hosts Veracode account data in Europe, replace api.veracode.com with api.veracode.eu.

Response

{
  "data": {
    "assets": {
      "pageData": [
        {
          "assetTypeLabel": "Azure Virtual Machine",
          "issueCount": 0,
          "name": "avm-server-example",
          "uri": "avm-server-example"
        },
        {
          "assetTypeLabel": "Azure Virtual Machine",
          "issueCount": 0,
          "name": "azure-example",
          "uri": "azure-example"
        },
        {
          "assetTypeLabel": "Azure Virtual Machine",
          "issueCount": 2,
          "name": "vuln_machine-example",
          "uri": "vuln_machine-example"
        },
        {
          "assetTypeLabel": "AWS S3 Bucket",
          "issueCount": 0,
          "name": "upgrade-example",
          "uri": "upgrade-example"
        },
        {
          "assetTypeLabel": "AWS S3 Bucket",
          "issueCount": 0,
          "name": "upgrade-prod-example",
          "uri": "upgrade-prod-example"
        },
        {
          "assetTypeLabel": "AWS S3 Bucket",
          "issueCount": 0,
          "name": "transformed-data-example",
          "uri": "transformed-data-example"
        },
        {
          "assetTypeLabel": "AWS S3 Bucket",
          "issueCount": 1,
          "name": "AWS-test-example",
          "uri": "AWS-test-example"
        },
        {
          "assetTypeLabel": "Azure Storage Account",
          "issueCount": 0,
          "name": "example_user_bucket",
          "uri": "example_user_bucket"
        },
        {
          "assetTypeLabel": "Azure User",
          "issueCount": 0,
          "name": "example_user",
          "uri": "example_user"
        },
        {
          "assetTypeLabel": "Veracode Application Profile",
          "issueCount": 1,
          "name": "example_app_profile",
          "uri": "example_app_profile"
        }
      ]
    }
  }
}

Keyboard shortcuts

You can use the following keyboard shortcuts while in the API Explorer window.

• Prettify query: Shift+Ctrl+P
• Run query: Ctrl+Enter
• Auto complete: Ctrl+Space or start typing