Skip to content

Commit 1f546c1

Browse files
psiinonpsiinon
committed
Add dev docs for creating a new add-on in zap-extensions
Signed-off-by: Simon Bennetts <psiinon@gmail.com>
1 parent d691ed3 commit 1f546c1

3 files changed

Lines changed: 150 additions & 0 deletions

File tree

‎site/content/docs/developer/_index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,11 @@ links:
1212
- name: 'Building ZAP with Eclipse'
1313
link: building-zap-with-eclipse/
1414
desc: How to build and run ZAP using the Eclipse IDE
15+
16+
- name: 'Creating a New Add-on in zap-extensions'
17+
link: creating-new-addon-in-zap-extensions/
18+
desc: A quick way to create a new add-on
19+
1520
---
1621

1722
ZAP documentation for developers. This is currently being worked upon and more articles will be published soon.

‎site/content/docs/developer/creating-new-addon-in-zap-extensions.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
title: "Creating a New Add-on in zap-extensions"
3+
description: "This guide will get you started with building and running ZAP in the Eclipse IDE."
4+
tags:
5+
- guide
6+
- tutorial
7+
type: page
8+
date: "2021-03-19"
9+
---
10+
11+
ZAP has a plugin architecture and new functionality is implemented via add-ons.
12+
13+
Add-ons can be defined in any repository but most of the ones that the ZAP core team maintains live in
14+
[zap-extensions](https://github.com/zaproxy/zap-extensions/).
15+
You should use the repository if you are planning on contributing your add-on to the ZAP project,
16+
but please talk to the ZAP Core team about this first via the [ZAP Developer Group](https://groups.google.com/g/zaproxy-develop).
17+
If you are planning on maintaining your add-on yourself then you should create it in another repository.
18+
19+
This guide will explain how you can quickly create a brand new add-on in this repository that you can then customise as you want.
20+
21+
## Preparation
22+
You will need to have followed the [Quick Start Guide to Building ZAP](../quick-start-build/) and have imported the ZAP code into your favourite IDE.
23+
24+
For the command line instructions given below you should be in the `zap-extensions` directory.
25+
26+
## Copy the Simple Example
27+
28+
The Simple Example is just what it sounds like, a simple example of a ZAP add-on.
29+
30+
Copy this add-on into a new directory, for example called `myaddon`.
31+
If you choose a different name then make sure that you use the name you have chosen in all of the commands below.
32+
33+
On Linux and MacOS this can be done from the command line using:
34+
```bash
35+
cp -R addOns/simpleexample addOns/myaddon
36+
```
37+
On Windows this can be done from the command line using:
38+
```bash
39+
xcopy addOns\simpleexample addOns\myaddon\ /E/H
40+
```
41+
42+
## Update the Project Files
43+
44+
### simpleexample.gradle.kts
45+
46+
Rename the file `simpleexample.gradle.kts` to be `myaddon.gradle.kts`.
47+
On Linux and MacOS:
48+
```bash
49+
mv addOns/myaddon/simpleexample.gradle.kts addOns/myaddon/myaddon.gradle.kts
50+
```
51+
On Windows this can be done from the command line using:
52+
```bash
53+
rename addOns\myaddon\simpleexample.gradle.kts addOns\myaddon\myaddon.gradle.kts
54+
```
55+
Edit the new file `myaddon.gradle.kts`, change the version, description, and name:
56+
```
57+
version = "0.0.1"
58+
description = "A new description."
59+
60+
zapAddOn {
61+
addOnName.set("My AddOn")
62+
zapVersion.set("2.10.0")
63+
64+
manifest {
65+
author.set("ZAP Dev Team")
66+
}
67+
}
68+
```
69+
70+
### settings.gradle.kts
71+
72+
Edit the file `settings.gradle.kts` and add `myaddon` into the `addOns` list.
73+
74+
Refresh the Gradle project in your IDE.
75+
76+
## Update the Source Code
77+
78+
These are the minimum changes needed to get your new add-on working.
79+
80+
### Message.properties
81+
82+
Edit the file `addOns/myaddon/src/main/resources/org/zaproxy/zap/extension/simpleexample/resources/Messages.properties`
83+
and change all of the instances of `simpleexample` in the keys to `myaddon` as well as changing the `Simple Example` strings to something like `My Add-on`.
84+
85+
```
86+
# An example ZAP extension which adds a top level menu item.
87+
#
88+
# This file defines the default (English) variants of all of the internationalised messages
89+
90+
myaddon.api.action.helloWorld = Logs "hello world called" with debug level.
91+
myaddon.desc = My Add-on
92+
myaddon.error.nofile = File not found : {0}
93+
myaddon.panel.msg = <html>This is My Add-on's status panel</html>
94+
myaddon.panel.title = My Add-on
95+
myaddon.popup.msg = Example right click menu invoked for:\n {0}
96+
myaddon.popup.title = My Add-on: Example right click menu
97+
myaddon.topmenu.tools.msg = My Add-on: Example message
98+
myaddon.topmenu.tools.title = My Add-on: Example top menu
99+
```
100+
101+
### ExtensionSimpleExample.java
102+
103+
Edit the file `addOns/myaddon/src/main/java/org/zaproxy/zap/extension/simpleexample/ExtensionSimpleExample.java` and change the NAME and PREFIX strings:
104+
105+
```
106+
// The name is public so that other extensions can access it
107+
public static final String NAME = "ExtensionMyAddOn";
108+
109+
// The i18n prefix, by default the package name - defined in one place to make it easier
110+
// to copy and change this example
111+
protected static final String PREFIX = "myaddon";
112+
```
113+
114+
## Deploy your Add-on
115+
116+
Deploy your add-on via the Gradle task:
117+
118+
On Linux and MacOS:
119+
```bash
120+
./gradlew addOns:myaddon:copyZapAddOn
121+
```
122+
On Windows this can be done from the command line using:
123+
```bash
124+
gradlew.bat addOns:myaddon:copyZapAddOn
125+
```
126+
127+
## Restart ZAP
128+
129+
Your new add-on should now be available in ZAP. It will add a new menu item and a new tab in the bottom window - you will need to click on the green plus to see it.
130+
131+
![ZAP Screenshot with My Add-on](/img/docs/developer/myaddon.png)
132+
133+
## Next Steps
134+
135+
You should update the following files before you make too many other changes:
136+
137+
### Package name
138+
139+
Change the package from `org/zaproxy/zap/extension/simpleexample` to something like `org/zaproxy/addon/myaddon/`
140+
You can change the package name (and class names in the following section) by just editing the files but in general your IDE is likely to make this easier.
141+
142+
### Class names
143+
144+
Change the class names to something more appropriate for your add-on.
145+

‎site/static/img/docs/developer/myaddon.png‎

107 KB
Loading

0 commit comments

Comments
 (0)