1. Overview

The Twistlock Jenkins plugin supports Jenkins Pipeline. Jenkins Pipeline lets you implement and integrate continuous delivery pipelines into Jenkins.

You cannot run the Twistlock scanner inside a container. The following example snippet will NOT work.

stage('Twistlock Scan') {
  steps {
    container('jenkins-slave-twistlock') {
      script {
        // THIS DOES NOT WORK
        twistlockScan ca: '', cert: '', compliancePolicy: 'critical', ...
      }
    }
  }
}

Instead, run the Twistlock scanner in the normal context:

stage('Twistlock Scan') {
  steps {
    // THIS WILL WORK
    twistlockScan ca: '', cert: '', compliancePolicy: 'critical', ...
  }
}

2. Setting up a Pipeline project

To set up a Jenkins Freestyle project:

Procedure

  1. Go to the Jenkins top page.

  2. Create a new project.

    1. Click New Item.

    2. In Item name, enter a name for your project.

    3. Select Pipeline.

    4. Click OK.

      jenkins pipeline project 764012
  3. Use Jenkin’s Snippet Generator to generate Pipeline Script for the Twistlock steps.

    In the Pipeline section, click on the Pipeline syntax link, which takes you to https://<JENKINS_CONSOLE>/job/docs_issue/pipeline-syntax/.

    jenkins pipeline project 764020
  4. Generate Pipeline Script for the scan step.

    1. In the Sample Step drop-down, select twistlockScan - Scan Twistlock images.

    2. Choose an action to take if the image contains packages with vulnerabilities.

      Select a severity threshold (Low, Medium, High) to fail the build if a vulnerability is found. Or select Never fail, only warn to allow the complete build process to proceed even if there is a vulnerability.

    3. Select the checkbox to ignore any vulnerabilities that do not have a vendor fix. For example, if you select a threshold of High, and a package with a high severity image is found, the build will not be failed if no vendor fix is available.

    4. Choose an action to take if the image has compliance issues.

      Select a severity threshold (Low, Medium, High) to configure the build to fail if a compliance issue is found. For more information about how checks are scored, see CIS benchmarks.

      Select Never fail, only warn to allow the complete build process to complete even if there are compliance issues.

    5. In the Grace period field, specify an interval (in days) from when a vulnerability is discovered until when the threshold action is enforced.

      This mechanism eliminates the need for admins to temporarily whitelist a CVE and manually maintain a list of exemptions. Instead, you can automtically grant your development teams time to schedule and implement a fix.

    6. If your image is created outside of this build, click Advanced, and then select Ignore image creation time.

    7. In the Image field, select the image to scan by specifying the repository and tag. You can use pattern matching expressions.

      For example, enter: myimage:1.0

      If the image you want to scan is created outside of this build, or if you want to scan the image every build, even if the build might not generate an new image, then click Advanced, and select Ignore image creation time.
    8. Click Generate Pipeline Script, copy the snippet, then set it aside for later.

  5. Generate Pipeline Script for the publish step.

    1. In the Sample Step drop-down, select twistlockPublish - Publish Twistlock analysis results.

    2. In the Image field, select the image to report. You can use pattern matching expressions.

      For example, enter: myimage:1.0

    3. Click Generate Pipeline Script, copy the snippet, then set it aside for later.

  6. Enter the complete Pipeline Script into your project configuration.

    The following example script builds a simple image, and runs a Twistlock scan using the options and scripts we ran in previous steps.

    node {
       stage('Preparation') {
           // for display purposes
           echo "Preparing"
       }
    
       stage('Build') {
           // Build an image for scanning
           sh 'echo "FROM ubuntu:14.04" > Dockerfile'
           sh 'echo "MAINTAINER Aqsa Fatima <aqsa@twistlock.com>" >> Dockerfile'
           sh 'echo "RUN mkdir -p /tmp/test/dir" >> Dockerfile'
           sh 'docker build --no-cache -t dev/ubun2:test .'
       }
    
      stage('Scan') {
        twistlockScan ca: '',
          cert: '',
          compliancePolicy: 'critical',
          dockerAddress: 'unix:///var/run/docker.sock',
          gracePeriodDays: 0,
          ignoreImageBuildTime: true,
          image: 'dev/ubun2:test',
          key: '',
          logLevel: 'true',
          policy: 'warn',
          requirePackageUpdate: false,
          timeout: 10
        }
    
      stage('Publish') {
         twistlockPublish ca: '',
            cert: '',
            dockerAddress: 'unix:///var/run/docker.sock',
            ignoreImageBuildTime: true,
            image: 'dev/ubun2:test',
            key: '',
            logLevel: 'true',
            timeout: 10
    
            }
    }
  7. Click Save, then click Build Now to start the build.

  8. After the build completes, examine the results.

    The Status page shows a summary of each build step:

    jenkins pipeline project 791179

    Click on a step to view the log messages for that step:

    jenkins pipeline project 791180

    Scan reports are available in the following locations:

    • Twistlock Console: Log into Console, and go to Monitor > Vulnerabilities > Jenkins Jobs.

    • Jenkins: Drill down into the build job, then click Vulnerabilities to see a detailed report.

      jenkins pipeline project 791181

3. Scan policy

The twistlockScan class from the Jenkins plugin provides two parameters for specifying how builds are passed or failed when the scanner finds issues in container images.

  • policy: Severity threshold for vulnerable packages.

  • compliancePolicy: Severity threshold for compliance issues.

Setting the scan policy to 'warn' lets you pass builds, regardless of the scan results. Alternatively, you can fail builds based on severity thresholds ('low', 'medium', 'high', or 'critical').

After builds complete, you can view the scan results in the Jenkins dashboard or Twistlock Console. If you set the scan policy to a threshold, and nothing in the scan results exceeds the specified threshold, the build passes, and nothing is reported.

If you set the scan policy to 'warn', then you must run the twistlockPublish step to see the scan results in the Jenkins console output.