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 also scan images that have been pushed to a registry.


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. Go to Aqua Security section.
  4. Enter the following details:
  • Aqua scanner image
  • Aqua API URL
  • User: name of an Aqua user with scanner permissions
  • Password: user’s 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.

    If you would like to connect Aqua with Jenkins through token based authentication, you should pass -e AQUA_TOKEN=a1b2c34..... (where a1b2c34....is the authentication token). If you pass authentication token, you should also pass --direct-cc flag in the Custom flags field. 

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



Use plugin to scan images

You can use Aqua Security plugin in the Jenkins build process in 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 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.


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', 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',  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', 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.

    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 SyntaxPipeline 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. Enter the following details as per your selection in the previous step:
  • Local image: Image name
  • Hosted image: URL for the registry and the image name
  • docker-archive: Tar file path
    6. Select the Register checkbox to register image with Aqua after scanning is passed successfully.
    7. Select the Show negligible vulnerabilities checkbox to show vulnerabilities of negligible severity in the output.
    8. Enter the following details:
  • Registry name
  • Policies
  • Custom flags

    9. 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, if you connect Aqua with Jenkins through token based authentication as configured in the Additional Docker run options in the Configure Plugin section. For more custom flags that can be passed in this field, refer to Scan Argument.

  10. 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.



   11. 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.


Console output for Pipeline jobs

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:


Freestyle Jobs

For Freestyle jobs, you should add a build step to scan images with the Aqua scanner, as part of the job configuration. To configure 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 8 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.


View image scan 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.