Last updated: 26 July 2026

ZAP, formerly known as OWASP ZAP, is a free and open-source web application security testing tool. It can act as a proxy between your browser and a web application, allowing you to inspect requests, analyse responses, discover application endpoints, and identify potential security vulnerabilities.

This guide explains how to install and configure ZAP Proxy on macOS from the beginning. Every step is written for new users, so you do not need previous penetration-testing or proxy-configuration experience.

As of July 2026, ZAP 2.17.0 is the latest stable core release. Separate installers are available for Intel-based Macs and Apple Silicon Macs. The official macOS installer includes the required Java runtime, so users installing through the standard macOS package do not normally need to install Java separately.

Important security and legal warning

ZAP can send attack-style requests designed to identify vulnerabilities. These requests may change data, create records, trigger application functions, increase server load, or affect the availability of the target system.

Only perform active scanning against:

Applications you own
Local applications running on your computer
Dedicated security-testing environments
Systems for which you have explicit written permission
Intentionally vulnerable training applications

Do not actively scan public websites merely because they are accessible through a browser. The ZAP project explicitly warns that active scanning is an attack and should not be performed against applications you do not own or have permission to test.

What you will configure

By the end of this guide, you will be able to:

Identify whether your Mac uses Apple Silicon or an Intel processor.
Download and install the correct ZAP version.
Open ZAP when macOS blocks the application.
Update the installed ZAP add-ons.
Configure ZAP’s local proxy listener.
Launch a browser through ZAP.
Capture HTTP and HTTPS requests.
Configure a browser manually when necessary.
install the ZAP Root CA certificate for HTTPS testing.
Perform passive and authorised active scans.
Review security alerts.
Generate an HTML or PDF report.
Save your ZAP testing session.
Troubleshoot common macOS problems.

Part 1: Check whether your Mac uses Apple Silicon or Intel

ZAP provides different macOS installers for Apple Silicon and Intel Macs. Installing the correct version helps avoid performance and compatibility problems.

Method 1: Check through About This Mac

Click the Apple menu in the upper-left corner.
Select About This Mac.
Look for the field labelled Chip or Processor.

You may see one of the following:

Apple M1
Apple M2
Apple M3
Apple M4
Intel Core i5
Intel Core i7
Intel Core i9

Any Mac using an M1, M2, M3, or M4 processor is an Apple Silicon Mac.

A Mac displaying Intel Core is an Intel Mac.

Method 2: Check through Terminal

Open Terminal by pressing:

Command + Space

Search for:

Terminal

Then run:

uname -m

Interpret the result as follows:

arm64    = Apple Silicon Mac
x86_64   = Intel Mac

Keep this information ready when selecting the ZAP installer.

Part 2: Install ZAP using the official macOS installer

For beginners, the official macOS installer is the recommended installation method.

Step 1: Open the official ZAP download page

Open your normal browser and visit the official ZAP website’s download section.

Look for the ZAP Stable section rather than Weekly, Nightly, or Cross Platform.

A stable release is the best choice for beginners because it is intended for normal use. Weekly and nightly versions may include newer features, but they can also contain incomplete or less-tested changes.

Step 2: Select the correct macOS installer

Choose the installer that matches your Mac.

For Apple Silicon

Select the option labelled similarly to:

macOS Apple Silicon
aarch64
ARM64

Use this version for M1, M2, M3, and M4 Macs.

For Intel Mac

Select the macOS Intel installer.

Do not download the Cross Platform package unless you specifically need it. The standard macOS installer already includes an appropriate Java runtime, while the Cross Platform package requires Java 17 or later to be installed separately.

Step 3: Wait for the download to finish

The installer will normally be saved in your Mac’s Downloads folder.

Open Finder and navigate to:

Downloads

The filename may look similar to:

ZAP_2_17_0_macos.dmg

The exact version number may be newer if another stable release has been published.

Step 4: Open the downloaded file

Double-click the downloaded .dmg file.

