Automation - Jenkins Plugin

Overview

The CAST Imaging Jenkins Plugin enables automated and repeatable application analysis through the CAST Imaging API via the Jenkins continuous integration system . The plugin supports the following operations:

• initial fast scan (process source code without running analysis)
• deep analysis and results publication in Viewer/Dashboards (fast scans must be completed)

Requirements

Software

• Jenkins version ≥ 2.60.3 (the plugin has been tested with Jenkins up to version 2.387.1) Please contact CAST Support if you are facing issues using more recent versions.
• Jenkins should be configured with Java Runtime Environment (JRE) or Java Development Kit (JDK) version 17 or higher (if you are running Jenkins as a Docker container, ensure the image you are using includes the appropriate Java release).

CAST Imaging installation

Before using the plugin, ensure you have:

1. CAST Imaging installation: A properly configured and accessible CAST Imaging v3 instance - see Global installation guide for CAST Imaging 3.x
2. API Token: API access via the plugin requires authentication using a user-specific API key. Generate a key using the CAST Imaging UI in the Profile section.
3. Source code preparation: Prepare your source code for analysis using one of these methods:
   • Archive file (.zip or tar.gz)
   • Path pointing to a Source Folder Location configured in the CAST Imaging UI

Where can I get the Jenkins Plugin?

The Jenkins Plugin is provided in an extension which you can download here: https://extend.castsoftware.com/#/extension?id=com.castsoftware.aip.console.tools&version=latest 

Unzip the extension anywhere on your local disk. The plugin is provided as aip-console-jenkins.hpi.

Plugin installation and configuration

Step 1 - Install the plugin

Use the Jenkins UI to upload the plugin file aip-console-jenkins.hpi: Manage Jenkins > Plugins > Advanced Settings > Deploy Plugin:

Restart your Jenkins instance to ensure the new plugin is taken into account. The plugin will be listed under Installed Plugins:

Step 2 - Configure the global plugin settings

Before you can start to use the plugin to create build jobs, configure the default settings using the UI: Manage Jenkins > System > CAST Imaging global configuration. Click Save/Apply to ensure the settings are taken into account:

Available options:

Using the plugin for your jobs

The plugin job settings are provided in the Build Steps section of the job configuration page:

• CAST Imaging Scan Application
• CAST Imaging Run Deep-Analysis

CAST Imaging Scan Application

• Creates a new application or updates an existing one
• Performs the initial source code fast scan for a new application or refreshes source code content for an existing application
• Must be performed before using the CAST Imaging Run Deep-Analysis option on new applications

Available options:

Advanced settings

Use these settings if you need to override the global settings explained in Step 2 - Configure the global plugin settings:

The Node Name option allows you to specify a specific analysis node if your CAST Imaging installation has multiple analysis nodes. Use the node name visible in the CAST Imaging UI Services administration options:

CAST Imaging Run Deep-Analysis

• Executes a deep analysis on an existing application with delivered source code (fast scan must be completed)
• Publishes results in Viewer and Dashboards (can be disabled)

Available options:

Advanced settings

Use these settings if you need to override the global settings explained in Step 2 - Configure the global plugin settings. See Advanced settings above.

Environment Variable usage

It is possible to use environment variables in both the CAST Imaging Scan Application and CAST Imaging Run Deep-Analysis build steps, for example:

You can leverage global Jenkins/custom environment variables  or custom job specific variables as required.

Pipeline/Jenkins files

All build steps and options can be used in Jenkins Pipelines or files. To extract the correct format, create a Pipelines job and use the Snippet Generator option:

Basic pipeline example

This basic pipeline performs the following:

• Initializes a “Preparation” stage, a visual separator for the different sections of the build
• In this stage, it will retrieve source code using Git from a URL to a subdirectory called “sources”
• Initializes a “Build” stage:
  • Moves to the “sources” folder where the source was checked out.
  • Inside the “sources” folder, the build will call git archive to create an archive from the local git repository and save it to the file source.zip which it will store in the parent directory
  • Moving back to the parent folder, the build will call Add Version, providing an application name, with auto create (create application if missing) set to true and point to the created source.zip file

node {
  // Stages to display on the build page
  stage('Preparation') {
    // Get some code from a GitHub repository
    checkout changelog: false, poll: false, scm: [$class: 'GitSCM', branches: [[name: '*/master']], extensions: [[$class: 'RelativeTargetDirectory', relativeTargetDir: 'sources']], userRemoteConfigs: [[url: 'https://github.com/jglick/simple-maven-project-with-tests.git']]]
  }
  stage('Build') {
    dir('sources') {
      sh "git archive -o ../source.zip HEAD"
    }
    aipAddVersion applicationName: 'my jenkins pipeline app', autoCreate: true, cssServerName: '', domainName: '', filePath: 'source.zip'
  }
}

Logging

If you are facing issues with the CAST Imaging Jenkins Plugin, you can provide more details to CAST Support by adding a log recorder to the plugin configuration:

• Manage Jenkins > System Log > Add Recorder
• Configure the new log recorder with two loggers:
  • com.castsoftware.aip.console.tools
  • io.jenkins.plugins.aipconsole

For example:

Next time you run a build using the CAST Imaging Jenkins Plugin, log messages of all levels should appear in your new logger: