Thursday, 20 March 2014

Hacking ZAP #2 - Getting Started

Welcome to a series of blog posts aimed at helping you “hack the ZAP source code”.
The previous post in this series is: Hacking ZAP #1 - Why should you?

In order to change the ZAP source code you will need to set up a development environment.

We provide a full Eclipse workspace that is updated very regularly and is available to download from:

However its worth understanding how the ZAP projects are structured, especially if you would like to use an alternative IDE.

Project structure

There are currently 2 main ZAP code projects, both one has been migrated to GitHub while the other is still on Google code (but will be migrated), and ongoing development takes place both on the trunks and in branches: 

There are more branches than shown, but you typically won’t need to use any of them.

As Google Code is closing down we are in the process of migrating to GitHub. This blog post will be updated to reflect any relevant changes.

There is also a zaproxy-test project, however the main part of the project contained unit tests which have now been migrated to a separate test folder within the other projects.

Setting up your IDE

If you choose not to use the Eclipse workspace then you can set up your IDE as follows:
  1. Import all of the projects you need, e.g.
  2. For each project, add all of the jars in the ‘lib’ directory to the classpath
You should update these projects at regular intervals in order to pick up the latest changes.

To run ZAP run

Each project also has a main Ant build file, build/build.xml, which we will examine in more detail later in the series.

There is more information about building ZAP on the
ZAP wiki
Note that if you just want to get going as quickly as possible you can just import the zaproxy trunk for core changes and/or the zap-extensions alpha branch for creating a new add-on.

The ZAP core

The zaproxy project is often called “the core”.

It has 2 main high level packages within the src folder:

  • org/parosproxy          The code inherited from the Paros project
  • org/zaproxy               New ZAP code
Other directories of note:
  • src/help                     The main ZAP help files
  • build                           Build related files
  • lib                              The jars ZAP relies on
  • test                            ZAP unit tests

We try to implement significant new features in the zap-extensions project as ‘add-ons’.

We do this for the following reasons:
  1. Core changes can only be delivered via ‘full’ ZAP releases. We typically only do these a few times a year.
  2. Add-ons can be released and updated as frequently as required. Users can dynamically install and update add-ons, often without having to even restart ZAP.
  3. Add-ons progress from alpha through beta to release, allowing users to understand how robust an add-on is likely to be. This allows developers to release early without worrying about breaking ZAP for everyone.
  4. Add-ons can still be included in ‘full’ ZAP releases - the WebSockets and Ajax Spider are 2 add-ons that we include by default.

Having said that, you may well find that changes you want to make can only be made in the core.
That is not a problem - you can make changes to the core - but these changes will probably not be available to users as quickly as those made to add-ons.

We also add new functionality to the core if we want it to be available for other add-ons to build on.

Its important to note that if you make changes to code in the Paros package then you must include a comment at the top of the file mentioning your change. This is required to satisfy the
Clarified Artistic License that Paros was released under.
We have a standard format for these comments
// ZAP: yyyy/mm/dd Issue xyz: Description of the changes
eg see

If you make changes to the core then you typically just need to make them to the trunk.
There is a branch for every release. If your change fixes a significant issue then we may also want to apply it to the latest release branch. But you dont need to worry about that.

Add-ons, Extensions and Rules

There are many ways to extend ZAP programmatically.
Some of the main ways include:

  • Extensions, which are classes that extend the class. They are a powerful way of adding functionality to ZAP, and much of the ‘core’ is actually implemented as extensions.
  • Active Scan rules, which are classes which extend, detect potential vulnerabilities and run as part of the Active Scanner. These rules typically make multiple requests on the target system. They only run when explicitly invoked by the user.
  • Passive Scan rules, which are classes which extend, detect potential vulnerabilities and run as part of the Passive Scanner. These rules cannot make any requests - all they can do is examine the requests and responses. They are typically invoked for every request that is proxied through ZAP.
Add-ons are packages which can include all of these components as well as ‘raw’ files. They are usually available on the ZAP Marketplace so that users can discover, download and install them from within ZAP. You can also install add-ons from your filestore via the “File / Load Add-on file…” menu.

New add-ons should be created in the alpha branch and only move to the beta and then release branches after they have been reviewed.

You can also create add-ons in your own repositories. If they are open source then they will still be eligible to be uploaded to the ZAP Marketplace, but it might take slightly longer to review them.

We will cover all of these components (and more) in more detail in a future posts.

If you have any questions about ZAP development then please ask them on the
ZAP Developer group.

The next post in this series is: Hacking ZAP #3: Passive scan rules


  1. This is great :) One thing that would help the paranoid among us would be a SHA1 hash for the latest version of ZAP and for the latest Eclipse workspace download. Just to keep with good security practices and so on.

    1. I stand corrected, there is hash info, you just have to click the "i" (info) button on the SF download site. Thanks for a great tool.

  2. So I just started getting things setup for this earlier today.

    Encountered a few hiccups.

    1) Gotta install JDK....
    2) Gotta make eclipse work. First gotta make sure eclipse is using the right JVM [set -vm in eclipse.ini .... figure out that -vm and the value go on separate lines :( ]
    Then had to install JDK/JRE 64 along with my existing 32 to get it working :( (64bit OS, eclipse DL was 32/64...).
    3) Workspace is gigantic, 1GB download as a zip, handled kind of poorly by Win7 integrated ZIP handler. At 1.1GB with almost a 100,000 files it takes forever for the ZIP "folder" to open, and almost an hour to extract (decent i5 based laptop with 8GB RAM).

    1. ZAP _is_ a big project :/
      Suggestions on a postcard (or comment, of ZAP dev group post..)

  3. Wasn't meant as a complaint or anything, just wanted to post the info in-case it might help someone else.

    As I get start with this being someone who hasn't coded in a number of years and hasn't worked on an OpenSource project it's becoming clear to me that I should aggregate all this info into a single spot. I'll probably end up doing a kind of "Total Newb" guide on my blog at some point.

  4. This comment has been removed by a blog administrator.

  5. stupid question but why did you not maven to build this ?

  6. stupid question but why did you not maven to build this ?

    1. Because when I started ZAP in 2010 I was much more familiar with Ant ;)
      We are looking to update our build route very soon.