Depending on the installer layout, you may see:

An installation wizard, or
A ZAP application icon that should be moved into Applications

Follow the instructions shown on the screen.

When presented with a ZAP application icon and an Applications folder:

Drag ZAP into the Applications folder.
Wait for macOS to finish copying the application.
Close the installer window.
Eject the mounted ZAP disk image from Finder.

Step 5: Open ZAP

Open:

Finder → Applications

Locate ZAP and double-click it.

You can also launch it using Spotlight:

Command + Space

Type:

ZAP

Then press Return.

Part 3: Fix “ZAP.app cannot be opened” on macOS

The first time you open ZAP, macOS may display a message such as:

“ZAP.app” cannot be opened because the developer cannot be verified.

This can happen because macOS Gatekeeper does not recognise the application as coming from a verified Apple developer. The official ZAP download documentation describes this warning and the Open Anyway process.

Only continue when you downloaded ZAP from its official website.

Step 1: Close the warning

Click:

Cancel

Step 2: Open Privacy & Security

Open:

Apple menu → System Settings → Privacy & Security

Step 3: Find the blocked application message

Scroll down until you see a message stating that ZAP was blocked.

Click:

Open Anyway

Step 4: Confirm the action

macOS may ask for:

Your account password
Touch ID
Administrator approval

Approve the request.

You may receive another warning. Click:

Open

ZAP should now start normally.

Part 4: Complete the first-start configuration

When ZAP starts for the first time, it may need a few moments to initialise its database, add-ons, interface, and certificate information.

Step 1: Choose whether to save the session

ZAP may ask whether you want to persist the current session.

A session contains information such as:

Visited URLs
HTTP requests and responses
Discovered sites
Security alerts
Scan results
Context information

For practice or temporary testing, select:

No, I do not want to persist this session at this moment

For a real authorised assessment, select:

Yes, I want to persist this session

Give the session a meaningful name, such as:

customer-portal-security-test

or:

local-app-scan-2026-07-26

Persisted sessions are stored locally and remain available after ZAP closes. Non-persisted sessions cannot be reopened after you exit the application.

Step 2: Understand the main interface

The ZAP window contains several important areas.

Sites tab

The Sites tab displays applications, domains, folders, pages, scripts, and API endpoints discovered by ZAP.

History tab

The History tab displays every HTTP or HTTPS request sent through ZAP.

Request tab

The Request tab shows what your browser or client sent to the server.

Response tab

The Response tab shows what the server returned.

Alerts tab

The Alerts tab displays potential security weaknesses identified by passive or active scanning.

Quick Start tab

The Quick Start tab provides the simplest way to:

Explore an application manually
Perform an automated scan
Learn the basic ZAP workflow

Part 5: Update ZAP and its add-ons

ZAP uses add-ons to provide many of its features, including scan rules, browser integration, spiders, report generation, authentication support, and API import capabilities.

Updating them before your first test ensures that you have the latest available fixes and security rules.

Step 1: Open Manage Add-ons

Click the marketplace-style button in the ZAP toolbar, or open:

Tools → Manage Add-ons

Step 2: Open the Installed tab

Select:

Installed

Click:

Check for Updates

Install all available release-quality updates.

Step 3: Open the Marketplace tab

Select:

Marketplace

Useful add-ons for beginners include:

Passive Scan Rules
Active Scan Rules
Client Side Integration
Client Spider
Selenium
macOS WebDrivers
Report Generation
OpenAPI Support
GraphQL Support
Postman Support

Do not install every Alpha add-on simply because it is available. ZAP classifies add-ons as Release, Beta, or Alpha. Release add-ons are generally the most suitable starting point, while Alpha add-ons may still be experimental.

Restart ZAP when requested.

Part 6: Configure ZAP’s operating mode

ZAP provides four operating modes:

Safe
Protected
Standard
Attack

For a beginner, Protected mode is normally the safest practical choice.

Safe mode

