Support
Continuous Integration Systems

Integrating Invicti Enterprise with Jenkins

This document is for:
Invicti Enterprise On-Demand, Invicti Enterprise On-Premises

Jenkins is an automation server that lets software developers build automation into their projects by supplying plugins. You can extend Jenkins's functionality by using the Invicti Enterprise Scan Jenkins plugin.

This topic explains how to install and configure the new Invicti Enterprise Scan Jenkins Plugin with Jenkins Freestyle Projects. You can use Invicti Enterprise's advanced integration functionality with the plugin. So, you can launch automated scans and view reports of vulnerabilities in Jenkins.

Also, you can use our plugin with Jenkins Pipeline Projects, by adding the plugin script to your pipeline, which is generated by the Integration Script Generator in the Jenkins Integration window.

For further information, refer to What Systems Does Invicti Integrate With?

There are two scenarios to integrate Invicti Enterprise with Jenkins:

  1. Using the Invicti Enterprise Plugin for Jenkins. (This allows for a simplified configuration that can handle many use cases.)
  2. Generating and using Invicti Enterprise’s Integration Script Generator. (For complex cases.)

Prerequisites

  • Get the Invicti Enterprise URL. Depending on the region, your login URL can be one of the following:
  • If US-based: https://www.netsparkercloud.com
  • If EU-based: https://eu.netsparker.cloud
  • If CA-based: https://ca.netsparker.cloud
  • If on-premises: https://yourinvictiserver.com
  • Get the User ID and Token from Invicti Enterprise by following the steps below:
  1. Log in to Invicti Enterprise.
  2. Click your name in the upper right-hand corner, then select API Settings.
  3. On the API Settings page, enter your password.
  4. Copy the User ID and Token information.

Scenario 1. Using the Invicti Enterprise Plugin for Jenkins

Step 1. Downloading and installing the Invicti Enterprise Scan Jenkins Plugin

The plugin is packaged into an .hpi file called jenkins-plugin.hpi. This package has been tested and approved for Jenkins version 2.2+.

There are two ways to do this:

  • From the Plugin Manager in Jenkins
  • From Invicti Enterprise

How to install the Jenkins Plugin from the Plugin Manager

  1. Open Jenkins using an administrator account.
  2. From the main menu, select Manage Jenkins > Manage Plugins.
  3. From the Plugin Manager page, select the Available plugins option.
  1. Into the Filter box, enter 'netsparker'. From the filtered results, select the checkbox next to the Invicti Enterprise Scan plugin, then Install without restart.

  1. When the plugin has completed installation, select the Go back to the top page link.
  2. To use the plugin, restart Jenkins. To restart, from a browser, navigate to:
  • [jenkins_url]/safeRestart (restarts Jenkins after the current builds have completed)
  • [jenkins_url]/restart (forces a restart and builds will not wait to complete)

How to download and install the Jenkins Plugin from Invicti Enterprise

  1. Log in to Invicti Enterprise.
  2. From the main menu, go to Integrations > New Integrations > Jenkins.
  3. From the Use Plugin tab, select Download the plugin and save the file to a location of your choice.

  1. Open Jenkins using an administrator account.
  2. From the main menu, select Manage Jenkins > Manage Plugins.

  1. From the Plugin Manager window, select the Advanced Settings option.
  2. From the Deploy Plugin section, select Choose File.

  1. Select the jenkins-plugin.hpi file you downloaded previously, then Open.
  2. Select Deploy.

  1. To use the plugin, restart Jenkins.

Step 2. Configuring your Jenkins System for Invicti Enterprise Integration

  1. Open Jenkins using an administrator account.
  2. Select Manage Jenkins, then Configure System.
  3. Configure your Invicti Enterprise settings:
  1. Scroll down to the Invicti Enterprise section
  2. Enter the Netsparker Enterprise Server URL and API Token that you retrieved in the How to get the User ID and Token step.
  3. Select Test Connection.
  4. Select Save to confirm.

Step 3. Configure your Jenkins Project to Integrate with Invicti Enterprise

  1. Open Jenkins.
  2. Navigate to your project by selecting the project name.
  3. From the sidebar, select Configure.
  4. Scroll down to the Build Steps section.
  5. Select Add build step, then choose the Netsparker Enterprise Scan option from the drop-down list.
  6. Configure the Scan Settings in the following way:
  1. From the Scan Type drop-down list, choose Incremental, Full (With primary profile), or Full (With selected profile).
  2. From the Website Deploy URL drop-down list, choose the website you wish to scan.
  3. From the Profile Name drop-down list, choose the desired Scan Profile.
  4. From the Report Type drop-down list, choose the desired Report Type.
  5. Set your preferred setting for the section entitled Fail The Build If Scan Contains.
  6. Select Save.

With these settings configured, each time a build is triggered, a scan of the website will also be triggered.

Scenario 2. Generating and Using Invicti Enterprise Integration Scripts

Assumptions for using Invicti Enterprise Integration Scripts

  • To use Integration scripts with Jenkins, you must have already installed and configured the Jenkins plugin in your Invicti Enterprise setup
  • Integration scripts are intended for use with Jenkins Pipeline projects

