How do I scan a GraphQL endpoint?

Set -f graphql and point -t at the GraphQL URL. If the schema lives elsewhere, pass --schema so ZAP can enumerate queries and mutations.

Can I scan production safely?

Enable -S. Safe mode skips the active attack and runs a passive baseline, which suits APIs where you cannot send injection payloads.

How do I make a finding fail the workflow?

Supply a -c config that marks chosen rules as FAIL. The scan exits non-zero on those findings. Use -l to control which levels appear in the report.

Can it test authenticated endpoints?

Yes. Load a ZAP context with -n and name the account with -U. The scan replays that session against imported operations.

How is this different from zap-automation-framework?

zap-api-scan is one packaged scan driven by flags: import, scan, report. The Automation Framework chains jobs from YAML when a single scan command is not enough.

Updated Jul 14, 2026

Scanners

Test OpenAPI, SOAP, or GraphQL APIs with ZAP

OWASP ZAP against an API contract, not a crawlable site.

Scan an API from its OpenAPI spec Test a GraphQL endpoint Run a safe baseline first

overview

What zap-api-scan does

zap-api-scan points OWASP ZAP at an API definition instead of a browsable site. Set -f to openapi, soap, or graphql and -t to a local file or remote definition URL. ZAP imports every operation, then runs active and passive rules against them.

Use -S for a safe baseline that skips the active attack. Control report depth with -l and -s. A -c config file marks rules as INFO, IGNORE, or FAIL so chosen findings can break a build. Authenticated runs load a context with -n and -U.

Trickest runs zap-api-scan as a managed Scanners node. Feed a spec, take FILE and FOLDER findings. Prefer zap-full-scan for crawlable web apps; prefer nuclei for fast template checks without a full ZAP import.

source github.com/zaproxy/zaproxy

use cases

Where zap-api-scan fits

Scan an API from its OpenAPI spec

Import a Swagger or OpenAPI definition and let ZAP exercise every operation, surfacing injection, misconfiguration, and exposure issues across the whole contract.

Test a GraphQL endpoint

Point the scan at a GraphQL schema URL with the graphql format so ZAP enumerates queries and mutations instead of guessing at routes.

Run a safe baseline first

Use safe mode to skip the active attack and run a passive baseline, useful against production APIs where you cannot send live attack traffic.

Gate a deployment pipeline

Wire the scan into a workflow with a config file that fails on chosen rules, so a risky API change blocks the pipeline instead of shipping.

reference

zap-api-scan inputs and flags

17 inputs

Name	Type	Flag	Description
target-definition	FILE	-t	Target API definition file, OpenAPI or SOAP.
target-endpoint-url	STRING	-t	Target API definition URL (e.g. an openapi.json or /graphql endpoint).
format	STRING	-f	API format: openapi, soap, or graphql.
schema	STRING	--schema	GraphQL schema URL for GraphQL targets.
safe-mode	BOOLEAN	-S	Skip the active scan and run a baseline pass instead.
level	STRING	-l	Minimum level to show: PASS, IGNORE, INFO, WARN, or FAIL.
config_file	FILE	-c	Config file to mark warnings as INFO, IGNORE, or FAIL.
context-file	FILE	-n	Context file loaded before scanning, for authenticated runs.

Showing key inputs. zap-api-scan exposes 17 inputs in total.

Full flag reference (17 inputs)

Name	Type	Flag	Description
target-endpoint-url	STRING	-t	Target API definition URL, e.g. https://example.com/openapi.json or https://example.com/graphql.
target-definition	FILE	-t	Target API definition file, OpenAPI or SOAP.
format	STRING	-f	API format: openapi, soap, or graphql.
schema	STRING	--schema	GraphQL schema URL, e.g. https://example.com/schema.graphqls.
safe-mode	BOOLEAN	-S	Safe mode: skip the active scan and perform a baseline scan instead.
level	STRING	-l	Minimum level to show: PASS, IGNORE, INFO, WARN, or FAIL; use with -s to hide example URLs.
short-output	BOOLEAN	-s	Short output format: do not show PASSes or example URLs.
config_file	FILE	-c	Config file used to mark warnings as INFO, IGNORE, or FAIL.
context-file	FILE	-n	Context file loaded before scanning the target, for authenticated runs.
user	STRING	-U	Username to use for authenticated scans; must be defined in the given context file.
ajax	BOOLEAN	-j	Use the Ajax spider in addition to the traditional one.
alpha	BOOLEAN	-a	Include the alpha active and passive scan rules as well.
debug	BOOLEAN	-d	Show debug messages in stdout.
delay	STRING	-D	Delay in seconds to wait for passive scanning.
max-time	STRING	-T	Max time in minutes to wait for ZAP to start and the passive scan to run.
override	STRING	-O	Hostname to override in the (remote) OpenAPI spec.
zap-options	STRING	-z	Raw ZAP command line options passed through to the scanner.

example

Run zap-api-scan

zap-api-scan · command

# scan a remote OpenAPI definition and gate on chosen ruleszap-api-scan.py -t https://example.com/openapi.json -f openapi -c api-rules.conf -l WARN

sample output