Safe mode prevents potentially dangerous functions such as active scanning, fuzzing, and request modification.

Use this while learning the interface or inspecting ordinary browser traffic.

Protected mode

Protected mode permits potentially dangerous operations only against URLs that you have explicitly placed in scope.

This is the recommended mode for controlled security testing.

Standard mode

Standard mode does not place the same restrictions on potentially dangerous operations.

Beginners can accidentally scan the wrong application in Standard mode.

Attack mode

Attack mode automatically scans newly discovered in-scope nodes. It should not be used by beginners until they fully understand ZAP’s scope, context, and scanning behaviour.

The ZAP project recommends Protected mode to help ensure that users attack only the sites they intend to test.

Select Protected mode

Find the mode selector in the ZAP toolbar.

Select:

Protected Mode

If you are only learning how to capture traffic, you can begin with:

Safe Mode

Part 7: Verify ZAP’s local proxy configuration

ZAP acts as a local proxy server. Your browser sends requests to ZAP, and ZAP forwards them to the target application.

By default, ZAP listens on:

Address: localhost
Port: 8080

These settings can be viewed or changed through ZAP’s Local Servers/Proxies options.

Step 1: Open the proxy settings

In ZAP, open:

Tools → Options

Expand:

Network

Select:

Local Servers/Proxies

Step 2: Check the address and port

Confirm that the local proxy is configured as:

Address: localhost
Port: 8080

You may also see the address represented as:

127.0.0.1

Both refer to your own computer.

Step 3: Keep remote access disabled

Do not change the listener to:

0.0.0.0

unless you understand the security implications and specifically need another authorised device to connect.

For normal testing on your Mac, keep the proxy bound to:

localhost

This prevents other devices on your network from connecting to your ZAP instance.

Step 4: Change the port only when necessary

If another application already uses port 8080, change the ZAP port to something such as:

or:

Remember that your browser proxy configuration must use the same port.

Part 8: The easiest way to connect a browser to ZAP

The easiest and safest method is to launch a browser directly from ZAP.

ZAP automatically creates a temporary browser profile, configures the proxy, and handles certificate warnings. This means you normally do not need to change macOS network settings or install a root certificate manually.

Step 1: Open Manual Explore

In ZAP, select:

Quick Start

Click:

Manual Explore

Step 2: Enter the authorised target URL

For example, when testing an application running locally:

http://localhost:3000

Other common local development addresses include:

http://localhost:4200
http://localhost:5173
http://localhost:8000
http://localhost:8080

Do not use port 8080 for your application when ZAP itself is already listening on port 8080. In that case, either change your application’s port or change ZAP’s proxy port.

Step 3: Select a browser

Choose an installed browser such as:

Firefox
Chrome

Step 4: Leave the HUD disabled initially

The Heads Up Display can show ZAP information inside the browser, but it adds extra interface elements.

For your first test, leave:

Enable HUD

unchecked.

You can enable it later after understanding the basic workflow.

Step 5: Launch the browser

Click:

Launch Browser

ZAP will open a new browser window using a temporary testing profile.

Do not confuse this window with your normal browser profile. Your usual bookmarks, extensions, login sessions, and saved passwords may not appear.

Step 6: Browse the application

Use the ZAP-launched browser to visit the application’s:

Home page
Login page
Registration page
User dashboard
Forms
Search pages
Profile pages
Settings
File upload screens
API-driven features
Logout function

The more of the application you explore, the more URLs and functionality ZAP can observe.

Part 9: Confirm that ZAP is capturing traffic

Return to the ZAP desktop window.

Check the Sites tab

You should see the target domain or local application under:

Sites

Expand the site tree to view discovered paths.

For example:

localhost:3000
├── login
├── dashboard
├── profile
├── api
│   ├── users
│   └── orders
└── logout

Check the History tab

The History tab should contain requests such as:

GET
POST
PUT
PATCH
DELETE

Click any request to inspect its details.

The lower section should display:

