Research Academy
My account Customers About Blog Careers Legal Contact Resellers

Burp Suite User Forum

Create new post

How do I scan an OpenAPI 3.0 API?

Rui | Last updated: Jun 16, 2022 06:25PM UTC

Hello I am trying to follow the meager information at https://portswigger.net/burp/documentation/desktop/scanning/api-scanning in order to scan a REST API (I have the API definition file on disk). I cannot even find the option below anywhere, though I assume this functionality is turned on (I have definitely not turned it off). "Note 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." Has a set of step-by-step instructions been published on how to do this? I am using Burp Suite Professional v2022.5.1 (Early Adopter). And yes, I have looked for this functionality in the non-early adopter version, but no luck. Thanks R

Michelle, PortSwigger Agent | Last updated: Jun 17, 2022 08:25AM UTC

Thanks for your message. The API definition needs to be hosted somewhere where the crawler can find it. If the definition is not currently hosted and is on your local disk you have a couple of options: - You could use the OpenAPI Parser extension which is available on the BApp Store or - You could create a simple python HTTP server locally to host the file and then reference that in your scan configuration. The option to 'Parse API definitions is turned on by default, when starting a new scan it can be found by going to New Scan -> Scan configuration -> New -> Crawling -> Miscellaneous and you should see the checkbox for 'Parse API definitions' I hope this helps. Please let us know if you have any further questions.

Rui | Last updated: Jun 19, 2022 04:30AM UTC

Ok, so I have gone the Python web server route, but when I request that Burp crawl the API definition file (now at http://localhost:8000/file.openapi.json), Burp simply loads the file successfully but does not parse the contents at all. The (redacted) file starts with ... { "openapi": "3.0.1", "info": { "title": "... interface for the system module", "version": "0.1" }, "servers": [ { "url": "https://.../.../" } ], "paths": { "/report_type_parameters/": { "put": { "description": "Update an report type parameter", "requestBody": { ... What am I missing ? R

Ben, PortSwigger Agent | Last updated: Jun 20, 2022 01:53PM UTC

Hi Rui, Just to clarify, does the API meet both the pre-requisites and also not hit any of the API limitations set forward in the API scanning document: https://portswigger.net/burp/documentation/desktop/scanning/api-scanning

Rui | Last updated: Jun 20, 2022 02:34PM UTC

In terms of pre-requisites... 1) The API definition must be an OpenAPI version 3.x.x specification. The crawler uses the openapi key at the top level of the definition to help identify whether a discovered document is an API definition. Yes, see the snipped I provided. 2) The API definition must not contain any external references. I am not sure what is meant my this. What is an 'external reference' and how would I identify one in the OpenAPI file? In terms of the 'Limitations for API scanning' listed in the document, it is quite possible that some of these may be an issue, but it does not appear Burp even looks inside (crawls) the file to determine if that is the case. It simply makes a GET request for the file, gets an HTTP 200 OK, then stops. I can provide the OpenAPI file via e-mail so you can make your own determination. Can I send it to support@portswigger.net? Thanks

Rui | Last updated: Jun 20, 2022 02:38PM UTC

Just checked re external references, there appear to be none. All references are of the form... "$ref": "#/components/schemas/RESPONSE_O"

Ben, PortSwigger Agent | Last updated: Jun 22, 2022 06:59AM UTC

Hi Rui, Yes, it might be easier if we have a copy of the file so that we can take a look ourselves - please send this to support@portswigger.net. The 'external references' caveat relates to the $ref type - we allow Local References but not Remote or URL References. From what you have said it looks as though you are purely using Local References so, on the face of it, this should be fine. Out of interest, if you enable the 'Debug' flag on the 'Event log' on the Dashboard tab of Burp do you see any entries that mention 'Found API definition at location...' after you have run the scan?

Rui | Last updated: Jun 22, 2022 02:16PM UTC

The debug option shows the OpenAPI file is being parsed but Burp is skipping locations in the API definition because they "contain a path parameter of type String without examples or enumeration" which is apparently not yet supported. So that explains that. Any ETA when OpenAPI 3 will be more fully supported? Thanks R

Ben, PortSwigger Agent | Last updated: Jun 23, 2022 01:11PM UTC

Hi Rui, We do have an existing feature request to improve how we handle things like this when performing API scanning so I can certainly add your interest to this. At the moment, as the event log message alludes to, we are expecting the definition file itself to contain example values for us to use. The original reasoning behind this (which we still feel is somewhat valid) is that if we do not have any example values to submit then the chances of us being able to generate and submit valid values is fairly slim (and we would likely receive a whole host of 400 responses during the scan).

Rui | Last updated: Dec 17, 2023 05:13PM UTC

Ok, following on from the above, why would Burp Proxy Professional parse the OpenAPI file the first time a scan is launched, but ignore it for all subsequent scans. The debug option in shows the OpenAPI file is being parsed for the first scan, and not for any scans done afterwards. Thx

Syed, PortSwigger Agent | Last updated: Dec 18, 2023 03:39PM UTC

Hi Rui,

Burp does parse the API but does not show it in the Event log, as it has already parsed and crawled it to find all the locations in the API spec.

Parsing the same API for the same results will be redundant; therefore, you will not see the same message again in the Event log. You'd need to open a new project file to see that message in the Event log again.

You must be an existing, logged-in customer to reply to a thread. Please email us for additional support.