TABLE OF CONTENTS

Overview

Aqua Security Scanner plugin for Jenkins can be used to scan container images in the build pipeline to detect security issues. You can scan images in Jenkins through the following container engines:

  • Docker
  • Podman

If you use Docker container engine for scanning, you can scan local images, hosted images in a registry, and docker archive tar files.


If you use Podman container engine, you can only scan local images.


This plugin can be installed in Jenkins. Once installed, you should include details for scanning images in the build process. During the build process, the following actions can be performed: 

  • Images are scanned by the scanner
  • (Optional) Actions can be taken if any security issues are found in the scan results
  • Scan results can be viewed in Jenkins


This topic explains how to install and configure the Aqua Security plugin in Jenkins, and then how to use the plugin to scan images during the build process, and view the scan results.


Prerequisite

Before you configure the Aqua Security plugin in Jenkins, make sure that you have scanner permission assigned by your Aqua admin.


Integrate Aqua Security with Jenkins

This section explains two steps to complete setup the Aqua Security plugin in Jenkins as listed below:

  • Install plugin
  • Configure plugin

Install plugin

You can download the plugin either from the central Jenkins repo or from outside the repo as explained in the following sections.


Central repository

To install Aqua Security in Jenkins by downloading from the central Jenkins repo:

  1. In the Jenkins portal, click Manage Jenkins in the left pane.
  2. From the System Configuration, click Manage Plugins.




After you install the plugin for the first time, a red bell icon at Manage Plugins may appear at anytime later to indicate that an update is available for the Aqua Security Scanner plugin.


      3. Click the Available tab and search for Aqua Security Scanner in the search box. Search results appear.

      4. Select Aqua Security Scanner and click either Install without restart or Download now and install after restart to install the plugin.


You can view the recently obtained update information for this plugin by clicking the Check now button.


      5. Click the Installed tab to make sure that the plugin is installed and enabled.


For more information on installing the plugin, refer to the Jenkins document, Managing Plugins.

Outside the central repository

This is the advanced method of installing plugin in Jenkins. Through method, .hpi file from Aqua can be used to install plugin. To install Aqua plugin:

  1. Navigate to the web page for Aqua plugin for Jenkins through this URL.
  2. Click the Releases tab to see the list of Aqua releases of plugin.
  3. Click the link to the recent release to download Aqua Security Scanner plugin for Jenkins (aqua-security-scanner.hpi).



     4. In the Jenkins portal, click Manage Jenkins in the left pane.

     5. From the System Configuration, click Manage Plugins.

     6. Click the Advanced tab and navigate to Upload Plugin dialog.

     7. Click Choose File to upload the already downloaded aqua-security-scanner.hpi file.

     8. Click Upload to install the Aqua Security Scanner plugin from outside the central plugin repository.



Configure plugin

To configure the just installed Aqua Security plugin:

  1. In the Jenkins portal, click Manage Jenkins in the left pane.
  2. Click Configure System.
  3. Navigate to Aqua Security section.
  4. Enter the following details:
  • Aqua scanner image
  • Aqua API URL
  • Select Token for authentication.
  • Token: Enter scanner token. You can get the token of a specific scanner from the Administration > Scanners page. For more information, refer to Add Scanner Daemons.

Do not select Username/Password for authentication as your Aqua SaaS application does not support authenticating an Aqua scanner with username and password.


  • Timeout: (Optional) specify the scan timeout in seconds (where 0 means unlimited)
  • Additional Docker run options: Add more docker parameters as required. For example, if you want to run the scanner with root permissions, you can add the --privileged parameter in this field.

      5. Select Do not verify TLS certificates if you work in an environment (such as a development environment) without certificates.



Use plugin to scan images in the Docker container engine

You can use the Aqua Security plugin in the Jenkins build process in the Pipeline and Freestyle jobs. You can configure a job to scan images during or after the build process using the plugin and push the images to a registry.


Pipeline jobs

In the Pipeline jobs, the build step for Aqua scanning is included in a pipeline script, as part of the job configuration.


Prerequisite

Ensure that you have logged into the Docker repository where the Aqua scanner image is located. This is required before you proceed.


Configure a Pipeline job for image scanning using Docker


To configure a Pipeline job for image scanning by Aqua:

  1. In the Jenkins portal, navigate to the required pipeline.
  2. Click Configure on the left pane.
  3. Click the Pipeline tab. You are navigated to the Pipeline section.
  4. From the Definition dropdown, select Pipeline script.



       5. To scan a locally hosted image, include the following snippet in the pipeline script.

       6. Replace the localImage parameter value with the identifier of the actual image in your pipeline.

timestamps {
  node('build_node'){
      stage("Scan alpine image"){
          aqua locationType: 'local', localImage: 'alpine', localToken: Secret.fromString("6b319d24086718198a0bef664874c291bb991509"), hideBase: false, notCompliesCmd: '', onDisallowed: 'ignore', showNegligible: false
          }
   }
}


      7. To scan an image which is hosted in a registry, include the following snippet in the pipeline script.

      8. Replace the hostedImage parameter value with the identifier of the actual image in your pipeline.

