vamshikr / swamp-plugin

A Jenkins plug-in that allows projects using Jenkins to perform static code assessments in the SWAMP as part of a build.

SWAMP Jenkins Plugin

Table of Contents

• 1. Introduction:
• 2. Prerequisites:
• 3. Install the Plugin
  • 3.1. Install Using the Jenkins Plugin Store
  • 3.2. Install from a .hpi File
• 4. Configure the SWAMP Jenkins Plugin
• 5. Use the SWAMP Jenkins Plugin
• 6. Running an Assessment
• 7. Viewing your Results

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:

Note	Not available yet.

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

3.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. Configure the SWAMP Jenkins Plugin

The SWAMP Jenkins Plugin must be configured before use. 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
Credentials
Swamp Username	Your username to log into the SWAMP Note Third party credential such as github are not supported Create and use a SWAMP Application Password instead.
Swamp Password	Your password to log into the SWAMP
SWAMP URL	URL of SWAMP web site. The default is the SWAMP public instance at https://swa-csaweb-pd-01.mir-swamp.org. If you are using SWAMP-in-a-Box, contact your administrator for the URL to use.
Test Connection Button	Use this button to test your credentials and URL
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
Run even if build fails?	If checked, the package will be uploaded and assessed even if the build fails
Run Assessments in Background	If selected, you will not be able to view the results of the assessments in Jenkins. Use this option if you use a SWAMP viewer.

5. 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 destinguish 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.

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

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