Java Client-API Example

[Patrick Smith]

Hopefully this will be helpful to someone looking to get started with automated testing with ZAP.

Take note that I am not a Java developer and this is a super-simple example. Any criticism is definitely welcome as is tips and recommendations on how to use the ZAP API better (please read my caveats at the end as well).

Purpose:

We have two web applications; one is vulnerable for cross-site scripting, the other is not. Other than the vulnerability, these two apps are identical and very simple. They contain 2 scripts: index.pl and submit.pl. The index.pl script contains a form with one text field and a submit button. That form posts to submit.pl. The vulnerable app, prints the submission on the page, and the secure one just prints out that the user submitted something. In my environment, I have these two test apps running on localhost:8888.

I want to automate the vulnerability testing of these 2 applications via the Java API-Client. Here is what my example Java Program accomplishes:

1. Open ZAP

2. Start a session in ZAP that listens on port 8091

3. Use Selenium to click-through the web app while ZAP is listening

4. Spider the web app

5. Preform an Active Scan on the web app

6. Get all the vulnerability errors/warnings that ZAP has found

7. Save the ZAP session so it can be manually opened later for further actions if needed (e.g. fuzzing parameters, exporting built-in ZAP reports, etc...)

My Environment:

Windows 7 - 64 bit
Eclipse - Kepler

XAMPP - target application running on localhost via port 8888

- of course you can use any server you want, but if you use localhost be sure that this port is different from the port that ZAP listens on or you will get errors

ZAP 2.2.1 - listening on locaolhost on port 8091

- you can get the API here: https://code.google.com/p/zaproxy/downloads/detail?name=zap-api-v2-4.jar&can=2

- again, you can use any port you want here but be sure that this port is different from the port localhost is running on if applicable

Chrome

- I use chrome for this example. There is a down-side to using Chrome: you have to manually set the proxy. I believe I saw that if you're using the IE driver, you can programmatically set the proxy.

- ensure that the proxy is set to the same on that ZAP listens on (8091 in this case)

Selenium

- You can get the Selenium API for Java here: http://docs.seleniumhq.org/download/

- you can get the Chrome Driver here: https://code.google.com/p/chromedriver/downloads/detail?name=chromedriver_win32_2.3.zip&can=2

Note: You do not need to have this exact set up, it's just a point of reference

Instructions:

These 'instructions' are top-level. I am assuming you already have an understanding of Eclipse, Java, Proxies, etc...

1.

- Ensure you have Google Chrome, Java, and Eclipse

2.

- Open ZAP and configure the port that you want to proxy with on localhost. (Tools -> Options... -> Local Proxy)

- Close ZAP

3.

- Download the target app folder that I have attached. I am using perl, you can use whatever you want.

- Before you continue, make sure that you can open a browser and run the target apps manually and submit the forms.

- Here is what it looks like in my browser:

- if you are using localhost to run the target apps as I am, be sure that you are using a different port for this than ZAP is using from Step 2 above. In my case, I'm running localhost on port 8888.

4.
- Download the attached class files and import them into your Java project in Eclipse.
- Ensure you have the API jar files for Selenium and ZAP in your build path. If they are not, you will see a ton of errors in Eclipse.

5.
- Open up ZapTools.java and change the String value on line 18 to match your ZAP install directory (mine is C:/Program Files (x86)/OWASP/Zed Attack Proxy/).
- Change line 19 as well to the location that you want to save your ZAP Session to (I'm just saving it in the projects base directory in a folder called ZapSessions).
- Save your changes to ZapTools.java

6.
- Open up SeleniumTools.java and change line 13 to the location of your ChromeDriver executable
- Save your changes if necessary

7.
- SecureTest.java and VulnerableTest.java are the same other than the variables on lines 10-15 and the session file name on line 65. You will need to change these to your configuration if:
--- you are not running localhost on port 8888 from the cgi-bin directory using perl
--- you are not using proxy on port 8091

8.
- Configure your Internet Options to proxy through localhost on port 8091 (or whatever port you chose to proxy with)
- Right click on either SecureTest.java and VulnerableTest.java and select Run As... --> Java Application
- you should follow along in the console to see details but more noticeably you should notice ZAP open up, followed by Chrome.

9.
- Once the form is automatically submitted, the spider will begin. This may take a minute or two to complete.
- When the spider completes, the Active Scan will start. Be patient as this may take some time as well (you may think the status is stuck at 0 - just be patient).
- When the Active Scan is done, the alerts/warnings ZAP found will print out in the console in Eclipse.
- The session will then be saved and Chrome and ZAP will close and the program will finish.

Caveats:

I do not know how to use the ApiResponse Object for the ZAP API. You will notice some kludges in my code to determine whether the spider and scan is complete or not. If you have example code for working with the ApiResponse, please share :)

I am not creating a context for ZAP yet - in other words, if you have programs using the internet running on your machine while this is executing, the scan will pick run on those too (i.e. Google Talk, Outlook, etc...). I need to implement a way to only include a target URL regexp into the session context. Again, if you have example code of this, please share!

The URLs are very finicky when performing different functions such as Spider and Active scan. I think that's because I'm running against apps on port 8888 as opposed to 80 or 443. This is why I have ZAP_HOSTNAME, ZAP_URI, and ZAP_URI_PORT. I originally thought these should just all be "http://localhost:8888", but received errors from the ZAP API until I tweaked them to what they are now.

[Mostafa]

Hi Patrik,
Many many thanks for your generosity to share your work. I will post mine as soon as I figure out how to work with ApiResponse object. But meanwhile, have you noticed that if your web app (eg. DVWA) has a login page the scanner can not find any serious vulnerability despite the fact that the spider had crowled the pages within your web app? Unless you brows the pages of the web app manually.
Can you think of any work around here? I'd be glad to know that.

[psiinon]

Hey Patrick,

This is really great - thanks for sharing it!
The API and CI integration definitely needs better documentation and this will really help.
I'm going to try to improve the docs on the wiki but the more input from everyone the better!

So it would be great to hear from more of you:

• What did you need to do to get things working?
  
• Where did you have problems?
  
• What isnt documented well enough?
  
• What havnt you been able to do that you want to?
• Any other comments and suggestions?
  

Many thanks,

Simon