The ZAP API scan is a script that is available in the ZAP Docker images.
It is tuned for performing scans against APIs defined by OpenAPI, SOAP, or GraphQL via either a local file or a URL.
It imports the definition that you specify and then runs an Active Scan against the URLs found. The Active Scan is tuned to APIs, so it doesn’t bother looking for things like XSSs.
It also includes 2 scripts that:
- Raise alerts for any HTTP Server Error response codes
- Raise alerts for any URLs that return content types that are not usually associated with APIs
Usage: zap-api-scan.py -t <target> -f <format> [options] -t target target API definition, OpenAPI or SOAP, local file or URL, e.g. https://www.example.com/openapi.json or target endpoint URL, GraphQL, e.g. https://www.example.com/graphql -f format openapi, soap, or graphql Options: -h print this help message -c config_file config file to use to INFO, IGNORE or FAIL warnings -u config_url URL of config file to use to INFO, IGNORE or FAIL warnings -g gen_file generate default config file (all rules set to WARN) -r report_html file to write the full ZAP HTML report -w report_md file to write the full ZAP Wiki (Markdown) report -x report_xml file to write the full ZAP XML report -J report_json file to write the full ZAP JSON document -a include the alpha passive scan rules as well -d show debug messages -P specify listen port -D delay in seconds to wait for passive scanning -i default rules not in the config file to INFO -I do not return failure on warning (post 2.9.0) -l level minimum level to show: PASS, IGNORE, INFO, WARN or FAIL, use with -s to hide example URLs -n context_file context file which will be loaded prior to scanning the target -p progress_file progress file which specifies issues that are being addressed -s short output format - dont show PASSes or example URLs -S safe mode this will skip the active scan and perform a baseline scan -T max time in minutes to wait for ZAP to start and the passive scan to run -U user username to use for authenticated scans - must be defined in the given context file (post 2.9.0) -O the hostname to override in the (remote) OpenAPI spec -z zap_options ZAP command line options e.g. -z "-config aaa=bbb -config ccc=ddd" --hook path to python file that define your custom hooks --schema GraphQL schema location, URL or file, e.g. https://www.example.com/schema.graphqls
The configuration works in a very similar way as the Baseline Scan so see the Baseline page for more details.
You can configure how the API scan runs with a configuration file. A default configuration file can be created using the ‘-g’ parameter. Unlike the baseline configuration file the API configuration file handles both active and passive scan rules.
For more details see the blog posts:
This script supports scan hooks which allow you to override or modify behaviour of the script components instead of having to write a new script.
The source code for this script is in https://github.com/zaproxy/zaproxy/tree/main/docker.