Enterprise EditionProfessional

Requirements for API scanning

• Last updated: March 6, 2024

• Read time: 4 Minutes

Burp Scanner can scan APIs for vulnerabilities. This enables you to discover a larger attack surface in your applications.

Starting an API scan

You can start an API scan in various ways:

• Professional If you're using Burp Suite Professional, you can upload an API definition to run a specific API scan. Burp automatically detects endpoints and parameters in the definition, then audits the detected endpoints. For more information, see Scanning APIs.
• Enterprise If you're using Burp Suite Enterprise Edition, you'll need to host your API on a web server, then provide the URL as the Start URL when adding or editing a site. Burp crawls and audits the endpoints in the API definition.

Incidental API scanning

In both Burp Suite Professional and Burp Suite Enterprise Edition, Burp Scanner parses any API definitions that it encounters as part of its regular crawling activity, then crawls and audits any endpoints that it discovers.

API definition requirements

For Burp Scanner to parse and scan an API definition, the definition must meet the following requirements:

• It must be OpenAPI version 3.0.x, in JSON or YAML format.
• It doesn't contain external references.
• It includes scannable API endpoints. See below for the API endpoint requirements.
• The server URLs for API calls must be accessible by Burp Scanner. If you're uploading a definition from a file, make sure that the servers are listed as absolute URLs.

API endpoint requirements

Burp Scanner can scan most types of API endpoints, with the following exceptions:

• Endpoints with authentication at the endpoint level.

• Endpoints that require:

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

Note that non-standard JSON endpoints are supported, for example endpoints with a content type of application/json-patch+json or application*+json.

Endpoint testing rules

Burp Scanner creates requests to audit each endpoint in line with the following rules:

• For endpoints with optional parameters, Burp Scanner sends:

  • A request with only mandatory parameters.
  • A request with both mandatory and optional parameters.
• For endpoints that use enumerated types, Burp Scanner sends a separate request for each permitted value.
• For endpoints that use numeric values, Burp Scanner uses the maximum and minimum values in its requests.
• If the API definition includes example parameter values, Burp Scanner includes the final example in its request.

• For endpoints without example parameter values, Burp Scanner creates a value that it uses in its request. In certain cases Burp Scanner creates multiple values:

  • For an array, Burp Scanner creates the minimum required number of values to send in its request.
  • For path parameters, Burp Scanner creates a minimum, maximum, and a random value, and sends these in separate requests.

Crawling GraphQL APIs

Burp Scanner can scan and audit GraphQL API endpoints during a crawl and audit. 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 Endpoint testing rules 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.