Request headers
Request body
Response headers
Response body
HTTP status code
Cookies
Parameters

If the Sites and History tabs contain entries, your browser is successfully sending traffic through ZAP. The official getting-started guidance uses these tabs as the confirmation that proxying is working.

Part 10: Understand passive scanning

Passive scanning happens while traffic passes through ZAP.

It analyses requests and responses without deliberately sending attack payloads. Passive rules can identify issues such as:

Missing security headers
Insecure cookies
Information disclosure
Cache-control weaknesses
Potential cross-domain configuration problems
Server version exposure
Mixed-content conditions
Weak browser-security configuration

Passive scanning is safer than active scanning because it examines existing traffic instead of attacking the application.

Open the Alerts tab after browsing several pages. You may already see findings created by the passive scanner. ZAP’s passive scanner examines HTTP and WebSocket messages that pass through or are sent by ZAP.

Part 11: Manually configure Firefox to use ZAP

Launching a browser from ZAP is the recommended method. Manual configuration is useful when you need:

Your existing browser profile
A specific browser extension
An existing authenticated session
A browser configuration ZAP cannot launch automatically

Step 1: Open Firefox settings

In Firefox, open:

Firefox → Settings

Step 2: Find Network Settings

Under the General section, scroll to:

Network Settings

Click:

Settings

Step 3: Select manual proxy configuration

Choose:

Manual proxy configuration

Enter:

HTTP Proxy: 127.0.0.1
Port: 8080

Configure HTTPS traffic to use the same proxy. Depending on the Firefox version, this may appear as:

Also use this proxy for HTTPS

or as a separate HTTPS Proxy field.

Use:

HTTPS Proxy: 127.0.0.1
Port: 8080

Step 4: Consider localhost testing

Some browser configurations bypass the proxy for localhost.

When testing a local application, check the field containing proxy exceptions. Remove localhost or 127.0.0.1 from the exception list when necessary.

ZAP’s documentation notes that newer Firefox versions may require the following preference to proxy localhost traffic:

network.proxy.allow_hijacking_localhost

Open:

about:config

Search for that preference and set it to:

true

Only change this setting in a dedicated testing profile.

Step 5: Save the settings

Click:

OK

Keep ZAP running whenever Firefox is configured to use it. Otherwise, Firefox will be unable to reach websites.

Part 12: Configure Chrome or Safari through macOS

Chrome and Safari can use the macOS network proxy settings.

Be aware that this method may affect other applications on your Mac, not just the browser. The ZAP-launched browser method is generally safer and easier.

Step 1: Open network settings

Open:

Apple menu → System Settings → Network

Step 2: Select your active connection

Select the network service currently in use, such as:

Wi-Fi

or:

Ethernet

Click:

Details

Step 3: Open Proxies

Select:

Proxies

Apple documents this path as System Settings, Network, the active network service, Details, and Proxies.

Step 4: Enable the HTTP proxy

Enable:

Web Proxy (HTTP)

Enter:

Server: 127.0.0.1
Port: 8080

Step 5: Enable the HTTPS proxy

Enable:

Secure Web Proxy (HTTPS)

Enter:

Server: 127.0.0.1
Port: 8080

Leave username and password empty because the local ZAP proxy does not normally require proxy authentication.

Step 6: Review the bypass list

When testing an application on localhost, make sure that the proxy bypass list does not contain:

localhost
127.0.0.1

Also consider disabling:

Exclude simple hostnames

during local testing.

Step 7: Save the configuration

Click:

OK

or:

Done

Keep ZAP running while these proxy settings are enabled.

Important: Disable the proxy when testing is finished

Return to the same Proxies screen and disable:

Web Proxy (HTTP)
Secure Web Proxy (HTTPS)

Otherwise, your Mac may appear to lose internet access after ZAP is closed.

Part 13: Configure HTTPS interception

HTTPS traffic is encrypted. To inspect it, ZAP generates temporary certificates for the sites being tested and signs them using its own Root CA certificate.

Browsers do not normally trust this private ZAP certificate. That is why a manually configured browser may display errors such as:

Your connection is not private

or:

Unknown issuer

Browsers launched directly from ZAP are configured to handle these certificate errors automatically. Manual certificate installation is needed only when you use your own browser profile or another HTTP client.

Part 14: Export the ZAP Root CA certificate

Step 1: Open ZAP options

In ZAP, open:

Tools → Options

Step 2: Open Server Certificates

Navigate to:

Network → Server Certificates

Step 3: Save the certificate

Click:

Save

Save the file with a clear name:

zap_root_ca.cer

Store it temporarily in:

Downloads

ZAP creates a unique Root CA certificate when it first runs. The certificate should only be installed in clients that you intentionally want to route through ZAP.

Part 15: Trust the ZAP certificate in macOS Keychain

This step allows Safari, Chrome, and other applications using the macOS certificate store to accept certificates generated by ZAP.

Step 1: Open Keychain Access

Press:

Command + Space

Search for:

Keychain Access

Open the application.

Step 2: Select the login keychain

In the left sidebar, select:

login

Using the login keychain limits the certificate to your macOS user account. The System keychain affects all users and usually requires administrator approval.

Step 3: Import the certificate

Drag the following file into Keychain Access:

zap_root_ca.cer

Alternatively, use:

File → Import Items

Apple officially supports adding certificates by selecting a login or System keychain and dragging the certificate into Keychain Access.

Step 4: Find the certificate

Search for:

ZAP Root CA

or:

Zed Attack Proxy Root CA

Step 5: Change the trust setting

Double-click the certificate.

Expand:

Trust

Change:

When using this certificate

to:

Always Trust

Close the certificate window.

Enter your macOS password or use Touch ID when requested. Apple allows certificate trust policies to be changed from the Trust section in Keychain Access.

Step 6: Restart the browser

Completely quit Chrome or Safari:

Command + Q

Then reopen it.

HTTPS pages passing through ZAP should now load without certificate warnings.

Part 16: Import the certificate directly into Firefox when needed

Modern Firefox versions can use third-party certificates installed in the macOS certificate store. However, if Firefox still displays certificate errors, import the certificate into Firefox directly.

Step 1: Open Firefox settings

Open:

Firefox → Settings

Step 2: Open Privacy & Security

Select:

Privacy & Security

Step 3: Find Certificates

Scroll to:

Certificates

Click:

View Certificates

Step 4: Open Authorities

Select:

Authorities

Click:

Import

Step 5: Select the certificate

Choose:

zap_root_ca.cer

When prompted, enable trust for identifying websites.

Click:

OK

Restart Firefox.

Part 17: Understand the certificate risk

Installing a private Root CA certificate is a sensitive security change.

Anyone possessing the corresponding private key could potentially create certificates trusted by your browser. The ZAP documentation warns that trusting a self-generated Root CA introduces an additional attack surface.

Use the following precautions:

Install the certificate only on a testing machine or testing account.
Prefer a dedicated browser profile.
Never share the ZAP certificate’s private key.
Do not install certificates received from unknown people.
Remove the certificate when it is no longer required.
Do not use a ZAP-testing browser profile for online banking or personal email.
Prefer ZAP’s automatically launched browser when possible.

To remove the certificate:

Open Keychain Access.
Search for ZAP Root CA.
Select the certificate.
Press Delete.
Confirm its removal.
Restart your browser.

Part 18: Add the target application to scope

Scope tells ZAP which application you are authorised to test.

This is particularly important when using Protected mode.

Step 1: Browse the application

Launch a browser from ZAP and open the target application.

Step 2: Locate it in the Sites tab

Return to ZAP.

Under the Sites tab, find the target domain.

Step 3: Create a context

Right-click the target site and select an option similar to:

Include in Context → New Context

Give the context a meaningful name:

Local Test Application

or:

Staging Customer Portal

Step 4: Mark the site as in scope

