Burp Suite Enterprise Edition: GraphQL Schema

Introduction

This GraphQL API exposes the core functionality of Burp Suite Enterprise Edition. You can use it to read and write most of the same data as you can using the web UI, including your sites, scans, agent machines, and any issues that were found. This greatly facilitates the integration of Burp Suite Enterprise Edition, along with its built-in Burp Scanner, with a wide range of third-party software and your CI/CD workflow.

About GraphQL

In short, GraphQL is a query language for APIs and a runtime for handling those queries. Unlike a REST API, a GraphQL API is organized based on object types and their fields, rather than endpoints. This effectively means that all of the data is exposed at a single "endpoint". You specify which objects you want to fetch, and which of their fields, by nesting them all inside a single, hierarchical query that returns all of this data in one response. The structure of the returned JSON data directly mirrors the hierarchy of the query you send. This enables you to control how the returned data will be presented, ensuring that you always receive predictable results. Crucially, this also means you only receive data for exactly the objects and fields that you requested, and nothing more.

Object types that are available in a GraphQL API are defined in a schema. Each object type has a predefined set of fields, which in turn have a permitted object or scalar type for their values. The documentation on this page is generated from Burp Suite Enterprise Edition's GraphQL schema.

If you are not familiar with the basics of GraphQL, we recommend reading the guides on the GraphQL website for a more in-depth explanation.

Authentication

To use this API, you first need to create an API user in Burp Suite Enterprise Edition. This generates an API key that you can use to authenticate requests that you send to the API.

To create an API user:

  1. Log in to Burp Suite Enterprise Edition as an administrator.
  2. Click "Team > Add a new user".
  3. Enter a name and username that will help you identify the user later. For example, "GraphQL API User".
  4. Enter an email address. For example, "admin@example.com".
  5. From the "Choose a login type" menu, select "API key".
  6. Assign the user to one or more groups, ensuring that the assigned groups have the necessary permissions for the user to make the API calls they need.
  7. Click "Save".
  8. When prompted, click "Copy API key" and save the key somewhere secure.

When sending a request to the GraphQL API, include the API key in the Authorization header of the request.

Some APIs allow all authenticated Burp Suite Enterprise Edition users to retrieve the following non-sensitive information:

  • Information on agent pools. The list of sites in the pools only includes the sites that the user is authorised to see.
  • The id, name, and current_scan_count of agents.
  • The id and names of all scan configurations.

Using this API

Unlike a REST API, you interact with the GraphQL API via a single endpoint: your-web-server-url/graphql/v1

All operations are performed by sending POST requests to this endpoint. What happens server-side is determined by the specific query or mutation that your request contains. The available queries and mutations, along with the queryable object types, are defined in the Burp Suite Enterprise Edition GraphQL Schema. You can access the documentation for the schema using the links in the sidebar.

For examples of some common tasks that you can perform using Burp Suite Enterprise Edition's GraphQL API, see ‘Performing common tasks with the GraphQL API’ in the documentation.

Queries

All read operations on the GraphQL API must be nested inside a root Query object. In practice, this means that each time you want to fetch some data from the API, the top level of the hierarchy is a new Query object (with a name that you provide) and at least one query field. For example, a query to fetch an issue found by a scan would start as follows: 

query getIssue ($scanId: ID!, $serialNumber: ID!) {
    issue (scan_id: $scanId, serial_number: $serialNumber) {
            ...
    }
}

In this example, getIssue is the name that we have given to this new Query object and issue is the query field. The "Queries" page provides information about all of the available query fields, including which filters you can use and which object types they return.

Within the query, you specify exactly which fields you want to return for this object. If you look at the documentation for the returned object type, you can see which fields this object type can contain. For example, we know that the issue query returns an Issue object. After looking at the available fields for an Issue object, we decide that we want to fetch the values of the confidence, serial_number, and severity fields. To do this, we would just nest the names of these fields inside the issue query field as follows: 

query getIssue ($scanId: ID!, $serialNumber: ID!) {
    issue (scan_id: $scanId, serial_number: $serialNumber) {
        confidence
        serial_number
        severity
    }
}

This would return an Issue object with each of these fields in the same hierarchical structure as your query: 

{
    "data": {
        "issue": {
            "confidence": "firm",
            "serial_number": "123456789123456789",
            "severity": "high"
        }
    }
}

Queryable objects

The list of "Queryable Objects", as the name suggests, contains information about all of the standalone objects about which you can fetch data. The object pages contain a brief description of the object and a list of all of its fields. For each field, you can see what object type it returns or, if that field does not contain any children, the scalar in which the value is expressed. Note that non-nullable values are indicated with an exclamation point. This means that when creating this type of object, this field will always be populated and, consequently, querying this field is guaranteed to return a value.

Other objects

In addition to queryable objects, there are various other objects that represent entities in Burp Suite Enterprise Edition. These objects can be nested inside the fields of other objects, but you cannot directly query them as a standalone object.

Enums, or enumerators, are a special scalar type that is restricted to a predetermined set of allowed values. For example, the enum Severity can have one of four values: info, low, medium, high, which correspond to Burp Scanner's severity ratings.

Mutations

In addition to fetching data from the API using queries, you can also create, update, and delete data from Burp Suite Enterprise Edition. In GraphQL terminology, these write operations are known as "mutations". Just as queries are all self-contained in a root object, mutations all start with a root Mutation object. The "Mutations" page contains a list of available mutations and which input you need to provide for them.

For example, you can use the mutation delete_site to permanently remove a site from Burp Suite Enterprise Edition. In the documentation for the delete_site mutation, you can see that the only required input is the ID of the site that you want to delete. As a result, you would create a new Mutation object as follows: 

mutation DeleteSite($input: DeleteSiteInput!) {
    delete_site(input: $input) {
        id
    }
}

You can find more examples of both queries and mutations throughout the rest of this documentation. For further information about using GraphQL in general, please refer to the official GraphQL documentation.