Scanning APIs

Burp Scanner can scan JSON-based API definitions 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 API definition must be a JSON-based OpenAPI version 3.x.x specification.
• 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.
• Burp Scanner only supports server and path parameters 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.