Right-click the site and select:

Include in Scope

A scope indicator should appear beside the site.

Step 5: Confirm Protected mode

Check that ZAP remains in:

Protected Mode

ZAP should now allow dangerous operations only against the authorised in-scope application.

Be careful when the target page loads resources from third-party domains such as analytics platforms, CDNs, payment providers, or social-media services. Do not add those external domains to scope unless you are specifically authorised to test them.

Part 19: Perform your first passive security assessment

A beginner should start with passive testing before running an active scan.

Step 1: Launch the target through ZAP

Open:

Quick Start → Manual Explore

Enter your authorised application URL and launch a browser.

Step 2: Explore every authorised feature

Navigate through the application manually.

For authenticated testing:

Open the login page.
Sign in using a dedicated test account.
Visit all permitted application sections.
Submit authorised forms.
Use search and filtering functions.
Open profile and account settings.
Perform ordinary test transactions.
Log out.

Avoid using real production customer data.

Step 3: Wait for passive scanning

Return to ZAP and allow the passive-scan queue to complete.

You can usually see scanning activity in the status area.

Step 4: Review the Alerts tab

Expand the Alerts tree and inspect each finding.

A typical alert contains:

Alert name
Risk level
Confidence level
Affected URL
Parameter
Evidence
Description
Recommended solution
Reference material

Treat scanner findings as leads requiring validation. An automated tool may produce false positives, and it may miss vulnerabilities based on application logic or business rules.

Part 20: Run your first authorised automated scan

An automated scan normally combines application discovery with active security testing.

Only continue against an authorised test target.

Step 1: Open Automated Scan

In ZAP, select:

Quick Start → Automated Scan

Step 2: Enter the target URL

For example:

http://localhost:3000

or an authorised staging URL.

Double-check the hostname before continuing.

Step 3: Select the spider

ZAP may offer:

Traditional Spider
Client Spider
AJAX Spider
Automatic selection

The Traditional Spider is fast and discovers links from conventional HTML.

A modern browser-driven spider is more appropriate for applications that depend heavily on JavaScript. ZAP’s Quick Start documentation explains that a modern spider launches a browser and interacts with links, while the traditional spider cannot fully handle JavaScript-heavy applications.

For a conventional server-rendered website, start with:

Traditional Spider

For a React, Angular, Vue, or other single-page application, use a modern spider such as:

Client Spider

Using both can improve application coverage.

Step 4: Verify the scan policy

For the first scan, use a standard or default scan policy.

Do not immediately increase every rule to maximum strength. Stronger settings generate more requests, take longer, and may place more load on the application.

Step 5: Start the scan

Click:

Attack

ZAP will begin:

Discovering application pages and endpoints
Sending active test requests
Analysing responses
Recording potential vulnerabilities

Step 6: Monitor the scan

Watch the following tabs:

Spider
Active Scan
Sites
History
Alerts

You can stop the scan when:

You selected the wrong target
The application becomes unstable
The server experiences excessive load
Unexpected data changes occur
You discover that the scope is incorrect

Part 21: Review the findings correctly

ZAP findings are commonly grouped by risk level.

High risk

Potentially serious vulnerabilities requiring urgent investigation.

Examples may include:

SQL injection
Remote code execution conditions
Serious authentication weaknesses
High-impact cross-site scripting

Medium risk

Important security weaknesses that should be investigated and remediated.

Low risk

Lower-impact weaknesses or defence-in-depth opportunities.

Informational

Observations that may not represent direct vulnerabilities but can provide useful security context.

Confidence level

Risk and confidence are different.

Risk estimates potential impact.
Confidence indicates how certain ZAP is that the issue exists.

A High-risk finding with Low confidence needs careful manual verification. An Informational alert with High confidence may be accurate but have limited direct impact.

Do not send a raw ZAP report to developers without reviewing it. Validate each important finding and add:

Reproduction steps
Screenshots
Affected parameter
Request and response evidence
Business impact
Recommended remediation
Verification after the fix

