OWASP ZAP review: what it is, tutorial and alternatives

ZAP sits between a browser, or any HTTP client, and the application. It generates its own root certificate so it can decrypt HTTPS, and browsers launched from ZAP are preconfigured to trust it and proxy through it. Every request and response that passes through is recorded in the Sites tree, which becomes the map of what ZAP knows about the application. Everything else builds on that map: passive rules read it, spiders extend it, and the active scanner attacks the nodes in it. This is why exploring an application by hand through ZAP improves an automated scan, and why anything ZAP never sees, such as a page behind a login it cannot perform, is never tested.

Passive scan rules inspect traffic without sending anything new: missing or weak security headers, cookies without Secure or HttpOnly flags, information leaks in error pages and comments. They run in the background and are safe against any system you are allowed to browse. Active scan rules send crafted requests, for example SQL injection, cross-site scripting and path traversal payloads, against every parameter of every node in scope, and judge the responses. That is a real attack: it can create records, send emails and corrupt data. Rules carry a quality status, release, beta or alpha, and the packaged baseline scan leaves alpha passive rules out unless you pass -a, since less mature rules produce more false positives.

The traditional spider parses HTML responses for links and forms. It is fast but misses routes that only exist in JavaScript. The AJAX spider drives a real browser through Selenium and clicks through the user interface. The Client spider, included as standard since ZAP 2.16, also launches browsers but adds a ZAP browser extension that streams DOM events back, so it can find content the AJAX spider cannot. ZAP’s own getting started guide now recommends the Client spider for modern applications and says the AJAX spider is no longer recommended in most cases. Spiders only enter basic default data into forms, so a registration form that needs a valid email address may stop them; manual exploration fills those gaps.

Most of ZAP’s functionality ships as add-ons that update independently of the core: scan rule packs, the spiders, the fuzzer, reporting, the Automation Framework, authentication helpers, and in 2.16 even the passive scanner moved out of the core. Full releases are infrequent, 2.16.0 in January 2025 and 2.17.0 on 15 December 2025, while add-ons and a weekly build move faster. The practical consequence is that two installations of the same ZAP version can behave differently if their add-ons differ, so automated runs should pin a Docker image or update add-ons deliberately with -addonupdate, rather than drifting.

A context tells ZAP what belongs to the application: the top-level URLs, include and exclude path regexes, the authentication method, the users and the technology in use. Define one per application and keep it in the plan file, not in someone’s desktop session. Exclude logout links so the spider does not end its own session, exclude anything that sends real emails, payments or messages, and exclude third-party domains you are not authorised to test, such as payment providers and analytics. Scope is also a safety control: the active scanner attacks what is in scope, so a careless include pattern can aim attacks at a system you have no permission to touch. Record the written authorisation for each target alongside the plan.

A plan runs its jobs top to bottom. The usual order is: spider the context, wait for passive scanning to finish, actively scan, write reports, then set the exit status. The exitStatus job turns alert risk levels into exit codes, here a warning for Medium and an error for High, which is what makes the plan usable as a gate. maxDuration and maxScanDurationInMins keep a nightly run bounded. Variables written as ${NAME} read operating system environment variables, so the target and credentials come from CI secrets. Run it with zap.sh -cmd -autorun zap.yaml, or in Docker with the working directory mounted at /zap/wrk.

Split the work by cost. On pull requests, run the passive baseline against a preview or staging deployment: it takes minutes and sends no attacks. Nightly, run the Automation Framework plan with the active scan against a disposable environment. The official zaproxy/action-baseline (v0.15.0) wraps the baseline script and by default opens or updates a GitHub issue with the findings and does not fail the job. Set fail_action to true to make it a gate, point rules_file_name at your tuned rules file, and set allow_issue_writing to false if you would rather read the uploaded report. zaproxy/action-af (v0.3.0) runs a plan file the same way and exits with the plan’s exit code.

For a JSON API, skip the spider and give ZAP the definition. zap-api-scan.py imports an OpenAPI, SOAP or GraphQL definition from a file or URL and actively scans every operation, which reaches endpoints a crawler would never find. Because it is an active scan, point it only at an environment you are authorised to attack, and seed that environment with data that can be damaged. Supply authentication with ZAP_AUTH_HEADER_VALUE, or ZAP_AUTH_HEADER for a custom header name, and limit it to the API host with ZAP_AUTH_HEADER_SITE so the token is not sent elsewhere. Keep the definition in the repository so the scan follows the API as it changes.

A scan nobody reads is worse than none, because it creates the impression of coverage. Review the first reports with a developer, and record each decision where the scan can use it: IGNORE or FAIL in the packaged-scan rules file, or an alertFilter job in a plan that marks a specific rule and URL as a false positive or changes its risk. Prefer narrow filters, a rule plus a URL pattern, over ignoring a rule everywhere. Use ZAP 2.17’s systemic alerts and de-duplication to keep header findings to one line each. Read the Insights section for signs that a scan ran into trouble, and compare URL counts between runs: a sudden drop usually means the spider or authentication broke, not that the application shrank.