OWASP ZAP Tutorial 2026: Install, Configure & Scan the Free Web App Security Scanner

DAST On A Budget

Full-featured dynamic scanning with zero licensing cost — the entry point for solo testers, students, and teams that cannot justify commercial tooling.

CI/CD Gate

The headless baseline and full scans plug into GitHub Actions, GitLab CI and Jenkins so every build gets a security pass before it ships.

API Security Testing

Import an OpenAPI, SOAP or GraphQL definition and ZAP scans every endpoint — no manual browsing of the API required.

Blue-Team Validation

Defenders use ZAP to confirm WAF rules fire, headers are enforced, and detections trigger — running the attack so the SOC can watch it land.

Before installing the cross-platform or Linux build, verify the runtime. If java -version reports 17 or higher you are set; anything lower (or "command not found") means you install a JDK first.

Never scan a site you do not control. The fastest deliberately-vulnerable target is OWASP Juice Shop — one container, ready in seconds — which every command in this guide can point at safely.

Download the Windows installer from zaproxy.org (it bundles Java), or install headlessly with winget, Chocolatey or Scoop. The package-manager route is best for scripted or repeated builds.

Grab the Intel or Apple-Silicon DMG (Java is bundled), or install the Homebrew cask. On first launch macOS Gatekeeper may block the app; approve it once under System Settings.

The distro-agnostic route: download the Linux installer .sh, make it executable, and run it. This works on Ubuntu, Debian, Fedora, Arch — anything with Java 17. Use the headless flag -q for an unattended install.

On Kali (and other pentest distros) ZAP is packaged as zaproxy in the default repos. This is the least-effort path if you are already on Kali, though the repo version can trail the official release by a point or two.

For a sandboxed desktop install that auto-updates, use Flatpak or Snap. Note the sandbox restricts filesystem access, so reports save inside the sandboxed home — grant extra paths if you need reports elsewhere.

Regardless of method, confirm ZAP runs and reports its version. The -version flag prints the build and exits — the quickest smoke test for scripts.

Pull the stable image once. It is regenerated on the first Monday of each month with the latest base OS and updated add-ons, so re-pull periodically to stay current.

The image can serve the complete desktop GUI over the web via Webswing — useful on a headless server. Port 8080 serves the UI; 8090 exposes the API.

Daemon mode runs ZAP as an API-only service — the backbone of scripted scanning. Bind the API to all interfaces inside the container and set an API key you will reuse from your client.

The image ships three turnkey scan scripts. Baseline spiders and passive-scans only (safe, fast, CI-friendly). Full adds active scanning. API imports an OpenAPI/SOAP/GraphQL definition and scans the endpoints. Mount a working directory so reports land on the host.

A compose file wires the ZAP daemon and a target on a shared network so ZAP can reach the app by service name. Save this as docker-compose.yml and bring it up with docker compose up.

On a fresh Ubuntu 24.04 VM, install Java and ZAP via the cross-platform script, then create a low-privilege user to run it. Never run the daemon as root.

Wrap the daemon in a systemd unit so it survives reboots and restarts on failure. Bind the API to the VM's LAN interface only, behind a firewall rule that permits your workstation.

From your workstation, point curl or the ZAP client library at the VM's API. This is also how a remote GitHub/GitLab runner can share one scanning engine across jobs.

On launch ZAP asks whether to persist the session. For any real engagement, choose to persist so requests, alerts and history survive a crash. Ephemeral sessions are fine only for a throwaway look.

• 1
  Yes, persist with name based on current timestamp — recommended default; auto-names the session file.
• 2
  Yes, persist to a specific location — pick this to keep client engagements in separate, clearly named files.
• 3
  No, do not persist — memory only; everything is lost on exit.

The mode dropdown (top-left of the toolbar) is your safety switch. It governs what ZAP is permitted to do, regardless of what you click.

To read HTTPS traffic, ZAP presents its own dynamically-generated certificate for each site, signed by its root CA. Your browser must trust that root CA or every page throws a certificate error. Generate a fresh CA and export it.

Import the exported .cer into the trust store the browser actually uses. Firefox has its own store; Chrome and Edge use the OS store.

• FF
  Firefox: Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import → tick "Trust this CA to identify websites".
• CR
  Chrome/Edge: imports into the OS store — see the CLI below for Linux, or Keychain Access (macOS) / certmgr.msc (Windows).

ZAP listens on 127.0.0.1:8080 by default. Configure the browser to use it as an HTTP proxy — manually, or with a proxy-switcher extension so you can toggle it quickly.

The simplest path for beginners: ZAP launches a pre-configured browser with the CA already trusted and the Heads Up Display overlaid on the page. No proxy config, no cert import.

• 1
  Click the Firefox/Chrome browser button in the ZAP toolbar (top).
• 2
  Browse the target normally — the HUD shows alerts, scan controls and site info as on-page overlays.
• 3
  Use the HUD's spider and attack buttons directly, or drive everything from the main ZAP window.

A Context is ZAP's model of your target: which URLs belong to it, how to authenticate, which parameters to fuzz. Setting scope keeps active scanning surgical and prevents it wandering onto third-party domains.

• 1
  Right-click the target node in the Sites tree and add it to a new Context.
• 2
  Refine the include/exclude regex so only the app's own URLs are in scope.
• 3
  Toggle the target-scope button so the display filters to in-scope traffic only.

The traditional spider parses HTML and follows links to map the site. Run it first so the scanner knows what endpoints exist. Drive it from the GUI or the API.

Single-page apps built on React, Angular or Vue render links in JavaScript that the traditional spider never sees. The AJAX Spider drives a real headless browser to click through the app and capture those routes.

Passive scanning ran automatically on everything the spiders touched — no action needed. Review the Alerts tab: it flags missing headers (CSP, HSTS, X-Content-Type-Options), insecure cookie flags, and information leakage, colour-coded by risk.

The active scan is the attack phase — it injects payloads to test the discovered endpoints for injection, XSS, traversal and more. Run it only against in-scope, authorised targets. Then export a report.

In the Context, set an authentication method so ZAP can log in and hold a session while it scans. ZAP supports form-based, JSON, HTTP/NTLM, script-based, and (new in 2.17) improved token handling for JWT-bearing apps.

• 1
  Choose the method (Form-based for classic apps, JSON for SPA/API logins).
• 2
  Set the login URL, and the username/password field names from the login request.
• 3
  Define Logged-in / Logged-out indicators — a regex ZAP uses to know if its session is still valid.
• 4
  Add a User with real credentials, then set the scan to run "as user".

You do not browse an API — you import its contract. ZAP's OpenAPI, SOAP and GraphQL add-ons read the definition and populate the Sites tree with every endpoint, ready to scan.

The official ZAP GitHub Actions run a baseline or full scan on every push and open issues for findings. Drop this workflow into .github/workflows/zap.yml.

Beyond HTML, ZAP exports SARIF, JSON, XML and Markdown. SARIF uploads straight into GitHub code-scanning; JSON feeds dashboards and ticketing.

For defenders, the value loop is: run a controlled scan, then confirm the SOC saw it. ZAP's traffic should light up your WAF and detection rules — the JSON report gives you the exact timestamps and payloads to pivot on.

Each YAML job runs in order: define the environment/context, spider, wait for passive scan, active-scan, then report. Save this as zap.yaml.

Execute the plan with -autorun. In Docker, mount the directory holding the YAML so ZAP can read the plan and write the report back to the host.

A scan policy decides which attack rules fire and how hard. Dialling threshold and strength trades speed against coverage — a targeted policy that skips irrelevant rules finishes far faster.

Nearly all ZAP capability ships as add-ons from the Marketplace — OpenAPI import, GraphQL, the report engine, extra active rules. Manage them from the GUI or the command line for reproducible images.

Every GUI action has an API equivalent, so you can build custom orchestration in any language. The API is browsable at http://localhost:8090 once the daemon is up. Endpoints come in JSON (actions/views) and OTHER (binary output like reports).

Scan rules ship in add-ons that update independently of the core. A monthly update keeps detection current; re-pull the Docker image monthly for the same reason.

Large sites and long scans exhaust the default heap and ZAP slows or crashes with OutOfMemory. Raise the maximum heap with a JVM flag.

Every DAST tool produces false positives. Mark them once and ZAP remembers: right-click an alert → Mark as False Positive, or raise the rule threshold to High. In CI, encode these in the rules file so the gate stays honest.