Total of 47 URLsPASS: Cookie No HttpOnly Flag [10010]PASS: Re-examine Cache-control Directives [10015]WARN-NEW: Content Security Policy (CSP) Header Not Set [10038] x 12WARN-NEW: Server Leaks Version Information via "Server" HTTP Response Header Field [10036] x 8FAIL-NEW: SQL Injection [40018] x 1	http://example.com/api/v3/products?id=1FAIL-NEW: Cross Site Scripting (Reflected) [40012] x 2	http://example.com/api/v3/search?q=testFAIL-NEW: 2	WARN-NEW: 2	WARN-INPROG: 0	INFO: 0	IGNORE: 0	PASS: 61

guidance

Choosing zap-api-scan

Use zap-api-scan when you have an OpenAPI, SOAP, or GraphQL contract and want ZAP to exercise every defined operation. For a browser-facing site with pages to crawl, use zap-full-scan. For quick template-based checks, use nuclei. Reach for zap-automation-framework when you need a multi-job YAML plan instead of one scan command.

zap-full-scan

ZAP against a crawlable web app. Use for sites, not API specs.

zap-automation-framework

Drives ZAP from one YAML plan, including API imports. More flexible, more setup.

wapiti

Black-box web and API scanner. Lighter when you do not need ZAP rule depth.

faq

zap-api-scan questions

OpenAPI/Swagger, SOAP, and GraphQL. Set -f so ZAP imports the right operations instead of guessing routes.

Run zap-api-scan yourself

An API spec feeds zap-api-scan, which imports every operation, tests it with ZAP, and writes the findings as a queryable output.

Run zap-api-scan in Trickest View the workflow

Facts on this page come from the live Trickest tool library.

Name

Type

Flag

Description

target-definition

FILE

-t

Target API definition file, OpenAPI or SOAP.

target-endpoint-url

STRING

-t

Target API definition URL (e.g. an openapi.json or /graphql endpoint).

format

STRING

-f

API format: openapi, soap, or graphql.

schema

STRING

--schema

GraphQL schema URL for GraphQL targets.

safe-mode

BOOLEAN

-S

Skip the active scan and run a baseline pass instead.

level

STRING

-l

Minimum level to show: PASS, IGNORE, INFO, WARN, or FAIL.

config_file

FILE

-c

Config file to mark warnings as INFO, IGNORE, or FAIL.

context-file

FILE

-n

Context file loaded before scanning, for authenticated runs.

Name

Type

Flag

Description

target-endpoint-url

STRING

-t

Target API definition URL, e.g. https://example.com/openapi.json or https://example.com/graphql.

target-definition

FILE

-t

Target API definition file, OpenAPI or SOAP.

format

STRING

-f

API format: openapi, soap, or graphql.

schema

STRING

--schema

GraphQL schema URL, e.g. https://example.com/schema.graphqls.

safe-mode

BOOLEAN

-S

Safe mode: skip the active scan and perform a baseline scan instead.

level

STRING

-l

Minimum level to show: PASS, IGNORE, INFO, WARN, or FAIL; use with -s to hide example URLs.

short-output

BOOLEAN

-s

Short output format: do not show PASSes or example URLs.

config_file

FILE

-c

Config file used to mark warnings as INFO, IGNORE, or FAIL.

context-file

FILE

-n

Context file loaded before scanning the target, for authenticated runs.

user

STRING

-U

Username to use for authenticated scans; must be defined in the given context file.

ajax

BOOLEAN

-j

Use the Ajax spider in addition to the traditional one.

alpha

BOOLEAN

-a

Include the alpha active and passive scan rules as well.

debug

BOOLEAN

-d

Show debug messages in stdout.

delay

STRING

-D

Delay in seconds to wait for passive scanning.

max-time

STRING

-T

Max time in minutes to wait for ZAP to start and the passive scan to run.

override

STRING

-O

Hostname to override in the (remote) OpenAPI spec.

zap-options

STRING

-z

Raw ZAP command line options passed through to the scanner.

Total of 47 URLsPASS: Cookie No HttpOnly Flag [10010]PASS: Re-examine Cache-control Directives [10015]WARN-NEW: Content Security Policy (CSP) Header Not Set [10038] x 12WARN-NEW: Server Leaks Version Information via "Server" HTTP Response Header Field [10036] x 8FAIL-NEW: SQL Injection [40018] x 1 http://example.com/api/v3/products?id=1FAIL-NEW: Cross Site Scripting (Reflected) [40012] x 2 http://example.com/api/v3/search?q=testFAIL-NEW: 2 WARN-NEW: 2 WARN-INPROG: 0 INFO: 0 IGNORE: 0 PASS: 61

Test OpenAPI, SOAP, or GraphQL APIs with ZAP

What zap-api-scan does

Where zap-api-scan fits

Scan an API from its OpenAPI spec

Test a GraphQL endpoint

Run a safe baseline first

Gate a deployment pipeline

zap-api-scan inputs and flags

Run zap-api-scan

Choosing zap-api-scan

zap-full-scan

zap-automation-framework

wapiti

zap-api-scan questions

More Scanners tools

airixss

cmseek

joomscan

nikto

nomore403

nuclei

Run zap-api-scan yourself

Test OpenAPI, SOAP, or GraphQL APIs with ZAP

What zap-api-scan does

Where zap-api-scan fits

Scan an API from its OpenAPI spec

Test a GraphQL endpoint

Run a safe baseline first

Gate a deployment pipeline

zap-api-scan inputs and flags

Run zap-api-scan

Choosing zap-api-scan

zap-full-scan

zap-automation-framework

wapiti

zap-api-scan questions

More Scanners tools

airixss

cmseek

joomscan

nikto

nomore403

nuclei

Run zap-api-scan yourself