Configure the Job to use Environment Inject Variables

1. Env Inject – Documentation, how to use Env Inject in your own job configuration can be found here.

   Info: Makes it possible to have an isolated environment for your jobs by setting up job defined environment variables.

   Warning: Not available when run in Pre-Build, the build will result in FAILURE if attempted.

Configure the Job to Execute ZAP

Admin Configurations

1. workspace
    
   • Represents the directory to the job's workspace on the Slave machine.

     Info: In this directory the ZAP session(s), report(s) and log(s) will be saved.

2. Host and Port

   Required: The host and port set here should be the SAME set in Firefox and in the ZAP security tool.

   Notice: This should be the IP address of the Slave (the machine where ZAP security tool is installed).

   Info: Can override the default ZAP host (e.g. "localhost") and default ZAP port (e.g. "8090") for this job which were set under Jenkins Settings: ZAP Proxy Settings. Overriding the host and/or port allows to run multiple concurrent builds on different host(s) and/or port(s).

   Info: Accepts System Environment Variables, Build Variables as well as Environment Inject Plugin Variables(cannot be used during pre-build).

Startup

• Run as Pre-Build Step – Leave unchecked
   

Java

• Select the JDK used by ZAP – Leave as inheritFromJob

  Notice: ZAP security tool requires Java 7 or higher to run.

Installation Method

ZAP Jenkins plugin requires Zed Attack Proxy 2.5.0+ to run and can be installed via either of the following methods:

• Custom Tools – Documentation, how to setup ZAP for use with Jenkins and the Custom Tools plugin can be found here.

  Info: A generic tool installer. You define how tools get installed, and the plugin will automatically install them when needed.

• System Installed – Documentation, how to setup ZAP for use with Jenkins as a System Installation can be found here.

  Info: Requires ZAPROXY_HOME to be defined as a System Environment Variable.

Run Configurations

Clicking the Advanced... button, a new block appears below:
 

1. Initialization Timeout
    
   • Total time (in seconds) to wait for ZAP to initialize.

     Warning: If ZAP has not been initialized after the specified time then the program is stopped and the build is marked as a FAILURE.

2. Add ZAP command line option
    
   • This fields allows you to add ZAP command line options.

     Recommend: If having followed the System Installed guide above, it is recommended to set the installdir command line option.

     Info: Please see HelpCmdline for more information.

     Warning: Adding a ZAP command line option can interfere with other UI options of the ZAP Jenkins plugin. Use with caution!

ZAP Settings

• Path
   
  • Path to the 'default directory' that ZAP uses on the Slave (the machine where ZAP security tool is installed).

    Info: Please see FAQconfig for more information.

    Info: Accepts System Environment Variables, Build Variables as well as Environment Inject Plugin Variables(cannot be used during pre-build).

    Warning: Do not override with command line options.

Session Management

• Load Session
   
  • Select a ZAP session to load. The session must be stored in the 'Jenkins Job's Workspace'.
     

Session Properties

1. Context Name
    

   • Provide a unique name for the context.

     Info: Append the Build Variable BUILD_ID to the Context Name to ensure a unique name. e.g.  

     My Context ${BUILD_ID}

     Info: Accepts System Environment Variables, Build Variables as well as Environment Inject Plugin Variables(cannot be used during pre-build).

     Warning: The context should not exist in the loaded session.

2. Include in Context
    

   • List of URLs which will be included in the Context unless also excluded.

     Info: Each line is a URL Regex and should be in the form of:
      
     e.g. http://localhost:8180/bodgeit.*
     e.g. \Qhttp://localhost:8180/bodgeit\E.*
     e.g. http://localhost:8180/bodgeit/logout.php
     e.g. \Qhttp://localhost:8180/bodgeit/logout.php\E

     Info: Accepts System Environment Variables, Build Variables as well as Environment Inject Plugin Variables(cannot be used during pre-build).

3. Exclude from Context
    

   • List of URLs which will be excluded from the Context.

     Info: Each line is a URL Regex and should be in the form of:
      
     e.g. http://localhost:8180/bodgeit.*
     e.g. \Qhttp://localhost:8180/bodgeit\E.*
     e.g. http://localhost:8180/bodgeit/logout.php
     e.g. \Qhttp://localhost:8180/bodgeit/logout.php\E

     Info: Accepts System Environment Variables, Build Variables as well as Environment Inject Plugin Variables(cannot be used during pre-build).

4. Alert Filters – Placeholder for New Feature Addition. (Go to step 5. for now)
   

    

5. Authentication – ZAP will perform the Attacks (Spider and/or Active Scan) as an authenticated user.
    
   • Form-Based – Documentation, how to setup the context to use Form-Based Authentication can be found here.
      
   • Script-Based – Documentation, how to setup the context to use Script-Based Authentication can be found here.

Attack Mode

1. Starting Point
    
   • The starting point is the request you desire from which you would like all attacks to originate from.

     Info: Specify a URL as the starting point in the form of:
      
     e.g. http://localhost:8180/bodgeit/

     Info: Accepts System Environment Variables, Build Variables as well as Environment Inject Plugin Variables(cannot be used during pre-build).

2. Spider Scan – Evaluates URL for Passive Alerts.
    
   • Recurse – Default: True

     Info: If you select 'Recurse' then all of the nodes underneath the one specified will also be used to seed the spider.

   • Subtree Only – Default: False

     Info: If you select 'Subtree Only' the spider will only access resources that are under the starting point (URI). When evaluating if a resource is found within the specified subtree, the spider considers only the scheme, host, port, and path components of the URI.

   • Max Children to Crawl – Default: 0

     Info: Specify the 'Max Children to Crawl'. This parameter limits the number of children that will be crawled at every node in the tree. This is useful for data driven applications that have large numbers of 'pages' that are in fact exactly the same code but containing different data, for example from a database. By default this is set to zero which means there are no limits applied to the number of child nodes crawled.

3. AJAX Spider
    
   • In Scope Only – Default: False

     Info: If you select 'In Scope Only' then any URLs which are out of scope will be ignored.

     Notice: Does not support authentication.

4. Active Scan – Evaluates URL for Active Alerts.
    
   • Policy

     Info: Select a ZAP policy to use for the Active Scan. The policies must be stored in the Path provided for 'ZAP Settings'. "Default Policy" is used if no policy is specified.

   • Recurse – Default: True

     Info: If you select 'Recurse' then all of the nodes underneath the one selected will also be scanned. Custom input vectors are only supported if this option is not selected.

Finalize Run

1. Generate Reports – The security alerts found by ZAP will be saved into a report file in the build's workspace.
    
   • Generate Report – Documentation, how to generate the default report(s) can be found here.

     Info: This generates a new report containing the alerts raised in a supported format (.html , .xml ).

     Info: This is the default method of report generation for ZAP.

   • Export Report – Documentation, how to export customized report(s) can be found here.

     Required: A plugin called Export Report which can be found in ZAP > Manage Add-ons > Marketplace.

     Info: An official ZAP marketplace extension which allows you to customize content and export in a desired format (.xhtml , .xml , .json ). Supports GUI, command line and API calls.

2. Create JIRA Issues – Documentation, how to Create JIRA Issues can be found here.

   Warning: An unofficial ZAP extension which allows you to create JIRA issues. It is an add-on NOT bundled with ZAP, nor available in the marketplace. DOWNLOAD AT YOUR OWN RISK AND DISCRETION.

Continue to Configure the Job's Post Build Actions