ZAP Add-on Development Guide

[Matteo Simionato]

Hi,

my team and I are developing a simple add-on which add a single button to the UI. By clicking on it, a script we created can be enabled/disabled.

The only thing we were able to find to achieve our goal was this link, which kinda helped us to add the button to the UI. On the contrary, trying to manage our script from our add-on ended up being extremely difficult.
We started looking for some sort of guide, both online and inside the main repos (zaproxy and zap-extensions), with no luck at all. There's too many info scattered around, to much code to read and understand. We felt lost, basically.
We were wondering, is there any kind of documentation we can read? Is there any tutorial/guide we can follow? Any kind or resource.
Thanks in advance and have a nice day!

[psiinon]

Hiya,

https://www.zaproxy.org/docs/developer/ is pretty much everything we've got, along with the source code of course ;)

But feel free to ask specific questions here - thats what this group is for!

Cheers,

Simon

[Matteo Simionato]

Thank you for your quick reply.

As I said, we followed this link and we managed to add a toggle button to the UI. Now the challenge is to enable/disable a script we wrote based on button state. I'm going to show you relevant code:

private JToggleButton toggleButton() {
     if (toggleButton == null) {
         toggleButton = new JToggleButton();

         toggleButton.addItemListener(
                 e -> {
                     int state = e.getStateChange();
                     if (state == ItemEvent.SELECTED) {

                         // Change button icon based on state

                         // Enable script
                     } else if (state == ItemEvent.DESELECTED) {

                         // Change button icon based on state

                         // Disable script

                     }
                 });

         toggleButton.setSelected(true);
     }
     return toggleButton;
}

So far I found some code snippets which may be useful.
Inside ScriptJobUnitTest.java (line 1045) there are a couple of classes which seem to do what I'm trying to do, I'm speaking of ScriptJob, AutomationProgress and AutomationEnvironment. I tried to access them from my add-on, but looks like they are not recognized unless you update your dependencies. Since there's no documentation about it I still don't know if my intuition was good and if this is the right approach.

ExtensionFrontEndScanner.java seems it does what I'm trying to do (starting/stopping scripts), but since I don't have full knowloedge about ZAP APIs I don't fully understand what's happening.

Seems the two approaches are different, plus I don't know which might be the right implementation. Can you help me?

Thanks in advance and have a nice day!

[kingthorin+zap]

What type of script are you trying to enable/disable?

[Matteo Simionato]

From the UI is possible to enable/disable a script from a contextmenu. I'd like to enable/disable our script based on toggle button state (code provided above).
Thanks in advance!

[thc...@gmail.com]

Use the method ExtensionScript.setEnabled(ScriptWrapper, boolean).

Best regards.

On 20/10/2023 09:31, Matteo Simionato wrote:
> [image: zap.png]
> From the UI is possible to enable/disable a script from a contextmenu. I'd
> like to enable/disable our script based on toggle button state (code
> provided above).
> Thanks in advance!
>
> Il giorno giovedì 19 ottobre 2023 alle 19:37:24 UTC+2 kingthorin+zap ha
> scritto:
>
>> What type of script are you trying to enable/disable?
>>
>> On Thursday, October 19, 2023 at 11:29:09 AM UTC-4 ZAP Developer Group
>> wrote:
>>
>>> Thank you for your quick reply.
>>> As I said, we followed this link

>>> <https://www.zaproxy.org/docs/developer/creating-new-addon-in-zap-extensions/>

>>> <https://github.com/zaproxy/zap-extensions/blob/main/addOns/frontendscanner/src/main/java/org/zaproxy/zap/extension/frontendscanner/ExtensionFrontEndScanner.java>

>>> seems it does what I'm trying to do (starting/stopping scripts), but
>>> since I don't have full knowloedge about ZAP APIs I don't fully understand
>>> what's happening.
>>> Seems the two approaches are different, plus I don't know which might be
>>> the right implementation. Can you help me?
>>>
>>>
>>> Thanks in advance and have a nice day!
>>>
>>> Il giorno giovedì 19 ottobre 2023 alle 14:58:16 UTC+2 psiinon ha scritto:
>>>
>>>> Hiya,
>>>>
>>>> https://www.zaproxy.org/docs/developer/ is pretty much everything we've
>>>> got, along with the source code of course ;)
>>>>
>>>> But feel free to ask specific questions here - thats what this group is
>>>> for!
>>>>
>>>> Cheers,
>>>>
>>>> Simon
>>>>
>>>> On Thursday, 19 October 2023 at 13:31:18 UTC+1 ZAP Developer Group wrote:
>>>>
>>>>> Hi,
>>>>> my team and I are developing a simple add-on which add a single button
>>>>> to the UI. By clicking on it, a script we created can be enabled/disabled.
>>>>> The only thing we were able to find to achieve our goal was this link

