SWAMP Jenkins Plugin

Table of Contents

• 1. Introduction:
• 2. Prerequisites:
• 3. Install the Plugin
  • 3.1. Install Using the Jenkins Plugin Store
• 4. Update the Plugin
  • 4.1. Install Using the Jenkins Plugin Store
  • 4.2. Install from a .hpi File
  • 4.3. Jenkins plugin with Swamp-In-The-Box (SiB) instances
• 5. Configure the SWAMP Jenkins Plugin
• 6. Use the SWAMP Jenkins Plugin
• 7. Running an Assessment
• 8. Viewing your Results
• 9. Accessing SWAMP via a HTTP Proxy:

1. Introduction:

This plugin allows you to submit SWAMP assessments during Jenkins builds. The SWAMP assessment will use open source static analysis tools to test your source code for vulnerabilities and flaws. For more information on the SWAMP, visit https://continuousassurance.org For more information on Jenkins, visit https://jenkins.io/

2. Prerequisites:

The usage of this plugin requires the following:

• A functional instance of Jenkins.
  If you do not have a Jenkins installation, go to https://jenkins.io to get Jenkins.
  A good tutorial for how to set it up is at http://www.tutorialspoint.com/jenkins/.

• A valid SWAMP account.
  We suggest that you create an Application Password for use with Jenkins.
  If you do not have an account, go to https://continuousassurance.org to register.

3. Install the Plugin

To use the SWAMP Assessment Plugin it must first be installed using either the Jenkins plugin store, or using a .hpi file containing the plugin.

3.1. Install Using the Jenkins Plugin Store

The SWAMP Jenking Plugin can be installed directly from Jenkins using the on-line plugins available within Jenkins using the following steps:

1. Go to your Jenkins URL in a web browser

2. Click Manage Jenkins → Manage Plugins

3. Click the Available tab

4. Enter SWAMP in the search field at the top right of the page

5. Click the install checkbox next to the SWAMP Plugin

6. Click the install without restart button

7. Click the Go back to the top page link

4. Update the Plugin

To update the SWAMP Plugin

1. Go to your Jenkins URL in a web browser

2. Click Manage Jenkins → Manage Plugins

3. Click the Updates tab

4. Enter SWAMP in the search field at the top right of the page

5. Click the install checkbox next to the SWAMP Plugin

6. Click the Download now and install after restart button

7. Click the Go back to the top page link

Warning

Reconfiguration required if updating from 1.0.x or 1.1.x versions to 1.2.x or higher. Starting 1.2.0, SWAMP plugin uses credentials API to store SWAMP credentials in Jenkins. If you are updating from 1.0.x or 1.1.x versions to 1.2.x or higher, re-configuration of the SWAMP plugin is required. Please re-configure the plugin at Manage Jenkins → Configure System → SWAMP.

4.1. Install Using the Jenkins Plugin Store

The SWAMP Jenkins Plugin can be installed directly from Jenkins using the on-line plugins available within Jenkins using the following steps:

1. Go to your Jenkins URL in a web browser

2. Click Manage Jenkins → Manage Plugins

3. Click the Available tab

4. Enter SWAMP Plugin in the search field at the top right of the page

5. Click the install checkbox next to the SWAMP Plugin

6. Click the install without restart button

7. Click the Go back to the top page link

4.2. Install from a .hpi File

The SWAMP Jenkins plugin can be installed directly from SWAMP.hpi file using the following steps:

1. Aquire the SWAMP.hpi on your computer from https://github.com/mirswamp/swamp-jenkins-plugin

2. Go to your Jenkins URL in a web browser

3. Click Manage Jenkins → Manage Plugins

4. Click the Advanced tab

5. In the Upload Plugin section, click the Browse button and select the SWAMP.hpi file on your computer

6. Click the Upload button

7. Click the install without restart button

8. Click the Go back to the top page link

4.3. Jenkins plugin with Swamp-In-The-Box (SiB) instances

If you are using an SiB instance that uses a self-signed SSL/TLS certificate then, the SWAMP Jenkins plugin will fail to communicate with that SiB instance. The reason being Java’s security model by default does not allow communicating with a web-service that has a self-signed SSL/TLS certificate. To overcome this restriction, the web-service’s self-signed SSL/TLS certificate has to be added to the Java installation’s default keystore on the machine that is running the Jenkins server. The following are the instructions on how to do it:

1. Access the SiB from the web-browser and download the SiB’s self-signed certificate by following these instruction here: https://www.thesslstore.com/blog/how-to-view-ssl-certificate-details-in-chrome-56/

2. Run the following commands to add the self-signed certificate to the Java installation’s keystore:

1. Change the present working directory to your Java installation directory + jre/lib/security/.

      cd $JAVA_HOME/jre/lib/security

2. Make a backup copy of the cacerts file

      cp cacerts cacerts.original

3. Add the certificate to the keystore (Assuming here that the self-signed certificate is stored on the desktop as www.sib-swamp.org.cer)

      sudo keytool -importcert -alias sib-name -file ~/Desktop/www.sib-swamp.org.cer -keystore $PWD/cacerts

