ZAP Utils

Utils module responsible for ZAP automatic initialization

License

License

Categories

Categories

Security
GroupId

GroupId

br.com.softplan.security.zap
ArtifactId

ArtifactId

zap-utils
Last Version

Last Version

1.2.1-0
Release Date

Release Date

Type

Type

jar
Description

Description

ZAP Utils
Utils module responsible for ZAP automatic initialization
Project URL

Project URL

https://github.com/pdsoftplan/zap-maven-plugin
Project Organization

Project Organization

Softplan
Source Code Management

Source Code Management

https://github.com/pdsoftplan/zap-maven-plugin

Download zap-utils

How to add to project

<!-- https://jarcasting.com/artifacts/br.com.softplan.security.zap/zap-utils/ -->
<dependency>
    <groupId>br.com.softplan.security.zap</groupId>
    <artifactId>zap-utils</artifactId>
    <version>1.2.1-0</version>
</dependency>
// https://jarcasting.com/artifacts/br.com.softplan.security.zap/zap-utils/
implementation 'br.com.softplan.security.zap:zap-utils:1.2.1-0'
// https://jarcasting.com/artifacts/br.com.softplan.security.zap/zap-utils/
implementation ("br.com.softplan.security.zap:zap-utils:1.2.1-0")
'br.com.softplan.security.zap:zap-utils:jar:1.2.1-0'
<dependency org="br.com.softplan.security.zap" name="zap-utils" rev="1.2.1-0">
  <artifact name="zap-utils" type="jar" />
</dependency>
@Grapes(
@Grab(group='br.com.softplan.security.zap', module='zap-utils', version='1.2.1-0')
)
libraryDependencies += "br.com.softplan.security.zap" % "zap-utils" % "1.2.1-0"
[br.com.softplan.security.zap/zap-utils "1.2.1-0"]

Dependencies

compile (3)

Group / Artifact Type Version
org.slf4j : slf4j-api jar 1.7.14
org.apache.commons : commons-lang3 jar 3.4
commons-io : commons-io jar 2.4

Project Modules

There are no modules declared in this project.

ZAP Maven Plugin

Build Status Maven Central

Check out the ZAP SonarQube Plugin

This plugin makes it easier to integrate OWASP Zed Attack Proxy (ZAP) security tests with the application development and build process for Maven users. With this plugin, you can:

  • Run ZAP analysis during the build of your application;
  • Run authenticated analysis on CAS and on many other applications with complex authentication strategies;
  • Use your Selenium integration tests navigation to feed ZAP;
  • Easily run ZAP analysis during development.

Contents

Usage

Generally, the plugin configuration will follow the format below:

<plugin>
    <groupId>br.com.softplan.security.zap</groupId>
    <artifactId>zap-maven-plugin</artifactId>
    <version>${zap-maven-plugin.version}</version>
    <configuration>
        <!-- Configuration parameters -->
    </configuration>
    <executions>
        <execution>
            <phase>verify</phase>
            <goals><goal>analyze</goal></goals>
        </execution>
    </executions>
</plugin>

If you want to bind the plugin execution to the build lifecycle, it is necessary to define the phase where the plugin will be executed, as well as the goal that will be executed. Optionally, the plugin can be executed by directly calling the desired goal:

mvn br.com.softplan.security.zap:zap-maven-plugin:analyze

The main goal provided is analyze, responsible to execute a ZAP analysis according to the configuration parameters. However, the plugin also provides other goals for more specific situations. The list of available goals is presented bellow:

  • analyze: performs a complete analysis running (by default) the Spider before the Active Scan and starting ZAP automatically if necessary (and closing it after the analysis).
  • startZap: simply starts ZAP (via local installation or Docker).
  • seleniumAnalyze: assumes ZAP is already executing and simply runs the Active Scan, closing ZAP after the analysis. This goal is useful when there are Selenium integration tests that are executed with a proxy to ZAP and the navigation done by the tests should be used instead of the Spider. More on that at Selenium Integration.

The goals that run analysis save the generated reports in the end of the plugin execution. By default, the reports are saved in the directory target/zap-reports within the project. The parameter reportPath can be used to specify another directory (absolute or relative).

Configuration Parameters

Common parameters:

Parameter Description Required? Default
skip Skip the plugin execution (equivalent CLI property: zap.skip) No false

Analysis parameters:

