HP Fortify Jenkins Plugin

Software Version: 4.40

Installation and Usage Guide

Document Release Date: November 2015

Software Release Date: November 2015
Installation and Usage Guide

Legal Notices
Warranty
The only warranties for HP products and services are set forth in the express warranty statements
accompanying such products and services. Nothing herein should be construed as constituting an
additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.
The information contained herein is subject to change without notice.

Restricted Rights Legend

Confidential computer software. Valid license from HP required for possession, use or copying. Consistent
with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and
Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard
commercial license.
The software is restricted to use solely for the purpose of scanning software for security vulnerabilities that is
(i) owned by you; (ii) for which you have a valid license to use; or (iii) with the explicit consent of the owner of
the software to be scanned, and may not be used for any other purpose.
You shall not install or use the software on any third party or shared (hosted) server without explicit consent
from the third party.

Copyright Notice
© Copyright 2014 - 2015 Hewlett Packard Enterprise Development LP

Documentation Updates
The title page of this document contains the following identifying information:
l Software Version number
l Document Release Date, which changes each time the document is updated
l Software Release Date, which indicates the release date of this version of the software
To check for recent updates or to verify that you are using the most recent edition of a document, go to:
https://protect724.hp.com/welcome
You will receive updated or new editions if you subscribe to the appropriate product support service. Contact
your HP sales representative for details.

HP Fortify Jenkins Plugin (4.40) Page 2 of 15

Installation and Usage Guide

Contents
Preface 4
Contacting HP Fortify Support 4
For More Information 4
About the HP Fortify Software Security Center Documentation Set 4

Change Log 5

HP Fortify Jenkins Plugin 6

Preparing Software Security Center to Work with the Jenkins plugin 6
Creating a Jenkins Token Type 6
Generating an SSC Authorization Token 7
About Jenkins Installation 8
Installing the Jenkins plugin 8
Verifying the Jenkins plugin Installation 9
Configuring the Jenkins plugin 9
Configuring the Build Step to Use for the Jenkins plugin 10
Using the Jenkins plugin with Continuous Builds 12
Viewing Issues 13
Configuring the Number of Issues Displayed on a Page 14

Send Documentation Feedback 15

HP Fortify Jenkins Plugin (4.40) Page 3 of 15

Installation and Usage Guide
Preface

Preface
Contacting HP Fortify Support
If you have questions or comments about using this product, contact HP Fortify Technical Support
using one of the following options.
To Manage Your Support Cases, Acquire Licenses, and Manage Your Account
https://support.fortify.com
To Email Support
fortifytechsupport@hp.com
To Call Support
650.735.2215

For More Information

For more information on HP Enterprise Security Software products:
http://www.hpenterprisesecurity.com

About the HP Fortify Software Security Center

Documentation Set
The HP Fortify Software Security Center documentation set contains installation, user, and
deployment guides for all HP Fortify Software Security Center products and components. In addition,
you will find technical notes and release notes that describe new features, known issues, and last-
minute updates. You can access the latest versions of these documents from the following
HP ESP user community Protect724 website:
https://protect724.hp.com/welcome
You will need to register for an account.

HP Fortify Jenkins Plugin (4.40) Page 4 of 15

Installation and Usage Guide
Change Log

Change Log
The following table lists the changes made to this guide.

Software Release-
Version Change

4.40-01 Updated: Made minor edits

HP Fortify Jenkins Plugin (4.40) Page 5 of 15

 HP Fortify Jenkins Plugin
