Twelve Days of ZAPmas - Day 1 - Setting Up ZAP

Twelve Days of ZAPmas - Day 1 - Setting Up ZAP
Mic Whitehorn
Author: Mic Whitehorn

This holiday season, I’m going to run down some of the ins and outs of working with OWASP Zed Attack Proxy (ZAP). I came at this having barely touched ZAP, before, but having used Burp Suite as my daily driver for years as a penetration tester. This gives me a relatively fresh eye on ZAP, and I will focus on what’s important to the developer trying to reproduce a reported flaw or the QA specialized trying to work some additional security in their game. For twelve days, I will have a daily topic, provide bite-sized tutorials, tips, and examples. But first, let me address an important duo of questions:

What is OWASP ZAP, and what can it do for me?

ZAP is an interception proxy, a tool that passes traffic in between an HTTP client application (e.g. browser, mobile app) and the server(s) it interacts with. The traffic it handles is similar to what you would see in the Network tab of your browser’s built-in dev tools, but ZAP provides richer tooling for tampering with and replaying the traffic in ways that are useful for discovering and proving exploitability of flaws in applications and web services. It also has tools to help discover flaws, such as automated crawling and traffic analysis facilities.

OWASP Zed Attack Proxy is available at

An important note about permission

One of the most prominent experts on physical security, known by the pseudonym Deviant Ollam, has written a book called Practical Lock Picking. This book has a section on Ethical Considerations prepended to the first chapter. In short, the rules concluded in that section are:

  1. Don’t pick locks you do not own.
  2. Don’t pick locks on which you rely.

The same approximate guidance applies to using ZAP to mess with applications. Sending malformed, modified, or manipulated traffic to a server is attacking the server. This can have unexpected and catastrophic consequences, and is a crime if done without permission from the individual(s) or organization(s) who own the application software and the infrastructure it’s running on.

Being hired to develop an app doesn’t grant you the permission to attack it either, so if you want to test an app you’ve been developing at work, be sure to follow any existing guidance, and to obtain buy-in and permission from the application and infrastructure owners. Choose a non-production environment, and make sure stakeholders are aware of when you’re going to be testing. 

The best option is to play around with ZAP on your own personal machine against a target application designed for security labs or learning. This fulfills Deviant’s rules above: 

  1. You own it, it’s open source software running on your own machine.
  2. You don’t rely on it, your instance of the app doesn’t have real users, if you put it into a broken state it’s no big deal.

My examples primarily use Wayfarer, which is available at Wayfarer is a vulnerable single-page app and API that was created for SamuraiWTF, the open-source Linux-based training lab that we use for many of our training classes. The OWASP Juice Shop app is another popular target app which has some simple options to run locally with Docker or Vagrant. It is available at:

Day 1 - Proxying HTTP and HTTPS Traffic

The thing about an interception proxy is that it’s kind of useless if you can’t intercept the traffic. So Day 1’s tutorial is a necessary step to address that. It’s probably the least interesting topic of the series, but it’s a crucial step.

The Easy Way

Step 1 - Launch Zap

No surprise here, we have to launch the app if we’re going to use the app. We’re quickly met with the following dialog asking about persisting our session.  Either of the persistence options should work if you want to be able to come back to the project, but since I’m just playing around, I’m going to choose No, I do not want to persist this session at this moment in time.

owasp zap

Step 2 - Choose Manual Explore

In case you happen to be navigated away, this is in the middle of the Quick Start tab.

ZAP quick-start screen with the Manual Explore button highlighted.

Step 3 - Choose a target and launch your browser

Enter a URL to explore, in my picture I have localhost:3000 for a local app I’m testing.  Obviously you would use the url for your target application.  

Enable HUD should be unchecked for now. We’ll look at that piece in a few days, but for now we’ll look without it.

Choose a browser on your system, and launch it with the Launch Browser button.  If this doesn’t work for you, checkout the Manual Setup method below.Manual Explore option in ZAP's quick-start screen, with URL to explore set to http://localhost:3000, Enable HUD unchecked, and the Launch Browser button highlighted.

Step 4 - Navigate Around the App

As you browse, you’ll see the History pane at the bottom being populated with your traffic. You might recognize this as the same sort of data you get in the Network tab of your browser’s dev tools.  You can expect to also see some noise from the browser interacting with services such as

ZAP history tab showing a list of request traffic.

Step 5 - Take a closer look

If you select a request from the History tab, the main pane will show the Request and Response in those respective tabs.

Screenshot from ZAP cropped to the Response panel.

Manual Setup

There are a few reasons The Easy Way might not work for you. Maybe you want to use a browser that ZAP didn’t detect or won’t launch, for example some of my browsers generated the pop-up below.

Pop-up warning saying The provided browser was not found.

It’s not terribly difficult to manually setup a browser to proxy, but there is a caveat, ZAP won’t be able to setup the certificate trust, so you will need to do that yourself or else you will get TLS certificate errors for HTTPS traffic.

Step 1 - Launch Zap

Again, the persistence option doesn’t matter.

Note what port your proxy is listening on. Mine was on 8081, indicated by the text in the footer of the window.

Main ZAP window showing the Main Proxy indicated in the information bar at the bottom of the window.

Step 2 - Open your Browser

I’m going to narrow the focus here to Chrome and Firefox. If for some reason you have to use Safari, IE, or a non-Chromium version of Edge, setting the proxy will be a little more difficult, so we’ll skip them at least for the moment.

