The slides from the first ZAP Hackathon at AppSec USA

1. The OWASP Foundation
http://www.owasp.org
OWASP
Zed Attack Proxy
Hackathon
Simon Bennetts
OWASP ZAP Project Lead
Mozilla Security Team
psiinon@gmail.com
Copyright © The OWASP Foundation
Permission is granted to copy, distribute and/or modify this document under the terms of the OWASP License.

2. The Plan
•
•
•
•
•
Overview of how to extend ZAP
Describe the topics I could talk about
Find out what you really want to know ;)
Agree topics to cover
For each topic:
– Talk for a bit, hack for a bit
• But its all up for grabs, so we can change anything
• And feel free to do your own thing!
• I'll help out during the hacking sections
2

3. How you can extend ZAP
• Without a dev environment:
– 3rd party tools
– Scripts
– Translations
– Documentation
• With a development environment
– Active & passive scan rules
– 'Full' extensions

4. What can you plug in?
•
•
•
•
Scripts
Script types
Active and Passive rules
UI elements – tabs, popups, toolbar buttons,
menus, right click options...
• API calls
• Request / Response views
• Breaking, Fuzzing, Searching

5. Topics I could talk about
•
•
•
•
•
•
•
•
The ZAP project structure
Setting up a ZAP development environment
ZAP documentation and internationalization
Implementing 'standard' scripts
Implementing Zest scripts
Implementing active and passive scan rules
Implementing Add-ons and extensions
Features and fixes to work on

6. More topics I could talk about
•
•
•
•
•
•
•
•
Key classes
Accessing core functionality and extensions
Internal events
The user interface
The API
The database
Request / Response views
Breaking, fuzzing, searching

7. Project Structure
• zaproxy
– http://code.google.com/p/zaproxy/
– The 'core' plus a lot more
• zap-test
– http://code.google.com/p/zaproxy-test/
– Unit tests
• zap-extensions
– http://code.google.com/p/zap-extensions/
– The add-ons
– Trunk, alpha and beta branches!

8. Project Structure
• zaproxy
– src
All the 'core' source code
• org/parosprozy
The 'old' Paros code
• org/zaproxy
The 'new' ZAP code
• help
Help files
• lang
Property files (UI)
– build
Build directory
– lib
Jar files
– scripts
Default script templates

9. Development Environment
•
•
•
•
Java 7
Eclipse (or your favorite Java IDE)
Subversive SVN (or equivalent)
Import ZAP projects via SVN
– https://zaproxy.googlecode.com/svn/trunk/
– https://zaproxy-test.googlecode.com/svn/trunk/
– https://zap-extensions.googlecode.com/svn/trunk/
– https://zap-extensions.googlecode.com/svn/branches/alpha/
– https://zap-extensions.googlecode.com/svn/branches/beta/
• Add 'lib' jars to build path
• Run org.zaproxy.zap.ZAP.java

