ENTERPRISEPROFESSIONAL
Scanning APIs
-
Last updated: February 21, 2023
-
Read time: 3 Minutes
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.
Note
If required, you can disable API scanning by deselecting the Parse API definitions crawl option in the Miscellaneous section of your scan configuration.
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.
Related pages
- Adding new sites - information on setting scan URLs in Burp Suite Enterprise Edition.
- Scan launcher - information on setting scan URLs in Burp Suite Professional.
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
andPOST
) in the API definition as its own endpoint. For example, if a definition had three servers, each withGET
andPOST
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 anapplication/x-www-form-urlencoded
body. - Query parameters of type
JSON
. Body parameters of this type are supported. - Body parameters of type
multipart
.
Note
To find out why Burp Scanner has skipped an endpoint, check the event log.