ZAP Maven Plugin

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
• Configuration Parameters
• Authentication Strategies
• Examples
  • Using a running instance of ZAP
  • Starting ZAP automatically
  • Starting ZAP with Docker
  • Form authentication example
  • CAS authentication example
  • Selenium authentication example
• Selenium Integration

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:

Analysis parameters:

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:

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:

HTTP authentication parameters:

CAS authentication parameter:

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:

Selenium authentication parameters:

• 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.

⚡