The HP Fortify Jenkins Plugin (Jenkins plugin) is used in conjunction with HP Fortify Software Security
Center (SSC), a collaborative system for reviewing and auditing security analysis results.  If you use a
Fortify plugin such as maven to scan your source code after each build, the Jenkins plugin
automatically uploads the Fortify project results (in an FPR file) to an SSC server and enables you to
view the details within Jenkins. It also provides metrics for each build and an overview of the results,
without having to connect to SSC.
This document provides instructions on how to prepare SSC to work with the Jenkins plugin, and how
to install, configure, and use the plugin. For information about Jenkins, see the Jenkins web site
(http://jenkins-ci.org).

Preparing Software Security Center to Work

with the Jenkins plugin
To prepare SSC to work with the Jenkins plugin, you create a new token type, and then use the
fortifyclient utility to generate a token of that type. The following topics provide instructions on how to
perform these two tasks.

Creating a Jenkins Token Type

The Jenkins plugin communicates with HP Fortify Software Security Center (SSC) in several ways. 
Since SSC web services are access-controlled, you must define a new authentication token type that
authorizes the various web service requests that the Jenkins plugin uses.  
To create this token type:
1. From your Software Security Center installation directory, navigate to the
Core/support/tomcatForSSC/webapps/ssc/WEB-INF/internal directory, and then open the
serviceContext.xml file in a text editor.
2. Add the following block of text to the file:

<bean id="jenkinsToken"
class="com.fortify.manager.security.ws.AuthenticationTokenSpec">
<property name="key" value="JenkinsToken"/>
<property name="maxDaysToLive" value="365"/>
<property name="actionPermitted">
<list value-type="java.lang.String">
<value>AddProjectRequest</value>
<value>AddProjectVersionRequest</value>
<value>AddProjectAndVersionRequest</value>
<value>GetAuthenticationTokenRequest</value>

HP Fortify Jenkins Plugin (4.40) Page 6 of 15

Installation and Usage Guide
HP Fortify Jenkins Plugin

<value>ProjectListRequest</value>
<value>ActiveProjectVersionListRequest</value>
<value>ProjectVersionListRequest</value>
<value>ProjectTemplateListRequest</value>
<value>FPRUploadRequest</value>
<value>AuditViewRequest</value>
<value>PerformAuditActionRequest</value>
<value>IssueListRequest</value>
<value>GetProjectVersionIdentifiersRequest</value>
<value>ProjectMetaDataDefinitionsListRequest</value>
<value>AddProjectMetaDataDefinitionRequest</value>
<value>UpdateProjectMetaDataDefinitionRequest</value>
<value>ProjectMetaDataValuesListRequest</value>
<value>ProjectMetaDataValueRequest</value>
<value>GetSingleUseFPRUploadTokenRequest</value>
<value>CreateAuditSessionRequest</value>
<value>InvalidateAuditSessionRequest</value>
<value>GroupingValuesRequest</value>
</list>
</property>
<property name="terminalActions">
<list value-type="java.lang.String">
<value>InvalidateTokenRequest</value>
</list>
</property>
</bean>

3. Save and close the serviceContext.xml file.

Generating an SSC Authorization Token

After you define a Jenkins token type, you must use the fortifyclient command-line utility to generate a
token instance.
To generate an SSC authorization token:
1. From the <ssc_install>/Deployment/fortifyclient/bin directory, run the following:

fortifyclient token -gettoken JenkinsToken -daysToLive 365

-url <ssc_url>/ssc -user <user_with_appropriate_credentials>

where JenkinsToken is the case-sensitive fortifyclient upload token specifier.

Notes:
l The Software Security Center URL provided to fortifyclient must include both the port
number and the context path /ssc/. The correct format for the SSC URL is as follows:
http://<host_ID>:<port_number>/ssc/

HP Fortify Jenkins Plugin (4.40) Page 7 of 15

Installation and Usage Guide
HP Fortify Jenkins Plugin

l The ability of fortifyclient to use the token to read or write information to or from SSC
depends on the account privileges of the SSC user account specified by the -user
parameter.

The fortifyclient utility prompts for a password.

2. Type the password for <account_name>.
The fortifyclient utility returns a token of the general form cb79c492-0a78-44e3-b26c-
65c14df52e86.
3. Copy the returned token into a text file.
For detailed information about the fortifyclient command-line utility, see the HP Fortify Software
Security Center Installation and Configuration Guide.

About Jenkins Installation

If you do not have Jenkins installed, download it from http://mirrors.jenkins-ci.org/war. See the
HP Fortify System Requirements document for supported Jenkins versions.
For more information about how to install and start Jenkins, see the following web sites:
l https://wiki.jenkins-ci.org/display/JENKINS/Installing+Jenkins
l https://wiki.jenkins-ci.org/display/JENKINS/Starting+and+Accessing+Jenkins

Installing the Jenkins plugin

To install the Jenkins plugin, you must have Jenkins installed on your system.
To install the Jenkins plugin: 
1. Open a browser window and navigate to http://<jenkins_server_url>:8080/.
To start Jenkins locally, run java -Xmx1024m -XX:MaxPermSize=512m -jar <jenkins.war_
file_path>.
2. From the Jenkins user interface, select Manage Jenkins, and then select Manage Plugins.
3. On the Plugin Manager page, click the Advanced tab.
4. Under Upload Plugin, click Choose File, and then locate and select the HP_Fortify_Jenkins_
Plugin_<version>.hpi file.
5. Click Upload.
6. Restart Jenkins.
If you started Jenkins locally, press CTRL+C in the command-line window to restart it.

HP Fortify Jenkins Plugin (4.40) Page 8 of 15

Installation and Usage Guide
HP Fortify Jenkins Plugin

Verifying the Jenkins plugin Installation

To verify that the Jenkins plugin is installed:
1. Open a browser window and navigate to http://<jenkins_server_url>:8080/.
2. From the Jenkins menu, select Jenkins > Manage Jenkins > Manage Plugins.
3. On the Plugin Manager page, click the Installed tab.
4. Check to make sure that HP Fortify Jenkins Plugin appears in the list of installed plugins.
For more information about how to install Jenkins plugins, see the Jenkins Plugin site
https://wiki.jenkins-ci.org/display/JENKINS/Plugins#Plugins-Howtoinstallplugins.

Configuring the Jenkins plugin

To configure the Jenkins plugin for use with SSC:
1. Open a browser window and navigate to http://<jenkins_server_url>:8080/.
2. From the Jenkins menu, select Jenkins > Manage Jenkins > Configure System.
3. In the HP Fortify Assessment section, do the following:
a. In the URL box, type the URL for the SSC server for which you configured the Jenkins token
type.
The correct format for the SSC URL is http://<host_IP>:<port_number>/ssc/.
b. In the Authentication Token box, enter the authentication token generated for the SSC
server.
4. Click Advanced Settings, and then click Test Connection.
The Project Template list is now populated with available SSC project templates. SSC uses the
selected project template when it creates new projects.
New projects are always of the Basic Remediation Project type. Therefore, you must choose a
project template. The project template optimizes the categorization, summarization, and reporting
of the project version data.
5. From the Project Template list, select the appropriate project template for your project.
6. Click Save.

Note: There is no need to specify a value in the Issue breakdown page size box at this time. You
can always change this setting later. This setting controls the Issue Breakdown table view. The
default is 50 issues per page.

HP Fortify Jenkins Plugin (4.40) Page 9 of 15

Installation and Usage Guide
HP Fortify Jenkins Plugin

Configuring the Build Step to Use for the

Jenkins plugin
To configure the build step to use the Jenkins plugin:
1. From Jenkins, select the job to view or create a new job.
2. On the job page, click Configure.
3. On the configuration page that opens for the job, in the Post-build Actions section, select the HP
Fortify Assessment check box.
4. In the HP Fortify Assessment section, provide or change values for the properties and actions
listed in the following table.

Note: To see a description of an action or property, click the help icon.

Action or Property Description

FPR Filename FPR base name to be published (for example, audit.fpr). If no

value is specified, the Jenkins plugin searches "./**/*.fpr" files
in the workspace with the latest modified date.

FilterSet Filter set to be used when reading the FPR. If no value is specified,
the default filter is used.
SSC, by default, has two filter sets: Security Auditor View and
Quick View. Quick View is the default filter set. However, the exact
filter set configuration is determined by the project template used to
create the project.
Fail condition and NVS calculation depend on the issues filtered by
the filter set. For example, if some “Critical Exposure” filter is
applied to the project issues (and issues quantity shows 0), then fail
condition “sees” no reason to set this build as “unstable” and NVS is
set to 0. The graph summary also shows 0.

Fail Condition A build is considered unstable if the fail condition is met.

To get the unstable build where there is an SQL injection issue in
the High folder, use the following search string:
[fortify priority order]:high category:SQL Injection
This search string syntax is the same as that used for the SSC
search and filter capabilities. Therefore, there are some limitations
compared to Audit Workbench applications. For example, using a
regular expression for a search is not supported.

Project Name Project name used when uploading FPR files to SSC. Leaving this
field blank disables the upload.

HP Fortify Jenkins Plugin (4.40) Page 10 of 15

Installation and Usage Guide
HP Fortify Jenkins Plugin

Action or Property Description

Project Version is always used in conjunction with Project Name.

To upload an FPR file to SSC:
l Project Version and Project Name must be specified.

l SSC URL and the authentication token must be correctly

specified.

Note: If a project with the specified project name does not

exist on SSC, SSC creates it upon the successful build.

Enable this plugin and save the configuration. The next time you
visit this configuration page, a menu populated with all the available
project names is displayed.
Alternatively, run the following command to list all available
projects and their corresponding project IDs:
# fortifyclient listprojects -url <ssc_url>/ssc -user
<your_login>

Project Version Project version used when uploading to SSC. Leaving this field
blank disables the upload.
Project Version is always used in conjunction with Project Name.
To upload an FPR file to SSC:
l Project Version and Project Name must be specified.

l SSC URL and the authentication token must be correctly

specified.

Upload Wait Time Click Auto Job Assignment to access this box. Because the
FPR upload process to SSC is asynchronous, the WebService
function call is returned while SSC is still processing the upload
request. Therefore, the plugin waits for a specified number of
minutes before running the Normalized Vulnerability Scope (NVS)
calculation.
Valid values are 0-60.

5. Click Save.

HP Fortify Jenkins Plugin (4.40) Page 11 of 15

Installation and Usage Guide
HP Fortify Jenkins Plugin

Using the Jenkins plugin with Continuous Builds

To use the Jenkins plugin with continuous builds:
1. Place the FPR resulting from a source code scan into the workspace directory for the job.
On Windows systems, the default directory is
C:\Users\<username>\.jenkins\jobs\<project_name>\workspace.

Note: Configure your build procedure to do this automatically. You can specify the path to
your FPR file with the FPR Filename setting on the Job Configuration page, see
"Configuring the Build Step to Use for the Jenkins plugin" on page 10.

2. From Jenkins, select Build Now.

3. To read progress messages from the Jenkins plugin, in the Build History box, select the build
link, and then, on the <build_number> page, select Console Output.
4. After the build is completed (after you see the “Finished: SUCCESS” message), return to the
project page.
The project page displays the Normalized Vulnerability Score (NVS) graph. NVS is a normalized
score that gives you a rough idea of how good (or how bad) your application is. The plugin
calculates the NVS using the following formula:

where:
CFPO = Number of critical vulnerabilities (unless marked as “Not an Issue”)
HFPO = Number of high vulnerabilities (unless marked as “Not an Issue”)
MFPO = Number of medium vulnerabilities (unless marked as “Not an Issue”)
LFPO = Number of low vulnerabilities (unless marked as “Not an Issue”)
and:
PABOVE = Exploitable
P3 = Suspicious
P2 = Bad practice
P1 = Reliability issue
The total issues count is not very useful. For example, if application A has 0 critical issues and 10
low issues, the total issues value is 10. If application B has five critical issues and no low issues,
the total issues value is 5. These values might mislead you to think that application B is better
than A, when it is not.
The NVS calculated for the two applications present a different picture (simplified equation):
application “A” NVS = 0*10 + 10*0.1 = 1
application “B” NVS = 5*10 + 0*0.1 = 50
5. Click the HP Fortify Assessment link in the column of project options on the left.

HP Fortify Jenkins Plugin (4.40) Page 12 of 15

Installation and Usage Guide
HP Fortify Jenkins Plugin

The interactive List of HP Fortify SSC issues page displays the Summary and Issue breakdown
by Priority Order tables.

The Summary table shows the difference in the number of issues in different categories between the
two most recent builds. A blue arrow next to a value indicates that the number in that category has
decreased, and a red arrow indicates that the number in that category has increased.
The Issues breakdown by Priority Order table shows detailed information about the issues for the
specified location and category in each priority folder. Wait for the table to load. If the data load takes
too long, you might need to refresh the browser window (F5).
By default, you see the critical issues first. To see all issues, click the All tab.

Note: The more issues a page shows, the longer it takes to load. HP Fortify recommends that you
not use the All tab for large projects.

Viewing Issues
To see only those issues that were introduced in the latest build of your code, click the Show New
Issues link at the top of the table.
The first and the second columns show the file name and a line number of the finding and the full path to
this file. The last column displays the category of each vulnerability.
By default, issues are sorted by primary location. To organize them by category, click the Category
column header.

HP Fortify Jenkins Plugin (4.40) Page 13 of 15

Installation and Usage Guide
HP Fortify Jenkins Plugin

To see more details about or to audit a specific issue, click its file name in the first column. The link
takes you directly to the details of that issue on the SSC server. If you are not logged in to SSC, you
are prompted to log in.

Configuring the Number of Issues Displayed on a Page

The page displays 50 findings by default. To navigate to all findings, use Next>> and <<Previous on
the top and bottom of the table. To increase the number of issues to 100 per page, from the 50 | 100 |
All section at the bottom of the page, click 100.
To control the number of the issues shown on a page from the Configure System page:
l In the HP Fortify Assessment section, click Advanced Settings, and then change the value in the
Issue breakdown page size box.

HP Fortify Jenkins Plugin (4.40) Page 14 of 15

Installation and Usage Guide
Send Documentation Feedback

Send Documentation Feedback

If you have comments about this document, you can contact the documentation team by email. If an
email client is configured on this system, click the link above and an email window opens with the
following information in the subject line:
Feedback on Installation and Usage Guide (Fortify Jenkins Plugin 4.40)
Just add your feedback to the email and click send.
If no email client is available, copy the information above to a new message in a web mail client, and
send your feedback to HPFortifyTechPubs@hp.com.
We appreciate your feedback!

HP Fortify Jenkins Plugin (4.40) Page 15 of 15