FoxyProxy Standard is a free extension available for both Chrome and Firefox in their respective extension stores. I recommend it, as it makes it easy to toggle the proxy on and off, and even limit its scope to certain URLs. I’m going to use it in the setup process here.

Foxy Proxy Standard for Chrome

Note: Chrome doesn’t respect the proxy setting for apps on localhost. This can be solved by adding an entry to your hosts file.

Foxy Proxy Standard for Firefox

Step 3 - Configure your proxy

In your browser, open the options for the Foxy Proxy extension

Screenshot of Chrome with the FoxyProxy extension menu open and the Options menu item indicated.

The next part looks a little depending on whether you have the Chrome version or the Firefox version, but the principle is the same. You want Add a proxy (configuration) or select and edit the default one if there is one.


FoxyProxy options in Chrome with the Default entry indicated and the Edit Selection menu option indicated.


FoxyProxy options in Firefox highlighting the Add button.

Set your proxy Host or IP to, with the Port set to whatever port Zap is listening on (from Step 1), mine was 8081, your could be 8080 or something different.


FoxyProxy settings in Chrome showing Manual Proxy Configuration selected with the IP address set to and the port set to 8081.



Configuration form in Foxy Proxy for Firefox with the Proxy Type defaulted to HTTP, the IP address set to, and the Port set to 8081.

Save your configuration and close the Foxy Proxy settings.

Then click the extension icon in the browser toolbar and select the Proxy you created.

Firefox menu bar with the Foxy Proxy extension icon opened to highlight selecting the item for port 8081.

The icon will change to indicate your proxy is selected. e.g. Close-up image of the extension icon for foxy proxy in Firefox. or Close-up image of the extension icon for foxy proxy in Chrome.

Now you should be able to browse to anything available over HTTP, and see the traffic collected in the History tab of ZAP. But if you go to a TLS protected site (i.e. most sites today), the browser will complain, as shown here:


Firefox browser window navigated to localhost port 3005, showing an SSL certificate trust issue.


Step 4 - Add the CA Certificate Trust

The background on this step is that, in order to inspect the TLS encrypted traffic, ZAP is essentially taking one connection (Browser -> Server) and separating it into two separate TLS connections (Browser -> Zap -> Server). As a result, when ZAP passes a response to your browser, it’s having to re-encrypt it with its own CA cert. This is also a generated certificate that’s unique to your installation of ZAP, so you are trusting your own CA Cert that only you have. My instance of ZAP will generate a different cert that is uniquely mine. With that in mind…

First navigate the browser that’s proxying to http://zap, this will open a special webpage served by the proxy itself, so that you can easily download your CA certificate (.cer file).

Zed Attack Proxy webpage with a link to download the CA certificate.

Next, open the certificate management interface in the browser’s settings.

Manage Device Certificates in Chrome

Open settings

Chrome main menu with the item for Settings highlighted.

Use the search bar to search for cert, which will highlight the Security section of the settings. Open that.

Chrome settings filtered to highlight the entry for Security under the Privacy and security group.

Scroll down to Manage device certificates (it’s near the bottom the Security settings)


Chrome security settings with the entry highlighted for "Manage device certificates."


And select it.

What this does will vary depending on your operating system. On many mainstream Linux distros, it will bring up a certificate management interface within the browser. On Windows, it will open the system certificate manager.

Whichever app it is, the goal is to import your .cer file as a certificate authority. In Keychain, it’s under the File menu, Import Items. You will see the OWASP Zed Attack Proxy Root CA in the list once it’s successful.


Keychain certificates list showing an untrusted indicator icon next to OWASP Zed Attack Proxy Root CA.

If you notice the red X icon on it, that certificate is not yet trusted. Windows and Linux work the same, in that trusting the cert is an additional step.

In Keychain, I double-click it and it pops up a dialog, and I can set it to Always Trust for SSL.

Certificate trust dialog with the select box next to Secure Sockets Layer (SSL) set to "Always Trust".

When I close the dialog, I get prompted for the elevated permissions to make the change, and then it shows as trusted.

Keychain certificate list entry showing a Trusted icon next to OWASP Zed Attack Proxy Root CA.

Certificate Manager in Firefox

Open the menu and go to Settings

Firefox main menu with the Settings item highlighted.

Search for cert and select View Certificates… from the Certificates result.

Settings window showing a search for the word "cert" filtering the list to reveal the View Certificates button under the Certificates entry.

This brings up Firefox’s built-in Certificate Manager, which has an Import button. Click that.

Firefox's built-in certificate manager window with location of Import button highlighted.

Using the file dialog, select your .cer to import.  This opens a new dialog to set the trust.

Pop-up dialog asking: "Do you want to trust OWASP Zed Attack Proxy Root CA for the following purposes?" with checkboxes for "identify websites" and "identify email users".

Once that’s done, I can find an entry in the list under OWASP Root CA.

OWASP Zed Attack Proxy Root CA appearing in trusted certificates list.

Step 5 - Verify that it’s working

Browse to an HTTPS site to capture some traffic, to validate that it’s working. You should see traffic populated in the History pane, and you can select entries to view the request and response.

Zed Attack Proxy desktop app cropped the Response tab.

In Summary…

Just about everything you would manually do within ZAP is dependent on getting requests into the application, and this is the primary way of doing it. While it’s not very interesting on its own, it’s a building block.

Check out Day 2 for an introduction to Replaying and Tampering with ZAP.

Join the professionally evil newsletter