OpenAPI and Swagger Import,
API Scope Before the First Request
Import an OpenAPI or Swagger spec and every endpoint, method, and parameter lands in your engagement as API pentest scope, mapped before the first request is sent.
Import Once. Report From One Place.
An API pentest usually starts with a spec file: an OpenAPI 3 document or an older Swagger 2.0 file the client exported from their gateway. Turning it into a test plan means reading hundreds of operations and copying paths into a spreadsheet. Import the spec and the attack surface is mapped before the first request.
Upload the JSON or YAML and Neuron reads its servers and paths, resolves internal $ref references, and creates the host, the web app, an endpoint for every path with the methods defined on it, and every path, query, header, cookie, and body parameter with its type and whether it is required.
Each endpoint also records whether the spec requires authentication and which scheme it uses, such as bearer, basic, API key, OAuth 2, or OpenID Connect, so the operations that need no credentials stand out before testing starts.
$ curl -so acme-api.json \ https://api.acme.example/openapi.json$ neuron import acme-api.json✓ 1 web app, 86 endpoints, 214 parameters $ neuron import --source openapi \ --tag partner-api partner-api.yaml✓ 1 web app, 31 endpoints, 77 parameters- 09:26 Finding BOLA on GET /orders/{id}
- 09:05 Import OpenAPI: 31 endpoints, partner-api
- 09:02 Import OpenAPI: 86 endpoints, 214 params
- 09:01 Command curl -so acme-api.json .../openapi.json
Why OpenAPI Reporting Takes So Long
API scope is easy to get wrong. A spec with hundreds of operations, path parameters, nested request bodies, and a mix of authenticated and public routes does not fit in a scoping email, and a tester working from the docs page will miss the operations nobody clicks.
So coverage gets tracked in a spreadsheet that drifts from reality the moment the client ships a new version. Halfway through the test, nobody can say which endpoints have been exercised, and the report lists the vulnerable ones without showing what else was in scope.
And when the client sends v2 of the spec for the retest, the mapping starts again from nothing.
Everything OpenAPI Produces, On the Engagement
Import OpenAPI output from the browser or with neuron import, and it lands the moment the import finishes.
Web Apps From Servers
A host, port, and web app for each server URL in the spec, from the servers list in OpenAPI 3 or host, basePath, and schemes in Swagger 2.0, or from a base URL you supply.
Every Path as an Endpoint
Each path becomes an endpoint with every method the spec defines on it, and path templates such as /orders/{id} are kept intact.
Typed Parameters
Path, query, header, cookie, and body parameters with their type and required flag, including the top-level properties of JSON, form, and multipart request bodies.
Authentication Requirements
Whether each endpoint requires authentication, and the scheme the spec declares for it: bearer, basic, API key, OAuth 2, or OpenID Connect.
Swagger 2.0 and OpenAPI 3.x
Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1 documents in JSON or YAML, with internal $ref references resolved. External references are never fetched.
Tags and Assessments
Tag what the import creates, or assign it to an assessment, so the API scope stays separate from the web front end tested alongside it.
How to Import OpenAPI Results
- 01
Get the spec
Ask the client for the OpenAPI 3 or Swagger 2.0 document as JSON or YAML. Most API gateways and frameworks can export one, and many APIs serve it at a path such as /openapi.json or /swagger.json.
$ curl -so acme-api.json https://api.acme.example/openapi.json - 02
Pin the spec to the engagement
Copy the spec into the engagement File Share. When the client ships v2 mid-test, the version you scoped against is still there to show which endpoints were in.
$ neuron copy acme-api.json neuron:API/ - 03
Import the spec
A JSON spec is recognised from its content. Name the importer with --source openapi for YAML, and add --tag to label everything the import creates. Each file is sent as its own import.
$ neuron import --source openapi --tag api acme-api.yaml - 04
Supply a base URL when the spec has none
If the spec only lists relative servers, or none at all, upload it on the engagement's Import page under OpenAPI and enter the base URL to resolve its paths against, such as https://api.acme.example/v1.
Your Infrastructure. Your Data.
Neuron is self-hosted. Import OpenAPI results from the browser or the CLI and they land on your own server, inside your network. Scan data never passes through a third-party cloud.
From OpenAPIto the Final Report
With every operation on the engagement before testing starts, coverage is visible as you go. Findings attach to the exact endpoint and parameter they affect, so the report names /orders/{id} and its id parameter instead of a URL typed by hand.
Endpoints the spec leaves unauthenticated are the first place to look for broken access control, and the declared scheme on each one tells the tester which credentials to bring.
Traffic from the Burp Suite extension, the ZAP add-on, or the Caido plugin lands on the same engagement, so the spec and the requests that tested it sit side by side, and findings move through the Findings Library and QA pipeline to the final report.
OpenAPI Integration FAQ
The questions teams ask most about OpenAPI and Neuron.
How do I import an OpenAPI spec for an API pentest?
Run neuron import on the OpenAPI spec file, or upload it on the engagement's Import page under OpenAPI. Neuron creates the web app from the spec's servers, an endpoint for every path with its methods, and every parameter with its type and required flag.
Does Neuron support Swagger 2.0 files?
Yes. Swagger 2.0 imports alongside OpenAPI 3.0 and 3.1, in JSON or YAML. For a Swagger 2.0 file, the web app comes from its host, basePath, and schemes fields.
What if the OpenAPI spec has no server URL?
Upload the OpenAPI spec on the Import page and enter a base URL, and Neuron resolves every path against it. That covers specs with only relative servers, such as /v1, and specs with no servers at all.
Does Neuron fetch external $ref references in an OpenAPI spec?
No. Internal references are resolved so shared parameters and request body schemas import fully, but external references are never followed, so an uploaded OpenAPI spec cannot make the Neuron server read files or fetch URLs.
Can I import several OpenAPI files at once?
Yes. Pass them all to neuron import and the CLI sends each OpenAPI file as its own import, so every API gets its own import job you can review or roll back.
Which parameters does the OpenAPI import create?
Path, query, header, and cookie parameters from each OpenAPI operation, plus the top-level properties of JSON, form, and multipart request bodies, each with its type and whether the spec marks it required.
More Neuron Integrations
Burp Suite Reporting and Findings Import
Web TestingZAP Reporting and OWASP ZAP Alert Import
Web TestingCaido Reporting and HTTP History Import
Web TestingNuclei Scan Reporting and Import
Web Testingffuf Reporting and Content Discovery Logging
Web TestingNikto Reporting and Output Import
Web TestingAcunetix Report Import for Pentest Reports
Web TestingInvicti and Netsparker Report Import
Web TestingReady to Transform Your Security Practice?
See how Neuron helps security teams replace fragmented tools with a single platform for offensive security, bringing structure, visibility, and consistency to every engagement.
Platform