Automated active scanning cannot discover every vulnerability, particularly business-logic and some access-control weaknesses. Manual security testing remains necessary.

Part 22: Generate a ZAP security report

ZAP can generate reports in formats including HTML, JSON, Markdown, XML, and PDF, depending on the installed report templates.

Step 1: Open the report generator

Open:

Report → Generate Report

Step 2: Enter the report title

For example:

Customer Portal Security Assessment

Step 3: Enter a report filename

For example:

customer-portal-zap-report.html

Step 4: Select the report directory

Choose a folder such as:

Documents/Security-Reports

Step 5: Select the target

Under Sites or Contexts, select only the application you tested.

This prevents unrelated traffic from appearing in the report.

Step 6: Select a template

For beginners, choose an HTML report such as:

Risk and Confidence HTML

or:

Traditional HTML

HTML is normally easier to review than raw JSON or XML.

Step 7: Choose included risks

Include:

High
Medium
Low
Informational

For an executive report, you may later create a separate version containing only High and Medium findings.

Step 8: Generate the report

Click:

Generate Report

Open the resulting file in your browser and review it before sharing.

Reports can contain sensitive information, including:

Internal URLs
Request parameters
Session information
Application paths
Vulnerability evidence
Portions of HTTP responses

Store reports securely and share them only with authorised recipients.

Part 23: Save and reopen your ZAP session

If you did not persist the session when ZAP started, you can save it later.

Open:

File → Persist Session

Choose a secure location and meaningful name.

Once a session is persisted, ZAP continually records subsequent changes. You do not need to repeatedly click Save.

To open an existing session later, use the appropriate Open Session option from the File menu.

Avoid saving sensitive testing sessions in cloud-synchronised folders unless your organisation permits it.

Part 24: Optional Homebrew installation

Users comfortable with Terminal can install ZAP using Homebrew.

When Homebrew is already installed, run:

brew install --cask zap

Launch ZAP with:

open -a ZAP

Check the installed cask information:

brew info --cask zap

Upgrade it with:

brew upgrade --cask zap

Remove it with:

brew uninstall --cask zap

The ZAP download page currently lists Homebrew Cask as a macOS installation option. However, as of 26 July 2026, the Homebrew package page marks the ZAP cask as deprecated with a scheduled disable date of 1 September 2026. For a guide intended to remain usable beyond that date, the official ZAP macOS installer is the safer primary method.

Part 25: Start ZAP from Terminal

When ZAP is installed under Applications, its command-line script can be run from:

/Applications/ZAP.app/Contents/Java/zap.sh

Start the normal desktop interface:

/Applications/ZAP.app/Contents/Java/zap.sh

Display the help:

/Applications/ZAP.app/Contents/Java/zap.sh -help

Display support information:

/Applications/ZAP.app/Contents/Java/zap.sh -suppinfo

Update installed add-ons:

/Applications/ZAP.app/Contents/Java/zap.sh -addonupdate

The official documentation identifies this script as the command-line entry point for a ZAP application installed in /Applications.

Part 26: Troubleshoot common problems

Problem 1: ZAP does not open

Possible solution

Open:

System Settings → Privacy & Security

Find the blocked application message and click:

Open Anyway

Verify that you downloaded the correct Apple Silicon or Intel installer.

Problem 2: Browser launched from ZAP cannot be found

Possible causes

Chrome or Firefox is not installed.
Selenium add-ons are missing.
The macOS WebDrivers add-on is missing.
Browser or WebDriver versions are incompatible.
ZAP add-ons are outdated.

Solution

Open:

Tools → Manage Add-ons

Install or update:

Selenium
macOS WebDrivers
Client Side Integration

Restart ZAP and try again.

ZAP’s macOS WebDrivers add-on provides browser drivers used for supported Chrome and Firefox browser automation.

Problem 3: The browser has no internet connection

Check the following:

