The ZAP Automation Framework controls ZAP from a single YAML file. The file has an env section naming the applications and a jobs list of steps such as spider, active scan and report. You start it from the command line with the autorun option, and it returns an exit code your pipeline can read.
Why use a plan file
A plan makes a scan reviewable. It lives in version control, changes go through pull requests, and every run does the same thing. ZAP's documentation recommends the framework as the way to automate ZAP for most people, and says it is not tied to a particular container technology.
Structure
| Part | Purpose |
|---|---|
| env | The applications and contexts the plan acts on, including authentication and session settings |
| jobs | Ordered steps, each with a job type |
| Job tests | Checks that validate a job's outcome |
Job types documented include spider, spiderAjax, spiderClient, activeScan, passive scan configuration and wait jobs, openapi, graphql, soap, postman, report, requestor, replacer, alertFilter, delay and exitStatus.
Running a plan
The documented command form is zap.sh with the cmd option and autorun pointing at your plan file. Exit codes are 0 when the plan ran without problems, 1 when it failed with an error, and 2 when it ran but reported warnings.
Steps
- Start from a small plan: one environment, a spider job, a passive scan wait job and a report job.
- Run it locally against staging and open the report.
- Add authentication in the environment section, and a logged-in check.
- Add an openapi or graphql import job for API coverage.
- Add an active scan job with a time limit, then an exit status job so the pipeline fails on the severity you choose.
- Commit the plan, and run it in a scheduled pipeline.
Tips
Use alert filters to suppress known false positives in the plan itself, with a comment explaining each. Keep separate plans for the fast baseline and the deep scan. Check the current documentation for your ZAP version, since job options change between releases.
Try it yourself
Walk through the demo steps and map each to a job you would put in a plan.
Click through it at your own pace, or open it full screen.
Quick check
Is the plan file only for Docker?
No. The documentation says the framework is not tied to container technology, though it is in the stable Docker image.
What does exit code 2 mean here?
The plan ran but reported warnings. This applies even when fail on warning is false.
Where Safeguard fits
Safeguard offers dependency and SBOM scanning, reachability analysis and policies and gates that can block a pull request, so the libraries behind your app are checked alongside the app itself. You can try a free scan at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