timestamps {
  node('build_node'){
      stage("Scan mongo"){
          aqua locationType: 'hosted', registry: 'Docker Hub', hostedImage: 'mongo', localToken: Secret.fromString("6b319d24086718198a0bef664874c291bb991509"), notCompliesCmd: '', onDisallowed: 'ignore', hideBase: false, showNegligible: false
          }
   }
}

      9. To scan a Docker image contained in a .tar file, include the following snippet in the pipeline script.

    10. Replace the dockerarchive parameter value with the identifier of the actual image in your pipeline.

node(){
    stage("scan") {
        aqua locationType: 'dockerarchive', tarFilePath:'/home/aqua/alpine.tar', localImage: 'alpine', localToken: Secret.fromString("6b319d24086718198a0bef664874c291bb991509"), hideBase: false, notCompliesCmd: '', onDisallowed: 'ignore', showNegligible: false
    }                   
}

    11. Make sure to add the following parameters in the snippet, as required: 

  • notCompliesCmd (optional): a command (of your choice) to run each time a scanned image is found to be non-compliant.
  • onDisallowed: set either to ignore (if you want the pipeline to continue even if the image is non-compliant) or fail (if you want to stop the pipeline).
  • hideBase (optional): hides vulnerabilities in the base image. This is used to hide any existing vulnerabilities from a base image. These vulnerabilities are known from the base image and not required to be reported on every image created from the specific base image. 
  • showNegligible (optional): shows vulnerabilities of negligible and unknown severity.
  • localToken: (mandatory) Enter the scanner token that you have collected from the Administration > Scanners page. For more information, refer to Add Scanner Daemons. This token value allows you connecting a Jenkins job with a different Aqua scanner than configured in the plugin.

    12. Click Apply or Save as required.


Jenkins Snippet Generator

You can use Jenkins snippet generator to generate a specific syntax for including in the pipeline script. To generate pipeline syntax:

  1. In the Configure job > Pipeline tab, click Pipeline Syntax. Pipeline Syntax dialog appears.


2. From Sample Step dropdown, select aqua: Aqua Security.
3. In the 'When image doesn't comply with Aqua policy' section, select either Never fail builds or Perform the action defined in Aqua's policy as shown in the following screenshot. For more information on the actions in a policy that apply to the image to be scanned, refer to Image Assurance Policies.
4. Select either Local image, Hosted image, or docker-archive as required.
5. If you select Local image, enter the following details:
  • Local image: Image name
  • Container Runtime: enter docker or leave it blank, as container runtime defaults to docker
  • Aqua Scanner path: Leave this field blank as Aqua Scanner is provided by the plugin
6. If you select Hosted image, enter the following details:
  • Image name: URL of the registry with the image name
  • Hide base image vulnerabilities: Enable this to hide any existing vulnerabilities from a base image. These vulnerabilities are known from the base image and not required to be reported on every image created from the specific base image.
7. If you select docker-archive, enter Tar file path.
8. Select the Register checkbox to register image with Aqua after scanning is passed successfully.
9. Select the Show negligible vulnerabilities checkbox to show vulnerabilities of negligible severity in the output.
10. Enter the following details:
  • Registry name
  • Policies
  • Token: Enter the scanner token that you have collected from the Administration > Scanners page. For more information, refer to Add Scanner Daemons. This token value allows you connecting a Jenkins job with a different Aqua scanner than configured in the plugin.
  • Custom flags: Add additional command-line flags in this field. You should pass the --direct-cc flag to connect to the CyberCenter directly. Passing this flag is mandatory. For more custom flags that can be passed in this field, refer to Scan Argument.

11. Click Generate Pipeline Script. Script is generated in the textbox below.


For example, to generate the pipeline script for a local image, Select Local image, enter the Image name, and then click Generate Pipeline Script.


Local images and Docker images contained in .tar files (docker-archive) will be scanned with the Default Image Assurance Policy. Images hosted in a registry will be scanned with all Image Assurance Policies that are applicable (according to the scope of the policy). Refer to Policy Scope.



   12. Copy the script and paste in the script textbox in the Pipeline tab as shown in the previous screenshot.

   12. Click Apply or Save as required.


For more information, refer to the Jenkins document, Snippet Generator.


Follow the same procedure to generate pipeline scripts for hosted images in a registry or docker archive. You can optionally enter the registry name, policies, or custom flags.

Freestyle Jobs

For Freestyle jobs, you should add a build step to scan images with the Aqua scanner, as part of the job configuration. 


Prerequisite

Ensure that you have logged in to the Docker repository where the Aqua scanner image is located. This is required before you proceed.


Configure a freestyle job

