TABLE OF CONTENTS

Overview

Aqua can scan images from several types of external image registries. The registries and specific repositories within them must be integrated with Aqua to enable image scanning. Once a specific image registry is integrated with Aqua, you can configure to scan images from registries directly or Aqua users can add images to the Aqua platform manually. This topic explains how to add image registries to Aqua. 


You can add image registries from the Administration > Integrations > Image Registries page. When you have multiple registries added to Aqua, you can search any registry with its name and type using the search box at the top of the page.


Add an image Registry to Aqua

To add an image registry to Aqua:

  1. Navigate to Administration > Integrations > Image Registries.
  2. Click Add Registry. Create New Registry page appears which has two tabs, Registry Details and Registry configuration as explained in the following sections.



Registry Details


* indicates that entering value in the field is mandatory.


In this tab, perform the following actions:


1. Enter the following details:

  • * Registry Name
  • Description: (Optional)
  • * Registry Type: Select a Registry type from dropdown.


 

2. Enter additional required details, as determined by the registry type. Refer the following table for more information on these details.


Registry TypeDetails
Amazon Elastic Container Registry (ECR)The default connection type is Credentials in which following credentials are used for integration:

  • * AWS Region:  Amazon region containing the registry
  • * Access Key 
  • * Secret Key

For more information on adding this registry and other connection types, Access Delegation and STS Token Authorization, refer to Configure Amazon Elastic Container Registry (ECR).
Azure Container Registry* Registry URL

The parameters depend on the Connection Type selected:

Credentials
* Username, * Password

Token
* Token Name, * Token Password

Service Principal
* Client ID, * Secret Key, * Tenant ID, * Subscription ID
CoreOS Quay* Registry URL, * Username, * Password