Parameter Description Required? Default
targetUrl URL of the application that will be scanned Yes -
spiderStartingPointUrl Starting point URL for the Spider (and AJAX Spider, in case it runs) No targetUrl
activeScanStartingPointUrl Starting point URL for the Active Scan No targetUrl
context The URLs to be set on ZAP's context (absolute or relative) No targetUrl
analysisTimeoutInMinutes Analysis timeout in minutes No 480
shouldRunAjaxSpider Indicates whether ZAP should execute the AJAX Spider after the default Spider (it can improve the scan on applications that rely on AJAX) No false
shouldRunPassiveScanOnly In case it's true, the Active Scan will not be executed No false
shouldStartNewSession Indicates whether a new session should be started on ZAP before the analysis No true

If the options spiderStartingPoint, activeScanStartingPoint and context are all provided, targetUrl will be ignored. These options are useful when you want to spider through the whole application, but want to run the Active Scan for only a portion of it, for instance. These parameters are very sensitive and should be set accordingly.

ZAP related parameters:

Parameter Description Required? Default
zapPort Port where ZAP is running or will run Yes -
zapHost Host where ZAP is running No localhost
zapApiKey API key needed to access ZAP's API, in case it's enabled No -
zapPath Absolute path where ZAP is installed, used to automatically start ZAP No -
zapJvmOptions JVM options used to launch ZAP No -Xmx512m
shouldRunWithDocker Indicates whether ZAP should be automatically started with Docker No false
zapOptions Options that will be used to automatically start ZAP No See bellow
initializationTimeoutInMillis ZAP's automatic initialization timeout in milliseconds No 120000
reportPath Absolute or relative path where the generated reports will be saved No ${project.build.directory}/zap-reports

To automatically start ZAP, it must be installed locally and the option zapPath must be provided. If the installation folder contains more than one Jar, zapPath should point to the core Jar file. To start ZAP with Docker, Docker must be locally installed and the option shouldRunWithDocker must be passed as true. In both cases, by default, ZAP is initialized with the following options:

-daemon -config api.disablekey=true -config api.incerrordetails=true -config proxy.ip=0.0.0.0 -port ${zapPort}

These options make ZAP start without a GUI, with its API key disabled, able to report errors details via API, and able to be accessed remotely. Besides that, it makes sure ZAP will run on the port specified by the port option. These options can be overridden by the zapOptions parameter.

Authentication parameters:

Parameter Description Required?
authenticationType Define the authentication type: 'http', 'form', 'cas' or 'selenium' Yes, for authenticated analysis
loginUrl Login page URL Yes, for authenticated analysis
username Username used in the authentication Yes, for authenticated analysis
password Password used in the authentication Yes, for authenticated analysis
extraPostData Used to define any extra parameters that must be passed in the authentication request (e.g. domain=someDomain&param=value) No
loggedInRegex Regex that identifies a pattern in authenticated responses (needed to allow re-authentication) No
loggedOutRegex Regex that identifies a pattern in non-authenticated responses (needed to allow re-authentication) No
excludeFromScan Define the URLs regexs that will be excluded from the scan No

HTTP authentication parameters:

Parameter Description Required? Default
hostname The host name of the server where the authentication is done Yes -
realm The realm the credentials apply to Yes -
port The port of the server where the authentication is done No 80

CAS authentication parameter:

Parameter Description Required?
protectedPages Define the URL of a protected page of the application that will be scanned Yes, if authenticationType is CAS

As it was stated, the option protectedPage should have as value the URL of a protected page of the application that will be scanned. For CAS authentication, the login is done directly at the CAS server. Thus, in the first access to the application there will be a redirect to the server, that ends up redirecting the user back to the protected page, since the user is already authenticated. ZAP doesn't support this circular redirect, and because of that the application needs to be accessed at least once before the scan is started. This option defines the URL of a protected page that will be accessed after the authentication and before the scan to make sure the circular redirect won't happen during ZAP's analysis.

Form and Selenium authentication parameters:

Parameter Description Required? Default
usernameParameter Name of the request parameter that holds the username No username
passwordParameter Name of the request parameter that holds the password No password

Selenium authentication parameters:

Parameter Description Required? Default
httpSessionTokens Any additional session tokens that should be added to ZAP prior authentication No -
seleniumDriver The web driver that will be used to perform authentication: 'htmlunit', 'firefox', or 'phantomjs' No firefox
  • It's important to realize that the HtmlUnitDriver lacks complete support for JavaScript. Therefore, it might not always work properly. If a GUI is not available, prefer to use PhantomJS.
  • When using PhantomJS, make sure its executable is in the system's path.

Notice that the parameters context, excludeFromScan, protectedPages and httpSessionTokens accept multiple values, like in the example below:

<excludeFromScan>
    <!-- It doesn't matter how you name the inner tag -->
    <exclude1>http://myapp/logout</exclude1>
    <exclude2>http://myapp/forbidden</exclude2>
</excludeFromScan>
<httpSessionTokens>
    <!-- And even for only one item, the inner tag is necessary -->
    <token>LtpaToken2</token>
</httpSessionTokens>

Authentication Strategies

There are three ways to perform authenticated scans with the ZAP Maven Plugin. The first and most simple one is the HTTP authentication. According to ZAP, three authentication schemes are supported: Basic, Digest, and NTLM, and reauthentication is possible. The hostname, realm and (optional) port parameters are passed to ZAP, which handles the authentication process.

The second is the form based authentication. This should be used for very simple form authentications (like the one found in the bodgeit application), where all you need to authenticate is a simple POST request. This strategy uses ZAP's form authentication mechanism, thus reauthentication is possible (through loggedIn and loggedOutRegex parameters).

It's also possible to run authenticated scans on applications that use CAS. This strategy uses ZAP's script authentication mechanism with a script to perform the CAS authentication. It might not work for all possible CAS configurations (there are many), and, as with the form authentication, reauthentication is possible.

The last strategy uses Selenium. The idea is to perform the authentication via Selenium, and pass to ZAP the session created (i.e. the session cookie). This should work in most situations, including more complex form based authentications. However, reauthentication is not possible, so make sure you use the excludeFromScan parameter to exclude the logout URL and avoid logging out during the scan.

Examples

Using a running instance of ZAP

For this to work, ZAP must already be running.

<plugin>
    <groupId>br.com.softplan.security.zap</groupId>
    <artifactId>zap-maven-plugin</artifactId>
    <version>${zap-maven-plugin.version}</version>
    <configuration>
        <!-- If ZAP is running on localhost, there is no need to define zapHost -->
        <zapHost>10.10.3.4</zapHost>
        <zapPort>8080</zapPort>
        <targetUrl>http://localhost:8090/testwebapp</targetUrl>
    </configuration>
</plugin>

Starting ZAP automatically

For ZAP to be automatically started, the option zapPath must be provided with the directory where ZAP is installed.

<plugin>
	<groupId>br.com.softplan.security.zap</groupId>
	<artifactId>zap-maven-plugin</artifactId>
	<version>${zap-maven-plugin.version}</version>
	<configuration>
		<zapPort>8080</zapPort>
		<targetUrl>http://localhost:8090/testwebapp</targetUrl>
		<zapPath>C:\Program Files (x86)\OWASP\Zed Attack Proxy</zapPath>
	</configuration>
</plugin>

There is no need to inform the host in this case, since it will obviously be localhost.

Starting ZAP with Docker

If ZAP is not installed, you can still start ZAP with Docker. For this, Docker must be installed and the option shouldRunWithDocker must be provided with value true.

<plugin>
	<groupId>br.com.softplan.security.zap</groupId>
	<artifactId>zap-maven-plugin</artifactId>
	<version>${zap-maven-plugin.version}</version>
	<configuration>
		<zapPort>8080</zapPort>
		<targetUrl>http://localhost:8090/testwebapp</targetUrl>
		<shouldRunWithDocker>true</shouldRunWithDocker>
	</configuration>
</plugin>

Form authentication example

<plugin>
	<groupId>br.com.softplan.security.zap</groupId>
	<artifactId>zap-maven-plugin</artifactId>
	<version>${zap-maven-plugin.version}</version>
	<configuration>
    	<zapPort>8080</zapPort>
		<targetUrl>http://localhost:8180/bodgeit</targetUrl>

		<authenticationType>form</authenticationType>
		<username>user</username>
		<password>pass</password>
		<loginUrl>http://localhost:8180/bodgeit/login.jsp</loginUrl>
		<loggedInRegex><![CDATA[\\Q<a href=\"logout.jsp\">Logout</a>\\E]]></loggedInRegex>
	</configuration>
</plugin>

Notice that it might be necessary to use the tag <![CDATA[]]> so the characters used within the parameter value are not parsed as part of the XML.

CAS authentication example

<plugin>
	<groupId>br.com.softplan.security.zap</groupId>
	<artifactId>zap-maven-plugin</artifactId>
	<version>${zap-maven-plugin.version}</version>
	<configuration>
		<zapPort>8080</zapPort>
		<targetUrl>https://localhost:8443/myapp</targetUrl>

        <authenticationType>cas</authenticationType>
        <username>user</username>
        <password>pass</password>
        <loginUrl>https://localhost:8443/cas-server/login</loginUrl>
        <protectedPages>
            <protectedPage>https://localhost:8443/myapp/protected/index</protectedPage>
        </protectedPages>
        <loggedOutRegex><![CDATA[\\QLocation: https://localhost:8443/cas-server/\\E.*]]></loggedOutRegex>
	</configuration>
</plugin>

A good way to achieve re-authentication with CAS is defining the loggedOutRegex with a value like \QLocation: https://your.domain/your-cas-server\E.*. Unauthenticated responses will be redirects to the CAS server, so this is the easiest way to identify that there was a redirection to the CAS server and thus the user is not logged in.

Selenium authentication example

<plugin>
	<groupId>br.com.softplan.security.zap</groupId>
	<artifactId>zap-maven-plugin</artifactId>
	<version>${zap-maven-plugin.version}</version>
	<configuration>
		<zapPort>8080</zapPort>
		<targetUrl>http://localhost:8090/testwebapp</targetUrl>

        <authenticationType>selenium</authenticationType>
        <username>user</username>
        <password>pass</password>
        <loginUrl>http://localhost:8090/testwebapp/login</loginUrl>
        <httpSessionTokens>
            <token>LtpaToken2</token>
        </httpSessionTokens>
        <seleniumDriver>phantomjs</seleniumDriver>
	</configuration>
</plugin>

Selenium Integration

If your application has Selenium integration tests that navigate through the application, it might be interesting to feed ZAP with the visited pages instead of relying on ZAP's Spider. The Spider can't ensure a complete navigation through the application. Besides that, by feeding ZAP with the visited pages, it's possible to easily define the analysis scope, since ZAP's tests will only be executed on the pages that were visited during the tests.

With that in mind, the goals startZap and seleniumAnalyze were developed. With them, it's possible to start ZAP before the integration tests and execute the analysis after the tests, using the navigation done by the tests.

The first step to feed ZAP with your integration tests navigation is to ensure the tests use ZAP as a proxy. This way, all requests made during the tests execution go through ZAP. The configuration needed for the most common drivers are presented bellow:

    WebDriver driver;

    // HtmlUnit
    driver = new HtmlUnitDriver();
	((HtmlUnitDriver) driver).setProxy(ZAP_HOST, ZAP_PORT);
	
	// Firefox
	FirefoxProfile profile = new FirefoxProfile();
	profile.setPreference("network.proxy.type", 1); // 1 = 'Manual proxy configuration'
	profile.setPreference("network.proxy.share_proxy_settings", true);
	profile.setPreference("network.proxy.no_proxies_on", "");
    profile.setPreference("network.proxy.http", ZAP_HOST);
    profile.setPreference("network.proxy.http_port", ZAP_PORT);
    driver = new FirefoxDriver(profile);
	
	// Chrome
	Proxy proxy = new Proxy(); // org.openqa.selenium.Proxy
	proxy.setHttpProxy(ZAP_HOST + ":" + ZAP_PORT);
	DesiredCapabilities capabilities = DesiredCapabilities.chrome();
	capabilities.setCapability("proxy", proxy);
	driver = new ChromeDriver(capabilities);

With that done, all that remains are the plugin goals configuration:

<plugin>
    <groupId>br.com.softplan.security.zap</groupId>
    <artifactId>zap-maven-plugin</artifactId>
    <version>${zap-maven-plugin.version}</version>
    <configuration>
		<!-- whatever configuration -->
	</configuration>
	<executions>
		<execution>
			<id>start-zap</id>
			<phase>pre-integration-test</phase>
			<goals><goal>startZap</goal></goals>
		</execution>
		<execution>
			<id>selenium-analyze</id>
			<phase>post-integration-test</phase>
			<goals><goal>seleniumAnalyze</goal></goals>
		</execution>
	</executions>
</plugin>

This will ensure that ZAP is started before the integration tests, so the tests can be proxied through it. Also, with that configuration ZAP will only execute the analysis after the tests execution.

br.com.softplan.security.zap

Softplan

Versions

Version
1.2.1-0
1.2.0-0
1.0.1-0