To configure a freestyle job:

  1. In the Jenkins portal, navigate to the required freestyle job.
  2. Click Configure on the left pane.
  3. Click the Build tab. You are navigated to the Build section.
  4. Perform the actions as mentioned from steps 3 thru 10 as instructed in the previous section Jenkins Snippet Generator.



Local images and Docker images contained in .tar files (docker-archive) will be scanned with the Default Image Assurance Policy. Images hosted in a registry will be scanned with all Image Assurance Policies that are applicable (according to the scope of the policy). Refer to Policy Scope.


Use plugin to scan images in the Podman container engine

You can use plugin in the build process in the Pipeline and Freestyle jobs running with Podman container engine. Using the Podman container engine, you can only scan locally hosted images.


You can configure a job to scan images during the build process. Configuration of jobs for the Podman container engine is similar to the configuration for the Docker container engine. In this section, difference in the configuration steps from the Docker to Podman container engine is explained.


Pipeline jobs in the Podman container engine

In the Pipeline jobs, the build step for Aqua scanning is included in a pipeline script, as part of the job configuration.


Prerequisites

  • Podman container engine should be installed on the build node where you use the plugin
  • Aqua Security Scanner plugin for Jenkins ("the plugin") should be updated to v3.1.2 or latest, to get the support on scanning images in the Podman container engine
  • Ensure that you logged in to the Aqua registry where the Aqua scanner image is located, in the plugin configuration


Configure a Pipeline job for image scanning using Podman

To configure a image scanning job:

  1. Perform the steps 1 thru 4 mentioned in the Configure a Pipeline job for image scanning using Docker section.
  2. Include a snippet similar to the example shown below, to scan locally hosted images. Replace the localImage parameter value with the identifier of the actual image in your pipeline.
  3. Add the following parameters to scan images using the Podman container engine. Scanner path must be added with the location of scannercli binary in your host.
  • containerRuntime: 'podman'
  • scannerPath: '/absolute/location/of/scannerbinary'
timestamps {
  node('build_node'){
      stage("Scan alpine"){
          aqua locationType: 'local', localImage: 'alpine:latest', localToken: Secret.fromString("6b319d24086718198a0bef664874c291bb991509"), customFlags: '', hideBase: false, notCompliesCmd: '', onDisallowed: 'ignore', showNegligible: false, aqua containerRuntime: 'podman', scannerPath: '/absolute/location/of/scannerbinary'
          }
   }
}

        4. Perform the steps 8 and 9 mentioned in the Configure a Pipeline job for image scanning using Docker section.


Jenkins snippet generator for the Podman container engine

To generate the pipeline syntax to support for the Podman container engine:

  1. In the Configure job > Pipeline tab, click Pipeline Syntax. Pipeline Syntax dialog appears.
  2. From the Sample Step dropdown, select aqua: Aqua Security.
  3. In the 'When image doesn't comply with Aqua policy' section, select either Never fail builds or Perform the action defined in Aqua's policy as shown in the following screenshot. For more information on the actions in a policy that apply to the image to be scanned, refer to Image Assurance Policies.
  4. Select Local image, as Podman container engine scans locally hosted images only.
  5. Enter the following details:
  • Local image: Image name
  • Container runtime: Specify podman. If you do not specify podman here, it defaults to docker
  • Aqua Scanner path: Add the scannercli with its location in your host. /absolute/location/of/scannerbinary. For example: /home/tmp/scannercli.

        6. Perform the steps 6 thru 8 mentioned in the Jenkins snippet generator for Docker section.

        7. Perform the steps 9 thru 11 mentioned in the Jenkins snippet generator for Docker section.


Local images will be scanned with the Default Image Assurance Policy.



For more information, refer to the Jenkins document, Snippet Generator to generate a specific syntax for including in the pipeline script.


Freestyle jobs for the Podman container engine

In the Freestyle jobs, add a build step to scan the image with the Aqua scanner binary, as a part of the job configuration.


Prerequisites

  • Podman container engine should be installed on the build node where you use the plugin
  • Ensure that you logged in to the Aqua registry where the Aqua scanner image is located, in the plugin configuration


Configure Freestyle job for the Podman container engine

To configure a Freestyle job for the Podman container engine:

  1. Perform the steps 1 thru 3 mentioned in the Configure freestyle job for Docker section.
  2. Perform the steps 3 thru 6 mentioned in the Jenkins snippet generator for the Podman container engine section.


Jenkins plugin image scanning results

Console output for Pipeline jobs using the Docker container engine


After you run the plugin, navigate to the required pipeline and click Console Output on the left pane. the console shows output as shown below:


Console output for Pipeline jobs using the Podman container engine

After you run the plugin, navigate to the required pipeline and click Console Output on the left pane. The console shows output as shown below:



View image scanning results for Freestyle job

To view scan results in a Freestyle job:

  1. Open the required Freestyle job.
  2. In the Jenkins build menu, select job from the left pane whose results that you want to see.
  3. Click Aqua Security Scanner on the left pane. You can see the example scan report for a Freestyle job as shown below.