Requirements for API scanning

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

Starting an API scan

Both Burp Suite Enterprise Edition and Burp Suite Professional enable you to upload an API definition to be scanned. Burp Scanner automatically detects endpoints, parameters, and authentication details in the definition, then audits the detected endpoints.

Incidental API scanning

Burp Scanner also 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 either:

  • An OpenAPI definition in JSON or YAML format.
  • Professional A SOAP WSDL
• 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 (OpenAPI only)

Burp Scanner can scan most types of OpenAPI endpoints, for endpoints that require:

• Body parameters of type XML.
• Path parameters of type object or array.
• Header parameters of type object or array.
• Parameters where type is specified in a content block.
• Query or body parameter with embedded mixed types. For example, JSON parameters in an application/x-www-form-urlencoded body.
• Query parameters of type object.
• Parameters introduced in OpenAPI 3.1 or later.

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

Endpoint testing rules

For OpenAPI definitions, 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.

Professional For SOAP WSDLs, 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 both mandatory and optional parameters.
• For endpoints that use enumerated types, Burp Scanner sends a single request using the first permitted value.
• For endpoints that use numeric values, Burp Scanner sends a single request using a randomly generated value.
• If the API definition includes example parameter values, Burp Scanner includes the first example in its request.
• For endpoints without example parameter values, Burp Scanner creates a value that it uses in its request. For an array, Burp Scanner creates the minimum required number of values to send in its request.

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.