Step 1. Using Pipeline Script in the Pipeline Project

If you want to use Pipeline projects in Jenkins, you should use this method.

  1. Log in to Invicti Enterprise.
  2. From the main menu, go to Integration > New Integration > Jenkins.
  3. Select Use Integration Script tab.
  4. From the Integration Script Generator section, select the relevant Scan Settings:
  • From the Scan Type field, select an option
  • From the Website drop-down, select a website
  • From the Scan Profile drop-down, select a scan profile (this is not displayed if you select Full with Primary Profile as the Scan Type)
  • To override the Jenkins plugin general settings with specific settings for a particular project, select checkboxes for these options:
  1. Override API Token for Jenkins Pipeline Script; you will need to configure a project parameter for ncApiToken
  2. Override Server URL for Jenkins Pipeline Script
  3. Override Stop The Scan When Build Fails Parameter for Jenkins Pipeline Script
  4. Override Fail The Build If Scan Contains Parameter for Jenkins Pipeline Script

  1. Select Copy to clipboard () in the Pipeline Script field.

Step 2. Adjusting the code snippet to match your pipeline syntax

You need to adjust the snipped based on your pipeline syntax. For further information, see Declarative vs Scripted Pipeline Syntax.

The following is an example of snippet just created.

step([$class: 'NCScanBuilder', ncApiToken: '$APITOKEN', ncScanType: 'FullWithSelectedProfile', ncWebsiteId: '2a8d4f53-de39-46e4-4634-ace503ac99ab', ncProfileId: 'ba4e999a-731a-4786-bdd7-ae660483f1d9', ncStopScan: true, ncSeverity: 'Critical', ncDoNotFail: false, ncConfirmed: false, ncIgnoreFalsePositive: false, ncIgnoreRiskAccepted: false])

If you intend to use scripted pipeline syntax, you would wrap your script snippet within a node{...} section:

node{

  step([$class: 'NCScanBuilder', ncApiToken: '$APITOKEN', ncScanType: 'FullWithSelectedProfile', ncWebsiteId: '2a8d4f53-de39-46e4-4634-ace503ac99ab', ncProfileId: 'ba4e999a-731a-4786-bdd7-ae660483f1d9', ncStopScan: true, ncSeverity: 'Critical', ncDoNotFail: false, ncConfirmed: false, ncIgnoreFalsePositive: false, ncIgnoreRiskAccepted: false])

}

If you intend to use declarative pipeline syntax, you would insert your script snippet into a stage in your pipeline script, like in this example:

pipeline {

  agent any

  stages {

    stage('Hello') {

      steps {

        echo 'Hello World'

      }

    }

    stage('Invicti Scan') {

      steps{

        step([$class: 'NCScanBuilder', ncApiToken: '$APITOKEN', ncScanType: 'FullWithSelectedProfile', ncWebsiteId: '2a8d4f53-de39-46e4-4634-ace503ac99ab', ncProfileId: 'ba4e999a-731a-4786-bdd7-ae660483f1d9', ncStopScan: true, ncSeverity: 'Critical', ncDoNotFail: false, ncConfirmed: false, ncIgnoreFalsePositive: false, ncIgnoreRiskAccepted: false])

      }

    }

  }

}

Step 3. Adding parameters to your Jenkins Project

This example overrides the API Token, and the script snippet assumes that your Jenkins project will supply the APITOKEN environment variable (note the $APITOKEN in the script snippet). To add the parameter:

  1. Open Jenkins.
  2. Navigate to your pipeline project by selecting the project name.
  3. From the sidebar, select Configure.
  4. From the General section, select the This project is parameterised checkbox.
  5. Select Add Parameter, then choose String Parameter. (For this example, we chose the String Parameter. Depending on your project, you can choose a different option.)

  1. To set the parameter's value and name, do the following:
  1. Set the parameter's Name to match the environment variable in your script snippet.
  2. Set the parameter's default value to match. (For this example, it is the API Token value for your Invicti Enterprise user account.)
  3. Select Save.

  1. From your project's sidebar, go to Configure > Pipeline.
  2. Insert your finalized script snippet into the Pipeline script field.
  3. Select Save.

With these settings configured, each time a build is triggered, a scan of the Website will also be triggered.

Checking Pipeline Results

Build Fail Errors

Your pipeline console output will show you when a build fails following an issue being detected by Invicti Enterprise via the Console Output panel.

Scan Reports for Executed Pipelines

If you have enabled the generation of reports for completed scans, the scan report will be reachable from the Netsparker Enterprise Report option in the pipeline sidebar:

Checking Scan Results

The Recent Scans page lists all scans performed. By default, the most recently triggered scan will show at the top of the list.

Examine the Scan Report

Select Report on the scan triggered by your Jenkins Pipeline to go to the scan summary.

Using Build Fail in Jenkins Project

It is possible to configure a failure in the Jenkins build to stop the scan when a vulnerability severity is detected, for projects.

This can be configured using the Severity, Confirmed, False Positive, and Accepted Risk parameters.

  1. Scan Severity: With this option, you choose which severity will fail this build when found in a related scan. If you choose “DoNotFail”, the detected vulnerability does not affect your Jenkins build.

