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

If you are writing scripts that will programmatically connect to the API, you need to create an API key so that your script can securely connect to VRM.

To create an API key:

1. Select the Settings icon .
2. Select API Keys.
3. Select Add API Key.
4. Enter a name and expiration date for the key.
5. Specify the role: Guest or Admin.
6. Select Add API Key.
7. Copy the API Key to a secure location. You will not be able to view the key again after you leave the page.

The API server you connect to depends on whether your tenant lives in the United States or European VRM server:

• United States - https://api.longbow.security:443/v1
• Europe - https://api.eu.longbow.security:443/v1

Add key-value pair to authentication header

When configuring applications such as Postman or creating your own script, you must add a key-value pair to your authentication header.

In Postman:

1. For Auth Type, select API Key.
2. For Key, enter X-API-KEY. The key is case-sensitive.
3. For Value, enter the API key you created in VRM and saved to a safe location.

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.longbow.security/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, you must use the /graphql endpoint in the query.

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