5. Configure the SWAMP Jenkins Plugin

The SWAMP Jenkins Plugin must be configured before use. Starting version 1.1.3, SWAMP plugin uses Credentials API. This configuration is modified on the following web interface:

1. Go to your Jenkins URL in a web browser

2. Click Manage Jenkins → Configure System

3. Scroll to the SWAMP Configuration Section (near the bottom of the configuration page), and enter the following:

Parameter	Description
Swamp URL	URL of SWAMP web site. The default is the SWAMP public instance at https://www.mir-swamp.org. If you are using SWAMP-in-a-Box, contact your administrator for the URL to use.
Credentials
Swamp Credentials	Select the SWAMP credentials from the drop-down list. If SWAMP credentials are not in the list, Add Credentials by clicking on Add button and choosing Jenkins (Jenkins Credentials Provider). In the Add Credentials page: 1. Choose a Domain to store SWAMP credentials. This is optional, default is Global Credentials (unrestricted). Users can create a domain to group credentials by going to Jenkins → Credentials and selecting Add Domain in the Jenkins drop-down list. 2. For Kind, Select Username with password from the drop-down list. 3. For Scope, choose Global. 4. Enter SWAMP username and password in the Username and Password text boxes. 3. In the Description textbox, enter SWAMP or any string that lets you distinguish SWAMP credentials. 4. Leave the ID text-box empty. 5. Save the credentials by clicking on the Add button. NOTE: If you use third party credential such as github to log into SWAMP then, create and use a SWAMP Application Password.
Test Connection Button	Use this button to validate the credentials and URL that you have entered
Global Project Settings
Default Project	The default project to be used for each upload Can be modified in build settings
Miscellaneous Options
Verbose Mode	Provide extra output for status updates and error checking

6. Use the SWAMP Jenkins Plugin

1. Go to your Jenkins URL in a web browser

2. Click on the project link that you want to assess with the SWAMP

3. Click on the Configure link for the project on the left side

4. Scroll to the Post Build Actions section (or click the Post Build Actions tab)

5. Click the Add Post Build Action button and select "Swamp Assessment"

6. In the SWAMP Assessment section, fill out the data as follows:

Parameter	Description
Package Settings
Package Directory	If the main directory of your package is located in a subdirectory, enter it here.
Package Name	Enter the name of your package here. This is the name that will be used in the SWAMP UI.
Package Version	Enter the version string of your package. Every build should have a unique version String. The following macros may be used $build unique Jenkins build id $date current date $git most recent git commit id $svn most recent svn commit id If you do not update the version number each build (either using any of the above options or manually updating the version) then submissions will have the same version and be difficult to distinguish in the user interface.
Package Language	The language that your package uses.
Build Settings
Build System	Select the build system your project uses.
Build Directory	Enter a value if your software needs to build in different directory than the Package Directory. The directory is relative this the Package Directory
Build File	Leave blank if using a standard build file name for the select Build System (i.e. build.xml for Ant, pom.xml for Maven, Makefile for Make) Enter a path to the file if the build file is using a non standard name. The path is relative to the Build Directory.
Build Target	If building your package requires a special build target, enter it here, otherwise leave blank
Build Command	If your package uses a build command other than a standard type specified by the build system enter it here. Otherwise leave blank and the command will be determined by the Build System. (Syntax is Bash)
Build Options	If your package requires options to passed to the build command, enter it here (e.g. --verbose --setInt 1), otherwise leave blank. Add multiple options separated by spaces as usual.
Configuration Command	If your package requires a configuration command, enter it here. If left blank, the configuration will be called without a command. (Syntax is Bash)
Configuration Options	If your package requires configuration options, enter them here similarly to the build options.
Clean Command	Enter the command to clean your build. Leave blank to use the [build-system] clean
Assessment Settings
Project Name	The name of the project to use in the SWAMP.
Click Add to configure the Tool and Platforms to use:
Tool	Select the tool you would like to use for this assessment.
Platform	Select the platform you would like to use for this assessment.
Output Settings
Assessment Output Directory	Places the output of the assessments from the SWAMP in this directory from the workspace.

7. Running an Assessment

When you run a build through any method (i.e. build button, git hook, etc.), the SWAMP Jenkins Plugin will send the package to the SWAMP for assessment. To view the status of your build, go to your project → build * (listed on the left hand side, pick the most recent build) → console output

8. Viewing your Results

Results from the assessments are viewable in Jenkins on completion. These results will be viewable in the source code, and will also be parsed into a graph. This graph is configurable by clicking the configure link beneath the graph.

Otherwise, the SWAMP web site can be used to view results of your assessments:

1. Login to the SWAMP as normal.

2. Click Results

3. Click the checkbox next to the assessment results you would like to review

4. Click View Assessment Results button

9. Accessing SWAMP via a HTTP Proxy:

SWAMP plugin uses the http proxy settings specified on the standard jenkins interface https://wiki.jenkins.io/display/JENKINS/JenkinsBehindProxy. Incase if you do not want the SWAMP plugin to use the http proxy, specify the SWAMP URL in the No Proxy Host section in the proxy settings.