The options for Scan Severity are:

  • DoNotFail
  • Critical
  • High or above
  • Medium or above
  • Low or above
  • Best Practice or above
  1. Confirmed: With this option, you choose to fail this build when a vulnerability found in a related scan is confirmed.

For example, if you choose the Medium or above option from the Scan Severity drop-down and select the Is Confirmed checkbox, the build fails only if the vulnerability has medium or higher severity and that vulnerability is confirmed. Otherwise, the build continues.

  1. False Positive: With this option, you choose not to fail this Jenkins build when the scan identifies a vulnerability set as a False Positive.

For example, if you choose the Medium or above option from the Scan Severity drop-down and select the False Positive checkbox, the build will not fail if the vulnerability has medium or higher severity and that vulnerability is false positive. Otherwise, the build fails.

  1. Accepted Risk: With this option, you choose not to fail this Jenkins build when the scan identifies a vulnerability set as an Accepted Risk.

For example, if you choose the Medium or above option from the Scan Severity drop-down and select the Accepted Risk checkbox, the build will not fail if the vulnerability has medium or higher severity and that vulnerability is accepted risk. Otherwise, the build fails.

Configuring the Jenkins Plugin to Build Fail

In the Jenkins plugin there are 2 options:

Fail the build if scan contains: With this option, you choose which severity will fail this Jenkins build. If you choose “Do not fail the build”, the detected vulnerability will not affect your Jenkins build.

Stop the scan when build fails: With this option, if build fails because of your selections, the scan will be cancelled.

Configuring the Jenkins Plugin to Support Multiple Invicti Enterprise Users and Creating Folder Admin Permissions

Role-Based Strategy authorization is used to allow different users to have access to different folders.

This section follows closely the steps described in Cloudbees' Role-Based Authorization Strategy: Limit folder access article, explaining how to create folder-based admin roles. The end goal is that User1 will have access to Folder1 and User2 will have access to Folder2. Each user will be able to access only their projects in their folders using Invicti Enterprise tokens.

  • Invicti Enterprise Jenkins Plugin handles required the plugins’ installations, so no extra steps are needed there.
  • Here is an example to show how user access can be restricted to specific jobs at both the folder and subfolder level.
  • We created a main folder (Folder1) that contains two different subfolders Folder1/FolderA and Folder1/FolderB.
  • We also created two Freestyle projects, 'job1' and 'job2' in the folders Folder1/FolderA/job1 and Folder1/FolderB/job2 respectively.
  • The main folder name is 'Folder1'.
  • The sub-folder names are 'Folder1/FolderA' and 'Folder1/FolderB'.

After completing the configuration steps, it is good practice to ensure that users have the correct access to the correct folders as described above.

This table lists and explains the role settings used in this example.

User

Role

Pattern

admin

admin

Folder1

Folder1View

Folder1

Folder1_FolderA_user

Folder1FolderA

Folder1/FolderA.*

Folder1_FolderB_user

Folder1FolderB

Folder1/FolderB.*

There are three steps involved in completing the configuration:

  • Configuring Authorization and Managing Roles
  • Assigning Roles
  • Creating Credentials for Users

Configuring Authorization and Managing Roles

First, you need to configure authorization and roles in Jenkins.

How to Configure Authorization and Manage Roles

  1. Open Jenkins.
  2. Navigate to Manage Jenkins > Configure Global Security.
  3. From Authorization, select Role-Based Strategy. Select Save.

  1. Navigate to Manage Jenkins then Manage and Assign Roles. Select Manage Roles. 

  1. Create the roles you need, and save them.

Assigning Roles

Next, you need to assign the correct roles in Jenkins.

How to Assign Roles in Jenkins

  1. To assign roles, go to Manage Jenkins > Manage and Assign Roles > Assign Roles.
  2. Set the roles as follows:
  • Global roles:
  • Folder1_user should have GlobalRead
  • Folder1FolderA_user should have GlobalRead
  • Folder1FolderB_user should have GlobalRead
  • Item roles:
  • Folder1_user should have Folder1
  • Folder1FolderA_user should have Folder1FolderA
  • Folder1FolderB_user should have Folder1FolderB

Creating Credentials for User1 and User2

Finally, you need to create credentials for each user.

How to Create Credentials for Users

  1. Open Jenkins.
  2. Go to Jenkins > Folder1 > FolderA.

  1. From the main menu, select Credentials.

  1. In the Credentials section, select Folder1 > FolderA.

  1. Select Global credentials (unrestricted) > Add Credentials.

  1. Complete the following fields:
  • Kind:                Username with password
  • Username:        https://www.netsparkercloud.com (Server Url)
  • Password:         User1’s Invicti Enterprise Api Token
  • Description:        This description will be shown when the Credentials dropdown is selected when configuring the job. Entering something meaningful here will help to distinguish this one from other credentials there.
  1. Select OK.

  1. Navigate to Jenkins > Folder1 > FolderB and repeat the steps for User2.

Invicti Help Center

Our Support team is ready to provide you with technical help.

Go to Help Center This will redirect you to the ticketing system.