OWASP ZAP Guide: Safe, Authorised Web App Scanning in CI/CD

Web applications change every week, but most teams only test them dynamically once a year, so missing security headers, broken session handling and injection flaws reach production and stay there. ZAP, still widely searched for as OWASP ZAP, is a free and open source dynamic application security testing (DAST) tool that can scan a running application from a laptop, a container or a CI/CD pipeline. This guide explains what ZAP does, which of its scan types are safe to run where, how to wire it into pipelines with exit codes and rule files, how to handle authentication and test credentials, and how to measure whether it is reducing risk. It is written for application security engineers, DevSecOps and platform teams, and testers who run authorised assessments. It covers defensive and authorised use only: scan only applications you own or have written permission to test.

Key takeaways

• Passive and active are different risk classes. The baseline scan spiders and observes traffic without attacking; the full and API scans run an active scan that sends real attack payloads and can change data, so they belong in test environments with permission.
• Exit codes make it a pipeline gate. The packaged scans return 0 for success, 1 when any rule is set to FAIL and fires, 2 for warnings only and 3 for other errors, so you choose exactly what breaks a build.
• A rules file is your policy. Every alert defaults to WARN; a checked-in configuration file promotes the rules you care about to FAIL and sets known noise to IGNORE.
• Authentication decides coverage. Without a context, a test user and logged-in or logged-out indicators, ZAP only tests the public surface of an application.
• The name changed, the licence did not. ZAP left OWASP in 2023 and has been "ZAP by Checkmarx" since September 2024, and it remains Apache 2.0 licensed with the core team in control of the project.

What the tool does

ZAP sits between a client and a web application as an intercepting proxy. It records requests and responses, discovers content with spiders, inspects every response with passive scan rules and, when you allow it, sends crafted requests with active scan rules to find vulnerabilities such as reflected cross site scripting and SQL injection. It runs as a desktop application, as a headless daemon controlled through its REST API, and as container images published at ghcr.io/zaproxy/zaproxy (the stable tag for releases, weekly images for newer rules).

For a short history: the project announced in August 2023 that it was leaving OWASP to become a founding project of the Linux Foundation's Software Security Project, at which point "OWASP ZAP" became simply "ZAP" and Docker Hub images moved organisation (the GitHub Container Registry images were unaffected). On 24 September 2024 the project announced it had joined forces with Checkmarx, which now employs the three project leaders; the ZAP core team keeps control of the project and the code stays under the Apache License 2.0. Checkmarx's commercial DAST product is built on ZAP, but the open source tool is complete in its own right.

Ways to run a scan

The packaged scan scripts share the same exit codes: 0 success, 1 at least one FAIL, 2 at least one WARN and no FAIL, 3 any other failure. The Automation Framework uses 0 for a clean run, 1 for an error and 2 for warnings. Reports are written as HTML (-r), Markdown (-w), XML (-x) or JSON (-J).

Defender use cases

• Security header and cookie regression testing: passive rules such as 10038 Content Security Policy (CSP) Header Not Set, 10020 Anti-clickjacking Header and 10021 X-Content-Type-Options Header Missing catch configuration drift on every build. These map directly to OWASP ASVS 5.0 requirements V3.4.1 (HSTS), V3.4.3 (Content-Security-Policy) and V3.4.4 (nosniff).
• Pre-release active testing: a nightly full scan against a test environment exercises injection classes such as 40012 Cross Site Scripting (Reflected) and 40018 SQL Injection before code reaches production. See the Web Application Security Testing Guide.
• API coverage from the contract: the API scan imports an OpenAPI, SOAP or GraphQL definition, so endpoints that a spider would never find are still tested. See the API Security Guide.
• Verifying fixes: rerunning the same plan gives repeatable evidence that a finding has closed.
• Triage support for manual testers: the desktop proxy history and alerts give a tester a map of the application before deeper manual work. See the Burp Suite for Authorised Web Testing Guide for the commercial alternative many testers pair it with.
• Coverage of the OWASP Top 10: ZAP finds many misconfiguration and injection issues but cannot reason about business logic or most access control flaws. See the OWASP Top 10 Guide.

Deployment and safe use

ZAP is a scanner that sends traffic you are responsible for. Treat every target as needing written authorisation, and agree scope, timing and contacts first. See the Penetration Test Scoping Checklist.

Rollout in phases

1. Inventory and authorise. List the applications and APIs in scope, record who owns each and get written approval, including for any third-party hosting or WAF provider whose terms cover scanning.
2. Start passive. Run the baseline scan against each application with -I (do not fail on warnings) so the pipeline reports but never blocks. Generate a default rules file with -g, where every rule is WARN.
3. Tune. Review two or three weeks of results with developers. Set accepted noise to IGNORE with a comment explaining why, and promote high-signal rules (missing CSP, cookie flags, information disclosure) to FAIL. Check the rules file into the repository and review changes to it like code.
4. Gate. Remove -I and let exit code 1 fail the build. In GitHub Actions, the official zaproxy/action-baseline action takes target, rules_file_name, cmd_options and fail_action, and by default files and maintains a single issue with the alerts; set allow_issue_writing: false if findings should go elsewhere.
5. Add active scanning in test only. Run full or API scans nightly against a dedicated environment with disposable data, never against production unless the owner explicitly approves and has backups. Active rules can submit forms, create records and trigger emails.
6. Move to the Automation Framework. Once authentication and multiple stages are involved, a YAML plan in version control is easier to review and reproduce than long command lines.
7. Rollback. If a gate blocks delivery unfairly, revert the rules file change or reinstate -I for that application, record the exception with an expiry date, and fix the rule rather than removing the scan.

Safety controls inside ZAP

• Modes: Safe mode blocks all potentially dangerous operations; Protected mode, which the documentation recommends, only allows spidering, active scanning, fuzzing, forced browsing and resending against URLs in scope; Standard mode restricts nothing; ATTACK mode actively scans new in-scope nodes as soon as they are found. Use Protected for manual work.
• Contexts and scope: define a context with include and exclude regular expressions so logout links, payment endpoints and third-party domains are never attacked.
• API key and binding: the REST API requires an API key for actions, and the documentation strongly recommends setting one (-config api.key=...) unless ZAP runs in a completely isolated environment. By default only the local machine can call the API; do not expose the daemon port (8080 by default) to a shared network.
• Pinning: pin container images by digest and GitHub Actions by full commit SHA. Security scanners run inside privileged pipelines and are attractive targets: in the Trivy supply chain attack, attackers force-pushed a scanner's action tags to an infostealer that harvested CI secrets.

Data handling and licensing

Session files, reports and proxy history contain full requests and responses, which can include session tokens, personal data and secrets returned by the application. Store reports as restricted pipeline artefacts with a short retention period, avoid attaching raw HTML reports to public issues, and use synthetic data in test environments. ZAP is Apache 2.0 licensed, so internal and commercial use is permitted. Keep the -a flag, which adds alpha rules, out of blocking gates.

Where identity fits

Authenticated scanning needs credentials, and those credentials are non-human identities in all but name. ZAP models login with a context, users defined per context, an authentication method (form-based, browser-based, client script or OAuth2), a session management method (cookie, header-based or auto-detect) and at least one logged-in or logged-out indicator so it can tell when it has been signed out. The documentation notes that Forced User Mode is for manual testing and should not be used in automation.

• Dedicated test accounts: create scan users that exist only in test environments, with the least privilege that still reaches the features under test, and one account per role you need to compare.
• Secrets out of plans: pass passwords and tokens through the CI secret store as environment variables, never in the YAML plan or rules file. See the Secrets Management Guide.
• Rotation and expiry: rotate scan credentials on a schedule and disable them when an environment is retired; a forgotten scanner account with a static password is an easy foothold.

Detection and hardening value

ZAP is a testing tool, not a monitoring tool, but it produces evidence that feeds both detection engineering and hardening. Its own traffic is also a useful test of your defences: if a web application firewall or SIEM never notices a nightly active scan, that is worth knowing. See the Web Application Firewall Guide.

Metrics that show it is working

• Coverage: percentage of internet-facing applications and APIs with a baseline scan in their pipeline, and percentage with an authenticated scan.
• Gate quality: number of rules at FAIL and the false positive rate of failed builds (target under 10 per cent before adding more FAIL rules).
• Time to fix: median days from first detection to the alert disappearing, by risk level (High, Medium, Low).
• Recurrence: alerts that reappear after closure, which point to missing shared configuration rather than individual bugs.
• Authentication health: share of authenticated scans where ZAP stayed logged in for the whole run, from the logged-in and logged-out indicators.

Common failure patterns

• Active scanning production by accident: a copied full-scan job pointed at a live URL creates junk records, sends emails and trips alerts. Separate baseline and active jobs and restrict active targets to test hostnames.
• Unauthenticated scans reported as full coverage: without a working context and indicators, ZAP tests the login page and little else, and dashboards show a clean result.
• Everything at WARN forever: with -I left on, the scan never fails and nobody reads the report. Promote a small, agreed set of rules to FAIL.
• Ignoring rules without a reason: IGNORE entries with no comment or owner hide real regressions later. Review the rules file quarterly.
• Exposed daemon API: a ZAP daemon with no API key listening on a shared network lets anyone drive scans from your infrastructure.
• Unpinned scanner images and actions: pulling a moving tag into a pipeline that holds deployment secrets repeats the lesson of the Trivy supply chain attack.

Alternatives

For small teams, the baseline scan plus a nightly full scan of one test environment covers most of the value. Large organisations usually add a findings platform to deduplicate ZAP results with SAST and SCA output. See the Open Source AppSec Tools Landscape Guide and the Application Security Testing Buyer's Guide.

Practitioner checklist

• Get written authorisation and a defined scope for every application and API before the first scan.
• Run the baseline scan in every pipeline, starting with -I and moving to a gate after tuning.
• Keep a reviewed rules file in the repository, with a reason recorded for every IGNORE.
• Restrict full and API active scans to test environments with disposable data.
• Configure contexts, test users and logged-in or logged-out indicators for authenticated coverage.
• Store scan credentials in the CI secret store and rotate them on a schedule.
• Set an API key on any daemon and never expose the API port to a shared network.
• Pin ZAP images by digest and actions by commit SHA.
• Retain reports as restricted artefacts and track time to fix and recurrence.

Standards and references

• ZAP: Baseline Scan
• ZAP: Full Scan
• ZAP: API Scan
• ZAP: Automation Framework
• ZAP: Modes
• ZAP: Authentication
• OWASP: Application Security Verification Standard 5.0
• NIST: SP 800-53 Rev. 5 Security and Privacy Controls

Related NHI Mgmt Group resources: Application Security Guide · DevSecOps Guide · Web Application Security Testing Guide · GitHub and GitHub Actions Security Guide · Open Source AppSec Tools Landscape Guide