⚠️ This library is now decommissioned in favour of a new Dynamic Application Security Testing approach.

This scala library is built for use in a Scalatest Suite, and provides an abstraction above the OWASP ZAP API which allows for simple configurable execution of spider and active scans. The zap-automation library also produces a report summarising the alerts captured during scans, and can be tuned to fail your test run depending on the severity of the vulnerabilities found.

Note: 2.x.x version of the zap-automation library only supports ZAP version 2.8.0. To run against 2.7.0 version of ZAP use the latest 1.x.x version of this library.

The below step-by-step guide assumes a running OWASP ZAP instance has already proxied traffic to build the context with which to launch an attack scan. Visit the following pages for help on how to achieve this with an existing WebDriver journey test suite:

• Starting OWASP ZAP
• Proxying your Tests via ZAP

In your build.sbt file, add the following:

resolvers += Resolver.bintrayRepo("hmrc", "releases")

libraryDependencies += "uk.gov.hmrc" %% "zap-automation" % "x.x.x" % "test"

Replace x.x.x with a valid zap-automation version

The library uses SLF4J for logging purposes. The binding used is slf4j-api. If your test suite already has a logger implemented, you will see the below warning:

SLF4J: Class path contains multiple SLF4J bindings.

This may result in the zap tests running at debug log level.

To fix this, exclude zap-automation's SLF4J dependency in SBT:

 "uk.gov.hmrc" %% "zap-automation" % "x.x.x % "test" exclude( "org.slf4j","slf4j-api")

If your test suite uses logback-classic as the SLF4J binding, then you will need to pass the relevant config to the ZAP test. For example:

sbt -Dlogback.configurationFile=logback.xml 'testOnly uk.gov.hmrc.test.ui.cucumber.utils.ZAPRunner'

Not passing the config file would result in zap-automation logging in debug level.

Alternatively you could remove your existing logger dependencies and rely on the logger dependencies from zap-automation library.

In your test suite's application.conf create a zap-automation-config configuration object. See the default configuration file for detail on each configuration option.

An simple example can be found here.

You can also make use of the functionality available via typesafe configuration if you would like to implement multiple security tests as part of the same test suite. See example here.

If you are running against a non-local environment (e.g. QA), you'll need to switch off the healthcheck that ZAP does to make sure the service under tests is up and running. To do this set debug.healthcheck = false

 debug {
     # Checks if the testUrl configured above returns a 2xx or 3xx response and fails if it returns anything else
     healthCheck = false
   }

Create a test run in your test suite by extending the ZapTest trait of the zap-automation library. The test must extend one of ScalaTest's testing styles.

The test must also override ZapConfiguration and call triggerZapScan().

See example here.

Execute the attack scans with sbt using test created in the previous step. For example, if you created a test named utils.support.ZapRunner then the following command should work:

sbt "testOnly utils.Support.ZapRunner"

The output of a successful run will look something like this:

A HTML report is created at target/zap-reports/ZapReport.html irrespective of whether or not vulnerabilities were found.

The report contains the following sections:

• Scanners not enabled: List of required scanners that are not installed/enabled in Zap
• Summary of Alerts: a summary of the vulnerabilities found during the scan
• Summary of Scans: which of the scans executed (passive/spider/active)
• Failure Threshold: the configured failure threshold
• Alert Details: detail on each vulnerability/alert recorded

The below table provides a description of each Alert detail:

A fresh installation of ZAP does not include all of the scanners that we intend HMRC services to assessed against. For this reason, prior to initiating a scan the zap-automation library will query the OWASP ZAP installation for all available scanners. When these scanners do not correlate directly with the required scanners listed in reference.conf, zap-automation will log a WARN message with the missing scanners' information.

An example:

[pool-6-thread-5] WARN [ZAP Logger] - The below required scanners are not enabled. This will affect ZAP results
   [pool-6-thread-5] WARN [ZAP Logger] - 
                Scanner ID   : 90001
                Name         : Insecure JSF ViewState
                Scanner Type : Passive

This information is also included in the HTML report under Scanners not enabled. Including these scanners in ZAP setup will address this warning and ensure accurate results.

sbt test

The library provides various debug flags for local development of the library.

The scanners' configuration, available in reference.conf, is used to filter ZAP results. If a scanner is not listed in this config, then the alerts for this scanner will not be included in the HTML report that zap-automation generates at the end of a run.

Be sure to update this configuration when new scanners are added to ZAP.

This library uses Scalafmt, a code formatter for Scala. The formatting rules configured for this repository are defined within .scalafmt.conf. Prior to checking in any changes to this repository, please make sure all files are formatted correctly.

To apply formatting to this repository using the configured rules in .scalafmt.conf execute:

sbt scalafmtAll

To check files have been formatted as expected execute:

sbt scalafmtCheckAll scalafmtSbtCheck

Please raise any issues or feedback here

This code is open source software licensed under the Apache 2.0 License.