ZAP Automation Framework

Shared publicly for comment.

Summary
A new ZAP automation framework is being implemented.
This document describes why the framework is being developed, the features it will eventually
provide and the way it is intended to work.
The document has been made publicly available in order to get as much feedback as possible
before the framework is released.

Why a new Framework?

Automation is one of ZAP’s strengths.
It is possible to automate ZAP:
● From the command line using the -quickstart options
● Using the packaged scans
● By using the API against ZAP running in daemon mode
However all of the options have some limitations.

Command Line
The quickstart command line options are very limited and provide very few configuration
options. This makes it unsuitable for anything other than simple scans.

Packaged Scans
The packaged scans are much more flexible and provide a number of configuration options.
However the configuration options are split between:
● Packaged scan command line options
● A configuration file with a non standard format
● ZAP command line -config options
They are also tied to Docker, for historical reasons.

API
The API is extremely powerful and is used by the packaged scans.
However it is possibly too flexible and can be very confusing for people new to ZAP.

How will it work?

A new add-on is being developed which will essentially move the functionality from the
packaged scans into ZAP.
All configuration will be handled via a new yaml file which the add-on will also be able to
generate.
The add-on will define Automation Jobs which run sequentially. Jobs will include:
● Traditional Spider
● Ajax Spider
● OpenAPI Import
● SOAP Import
● GraphQL Import
● Passive Scanner configuration
● Active Scanner
● Reporting
Jobs will run sequentially and in the order defined, and it will be possible to run the same type of
job more than once with different parameters.

The framework will be plugable so that any ZAP add-on will be able to define automation jobs.
Reflection will be used so that most of the existing ZAP options will be supported with minimal
work. Add-ons will also be able to define new options.
While initial versions of the add-on will not support the full range of ZAP options the plan will be
to support everything that could relate to automation. In the meantime it will still be possible to
specify ZAP options via the ZAP -config command line option.

It is worth noting that the existing automations will not be replaced, this add-on will add
functionality not remove it.

Advantages
The new add-on will allow ZAP to be run from the command line while supporting a wide range
of options, exceeding those available to the command line and packaged scan options.
It will also not be tied to Docker, unlike the packaged scans.
It will be much easier to add new automation related functionality to the add-on, such as failing
the scan if certain conditions are not met, for example if one of the spiders does not find as
many URLs as expected.
It will also be possible to expose existing ZAP functionality in a much easier to configure format.
For example in order to change the risk of a specific alert raised by a scan rule you need to
define an alert filter. This could be exposed in the YAML file as a simple one liner - see the
example file below which shows how the Vulnerable JS Library rule could be changed to
generate High risk alerts..
Example YAML File
This is just an example and should not be relied upon. The add-on will generate template files in the right format when it is released.

--- # OWASP ZAP automation configuration file, see https://www.zaproxy.com/docs/(TBA)

env: # The environment, mandatory

contexts : # List of 1 or more contexts, mandatory
- name: bodgeit # Name to be used by jobs
url: http://localhost:8080/bodgeit/ # The top level url, everything under this will be inc
includePaths: # An optional list of regexes to include
excludePaths: # An optional list of regexes to exclude
- 'http://localhost:8080/bodgeit/logout'
authentication: # TBA - in time to cover all auth configs
parameters:
failOnError: true # If set exit on an error
failOnWarning: false # If set exit on a warning

jobs:
- type: addOns # Add-on management
name: init # Whatever you like, by default will be the job type
parameters:
updateAddOns: true # Update any add-ons that have new versions
install: # A list on non std add-ons to install from the Marketplace
- ascanrulesBeta
- pscanrulesBeta
- pscanrulesAlpha
uninstall: # A list of standard add-ons to uninstall

- type: passivescan-conf # Will always run - this job defines the rules it will use
parameters:
 maxAlertsPerRule: 10 # Int: Maximum number of alerts to raise per rule
scanOnlyInScope: true # Bool: Only scan URLs in scope (recommended)
rules: # Can be used to override default settings
- id: 2
desc: Private IP Disclosure # Not used - just for documentation
threshold: high

- type: spider # The traditional spider

parameters:
maxDuration: 5 # The max time the spider will be allowed to run for
failIfFoundUrlsLessThan: 100 # Fail if less than the expected number of URLs found
warnIfFoundUrlsLessThan: 150 # Warn if less than the expected number of URLs found
context: bodgeit # If not specified will default to the first context

- type: spiderAjax # The traditional ajax spider

parameters:
maxDuration: 30 # The max time the ajax spider will be allowed to run for
url: http://localhost:8080/bodgeit/home.html # Will be able to override the default url

- type: passivescan-wait # Will always run - this job just waits for it to finish
parameters:
maxDuration: 5 # The max time to wait for the passive scanner, default: 0

- type: activescan # The active scanner - this actively attacks your app
parameters:
maxDuration: 120 # The max time the active scanner will be allowed to run
maxRuleDurationMinutes: 20 # The max time each scan rule will be allowed to run for
policy: 'Default policy'
rules: # Can be used to override default/policy settings
- id: 0
desc: Directory Browsing # Not used - just for documentation
strength: high
 - id: 10003
desc: Vulnerable JS Library # Not used - just for documentation
risk: high # Will result in an alert filter which will change the risk

- type: report # TBA - various reporting options

Implementation Plan

Phase 1
The first phase should provide all of the core functionality so that people can try it out. It will not
be recommended for production use as some key features will not have been implemented.
However it should provide enough functionality for people to see its potential and to be able to
provide feedback.
PR Submitted: https://github.com/zaproxy/zap-extensions/pull/2693

Phase 2
The second phase is intended to implement enough functionality to match that available in the
Baseline Scan, with one significant exception. The baseline scan will be changed to use the
new automation add-on.
The exception is support for Scan Hooks. Scan hooks are called from the python script which
uses the API to control ZAP. This functionality will be moved into the automation add-on making
it much harder to call the scan hooks. The plan is therefore to only use the new add-on if scan
hooks are not used - the old python code will be maintained so that scan hooks will still work.
A new script type (which will run within ZAP) will be introduced in a later phase in order to
provide equivalent functionality in the add-on.

Phase 3
The third phase is intended to provide enough functionality to match that available in the API
and Full scans. The associated scripts will be changed to use the automation add-on, again only
if scan-hooks are not used.

Future Phases
Future phases are intended to add features such as:
● A new script type to match the functionality available in the scan hooks
● Improved reporting options
● Support for secrets eg via env vars
● Exposing more ZAP functionality, including
○ Authentication
○ Scripts
● The most popular features requested by the community, eg
○ Variables which can be reused