Debugging and Developing ZAP Scripts with your IDE (Groovy)

[Dennis Kniep]

I was wondering how we can make script development in Zap more convenient and easy. 

IMHO I miss my IDE :). I would like to have the features from my IDE like searching for classes or symbols, types safety autocompletion, decompilation, debugging etc.

I wrote a new plugin with script support for the groovy language and a small walkthrough how you can debug and develop your Zap Scripts within your IDE.

Benefits

When you develop scripts for ZAP with the new feature you have all the benefits and convenient from your favorite IDE <3. And all that without checking out any of the Zap Repositories.

* IDE Debugger (Step also into the ZapFramework classes!)

* IDE Autocompletion

* IDE Search (For Classes, Symbols etc.) in JavaFramework and ZapFramework

* etc.

Demo-Video

https://drive.google.com/file/d/1xJXY-GiEhH_T_wGJN8Go0CutOUkoR3sC/view?usp=sharing

Walkthrough

1. Launch Zap with remote debugger

Launch Zap with the enabled remote debugger.

java -XX:+UseG1GC -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=127.0.0.1:1044 -jar zap-dev.jar 

I already changed the run.sh script in zapproxy to use the argument -d for that behaviour. (https://github.com/zaproxy/zaproxy/pull/4498)

Unfortunately the new run.sh will not be there until Release 2.8 is released.

2. Install Groovy (Alpha) Plugin into ZAP

You must install the new Groovy Plugin. 

Normally you can get that from the Zap-Marketplace. But if it isn't already on the Zap-Marketplace you must compile it 

from the repository (link https://github.com/zaproxy/zap-extensions/pull/1480). Or use this Download https://drive.google.com/file/d/11b0_ByXTjm64rArgeAZDW3_u6mzjgLVb/view.

3. IDE

I will use IntelliJ for that walkthrough, but I think it should work also with other IDEs (Eclipse etc.)

4. Configure Workspace

File > Open 

Choose ~/.ZAP_D/scripts/scripts or an other directory where your scripts are.

5. Run Configuration

Run > Edit Configurations

Add (green plus) > Remote

Change Name to i.e. "ZAP Remote" and Port to 1044.

6. SteppingInto config 

These settings prevents that the Debugger steps into and through the whole Groovy Framework code

File > Settings > Build,Execution,Deployment > Debugger > Stepping

Add following entries to the listbox under "Do not step into classes"

org.codehaus.groovy.*

groovy.lang.*

groovyjarjarasm.asm.*

7. Adding SDK and Libs

File > Project Structure > Project

Set ProjectSDK to Java 1.8

File > Project Structure > Modules

Click on the module "scripts" and then click on tab Dependencies and Add (green plus)

Click "Jars and Directories" and choose $ZAP_INSTALL_PATH/zap-*.jar

If you want to use also Zap-Plugins in your scripts you must add the *.zap packages as libraries.

Then add the Groovy SDK by clicking Add (green plus)

Then choose the Groovy SDK from the list.

If its not configured in intelliJ follow these instructions: https://www.bonusbits.com/wiki/HowTo:Add_Groovy_SDK_to_IntelliJ_IDEA

8. Add Groovy-Scripts to ZAP from Templates

Now we add groovy scripts to Zap from existing templates delivered by the Zap Groovy Plugin

Open the Scripts Tab in Zap

And add the followng Groovy Standalone Script from the templates and rename them to

* Debug_wrapper.groovy -> debugStandalone

* Standalone_default_template.groovy -> defaultStandalone

* Loop_through_history_table.groovy -> loopy

And add the followng Groovy Targeted Script from the templates and rename them to

* Targeted_debug_wrapper.groovy -> debugTargeted

* Targeted_default_template.groovy -> defaultTargeted

Save all newly created Scripts.

9. Start Run Configuration

Start the Run Configuration in IntellJ

Run > Debug 'ZAP Remote'

10. Set Breakpoint

Open the script "loopy.groovy" in IntelliJ.

Set the Breakpoint where you want.

11. Run Script in Zap

Go to the Scripts-Tab in Zap and select the Standalone "debugStandalone" Script.

The variable 'relativeScriptFilePath' contains the name of the script that should be debugged.

In our case we must change it to "scripts/standalone/loopy.groovy"

Now start the "debugStandalone" Script by clicking the Button "Run"

And enjoy your Debugging Session :)

12. Targeted Scripts

To debug targeted scripts you must run the 'debugTargeted' Script.

This debug wrapper script defines the function that will be called by Zap. 

And the debug wrapper script depends on a returned closure from the wrapped script, that executes the real function.

return { msg -> invokeWith(msg)}

The debug wrapper script uses this closure to execute the real function. The nice thing is that the closure has no impact on running this script without

the debug wrapper.

13. NextSteps

Maybe the Debug Wrapper Scripts can be included into Zap and we only have to click on the "Debug" Button.

An Refresh-Button to reload the script from file. Currently its very inconvenient that you do not see changes in ZAP made by IntelliJ on the Scripts. 

(Nevertheless changes on the scripts by intellJ will be executed correctly from Zap).

Maybe this post can be a base for a Blogpost or/and a wikipage

14. Feedback

What are your thoughts about that?

Cheerio

Dennis

[psiinon]

This is awesome - thanks Dennis!