Scanning APIs with Burp Scanner
Burp Scanner is able to scan both JSON and YAML-based API definitions for vulnerabilities. By default, the crawler attempts to parse any API definitions that it encounters to identify potential endpoints, along with their supported methods and parameters. You can also explicitly provide the URL of an API definition when launching a scan. Based on the endpoints that it discovers, Burp Scanner is then able to derive new locations to crawl and audit.
Just as when scanning any other part of an application, the same set of requests used during the crawl phase will also be used for auditing the API endpoints.
If you prefer, you can disable API scanning by deselecting the "Parse API definitions" crawl option in your scan configuration. You can find this option under "Miscellaneous".
Prerequisites for API scanning
Burp Scanner needs to be able to parse an API definition in order to scan it. Currently, this is only possible for definitions that meet the following requirements:
The API definition must be an OpenAPI version 3.x.x specification. The crawler uses the
openapikey at the top level of the definition to help identify whether a discovered document is an API definition.
- The API definition must not contain any external references.
Any definitions that do not meet these requirements will be skipped during the scan.
Deriving locations from an API definition
When parsing the API definition, the crawler will often create multiple locations for each endpoint. If an endpoint supports more than one method, a separate location is created for each of them. Similarly, if more than one API server is in scope, a single method and endpoint combination produces separate locations representing the same call to each distinct server.
For example, let's say a given endpoint supports both the
PUT methods. If only one server is in scope, two locations would be derived from this endpoint. However, if there are three servers, this would result in a total of six new locations.
Parameter handling during API scans
During the crawl, the way that parameters are defined for each endpoint influences the number of requests that Burp Scanner sends:
- If optional parameters are defined, the crawler will send at least two requests to that endpoint: one request containing only the mandatory parameters and another request that includes all of the optional parameters as well.
- In the case of enumerated types, the crawler will send a separate request for each of the parameter's permitted values.
This helps to ensure maximum coverage of each endpoint.
The values used for the parameters in each request are also determined partly by the API definition. If example values are provided for a parameter, the crawler will use the final example in each case. Otherwise, it will generate a suitable custom value.
Limitations for API scanning
The following limitations apply when the crawler is attempting to parse an API definition. If an endpoint does not conform to these limitations, it will be excluded from the scan. In each case, you can check the event log to see why a particular endpoint was skipped.
- Although the scan will continue to use Burp's normal authentication-handling features, the crawler is currently unable to handle any authentication that is implemented on the endpoint level.
- Server parameters and path parameters are only supported if they are of an enumerated type or if example values are provided in the definition.
Endpoints that require any of the following to be present in the request are not supported:
- Additional HTTP headers
Query or body parameters of the type
array. However, note that JSON body parameters of this type are supported.
Query or body parameters of the type
Query or body parameters with embedded mixed types, for example, JSON parameters in an
Query parameters of the type
JSON. However, note that body parameters of this type are supported.
Body parameters of the type