ENTERPRISEPROFESSIONAL

Scanning APIs

• Last updated: September 21, 2023

• Read time: 4 Minutes

Burp Scanner can scan API definitions that are based on either JSON or YAML for vulnerabilities. This enables you to discover a larger potential attack surface in your applications.

API scanning works in a similar way to web page scanning, but instead of crawling for web content Burp Scanner crawls for exposed API endpoints. Burp Scanner then audits these endpoints using the same configurations and techniques that it uses when scanning web pages.

Starting an API scan

By default, Burp Scanner attempts to scan any API definitions that it encounters as part of its regular crawling activity. You can also provide the URL of an API definition explicitly when launching a scan.

Prerequisites for API definitions

Burp Scanner needs to be able to parse an API definition in order to scan it.

Burp Scanner can only parse definitions that meet the following requirements:

• The specification of the API definition must be OpenAPI version 3.x.x, and based on either JSON or YAML.
• The API definition must not contain any external references.

Deciding what parameters to send in the crawl

When crawling an API definition, Burp Scanner sends a series of requests to identify potential endpoints, along with their supported methods and parameters. Burp Scanner can then derive new locations to crawl and audit based on the endpoints that it discovers.

Depending on the design of the API, each endpoint could have a huge number of potential parameters. For example, an open String parameter with no constraints would have a virtually unlimited number of potential valid inputs.

In these cases, it would be impossible for the crawler to attempt all parameter combinations. However, the crawler still needs to try a reasonable number of possible parameter combinations to make sure that it exposes all possible attack surfaces.

As such, Burp Scanner sends requests in line with the following rules:

• Burp Scanner treats every combination of in-scope server and path methods (such as GET and POST) in the API definition as its own endpoint. For example, if a definition had three servers, each with GET and POST methods, then Burp Scanner would identify six endpoints.
• If an endpoint has optional parameters, Burp Scanner sends at least two requests to that endpoint: one containing only mandatory parameters and one containing both mandatory and optional parameters.
• If an endpoint uses enumerated types, Burp Scanner sends a separate request for each of the parameter's permitted values.
• If an endpoint uses numeric values, Burp Scanner uses the maximum and minimum values as specified.
• If the API definition provides example sets of parameters, Burp Scanner uses the final provided example in its request.

Scannable endpoint definition

Burp Scanner can only scan API endpoints that meet certain criteria. Any endpoints that do not conform to these criteria are excluded from the scan:

• Burp Scanner cannot handle any authentication that is implemented on the endpoint level. However, it can use Burp's normal authentication-handling features when scanning APIs.
• Server and path parameters are only supported if they are of an enumerated type or if example values are provided in the definition.

• Burp Scanner does not support endpoints that require any of the following to be present in the request:

  • Additional HTTP headers.
  • Query or body parameters of type array. JSON body parameters of this type are supported.
  • Query or body parameters of type XML.
  • Query or body parameters with embedded mixed types. For example, JSON parameters in an application/x-www-form-urlencoded body.
  • Query parameters of type JSON. Body parameters of this type are supported.
  • Body parameters of type multipart.

Crawling GraphQL APIs

Burp Scanner can fully crawl and audit GraphQL API endpoints. GraphQL crawls rely on introspection. This is a built-in GraphQL feature that enables users to query the structure of the API itself.

If GraphQL scanning is enabled, Burp Scanner uses the following process when crawling:

• Check for GraphQL endpoints as part of a regular crawl. As GraphQL APIs use the same endpoint for all operations, the crawler does not need to find multiple endpoints to run a full crawl as it would with a REST API.
• If the initial crawl does not find a GraphQL endpoint and the Test common GraphQL endpoints setting is selected, the crawler attempts to guess GraphQL endpoints using a list of common endpoint suffixes.
• Once a GraphQL endpoint has been found, Burp Scanner sends an introspection query requesting details of all available queries and mutations.
• If the introspection query is successful, Burp Scanner sends requests to all available queries and mutations. It uses the rules explained in the Deciding what parameters to send in the crawl section to identify the arguments to send in each request. Where required, it sends multiple permutations of the same query.

Once the crawl is complete, Burp Scanner audits the discovered queries and displays discovered issues as it would with any other target.