ZAP - API Scan

ZAP - API Scan

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

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

Exit Value

The script will exit with codes of:

  • 0: Success
  • 1: At least 1 FAIL
  • 2: At least one WARN and no FAILs
  • 3: Any other failure

By default all alerts found by ZAP will be treated as WARNings.

You can use the -c or -u parameters to specify a configuration file to override this.

Configuration

The configuration works in a very similar way as the Baseline Scan so see the Baseline page for more details.

Configuration File

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.

# zap-api-scan rule configuration file
# Change WARN to IGNORE to ignore rule or FAIL to fail if rule matches
# Active scan rules set to IGNORE will not be run which will speed up the scan
# Only the rule identifiers are used - the names are just for info
# You can add your own messages to each rule by appending them after a tab on each line.
0	WARN	(Directory Browsing - Active/release)
10010	WARN	(Cookie No HttpOnly Flag - Passive/release)
10011	WARN	(Cookie Without Secure Flag - Passive/release)
10012	WARN	(Password Autocomplete in Browser - Passive/release)
10015	WARN	(Incomplete or No Cache-control and Pragma HTTP Header Set - Passive/release)
10016	WARN	(Web Browser XSS Protection Not Enabled - Passive/release)
10017	WARN	(Cross-Domain JavaScript Source File Inclusion - Passive/release)
10019	WARN	(Content-Type Header Missing - Passive/release)
10020	WARN	(X-Frame-Options Header Scanner - Passive/release)
10021	WARN	(X-Content-Type-Options Header Missing - Passive/release)
10023	WARN	(Information Disclosure - Debug Error Messages - Passive/beta)
10024	WARN	(Information Disclosure - Sensitive Informations in URL - Passive/beta)
10025	WARN	(Information Disclosure - Sensitive Information in HTTP Referrer Header - Passive/beta)
10026	WARN	(HTTP Parameter Override - Passive/beta)
10027	WARN	(Information Disclosure - Suspicious Comments - Passive/beta)
10032	WARN	(Viewstate Scanner - Passive/beta)
10040	WARN	(Secure Pages Include Mixed Content - Passive/release)
10045	WARN	(Source Code Disclosure - /WEB-INF folder - Active/beta)
10048	WARN	(Remote Code Execution - Shell Shock - Active/beta)
10095	WARN	(Backup File Disclosure - Active/beta)
10105	WARN	(Weak Authentication Method - Passive/beta)
10202	WARN	(Absence of Anti-CSRF Tokens - Passive/beta)
2	WARN	(Private IP Disclosure - Passive/release)
20012	WARN	(Anti CSRF Tokens Scanner - Active/beta)
20014	WARN	(HTTP Parameter Pollution scanner - Active/beta)
20015	WARN	(Heartbleed OpenSSL Vulnerability - Active/beta)
20016	WARN	(Cross-Domain Misconfiguration - Active/beta)
20017	WARN	(Source Code Disclosure - CVE-2012-1823 - Active/beta)
20018	WARN	(Remote Code Execution - CVE-2012-1823 - Active/beta)
20019	WARN	(External Redirect - Active/release)
3	WARN	(Session ID in URL Rewrite - Passive/release)
30001	WARN	(Buffer Overflow - Active/release)
30002	WARN	(Format String Error - Active/release)
30003	WARN	(Integer Overflow Error - Active/beta)
40003	WARN	(CRLF Injection - Active/release)
40008	WARN	(Parameter Tampering - Active/release)
40009	WARN	(Server Side Include - Active/release)
40012	WARN	(Cross Site Scripting (Reflected) - Active/release)
40013	WARN	(Session Fixation - Active/beta)
40014	WARN	(Cross Site Scripting (Persistent) - Active/release)
40016	WARN	(Cross Site Scripting (Persistent) - Prime - Active/release)
40017	WARN	(Cross Site Scripting (Persistent) - Spider - Active/release)
40018	WARN	(SQL Injection - Active/release)
40019	WARN	(SQL Injection - MySQL - Active/beta)
40020	WARN	(SQL Injection - Hypersonic SQL - Active/beta)
40021	WARN	(SQL Injection - Oracle - Active/beta)
40022	WARN	(SQL Injection - PostgreSQL - Active/beta)
40023	WARN	(Possible Username Enumeration - Active/beta)
42	WARN	(Source Code Disclosure - SVN - Active/beta)
50000	WARN	(Script Active Scan Rules - Active/release)
50001	WARN	(Script Passive Scan Rules - Passive/release)
6	WARN	(Path Traversal - Active/release)
7	WARN	(Remote File Inclusion - Active/release)
90001	WARN	(Insecure JSF ViewState - Passive/beta)
90011	WARN	(Charset Mismatch - Passive/beta)
90019	WARN	(Server Side Code Injection - Active/release)
90020	WARN	(Remote OS Command Injection - Active/release)
90021	WARN	(XPath Injection - Active/beta)
90022	WARN	(Application Error Disclosure - Passive/release)
90023	WARN	(XML External Entity Attack - Active/beta)
90024	WARN	(Generic Padding Oracle - Active/beta)
90025	WARN	(Expression Language Injection - Active/beta)
90026	WARN	(SOAP Action Spoofing - Active/alpha)
90028	WARN	(Insecure HTTP Method - Active/beta)
90029	WARN	(SOAP XML Injection - Active/alpha)
90030	WARN	(WSDL File Passive Scanner - Passive/alpha)
90033	WARN	(Loosely Scoped Cookie - Passive/beta)

For more details see the blog posts:

Scan Hooks

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.

Source Code

The source code for this script is in https://github.com/zaproxy/zaproxy/tree/main/docker.