>>>>> <https://www.zaproxy.org/docs/developer/creating-new-addon-in-zap-extensions/>,

>>>>> which kinda helped us to add the button to the UI. On the contrary, trying
>>>>> to manage our script from our add-on ended up being extremely difficult.
>>>>> We started looking for some sort of guide, both online and inside the

>>>>> main repos (zaproxy <https://github.com/zaproxy/zaproxy> and
>>>>> zap-extensions <https://github.com/zaproxy/zap-extensions>), with no

[psiinon]

When developing ZAP add-ons its important to understand Extensions.

These are the classes that implement Extension.java typically by extending ExtensionAdaptor.java and a key part of the plugability of ZAP.

All add-ons and most of the components in the core have an Extension, and they are the way to access ZAP functionality.

So you need to find the Extension which manages scripts, which, as Ricardo said, is ExtensionScript.java

You should depend on the relevant extension e.g. like this: https://github.com/zaproxy/zap-extensions/blob/c16fa913d760a933006663495e1a996262c3a59a/addOns/zest/src/main/java/org/zaproxy/zap/extension/zest/ExtensionZest.java#L117

And get hold of the Extension like this: https://github.com/zaproxy/zap-extensions/blob/c16fa913d760a933006663495e1a996262c3a59a/addOns/zest/src/main/java/org/zaproxy/zap/extension/zest/ExtensionZest.java#L381-L390

Does that help?

Cheers,

Simon

[Matteo Simionato]

Thanks to your advices I updtaed my code. This is the relevant snippet so far:

private final File scriptFile = new File(Constant.getZapHome(), "script.kt");

private ScriptWrapper scriptWrapper;

// I had to initailize script wrapper inside postInit(),

// cause I'd have gotten a NPE if I had initialized it right after the declaration

@Override
public void postInit() {
     super.postInit();
     scriptWrapper = new ScriptWrapper(
             scriptFile.getName(),
             "Lorem ipsum",
             "kotlin", // I don't know what should I put here, just guessing
             getExtScript().getScriptType(TYPE_HTTP_SENDER),
             true,
             scriptFile
     );
}

private JToggleButton getToggleButton() {

     if (toggleButton == null) {
         toggleButton = new JToggleButton();

         toggleButton.addItemListener(
                 e -> {
                     int state = e.getStateChange();

                     if (state == ItemEvent.SELECTED) {

                         // Update toggle button UI

                         getExtScript().setEnabled(scriptWrapper, true);

                     } else if (state == ItemEvent.DESELECTED) {

                         // Update toggle button UI
                         getExtScript().setEnabled(scriptWrapper, false);
                     }
                 });

         // Init toggle button UI
     }
     return toggleButton;
}

The add-on builds without any errors, but I have a couple of questions:
1) How can I verify, from ZAP UI, if my script it's really enabled and if it's doing anything?

2) Why my script wasn't added here?

Thanks in advance and have a nice day!

[thc...@gmail.com]

Hi,

1) The script should be shown in the UI and have the enabled icon.
Whether it's doing anything depends on what the script is doing, only
you can check that.

2) You didn't add the script. e.g.:
https://github.com/zaproxy/zap-extensions/pull/2581/files#diff-0c8e737d7df9bbc5066771e0ec31e31baa746053e5cb0ec1551c9c4861fd42f4R186


The engine name is correct, you can check that when creating new scripts
in the UI.

Note that the engine will not be available if the add-on is not
installed (you can have your add-on depend on the Kotlin add-on, and the
extension as well).

Best regards.

>> <https://github.com/zaproxy/zaproxy/blob/main/zap/src/main/java/org/parosproxy/paros/extension/Extension.java>
>> typically by extending ExtensionAdaptor.java
>> <https://github.com/zaproxy/zaproxy/blob/main/zap/src/main/java/org/parosproxy/paros/extension/ExtensionAdaptor.java>

>> and a key part of the plugability of ZAP.
>> All add-ons and most of the components in the core have an Extension, and
>> they are the way to access ZAP functionality.
>>
>> So you need to find the Extension which manages scripts, which, as Ricardo
>> said, is ExtensionScript.java

>> <https://github.com/zaproxy/zaproxy/blob/main/zap/src/main/java/org/zaproxy/zap/extension/script/ExtensionScript.java>