The OWASP ZAP Desktop User Guide
This release contains a large number of changes, in particular to the ZAP API.
We have added a significant number of new API endpoints, working towards our goal of making ZAP completely controllable via the API. We have also changed some of the existing endpoints and in all cases these changes are backwards compatible.
The full release also includes a new JxBrowser add-on as well as platform specific webdrivers to make it even easier to
interact with ZAP through a wide variety of browsers.
API Security Changes
We have changed the API security in response to issues reported to us via our bug bounty program. Details of the vulnerabilities are given below.
The security changes are by necessity not backwards compatible, although we have include options for disabling them if you use ZAP in a safe environment.
By default all API calls now require either the API key or a nonce.
These can be supplied via URL parameters, POST parameters or headers.
The supported ZAP API clients (including Java and Python) have been updated to supply the API key via a header.
Nonces are generated by ZAP and are intended to be used by ZAP add-ons that need to access the ZAP API.
For full details see the Options API screen.
There are a set of new API options related to security:
- UI Enabled - If enabled then the API Web UI is available to all machines that are able to use ZAP as a proxy. This is enabled by default.
- IP addresses permitted to use the API - By default only the machine ZAP is running on is able to access the ZAP API. You can allow other machines access to the API by adding suitable regex patterns. You should only add IP addresses that you trust.
- Do not require an API key for safe operations - If enabled then the API key is not required for Views or Other operations that are considered ‘safe’, in other words operations that do not make any changes to ZAP. Such operations do however give access to ZAP data such as alert, messages, and file system paths. They can also be used by web applications to detect the presence of ZAP.
- Report permission errors via API - If enabled then ZAP will report permission errors via the API, which can be used by web applications to detect the presence of ZAP. This is not a serious problem in a safe environment but if you are using ZAP against potentially malicious sites then you should not enable it.
All ZAP options can be specified via the command line when you start ZAP - see https://www.zaproxy.org/faq/why-is-an-api-key-required-by-default/ for full details.
We have also added even more security headers to the API including a strong Content Security Policy.
- Issue 368 : API - report URLS just found by spider
- Issue 689 : Improve Scope management
- Issue 958 : Java version identification when an environment variable for Java is exported
- Issue 1644 : Add response headers to Params tab
- Issue 1853 : Allow to active scan a Context through ZAP API
- Issue 1952 : Do not allow Contexts with same name
- Issue 2117 : set / update default threshold and strength for a scan policy
- Issue 2334 : Enable searching in ZAP Addons Pop-up
- Issue 2415 : Show the reason why an active scanner was skipped
- Issue 2559 : Do not clean up unsaved (file based) sessions
- Issue 2570 : Change proxy option to remove unsupported encoding
- Issue 2592 : Differentiate the source of alerts
- Issue 2611 : Change HTTP breakpoint dialogues to modal
- Issue 2633 : Enhance Client Cert File Chooser
- Issue 2647 : Support a/pscan rule configuration
- Issue 2655 : Provide skip reason for Script Active Scan Rules
- Issue 2682 : Sort (main) help add-on TOC entries
- Issue 2690 : Support ignoring specified forms when checking for CSRF vulnerabilities
- Issue 2699 : Enhancement Request: Improve SSL Negotiation Failure Error Handling
- Issue 2701 : Enhancement Request: Factory Reset
- Issue 2723 : Support POST requests for API actions
- Issue 2728 : Allow to remove spider parsers and filters
- Issue 2742 : Allow for override/customization of Java's “networkaddress.cache.ttl” value
- Issue 2750 : Add a reasonably strong CSP to the API
- Issue 2773 : Use UTF-8 to read/write ZAP scripts
- Issue 2782 : Support the -configfile cmdline parameter
- Issue 2825 : Additional Commentary for JS templates
- Issue 2853 : Override Alert details
- Issue 2855 : Support break functionality in the API
- Issue 2865 : Normalise Include/Exclude context panels
- Issue 2886 : Option to generate reports in Markdown format
- Issue 2891 : Show the cause why a script was not loaded
- Issue 2936 : Always set Java mem to 1/4 available (over 512Mb)
- Issue 2937 : Change ZAP API to read/use the request body
- Issue 2939 : Use non absolute URI base HTML element in spider
- Issue 2951 : Support active scan rule and scan max duration
- Issue 2954 : Allow to export a Context through the context menu
- Issue 2966 : Use L&F specified through JVM args
- Issue 2970 : Allow to configure, by script type, the enabled state of new/loaded scripts
- Issue 2982 : Allow to disable default standard output logging
- Issue 2994 : show column ‘Size Resp. Body’ of history in bytes
- Issue 3004 : Allow to passive scan just HTTP messages in scope
- Issue 3028 : Value Generator (previously Form Handling)
- Issue 3038 : Return request's type through the ZAP API
- Issue 3042 : Allow to select multiple parameters in Params tab
- Issue 3050 : Return requests’ timestamp/RTT through the ZAP API
- Issue 3058 : Allow to configure the domains always in spider scope (Spider API)
- Issue 3061 : Allow to deprecate API endpoints
- Issue 3069 : Context structural parameter only accepts alphanumeric charts
- Issue 3079 : Added cookie ignore list rule and inc sleep default to 20 to reduce FPs
- Issue 3081 : Change default time to 15 and make publicly accessible
- Issue 3090 : Be more lenient on add-on's file name format
- Issue 3098 : Log to file even if ZAP is run ‘inline’
- Issue 3118 : include subjectAlternativeName extension in generated certificates
- Issue 3123 : Added security annotations for forms that dont need anti CSRF tokens
- Issue 3130 : Added autoupdate API calls
- Issue 3149 : Baseline: Support context file and in-progress issues
- Issue 3159 : Allow esc to Close Marketplace Dialog
- Issue 3163 : Autoselect Imported Certificate
- Issue 3176 : Allow to show more request data in History tab
- Issue 3195 : Add workaround to local proxy for Android emulator
- Issue 3226 : Option to supply API key or nonces via header
- Issue 3227 : Limit API access to whitelisted IP addresses
- Issue 3229 : Use Referrer-Policy in ZAP API
- Issue 3232 : Active Scan API - Allow to start the scans with non-leaf nodes
- Issue 3238 : Add driver entries for CSPid Virtual Smartcards
- Issue 3261 : Client Cert PKCS#11 - UI/Exception Handling
- Issue 3285 : Edit Alert Enhancements
- Issue 3290 : Show requests with I/O errors in Spider tab
- Issue 3296 : Create script directories when initialising the home dir
- Issue 3297 : Start local proxy after processing command line arguments when in daemon mode
- Issue 1107 : Additional Commentary needed for Script Templates/Examples
- Issue 1152 : Passive CSRF Sensor Reports Missing CSRF Tokens for all Forms, not just POST Requests Missing Anti-CSRF Tokens
- Issue 1212 : False positives in SQLi tests
- Issue 2176 : NPEs during zapbot WAVSEP scans
- Issue 2218 : Persisted Sessions don't save unconfigured Default Context
- Issue 2546 : ZAP access URLs which are out of scope
- Issue 2550 : GUI freezes while opening Scan Progress dialogue
- Issue 2561 : Use UTF-8 to write the HTML Report
- Issue 2578 : Minor Usability Issue: Must click on text in Options column to select row
- Issue 2585 : Remove temp Sequence requests on session clean up
- Issue 2586 : Use option All Requests from Active Scan dialogue
- Issue 2605 : Prevent GUI hang when adding messages to History
- Issue 2608 : Removing a DDN from a Context Does Not Appear to Trigger an Update to the Sites Tab
- Issue 2637 : Prevent API UI from being loaded in a frame
- Issue 2642 : Slow mouse wheel scrolling in site tree
- Issue 2657 : Correct persistence of disabled extensions
- Issue 2674 : Automated authentication requests shown in HTTP Sessions tab
- Issue 2681 : Fix exception while adding script through the API
- Issue 2694 : Ability to set Excluded Parameters from the API
- Issue 2696 : Enable Copy URLs pop up menu item for all messages
- Issue 2707 : Manual add-on installation needs more meaningful dialog messages
- Issue 2735 : Wiki: ModesAndScope doesn't cover ATTACK mode
- Issue 2736 : Bug: Can't generate reports from saved Session data
- Issue 2737 : Correct API error message on missing script params
- Issue 2745 : Spider Exception when sitemap.xml not found
- Issue 2748 : ZAP Spidering HTML Forms with multiple submit buttons
- Issue 2757 : Alerts with different request method are considered the same
- Issue 2774 : Wrong value shown in fuzz location for body text when selected through combined view
- Issue 2792 : Able to overlap fuzz (HTTP) locations
- Issue 2793 : Wrong highlight in combined view with last part of request header
- Issue 2810 : Active scanners’ alerts persisted twice when with GUI
- Issue 2836 : ZAP hsqldb OutOfMemoryError when deleting records on cleanup
- Issue 2862 : XSS in url on page with no parameters not found
- Issue 2874 : Correct offset calculation in text header views
- Issue 2898 : Tweak spider parser to ignore/strip matched parenthesis around URLs
- Issue 2935 : Wrong charset used in response body if no charset set
- Issue 2977 : HTTP500 from JSON/httpSessions/view/sessions/?site=FOO
- Issue 3002 : Correctly render all nodes in checkbox tree
- Issue 3041 : Fix concurrency issues when publishing ZAP events
- Issue 3052 : Correct the loading of extensions’ enabled state
- Issue 3054 : Clear old contexts, always, when loading a session
- Issue 3073 : Skip process automated msgs for HTTP Sessions tab
- Issue 3100 : Context's in scope change might not be applied
- Issue 3142 : Properly show excluded parameters through ZAP API
- Issue 3157 : Session Comparison Exception
- Issue 3175 : Cancel/save StandardFieldsDialog on escape key
- Issue 3192 : URLs included in context are disregarded by the spider
- Issue 3211 : Can't find .ZAP_JVM.properties with %HOMEPATH% when using zap.bat in windows
- Issue 3215 : History Filter dialog cant be scaled
- Issue 3221 : Some icons not scaled correctly
- Issue 3224 : HTML injection in “Alert” tab
- Issue 3275 : Global Exclude URL (beta) - after close and reopen does not pick up added regex for excluding URLs
- Issue 3278 : Reset proxy excluded URLs on new session
- Issue 3309 : Improve node enumeration in pre-scan phase
- Issue 3320 : Correct creation of Git/SVN spider seeds
- Issue 3330 : Apply config arguments in the order specified
ZAP API Changed Endpoints:
ACTION ascan / scan
The url parameter is now optional and an optional contextId parameter has been added. You must supply one of these.
ACTION ascan / scanAsUser
The url and contextId parameters are now optional. You must supply one of these.
ACTION ascan / addScanPolicy
Added optional alertThreshold and attackStrength parameters.
ZAP API New Endpoints:
VIEW ascan / optionMaxRuleDurationInMins
Returns the maximum time in minutes that a scan rule can run for, zero is unlimited.
VIEW ascan / optionMaxScanDurationInMins
Returns the maximum time in minutes that a full scan can run for, zero is unlimited.
ACTION ascan / setOptionMaxRuleDurationInMins
Sets the maximum time in minutes that a scan rule can run for, zero is unlimited.
ACTION ascan / setOptionMaxScanDurationInMins
Sets the maximum time in minutes that a full scan can run for, zero is unlimited.
ACTION ascan / updateScanPolicy
Updates the specified scan policy with the specified alertThreshold or attackStrength.
VIEW break / isBreakAll
Returns True if ZAP will break on both requests and responses.
VIEW break / isBreakRequest
Returns True if ZAP will break on requests.
VIEW break / isBreakResponse
Returns True if ZAP will break on responses.
VIEW break / httpMessage
Returns the HTTP message currently intercepted (if any).
ACTION break / break
Controls the global break functionality. The type may be one of: http-all, http-request or http-response. The state may be true (for turning break on for the specified type) or false (for turning break off). Scope is not currently used.
ACTION break / setHttpMessage
Overwrites the currently intercepted message with the data provided.
ACTION break / continue
Submits the currently intercepted message and unsets the global request/response breakpoints.
ACTION break / step
Submits the currently intercepted message, the next request or response will automatically be intercepted.
ACTION break / drop
Drops the currently intercepted message.
VIEW core / optionDnsTtlSuccessfulQueries
Gets the TTL (in seconds) of successful DNS queries.
ACTION core / sendRequest
Sends the HTTP request, optionally following redirections. Returns the request sent and response received and followed redirections, if any. The Mode is enforced when sending the request (and following redirections), custom manual requests are not allowed in ‘Safe’ mode nor in ‘Protected’ mode if out of scope.
ACTION core / setOptionDnsTtlSuccessfulQueries
Sets the TTL (in seconds) of successful DNS queries (applies after ZAP restart).
OTHER core / mdreport
Generates a report in Markdown format.
VIEW httpSessions / sites
Gets all of the sites that have sessions.
VIEW pscan / scanOnlyInScope
Tells whether or not the passive scan should be performed only on messages that are in scope.
ACTION pscan / setScanOnlyInScope
Sets whether or not the passive scan should be performed only on messages that are in scope.
VIEW spider / allUrls
Returns a list of unique URLs from the history table based on HTTP messages added by the Spider.
VIEW spider / optionMaxChildren
Gets the maximum number of child nodes (per node) that can be crawled, 0 means no limit.
ACTION spider / setOptionMaxChildren
Sets the maximum number of child nodes (per node) that can be crawled, 0 means no limit.
The following vulnerabilities have been reported in previous versions of ZAP. Other less serious issues have been also been fixed as a matter of course.
Many thanks to all of the researchers who have ethically reported these issues to us via our bug bounty program. If you need more details about any of these vulnerabilities then please contact us.
RCE via Anti CSRF Test Form and API Key Disclosure
If the user used the Anti CSRF Test Form against a specifically crafted HTML page then the API key was leaked to that site. The site could then access the ZAP API and perform any action, including uploading ZAP scripts. Scripts can only be uploaded from ‘local’ filesystems but if the user is running ZAP on Windows then the attacker can make a malicious script available via a public SMB share. This appears to ZAP to be a local file and the script is therefore uploaded and can be run via the API.
The requirement for the API key or nonce on all API operations are a direct result of this vulnerability, as are changing add-ons to use nonces to reduce the risk of leaking the API key.
Credit: Artemy Bogdanov (@Abr1k0s)
Artemy was awarded a $1000 bug bounty as a result of this submission. This is the first bug bounty we have paid out - congratulations Artemy!
Windows Installer Vulnerable to DLL Hijacking
The ZAP Windows Installer for all versions up to and including 2.5.0 are vulnerable to DLL Hijacking on Windows 7 (and earlier versions). This is a vulnerability in the in 3rd party installer InnoSetup. The 2.6.0 Installers (on all platforms) are now generated using Install4J.
If for some reason you do need to install previous versions of ZAP on Windows 7 or earlier then we recommend that you move the installer to a clean directory before running it.
Note that Burp Suite also use Install4J so future vulnerabilities in Install4j-generated installers may be eligible for the Burp Suite bug bounty program: https://hackerone.com/portswigger
Credit: James Kettle (Burp Suite)
Arbitrary Code Execution via Invoke Applications Parameter Injection
HTML parameters could be specifically crafted to cause arbitrary code execution, if the user choose to invoke the targeted application with a request containing that parameter from within ZAP.
The Invoke Applications add-on has been updated to fix this issue - all ZAP users should install this new version before continuing to use the add-on.
Credit: Artemy Bogdanov (@Abr1k0s)
XSS via Anti CSRF Test Form
The Anti CSRF Test Form was vulnerable to XSS attacks if run against a specifically crafted HTML page.
The API now uses a strong Content Security Policy to prevent such issues
Credit: g_sato - https://bugcrowd.com/g_sato
API Vulnerable to DNS Rebinding
The API was vulnerable to DNS Rebinding attacks. It now checks the host header and rejects any requests from unexpected hosts.
Credit: Artemy Bogdanov (@Abr1k0s)
||the introduction to ZAP
||the full set of releases
||the people and groups who have made this release possible