Skip to end of metadata
Go to start of metadata

Deprecated: This plugin has been removed from the Jenkins Plugin Center, it is not available for new downloads but will be available for existing users.

 
Archived versions of this plugin remain available for download. Source code is available on GitHub.
 
Due to data incompatibility, the plugin will no longer be distributed. Please migrate to the Official OWASP Zed Attack Proxy Jenkins Plugin.

This plugin allows you to launch the security software ZAProxy (https://www.owasp.org/index.php/OWASP_Zed_Attack_Proxy_Project) via Jenkins.
With this plugin, you can spider and scan a target URL, save alerts security reports in all available formats in ZAProxy (xml, html) and also load and save ZAP sessions.

It is recommended to use the “Custom Tools Plugin” plugin in order to make sure to have the ZAProxy tool available during build. This plugin allows you to install the ZAProxy tool on the node (master or slave) used by Jenkins during build and thus be able to use features of zaproxy-plugin.

Plugin Information

No information for the plugin 'zaproxy' is available. It may have been removed from distribution.

“Custom Tools Plugin” configuration in administrator mode

Once installed, add a tool in “Custom Tools” section in Jenkins administrator mode. Name the tool “ZAProxy” for example and add an installer. In case of *.zip/*.tar.gz installer, the URL will look like this http://sourceforge.net/projects/zaproxy/files/2.4.0/ZAP_2.4.0_Core.tar.gz/downloadhttp://sourceforge.net/projects/zaproxy/files/2.4.0/ZAP_2.4.0_Core.tar.gz/download https://github.com/zaproxy/zaproxy/releases/download/2.4.1/ZAP_2.4.1_Core.tar.gz for the ZAProxy version 2.4.0. Finally, specify a sub-directory for the archive extraction (e.g ZAP_2.4.0). 

“zaproxy-plugin” configuration in administrator mode

Once “zaproxy-plugin” is installed, two fields are available in Jenkins administration allowing to specify the host and port on which ZAProxy will run. The Jira Base Url and Jira Username and thePassword fields are required ONLY if you are planning to use the create jira issues feature. If you are not using this feature then those 3 fields can be kept blank. 


“Custom Tools Plugin” configuration in jobs
In “Build Environments” section, tick the “Install custom tools” box and select the tool corresponding to ZAProxy.

“zaproxy-plugin” configuration in jobs

In order to use the plugin, add “Execute ZAProxy” build step. Several parameters are available and are grouped into three categories below.  

Configuration

This category shows to the user the plugin configuration informations in Manage Jenkins -> Configure System.

Workspace used: Represents the build workspace. It is in this repository where files will be saved (security reports, ZAProxy sessions).

Override ZAProxy host: Host when ZAProxy is used as a proxy. The default value is specified in administration mode and can be overridden here.

Override ZAProxy port: Port when ZAProxy is used as a proxy. The default value is specified in administration mode and can be overridden here.

Leaving the user the possibility to override ZAProxy host and port, it allows to run 2 or more builds at the same time but with different port and/or host.

Startup

This category allows setup ZAProxy launch during build.

Start ZAProxy in a pre-build step: If this box is checked, ZAProxy is started before all other build step (i.e. in a pre-build step). It can be used in harmony with a Selenium build step to let ZAProxy to catch all events throwing by Selenium (so, ZAProxy is used as a proxy: https://github.com/zaproxy/zap-core-help/wiki/HelpStartProxies).

The Selenium build step must be placed before the ZAProxy build step. So the lifecycle is Start ZAProxy > Run Selenium Tests > Scan urls with ZAProxy.

JDK: You can choose the JDK to use to start ZAProxy. ZAProxy requires Java 7 to run, so you must choose at least JDK 7.

Then comes a choice for how ZAProxy is installed:

  • ZAProxy is installed by Jenkins: indicates that ZAProxy is installed with a Jenkins tool (like Custom Tools Plugin). The user must choose the ZAProxy tool from the list of installed tools.
  • ZAproxy is already installed: indicates that ZAProxy is already installed on the machine where the build is done. The user must then enter the environment variable that points to the path where ZAProxy is installed on the machine.

Advanced

Clicking the advanced button, a new block appears below :

Timeout for ZAProxy initialization: This is the maximum waiting time for ZAProxy is properly initialized. If ZAProxy has not finished its initialization, then the build fails.

Add ZAProxy command line option: You can configure the command line option and his value (if necessary) in this two appropriate fields. You can add as many command line as you want with the "Add command line option" button and delete them with the "Delete command line" button. More information on https://github.com/zaproxy/zap-core-help/wiki/HelpCmdline

Add a ZAP command line option can interfere with other UI option of the plugin. Be careful !

Setup

Load session: Allows the user to load a ZAProxy session. The session must be in a folder's workspace, for example workspace/myFolder/mySession.session and the user must choose the wanted session in the list. If a session is loaded, it is not necessary to save it at the end because ZAProxy backup in real time until the session is closed.

Target URL: The URL will endure ZAProxy attacks.

URL to exclude from context : the URL(s) that ZAP has not to scan in order to prevent some edge effects (logging out while performing  an authenticated scan, performing dangerous actions like deleting users, …)

ZAProxy default directory: Uses the specified directory instead of the default one for ZAProxy (https://github.com/zaproxy/zaproxy/wiki/FAQconfig). This allows to choose your policy below (if the specified directory contains policy files into a "policies" folder) or the authentication scripts (if the specified directory contains authentication scripts files into a "scripts/authentication" folder).

Choose policy to use: This list contains all policy files located in "specifiedDirectory/policies". If no policy file is chosen, so the default policy file will be used for the scan.

Unauthenticated scan : ZAP will perform teh scan with no user profile

You need ZAProxy 2.4.2 or higher to use this functionnality.

  • Scan URL : If this box is checked, ZAProxy will do a scan (active scan ) of the specified URL.

Authenticated scan :

ZAP will perform the scan in the point of view of the defined user.Two authentication modes are available :

  • Form based authentication : can be used in the most of cases

  • Login URL : URL of the login page.
  • Logged in indicator : Indication that the Authentication is successful (existence of a sign out Link. This should be insert as a regular expression
  • POST Username parameter : Parameter (variable name) that used to carry user name for the authentication (https://github.com/zaproxy/zaproxy/wiki/FAQformauth).
  • POST password parameter : Parameter (variable name) that used to carry password for the authentication (https://github.com/zaproxy/zaproxy/wiki/FAQformauth).
  • Username : Username for authentication.
  • Password : Password for the given user for authentication.
  • Other post data : Other post data needed to perform the authentication scenario (e.g : action=login&perform=yes)
  • Scripts based authentication : can be used in the rest of cases where authentication process is more complicated (redirection to an authentication server,...)


In order to work correctly the full path to the scripts directory must be filled in the ZAP config file "config.xml" between the tags :<dirs></dirs>.Be sure that this path corresponds to the one filled in "ZAProxy default directory" text box or to the default one.You can find here the authentication script used in the example above : BodgeIt Store Authentication.js

Generate report: If this box is checked, the security alerts emitted by ZAProxy will be saved into a file in the build's workspace. File settings are:

  • Choose format report: This is a list of all available formats to save the report. You can selected several formats with CTRL + click.
  • Filename for report: The file name that will contain the security alerts. The addition of an extension is not required and user can user environment variables to rename the report (e.g : report_${BUILD_NUMBER})

With ZAproxy version 2.4.2, a new option is set by default. This option merge related alerts in report. If you want get back to the classic report, add a command line typing "-config" in command line option field and "alert.mergeissues=false" in command line value field.

Save session: Saves the current ZAProxy session in the build's workspace. If a session is already loaded, it is not necessary to save it again because it is automatically persisted as we go along.

  • Filename for session: The file name that will contain the ZAProxy session. If a session is loaded and the user saves the session with the same name, the build will fail.

Create Jira Issues (version 1.2.0)

This is an optional feature which can be ONLY used with Jira issue Creator Plugin for ZAP installed. The plugin can be installed by following the instructions mentioned in this document (pdf version here). A screenshot of this feature is attached below. 

The Jira Base Url, Jira Username and Jira Password has to be set in the global configuration of Jenkins. In using this feature the project key has to be set along with an assignee and the issues can be created depending on the alert level of each issue. A user can choose to export alerts as jiras depending on their threat level. At least one alert level has to be checked or else the plugin would fail. 
Filter issue URLS by resource type is an optional feature which can be used to categorize the urls by resource type. (eg css,html, js, jsp etc..) 

Observation

Due to an issue in zaproxy (https://github.com/zaproxy/zaproxy/issues/1617), exceptions can be thrown when you execute the plugin on headless machine although ZAProxy is launched in daemon (headless) mode. To bypass this problem, you can export DISPLAY variable before to start ZAProxy like that: "DISPLAY=:0.0". This variable can set in Jenkins -> Configure System -> Global properties or with a plugin like EnvInject Plugin. 

If it's not enough, you can install Xvfb on the node of the build to emulate frame buffer X11 server. After Xvfb is installed and running, export the DISPLAY variable like previously (with the Xvfb configuration) and launch the build. It should work.

Another solution is to use the Xvfb jenkins plugin to install and use Xvfb. It's certainly the best solution pending the issue in zaproxy is resolved. 

Version history

Version 1.2.1 (Feb 27, 2016)

Version 1.2.0 (Jan 26, 2016)

  • Added support for the ZAP Jira issue creator plugin. 

Version 1.1.9 (Dec 23, 2015)

  • Fix Github issue #4.
  • Fix Github issue #10.
  • Add the possibility to exclude some URLs from scan (log out url, dangerous actions,...)
  • Add the possibility to make either an unauthenticated or authenticated scan.

Version 1.1.8 (Oct 24, 2015)

Version 1.1.7 (Sep 15, 2015)

  • Fix JENKINS-29687 issue.
  • Minor fix according to the new zap-api (zap-api-2.4-v6).

Version 1.1.6 (Sep 14, 2015)

  • Added Authentication and Ajax spider features.

Version 1.1.5 (Jul 17, 2015)

  • Fix a bug introduced by 1.1.4 version.

Version 1.1.4 (Jul 9, 2015)

  • Add the possibility to override ZAP proxy host and port for each build.  

Version 1.1.1 (May 21, 2015)

  • Bug correction with ZAP command line option.

Version 1.1.0 (May 20, 2015)

  • Problem's resolution when the plugin is used with slaves. Now, ZAProxy is correctly launched on the node.
  • Add the possibility to choose a specific JDK to start ZAProxy.

Version 1.0.5 (Apr 29, 2015)

  • Modification to load session : now, the user must choose a session in the list instead of type the relative path.
  • Modification to generate report. Now, "true" report are generated instead of write alert security in a file (for more informations, see here). With this modification, json format is not available.

Version 1.0.4 (Apr 27, 2015)

  • Resolution of an internal conflict with imported library. 

Version 1.0.3 (Apr 24, 2015)

  • Remove the possibility to override ZAP config using "-config".
  • Add the possibility to add ZAP command line option (more generic than just use "-config")

Version 1.0.2 (Apr 23, 2015)

  • Add the possibility to choose a policy file for a scan.
  • Add the possibility to override ZAP config using "-config".

Version 1.0.1 (Apr 16, 2015)

  • Minor changes.

Version 1.0.0 (Apr 14, 2015)

  • Initial version.

29 Comments

  1. Hi there,

    Is there any way I can configure the scan policy that ZAP should use while passively and actively scanning an application using this plugin? I haven't been able to find any support in the ZAP command line, but was hoping this plugin allows using a scan policy.

    Thanks.

    1. Hi Divesh,

      It's not possible to configure ZAP scan policy through this plugin for the moment. I will have a look if it's possible to add this feature.

      Thanks for your feedback.

  2. Hello again,

    I might have misunderstood the usage of this plugin, but when I add ZAProxy as a build step, it start up the server and then shuts it down before the following build step.

    What I intend to do is

    1.) Start ZAP.

    2.) Run a build step that runs a Selenium test. This test uses ZAP as a proxy to route all its calls.

    3.) When the test completes, shutdown ZAP.

    When I use the plugin, Step 1 executes, immediately followed by step 3. This means that my Selenium tests in step 2 fail because ZAP is not running.

  3. Figured out why this was happening.

    I was adding the ZAProxy build step at the beginning of the build. So both the "prebuild()" and "perform()" methods executed one after the other and shut ZAP down.

    Got the desired behavior by putting the ZAProxy build step as the last step of the build. Might be worth adding this info on the documentation?

    Thanks for this plugin!

    -Divesh

    1. Yes, that's right !

      The Selenium build step must be placed before the ZAProxy build step and "Start ZAProxy in a pre-build step" must be checked in order to start ZAP before running your Selenium test.

      I will add it to the wiki, thanks !

      1. Thanks very much Ludovic!

  4. Hello Ludovic,

    Would it be possible to add supoort in this plugin for accepting command line arguments that ZAP can use? For example, the "-config" switch allows us to change the default scan policy that ZAP is loaded with by default. I can, therefore, start ZAP with my custom policy using

    zap.bat -config defaultPolicy=weak_scan_policy

    I can see that the plugin uses the "-daemon", "-host" and "-port" options by default. I think adding support for the "-config" option shouldn't be too hard.

    Thanks very much.

    1. Hi Divesh,

      It's a good idea to use "-config" but are you sure the following command line

      zap.bat -config defaultPolicy=myPolicy

      will override the default policy when you start ZAP ? Because I have tested and it's not working.

      Otherwise, I have got an other solution to load policy files but it's a bit annoying.

      The steps are the following :

      1. Setup rules in ZAP.
      2. Copy your policy files located in the default directory that ZAP uses (https://code.google.com/p/zaproxy/wiki/FAQconfig) into your job workspace, under OWASP_ZAP/policies.
      3. In the plugin configuration, you can see the list of policy files and choose one.

      For the moment, this feature is not added to the plugin on this page, I have to deal with that in depth.

  5. Hello Ludovic,

    Thanks for getting back to me. I had provided an incorrect command to set the default scan policy. Apologies.

    The correct command to set the default active scan policy is

    zap.bat -config scanner.defaultPolicy=myPolicy

    If you look in "OWASP_ZAP/config.xml", you'll notice that there is a "<defaultPolicy>" element nested within a "<scanner>" element. Hence, we should set its value using "scanner.defaultPolicy".

    The solution you've suggested sounds very nice - less tinkering with the command line and more UI based configuration. I cannot wait to try it :). However, I still believe that adding a catch all command line configuration option can benefit this plugin if, for example, ZAP adds new command line options tomorrow. Existing users of the plugin won't have to wait for a new version of the plugin for using the new command line options.

    Let me know what you think.

    Regards,

    Divesh

    1. Hello Divesh,

      Ok for this command, i didn't see "<defaultPolicy>" in "config.xml" because I didn't configure the default policy to use in ZAP UI :(

      I have improved my solution. Copy files is not longer necessary, but you need to type the absolute path of the default directory that ZAP uses and choose your policy file in the list.

      And I think your suggestion to catch all command line configuration option is a very good idea, I will work on it as soon as possible !

      I will release a new plugin version when this two features will be correctly added.

      Thanks for your feedback Divesh !

      Regards,

      Ludovic.

  6. Thanks for the command line and custom scan policy support Ludovic!!! I'll try it next week and let you know how it works.

    I appreciate your support on this.

    Cheers,

    Divesh

    1. Hi Divesh,

      I'm looking forward your feedbacks !

      I have resolved an internal problem with the 1.0.3 version so you must use the 1.0.4 if you want to test it !

      Regards,

      Ludovic.

  7. Hello Ludowic,

    For some reason, I'm not able to get the plugin to start ZAP on any port. I'm using a Linux slave, and this is the log that I get in the Jenkins build log -

    Cannot listen on port 18050

    I have confirmed that there is no other process listening on that port on the slave.

    However. if I start ZAP using a Shell build step in Jenkins (by invoking zap.sh -daemon -host localhost -port 18050), it works just fine.

    I *think* it may have something to do with the ProcessBuilder being used and its permissions.

    Did you ever face this issue?

    1. No, I have never encountered this issue. Have you ever test this environment with a previous version of the plugin ?

  8. This is the first time that I've used the plugin in our actual test environment (ver 1.0.4). The plugin works just fine when use it on my local machine. This leads me to believe that it may be an OS level or environment issue.

    I'll keep you posted.

    1. If you use "localhost", can you replace "localhost" by "127.0.0.1" ? (see here).

      1. Tried that already, does not make any difference.

        I saw in the code that a ProcessBuilder runs the zap.sh script by constructing the complete command line. I wonder if running a script from Java has any security implications?

        Thanks for the suggestion, I'll keep digging :)

        1. Normally, if a security problem is detected by Java, an exception is launched.

          Can you give me your test environment (machine on master/slave, physical/virtual machine, ...).

          Can you also send me by email (click on my name to see it) :

          • "zap.log" of the slave machine (normally located in "~/.ZAP" on linux machine) 
          • "config.xml" in the same location ?

          Thank you for your feedback !

          1. In this case, ZAP catches the exception and logs an error message ("Cannot listen on port"). I'll send you more details via mail.

            Cheers,

            Divesh

  9. Would you please open the issue tracker in your Github repository? It would be best way to report possible bugs and to ask new features. Thanks.

    1. Ok, it's done. Thanks !

  10. Hi, I have been testing the ZAP Plugin the last fews days and something i would love to be able to do is start multiple instances of zap using different -port and -fir parameters at start up.

    The plugin takes the host and port from the global settings. Is there a way of overiding or parameterising these so each build could pass in a different port and host name? So one build would start and create and instance of zap on localhost:8080 then
    another build for a different application starts and creates an instance of zap on localhost:8081 so they dont interfere with each other.

    Does that sound possible?

    Thanks

    1. Hi Shaun,

      It's a good idea to override port and host name for each build. But you must know some things before :

      • If you are on the SAME machine, it's not possible to have 2 ZAP instances running at the same time unless you specify 2 differents 'home' directories or if you have 2 differents ZAP installations.
      • If you start builds on differents nodes using ZAP, it should be work at the same time

      So, tell me, what is your configuration ?
      Otherwise, it sounds possible to override port and host name for each job, but I should add some modifications to the plugin.

      Regards,
      Ludovic.

      1. Thanks for the reply.

        Yea the idea is each build will start ZAP using its own -port and -dir ("home" directory) parameters on the same Jenkins server.

        Build One

        zap.sh -daemon -host localhost -port 8080 -dir /data/apps/ZAP_2.4.0/instance/8080

        Build Two

        zap.sh -daemon -host localhost -port 8081 -dir /data/apps/ZAP_2.4.0/instance/8081

        Both running on the same Jenkins server (master)

        In this case overiding the host is not needed but it might be useful.

        Thanks

        Kind Regards

  11. I get the following when I use this ZAProxy plugin :Perform ZAProxy
    Skip loadSession
    Spider the site https://www.mywebsite.com
    103089 ZAP-ProxyThread-2 WARN org.zaproxy.zap.extension.api.API - handleApiRequest error: Invalid or missing API key
    Invalid or missing API key (bad_api_key)

    My ZAP Plugin is version 1.1.5
    My ZAP version is 2.4.1

    I start ZAP as a pre-build step and ZAP is already installed on the jenkins machine. I see ZAP start up in my console log.

    The last line of the ZAP startup is :
    2037 ZAP-daemon INFO org.parosproxy.paros.extension.ExtensionLoader  - Initializing Tips and Tricks

    Has anyone else seen anything related, or have any ideas why I get this error?

    Thank you.

    1. Hi Shawn,

      Look at the beginning of this wiki. Due to the new ZAP version (2.4.1), you must type in "Advanced" menu : "-config" in option field and "api.disablekey=true" in value field.

      Regards,

      Ludovic.

  12. HI 

    is there a posibility to use this to test web application that has a authentication. 

    i have save and uploaded a session but i think when it scans it invalidate the session by login out.

    Thanks

    Thilina

  13. Hi, I am using the ZAProxy plugin in Jenkins and I am having some issues with reporting:

    After running the spiders + AJAX Spider + scanner the log console file showed:

    Total alerts: ApiResponseElment numberofAlerts = 280
    Total messages: ApiResponseElement numberoFMessages = 8648

    However when looking at the HTML report generated at the Workspace folder I only get 2 Medium and 2 Low alerts. 

    Anyone had the same issue? How can I get the full report available?

    Thanks in advance

  14. Hello,

    I managed to run the plugin successfully as the single step in the build and as the last step in a build with multiple steps.

    The build is successful and the html report is generated, and as expected, 2 high alerts are generated for xss and sql injection vulnerabilities.

    However, I'm wondering how to make the build actually fail when high alerts are found in this step. Could you please provide an example ?

    Thank you !