Jenkins plugin

This documentation is aligned with Kiuwan Jenkins Plugin's latest version.

• Proxy for Kiuwan Local Analyzer: The selected option only applies to Kiuwan Local Analyzer. Connections made by the plugin itself always use the configured Jenkins proxy (see [YOUR_JENKINS_URL]/pluginManager/advanced.
  • No proxy: Select this option if you do not want the Kiuwan Local Analyzer process to use a proxy server when connecting to Kiuwan.
  • Use Jenkins proxy: Select this option if you want the Kiuwan Local Analyzer process to use the Jenkins proxy settings when connecting to Kiuwan.
  • Use custom proxy: Select this option if you want the Kiuwan Local Analyzer process to use a custom proxy when connecting to Kiuwan. You can set here all the options supported by the Kiuwan Local Analyzer.

Once a connection profile is created, you are ready to add Kiuwan to your jobs.

Note: Make sure that you do not delete a connection profile that is referenced by any of your jobs. This would make the job fail when starting the Kiuwan step. The plugin shows a message listing jobs that are referencing an inexistent connection profile:

       First, you should:

• Choose a connection profile to use when analyzing. In case you see a message stating that there are no connection profiles created, please refer to the Configuring connections section.
• Choose a source folder to analyze. In case you want to analyze the current workspace, just leave blank the “Source path” text box. If a relative path is specified, it will be resolved against the current workspace.

There are three modes available to configure your analysis:

• Baseline Mode
• Delivery Mode
• Expert Mode

Hint: You can configure any parameter by referencing system variables with the following syntax: ${MY_VAR}

The main configuration parameters are:

• Kiuwan Application Name: Set to the application name defined in Kiuwan.
  • If the app does not exist, it will be created.
  • If not set, the Jenkins project name will be used.

• Analysis Label: Set a label to identify the analysis.
  • If not set, Jenkins build number (#n) will be used.

Click Advanced to define additional configuration parameters:

• Encoding: The encoding of the source files that will be analyzed.
• Include and Exclude patterns for the analysis: See Source Code Filters.
• Timeout: Indicates the maximum allowed time (in minutes) for Jenkins to wait for Kiuwan analysis. If that time is reached, the build will be set to ABORTED.
  • Indicate languages / Languages: Check this box if you want to indicate explicitly the list of languages to analyze. Leaving this box unchecked, the analysis engine will try to discover all available languages present in the current source path.

Note: In some operation modes, the plugin waits for the analysis to be processed in Kiuwan. The timeout set in this field includes this waiting time as well.
To customize any other configuration parameter when using this mode, the recommended approach is to use a centralized configuration. Check Centralized Analysis Configuration for more information.
You should also consider using the expert mode and passing configuration parameters from the command line.

Selecting the delivery mode configures the Kiuwan Plugin for Jenkins to define the analysis scope as delivery (partial or complete).

As in baseline mode, you need to define the Kiuwan Application Name and an optional Analysis label.

The Wait For Audit Results checkbox allows you to change the Jenkins execution result depending on the result of the audit associated with the Kiuwan application. If checked, the build will be marked by default as UNSTABLE in case the audit fails.

Also, clicking Advanced… allows you to set additional parameters:

• Change request: A text (usually a code in a ticketing system) that helps you identify and associate this analysis with a change request.
• Analysis Scope: Defines the type of delivery:
  • Complete delivery: Important delivery of the whole application.
  • Partial delivery: A delivery usually associated with a change request.
• Branch: Name of the branch you are working in. Kiuwan will use this field to label the current delivery.
• Change request status: Kiuwan can give you feedback at different phases of your development process.
  • In progress: When working in an isolated environment or when you need Kiuwan's feedback for a concrete code change.
  • Resolved: this is the default value, use this option when the delivery to analyze is stable enough to be committed to a common environment.
• Encoding, Include/Exclude pattern, Timeout, Indicate languages: See the baseline mode section for more information about these parameters.

Expert Mode

Selecting expert mode allows full control of the Kiuwan analysis configuration.

You can set the Kiuwan Local Analyzer's command-line options and extra parameters manually.

Expert Mode allows you to set/override any parameter value that can be passed to Kiuwan Local Analyzer. Check for more information: Kiuwan Local Analyzer CLI - Command Line Interface.

When clicking Advanced… you can bind the result codes of Kiuwan Local Analyzer with Jenkins' build results.

You can find a further reference on return codes in Local Analyzer Return Codes.

And the generated script, as follows:

kiuwan connectionProfileUuid: 'lYfV-SD13',
       sourcePath: 'folder/demo-app-repository', 
       applicationName: 'Demo application', 
       indicateLanguages: true,
       languages:'java,python', 
       measure: 'NONE'

Inspecting the analysis output for further processing

By default, Kiuwan Local Analyzer stores a .json file containing the analysis results in the following path: [WORKSPACE]/kiuwan/output.json

You can read this file from your pipeline code if you want to process the output of the analysis. In this example we are using the readJSON function from the “Pipeline Utility Steps” plugin to access the Kiuwan’s Code Security security rating of an analysis:

def kiuwanOutput = readJSON file: "${env.WORKSPACE}/kiuwan/output.json"
def secRating = kiuwanOutput.Security.Rating

For a complete reference of the analysis results JSON object, please refer to the output format of Kiuwan REST API’s method “Get application analysis”. For more information, check the REST API documentation.

Using pipelines for plugin versions older than 1.6.0

In case you are running an older version, please upgrade your installation. If you are running Kiuwan Local Analyzer directly from a Jenkins pipeline without using the Kiuwan plugin for Jenkins, note that since version 1.6.0 it will be much easier to execute analyses from a pipeline script, and it is now the recommended way to launch a Kiuwan analysis.

Notes when using ephemeral slave nodes

This section is worth reading if you are using ephemeral slave nodes to run your Kiuwan analyses (that is, a slave that is created exclusively to run a job and then it is destroyed, usually implemented through Docker, Kubernetes, or Mesos).

In case you are using the standard approach of having pre-allocated slaves or at-the-ready virtual machines, you can skip this section.

Kiuwan plugin for Jenkins uses Kiuwan Local Analyzer under the hood. This means that for each defined connection profile, an instance of Kiuwan Local Analyzer (and the corresponding Kiuwan Engine) is downloaded and installed in the node where the analysis is going to be performed. In case the node is an ephemeral node, the installation procedure will be done each time the node is created.

Since version 1.6.0, support for this kind of scenario has been improved and an up-to-date cache of Kiuwan Local Analyzer and Kiuwan Engine distributions will be maintained in the Jenkins master to improve the performance of the installation procedure. This means that whenever a new slave is allocated, the current Kiuwan Local Analyzer and Kiuwan Engine versions will be automatically installed on the slave machine, avoiding any necessary updates needed when running the analysis. The cache will be checked each time a new analysis is to be run, updating the necessary files before installing both Kiuwan Local Analyzer and Kiuwan Engine in the slave node.

Since version 1.6.0 of the plugin, the Jenkins master cache is located here: [JENKINS_HOME]/cache/kiuwan_[CONNECTION_PROFILE_UUID].

Since version 1.6.0 of the plugin, the Kiuwan Local Analyzer installation directory in a slave node (or master node if you are running analyses directly from the master) is located here: [JENKINS_HOME]/tools/kiuwan_[CONNECTION_PROFILE_UUID]/KiuwanLocalAnalyzer.

Viewing analysis results