Registry URL requirements:
  • If you use the cloud edition of the Quay registry (https://quay.io), You must use https://quay.io for the URL attribute to integrate with the registry.
  • If you use Quay installations on-premises, the URL should be the one that leads to the root path of the registry. The correct URL is, for example by adding /v2/ prefix: https://quay.io/v2/
Docker Hub* Username, * Password
Docker Registry (v1/v2)

* Registry URL, Username, Password


Refer to the Limitations below.

Docker Trusted Registry* Registry URL, * Username, * Password

prefer DTR API: Select this checkbox to prefer searching repositories with the DTR API. On failover of DTR API, switch the searching repositories with standard Docker V2 API.
Google Container Registry (GCR) and Google Artifact Registry (GAR)Following are the credentials required for this connection:

  • * Region: Google region containing the registry. For GAR, you can also select asia, europe, or us to support GAR multi-region.
  • * Authentication Method: Service Account JSON Key or Access Token

For more information on the authentication mechanisms in GAR and GCR, refer to Authentication Mechanisms for Google GAR and GCR Integration.
Harbor Registry* Registry URL, * Username, * Password
IBM Container Registry* Region, * Account ID, * Username, * Password
JFrog ArtifactoryThe parameters depend on the Authentication Method selected:

Username/Password
* Registry URL, * Username, * Password

API Key (refer to Artifactory Integration)
* Registry URL, * API Key

For more information on the JFrog Artifaction webhook plug, refer to Usage of JFrog Artifactory Webhook Plugin.
OpenShift Container Registry* Registry URL

Note: To access this registry, the following permissions are required for the service account that Aqua uses: 
  • resources:
    • imagestreams
    • imagestreams/layers
  • verbs:
    • get
    • list
    • watch
Red Hat Atomic Registry

* Registry URL, * Username, * Password


Refer to the Limitations below.

Sonatype Nexus Repository OSS* Registry URL, * Username, * Password

For more information on the configurations in Sonatype Nexus registry, refer to Configurations in Sonatype Nexus Repository OSS for Integration.


3. Select the scanner connection option, either Any Scanner or Specific Scanner. If you select Specific Scanner option, a dropdown field Scanner appears as explained in the next step.

4. Scanner: From the dropdown, select a specific scanner which was deployed as daemon scanner. For more information, refer to Add Scanner Daemons.


Limitations: Docker Registry (v1 API) and Red Hat Atomic Registry do not support the following:

- Automatically Register New Images under Administration > Integrations > Add Registry > Advanced Settings. For more information, refer to the following section.

- Registry Search for repositories under Images > Add Images; For more information, refer to Add images from the Images screen


Registry Configuration

General settings

  • Scan Timeout: (optional) You can set the timeout period for scanning images in this registry. If a scan takes longer than the specified time, the image will be re-queued for scanning. This setting pertains only to the registry being configured. If timeout is not set from this page, the value will be taken from the "Scan timeout" set under scanning settings.
  • Following are the additional settings available for certain registry types:
SettingApplies toDescription
Enable Registry Notification EventsAzure Container Registry, CoreOS Quay, Docker Hub, Docker Registry (v1/v2), Harbor Registry

Registry notification events include: new images, replacement of images, and changed image tags in a registry.

When this option is enabled, registry events are sent to the Aqua Webhook URL, entered below. Aqua will listen for these events, and automatically scan new or changed images.

Use case: This option can be used when you want to scan new or changed images automatically without having to wait for the automatic schedule scan.

Webhook URLsub-option of "Enable Registry Notification Events"Aqua URL for Webhook notifications: copy this URL to the registry events configuration
Webhook Authorization Headersub-option of "Enable Registry Notification Events"Copy this value to your registry events configuration.
Integrate with Azure's ACR Quarantine APIAzure Container RegistryWhen you select this checkbox, the Aqua Server will trigger an API call to ACR to remove the ACR quarantine state from an image after a successful scan.
Enable Image Stream Notification EventsOpenShift Container RegistryWhen you select this checkbox, Aqua will automatically scan images pushed to OpenShift's internal Docker registry or to an OpenShift image stream.


Pull and scan images

There are two options to pull and scan images either manually or automatically:

  • Manual: Aqua will not automatically pull images from the registry for scanning.
  • Automatic: Aqua will automatically pull images from the registry for scanning on a daily basis.

Automatic pull and scan overrides image repository cleanup

If you enable Automatic, the Remove the oldest images in each repository setting under Settings > Cleanup will be ignored for this registry.



There are a couple of options associated with the pull and scan images as explained below:


OptionDescription
Schedule every day at...Set this to the daily time at which Aqua should search the registry for new images to pull and scan. The time is that of the host on which the Aqua server is deployed.
Rescan existing imagesWhen you select this checkbox, existing images from the registry will also be rescanned whenever new images are pulled for scanning.



Advanced settings > Pull and scan settings

Settings in this section appear when you select Automatic pull and scan images option. Following are the two options in the advanced settings to pull and scan images.


OptionDescription
Name/tag criteriaYou can limit the selection of images to pull and scan by specifying one or more patterns for the image name and/or tag. You can add multiple patterns one at a time and click Add.

The general form of each pattern is:

<name><:tag>

  • If the text string name is specified, only images whose names contain name are selected
  • If the text string tag is specified, only images whose tags contain tag are selected

Examples:

  • alpine will select all images (of all tags) whose names contain alpine
  • :4 will select all images (of all names) whose tags contain 4
  • alpine:4 will select all images whose names contain alpine AND whose tags contain 4

You can delete a pattern by clicking x in its box.

No Additional ConditionsSelect this if you do not want to pull specific images by selecting one of the following options.
Image creation dateIf you select this checkbox, Aqua will pull images that were created in the last [set by user] days, months, or years. The default setting is 60 days.
Latest images from each repositoryIf you select this checkbox, Aqua will pull latest x number [set by user] of images from selected or all repositories. Latest images are based on image creation date in the repository.



Exceptions

There are two options in this section as explained below:


OptionDescription
Never pull images with name/tag pattern

You can restrict the selection of repositories further by specifying repositories that are not to be searched. These patterns are also character strings. Any repository names of which contain the string will be excluded. If none of the name/tag patterns are added, no repositories will be excluded.


You can add multiple pull patterns one at a time and delete pull patterns by clicking x in its box.

Always pull images with name/tag patternYou can specify image patterns for the image name and/or tag that only should be pulled and scanned . You can add multiple patterns one at a time and click Add.


Cleanup Settings


Automatically clean up images and repositories which are no longer present in the registry from Aqua console

When it is enabled, repositories and images will be removed from the Aqua Images screen automatically, if they were removed in the image registry. They will be removed at each occurrence of image pull schedule as configured in the Pull and Scan Images settings as shown above.


Note: This setting does not apply to Registry type "Docker Hub" as this registry type is public in nature.


Test Connection

Before completing the image registry integration, it is recommended that you test the connection. You can click Test Connection so that the Aqua server attempts to connect to the registry and validate your credentials (username and password) and pull an image. With all types of image registries except for Docker Registry (v1 API) and Red Hat Atomic Registry, you can test the connection without specifying the image to be pulled. Aqua then searches the registry, and pull an image selected at random. 


Once the connection is tested, you can see the results as shown below:



Once all the required configurations are completed, click Save at the top right of the page.


Registry specific configuration

Configurations explained in this topic are general and applicable to most of the image registry integrations with Aqua. For more information on the registry specific configurations, refer to the relevant documentation.