10. Creating the Projects
•
•
•
•
•
•
•
•
File / New / Other...
SVN / Project from SVN
Create a new repository location
URL, e.g. https://zaproxy.googlecode.com/svn/
Select Resource, e.g. trunk
Check out .. using the New Project Wizard
Select a wizard: Java / Java Project
Add all lib/*.jar files to the build path

11. Dev Rules and Guidelines
•
http://code.google.com/p/zaproxy/wiki/DevGuidelines
•
•
•
•
•
•
•
•
Ease of use and consistency are key
All UI string must in internationalized
Comment all changes to orp.parosproxy.paros
All functionality should have help pages
Keep a clean split between functionality and UI
Check in code cleaner that you checked out
Write unit tests
Extensions should expose functionality, not UI
elements (older ones still do)

12. Documentation and i18n
• ZAP Help file
– src/help
– {addon}/resource/help
– http://code.google.com/p/zaproxy/wiki/HelpIntro
• Home pages
– https://www.owasp.org/index.php/ZAP
• 'Official' home page, 'outward' facing?
– http://code.google.com/p/zaproxy/
• More details, 'internal' facing?
• http://crowdin.net/project/owasp-zap

13. Scripting
•
•
•
•
•
•
•
Passive Rules
Passive scanner
Active Rules
Active Scanner
Proxy
Inline
Stand Alone
User controlled
Targeted
Right click invoke
Library
Work in progress ;)
Plugable
Register at runtime

14. 'Standard' Scripts
•
•
•
•
No IDE required :)
JavaScript (and Zest) built in
Python and Ruby download from Marketplace
All other JSR 223 scripts supported with no
templates
• Templates give basic structure
• But you still need some idea of ZAP internals
– http://code.google.com/p/zaproxy/wiki/InternalDetails
– http://code.google.com/p/zaproxy/wiki/JavaDocs

15. Zest Scripts
•
•
•
•
•
•
•
Built in, same script types
But they are graphical
Implement JSR 223
And very new
Effectively ZAP's macro language
Right click everywhere!
https://developer.mozilla.org/en-US/docs/zest

16. Add-ons
•
•
•
•
Available from the ZAP Marketplace
Name format: id-status-version.zap
Status: alpha, beta, release
Standard ZIP file, containing:
– ZapAddOn.xml
– Active scan rules
– Passive scan rules
– Extensions
– Files

17. ZapAddOn.xml
<zapaddon>
<name>Short text name (no HTML)</name>
<version></version>
<description>Longer description</description>
<author>Author (no HTML)</author>
<url/>
<changes/>
<dependson>
<zapaddonid/>
</dependson>
<extensions>
<extension/>
</extensions>

18. ZapAddOn.xml
<ascanrules>
<ascanrule/>
</ascanrules>
<pscanrules>
<pscanrule/>
</pscanrules>
<filters>
<!-- not currently supported? -->
<filter/>
</filters>
<files>
<file/>
</files>
<not-before-version/>
<not-from-version/>
</zapaddon>

19. Add-on file structure
• Package: org.zaproxy.zap.extension.name
files
resource
help
icons
lib
•
•
•
•
Will be included as files
Help files
Images
Jars (will be expanded)
Classes and sub packages
Message.properties
Message_locale.properties
ZapAddOn.xml

20. Building Add-ons
•
•
•
•
zap-entensions/build/build.xml
zap-extensions/branches/alpha/build/build.xml
zap-extensions/branches/beta/build/build.xml
Typically just need to add your add-on to targets:
– build-all
– deploy-addon-id
– deploy-all
• Everything will be handled if you stick to the
standard file structure

21. Passive Scan Rules
• Extend org.zaproxy.zap.extension.pscan.
PluginPassiveScanner
•
•
•
•
•
•
Called for every request and response
Run in background thread
Cant change anything – look but dont touch ;)
Receive HttpMessage and DOM Source
Use PassiveScanThread.raiseAlert(..)
Lots of examples (trunk, beta, alpha?)

22. Active Scan Rules
• Extend org.parosproxy.paros.core.scanner.
AbstractPlugin
• AbstractAppPlugin
–AbstractAppParamPlugin
• AbstractHostPlugin
Every node
Every param
Hosts/1 node
st
• Can change anything – make new request etc
• AbstractPlugin – lots of utility methods
• Lots of examples (trunk, beta, alpha?)

23. Extensions
• Extend org.parosproxy.paros.extension.Extension
• Can do anything – much of the 'core' is really
extensions
• Should have their own language files
• Lots of examples – pick one that does something
vaguely similar?

24. Features and Fixes
•
•
•
•
•
•
•
•
Scripts, in Javascript, Python, Ruby, Zest
New script templates – Groovy, Scala ...
Active and passive scan rules
http://code.google.com/p/zaproxy/wiki/Projects
http://code.google.com/p/zaproxy/issues/list
'IdealFirstBug' tag
Wrap / port another tool (retire.js, ..)
Whatever you want to do!

25. Extension Hooks
•
•
•
•
•
•
•
•
OptionsChangedListener
ProxyListener
SessionChangedListener
SiteMapListener
PersistentConnectionListener
AddonFilesChangedListener
CommandLineListener

26. Key Classes
•
•
•
•
•
•
•
•
•
•
ZAP
main class
Model
singleton
View
singleton
Control
singleton
Session
access via Model
SiteMap
access via Session
SiteNode
a SiteMap node
HttpMessage
full request/response
HistoryReference
subset of HttpMessage
Alert
a vulnerability

27. Accessing Extensions
• Core Extensions (ie included by default)
ExtensionXXX extXXX =
Control.getSingleton().
GetExtensionLoader().getExtension(
ExtensionXXX.NAME);
if (extXXX != null) {
// Now you can use it...
extXXX.someFunction();
}
• For Extensions not included by default you must
use a String name and access functions via
reflection

28. API
• org.zaproxy.zap.extension.api.API - singleton
• api.registerApiImplementor (ApiImplementor impl)
• ApiElement
– ApiView- return structured info - ApiResponse
– ApiAction - make changes (return structured info)
– ApiOther - return raw data
• API generators
– JavaAPIGenerator
– PythonAPIGenerator
– WikiAPIGenerator

29. Database
•
http://code.google.com/p/zaproxy/wiki/InternalDatabase
• HSQLDB – can access directly via SQL tools
• Package: org.parosproxy.paros.db
• Shouldnt typically access the db directly – use the
extension that 'owns' the data
• Add-ons can create new tables – see websockets
• The schema must be backwards compatible
between releases

30. Pluggable HttpPanels
•
•
•
•
org.zaproxy.zap.extension.httppanel
Request and Response display options
Good examples – websockets & plugnhack (?)
httppanel
component
XxxComponent
models
extend Abstract*HttpPanelViewModel
views
extend HttpPanelTextArea...

31. Feedback?