Is ZAP running?
Is ZAP listening on port 8080?
Does the browser use 127.0.0.1:8080?
Is another application already using port 8080?
Did you close ZAP while macOS proxy settings remained enabled?

When testing is complete, disable the manually configured HTTP and HTTPS proxies.

Problem 4: Nothing appears in Sites or History

Check that:

You launched the browser from ZAP.
The manually configured browser uses the correct proxy.
The ZAP proxy port matches the browser proxy port.
The target application is running.
The browser is not bypassing localhost.
A VPN, security agent, or corporate proxy is not overriding the settings.

When browser traffic is routed correctly, requests should appear in both Sites and History.

Problem 5: HTTPS pages show certificate errors

Use one of these solutions:

Launch the browser directly from ZAP.
Export and trust the ZAP Root CA in Keychain Access.
Import the Root CA directly into Firefox.
Restart the browser after installing the certificate.
Regenerate an expired ZAP Root CA certificate.

ZAP-generated Root CA certificates are valid for a limited period and may eventually need to be regenerated.

Problem 6: Localhost traffic is not captured

For Firefox, check:

network.proxy.allow_hijacking_localhost

Set it to:

true

For macOS system proxies:

Remove localhost from the bypass list.
Remove 127.0.0.1 from the bypass list.
Disable Exclude Simple Hostnames if necessary.

The safest alternative is to launch the browser directly through ZAP.

Problem 7: Port 8080 is already in use

Check which process uses the port:

lsof -i :8080

Either stop the conflicting application or change ZAP to another port, such as:

Then update the browser proxy to use the same new port.

Problem 8: ZAP is using too much memory

Large applications, long testing sessions, modern browser spiders, and active scans can use significant memory.

Try the following:

Close unnecessary browser tabs.
Test one application at a time.
Reduce active-scan concurrency.
Avoid installing unnecessary add-ons.
Start a fresh ZAP session.
Scan a smaller application scope.
Exclude static resources where appropriate.
Close other memory-intensive applications.

Recommended beginner configuration

The following settings provide a practical and relatively safe starting point:

ZAP version: Latest stable release
Installation: Official macOS installer
Mode: Protected
Proxy address: localhost
Proxy port: 8080
Browser method: Launch from ZAP
Certificate installation: Not required for ZAP-launched browser
Initial testing: Passive scan
Active scan: Authorised test environments only
Spider: Traditional plus Client Spider for modern applications
Reports: HTML
Sessions: Persist for real assessments

Beginner workflow summary

Use this sequence whenever you begin a new authorised assessment:

1. Start ZAP.
2. Persist the session when results must be saved.
3. Update ZAP add-ons.
4. Select Protected mode.
5. Launch a browser from Quick Start.
6. Open the authorised target application.
7. Add the application to scope.
8. Browse all permitted application functions.
9. Review passive alerts.
10. Run a spider if additional discovery is needed.
11. Run an active scan only with permission.
12. Validate important findings manually.
13. Generate an HTML report.
14. Save the session.
15. Close the testing browser.
16. Remove manual proxy settings when used.
17. Remove the Root CA when it is no longer needed.

Final thoughts

Installing ZAP on macOS is straightforward, but using it safely requires understanding three important concepts:

The browser must send its traffic through ZAP.
HTTPS inspection requires temporary certificate trust.
Active scanning must be limited to authorised systems.

For beginners, the best approach is to install the official stable macOS release, select Protected mode, and use the browser-launch function under Quick Start. This automatically configures the browser proxy and certificate handling, avoiding most common setup problems.

After confirming that requests appear in the Sites and History tabs, begin with passive scanning. Move to spiders and active scanning only after establishing the correct scope and confirming that the target is a dedicated, authorised testing environment.

ZAP is powerful enough for experienced penetration testers, yet its Quick Start workflow makes it accessible to developers, testers, DevOps engineers, and security newcomers. With the configuration in this guide, you will have a safe foundation for learning web application security testing on macOS.

rajeshkumar