TABLE OF CONTENTS

Overview

The Azure DevOps Extension in the Azure Marketplace provides an easy way for Aqua to scan images in Azure DevOps projects to detect various security issues.


The Aqua Security extensions are installed in the Azure DevOps projects. Once installed, you can add a build step to scan the image.


This topic explains how to install and configure the Aqua Security extension for Azure DevOps, and then how to use it to scan images during the build process, and view the scan results.


Compatibility with Aqua components

Aqua Security Extension (images)

  • Linux: 6.x (container)
  • Windows: Artifacts (embedded scanner) (recommended) and 4.2.0


Supported agent pools

The list below shows which agent pools should be used to scan images through Aqua extension. The agent pool is different for Linux and Windows.


Linux

Ensure that the Aqua Scanner image is pulled to the agent pool through Docker registry connection in Azure DevOps. If the required scanner image is not already pulled, this will be done automatically before image scanning, when you connect to Docker registry in Azure DevOps.


Windows

If you use Aqua extension having scanner version later than 4.2.0, you should use Artifacts feature to download the scanner binary. For example, if you want to use Windows scanner version 5.2.0 or 6.2.0, you should create an artifact to download and publish the package from Aqua storage and add the package as a task in the Azure image scanning pipeline. Using artifacts, the desired scanner version is packaged and used in the Azure image scanning pipeline to scan Windows based images. For more information, refer to Usage of Artifacts in Azure DevOps Extension.


If you use Aqua extension having scanner version 4.2.0, the Aqua Scanner binary executable is embedded in the Aqua extension, so there is no need to pull or install it.


Prerequisites

  • Before you configure the Azure DevOps extension, make sure that you have scanner permission assigned by your Aqua admin.
  • You should add a Docker Login task before the Aqua's Image Scanning task, having a valid service connection to your docker instance. This task help scanning Linux images from Aqua, through your specific docker instance.


Install the Aqua Security extension in Azure DevOps

This procedure configures Aqua Server as a service connection in Azure DevOps. This is executed by installing the Aqua Security extension downloaded from Azure Marketplace. To download and install the extension:

  1. In your browser, navigate to this Azure Marketplace URL. You are navigated to the Aqua Security extension page.


      2. Click Get it free. You will be redirected to the Install extension page.


     3. From the dropdown, select an Azure DevOps organization.

     4. Click Install. The extension is installed to your Azure DevOps organization.


Create new service connection

You should create a new service connection from your Azure DevOps project to Aqua server using which system will scan images in the Aqua Security task. To create a new connection:

  1. In the Azure DevOps console, select the project in which you want to scan images with Aqua.
  2. In the left pane, select Project settings.


        3. In the left pane, navigate to Pipelines > Service connections.

        4. Click Create service connection and select Generic. New Generic service connection dialog appears.


        5. Enter following details in the new service connection dialog: 

  • Server URL: the Aqua Server URL or IP address
  • Username: an Aqua user with scanner permissions
  • Password/Token Key: the Scanner user password
  • Service connection name: a name for the connection
  • Description: (Optional) description for the service connection
  • Select Enable Grant access permission to all pipelines

       6. Click Save. A new service connection to the specified Aqua server is created.



Use extension to scan images

You can use the Aqua Security extension to scan images, as a step in a pipeline build process. This task scans a Docker image for security vulnerabilities and compare it against an image assurance policy. You should add this task after a step that builds a Docker image and before a step that pushes the image to a registry.

To add Aqua Security as a task in the build process:

  1. In the Azure DevOps console, navigate to Pipelines in the left pane.
  2. Select the required pipeline from the available list.
  3. Click Edit on the top right of the page. Pipeline detail view appears.


    4. In the Tasks tab on the left pane, Click + and go to the Marketplace tab.

    5. In the Marketplace tab on the right pane, in the search box, enter Container Security. Container Security extension from Aqua appears in the search results.

    6. Click Get it free. The Aqua Security extension is added to this pipeline and it is available in the All tab now.


This extension shows Installed, if you have already installed extension by following steps mentioned in the section, Install the Aqua Security extension in Azure DevOps.


   7. In the Tasks tab on the left pane, Click + and go to the All tab.

   8. Hover on the Aqua Security task and click Add. A new task Image Scanning is now added to the list of tasks on the left pane.

    9. In the Tasks tab on the left pane, click the just added task, Image Scanning. Task configuration page appears on the right pane.



  10. Enter the following details in the Aqua extension configuration page:


