Run scans

Web API scans

Scanning an API from its OpenAPI specification.

View as Markdown

API Scan tests a web API from its OpenAPI specification: it reads the routes and parameters the specification describes and attacks them with ZAP and Wapiti. It runs from the Dynamic Analysis page like any web scan; see Web App Scanning for the form.

Before you start

You needHow to check
An OpenAPI specification served by the API itselfOpen the specification URL in a browser or with curl -fsS <SPEC_URL>: it must return the JSON or YAML document.
The API host allowed for your teamTeams, Scanning tab, Web targets card, Check whether targets are allowed: the specification URL must be reported as allowed.
A productIt is listed under Product / Eng ID on the form.

Run an API scan

  1. 01
    Open the form

    Web App Scanning in the sidebar (the Dynamic Analysis page).

  2. 02
    Enter the specification URL

    In Specify the URLs, the address of the OpenAPI document itself, for example https://api.example.com/openapi.json, not the API root.

  3. 03
    Switch off Autonomous AI assessment

    It is on by default and, while on, the AI Pentest agent decides what runs instead of API Scan.

  4. 04
    Switch on API Scan

    Open the collapsed Specialized & API Scanning group under DAST Engine Settings and switch on API Scan.

  5. 05
    Add authentication

    Cookies (optional) or Custom header (optional), as the API expects them, see below.

  6. 06
    Select Start Analysis

    Scan submitted appears and the scan's page opens.

ScanSuite API scan configuration
Configuring an API scan

Check that it worked: the scan ends Finished on its page. Its findings are in the Report and, at Medium severity and above, on the Vulnerabilities page (with the team's Store scanner findings on, the default).

What the specification must look like

Rule
FormatOpenAPI (JSON or YAML).
AddressOnly letters, digits and : . _ / - are accepted, so a specification URL with a query string, such as …/openapi?format=json, is refused. Serve it at a plain path. See Targets on Web App Scanning.
HostThe API is tested on the scheme and host of the specification URL, so the specification should be served by the API's own host.
AuthenticationIf fetching the specification needs a header or cookie, give it: the same values are used for the specification and the API calls.
TLSWapiti checks the certificate; with a self-signed certificate its part of the scan may find nothing.
DurationThe ZAP part stops after about two hours. URLs containing logout are not called, so the session is not ended.

Authentication

API Scan uses the Cookies and the Custom header from the form, so the authenticated API surface is tested rather than skipped. Any header works, not only Authorization. Wapiti sends all of them; ZAP sends one value: the first header, or the cookies when no header is set. Put the credential that matters most first.

From a pipeline or a terminal

bash
scansuite-ci --scan-type dast --scanners api_scan \
  --target https://api.example.com/openapi.json --header "Authorization: Bearer $API_TOKEN"

See CI/CD and automation.

Last reviewed 2026-10-19