FieldDescription
Task versionVersion of the specific task
Display nameName of the step that should appear in the list of build steps
Scan typeSelect one of the following options:
  • local: if the images are on a local server
  • hosted: if images are hosted on another host server. If you select this option, you should enter more details in the Registry field explained in the next step
  • docker-archive: if the images are contained in a .tar file.
RegistryName of the Aqua registry in which the image is stored (for the remote scan). Entering details in this field is required when you select hosted in the Scan type field.
Aqua Management Console ConnectionFrom dropdown, select the required service connection name that you have created by following steps mentioned in the section, Install the Aqua Security extension in Azure DevOps.
Docker Compose FileSpecify the file which has multiple images that need scanning
Tar File PathEnter the file path which has images stored in the docker tar file
PoliciesApply the list of image assurance policies to the image. You can enter multiple policies separated by commas.
Shell command to execute when no compliance(optional) Add a shell command to be run after scanning, if the image is found to be non-compliant
Custom flagsAdd additional command-line flags in this field. The supported custom flags are shown in the Custom flags section below.
Do not verify TLS certificatesSelect this checkbox to prevent scanner check the valid TLS certificates (use this in a development environment, for example).
Collect malware files when scanning imageSelect this checkbox to look for malware files in images while scanning
Show vulnerabilities that will not be fixedSelect this checkbox to check images for vulnerabilities marked by the component vendors as "will not fix"
Register the image in the Aqua Server only if is determined to be compliantSelect this checkbox, if required
Local imageRegister: Select the Register checkbox to register the image with the Aqua Server after it is scanned. You can select this option if you have selected local in the Scan type field
Hosted imageEnter following details, if you have selected hosted in the Scan typefield:
  • Hide base image vulnerabilities: select this checkbox to prevent showing vulnerabilities found in the base image used by the image
  • Show negligible vulnerabilities: select this checkbox to show vulnerabilities with severity 'negligible'
Linux ParametersEnter the following Linux parameter if your image is Linux based:
  • Aqua Scanner Image name: name of the Aqua Scanner image (example: aquasec/scanner:6.5). The default Aqua scanner image is scanner:6.5. You can change the Aqua scanner image to the required scanner version.
  • Additional Docker run options: Pass any additional docker run options. If you would like to connect Aqua with Azure DevOps through token based authentication, you should pass -e AQUA_TOKEN=a1b2c34..... (where a1b2c34....is the authentication token). You can get the token of a specific scanner from the Scanners page or contact your Aqua admin. For more information, refer to Add Scanner Daemons.

    If you pass authentication token, you should also pass the --direct-cc flag in the Custom flags field.
Windows ParametersEnter the following Windows parameter if your image is Windows based:
  • Scanner Version 4.2.0: version of the Scanner, which defaults to 4.2.0. If you select this option, Windows scanner binary is embedded within the extension.
  • Artifacts: select this if you want to use a service where you can create package feeds to publish and consume the windows based scanner binary package. For more information, refer to Usage of Artifacts in Azure DevOps Extension.
Control OptionsEnter the following details for the Control Options:
  • Enabled: enable the extension (must be checked)
  • Continue on error: select this to enable continue scanning if controls in the applied assurance policies fail the image
  • Timeout: timeout for scanning an image (in minutes)
  • Run this task: Click Run this task to start executing task. For more information, refer to the Azure document, Task types & usage.
Output VariablesReference name: Enter a unique name in the Reference name field to allow a given task to publish a set of variables back to server, so the variables can be used in the downstream jobs. For more information, refer to the Azure document, Output Variables.


Aqua scans the image during execution of a task in the build process. For local images, Aqua uses the Default image assurance policy. For images in a registry, Aqua applies all image assurance policies. For more information, refer to Image Assurance Policies.


Scan results are returned to the build process. If the scan results are negative, the process will proceed as per action on the Continue on error switch and the policy actions settings in the policies.


Custom flags

Aqua extension supports the following custom flags in the configuration.


Custom flagDescription
--direct-ccTo connect to the Aqua CyberCenter directly. Passing this flag is mandatory if you connect Aqua with Azure DevOps through token-based authentication.
--disable-reportTo disable publishing image scan results in the pipeline > Aqua Scanner Report page; but image scanning artifacts will be stored in the build agent machine.
path=directory

To add a custom directory path where you want to store image scanning artifacts (HTML report and json file); by default, these reports are stored in the "tmp/" directory. Example: path=/home/ec2-user/aqua.


Note: When you want to pass multiple custom flags, the "path=directory" flag should be passed first.

View image scanning results

Select the desired pipeline from the list of available pipelines and select the Aqua Scanner Report tab to view the scan results. For each instance of Aqua scanning task, a new scan report is displayed.

A sample image scan result is shown below: