Scan a Container Registry

Use the Tenable Cloud Security CLI to scan a container registry for vulnerabilities. After Tenable Cloud Security scans your container registry, you can view the detailed scan results on the Tenable Cloud Security Console. Tenable Cloud Security supports the following registries for scanning:

Amazon Elastic Container Registry (ECR)
Docker Hub
Docker Registry V2
Nexus
Harbor
Quay
JFrog
Azure Container Registry

You can run the scan in two ways:

Container Registry Scan using CLI
Container Registry Scan using Tenable Cloud Security Docker Image

Container Registry Scan using CLI

This section provides the steps to run a container registry scan using CLI on an Amazon EC2 instance.

Before you begin:

Download and install the Tenable Cloud Security CLI.
Create a project in the Tenable Cloud Security Console to use for the container registry scan.

Note: For accurate results in scan reports and dashboards, Tenable recommends to avoid scanning the same image from multiple projects.
To use an EC2 machine for registry scanning, do the following:
1. Create an EC2 Linux machine.
2. Open firewall for Tenable Vulnerability Management, if not open already.
3. Check that the EC2 machine has internet access.

To scan a container registry with registry credentials:

From the CLI, run the tcs consec command in one of the following ways:
- Without the configuration file
  Copy
```
tcs consec registry <registry_url> \
    --username=<registry_username> \
    --password=<registry_password> \
    --project=<project_ID> \
    --token=<API_token> \
    --allowList=<images_to_scan> \
    --denyList=<images_to_skip> \
    --mode=[scan | dry-run]
```
- With the configuration file:
  Copy
```
tcs consec registry <registry_url> \
    --username=<registry_username> \
    --password=<registry_password> \
    --config=<config_file_path>
    --allowList=<images_to_scan> \
    --denyList=<images_to_skip>  \
    --mode=[scan | dry-run] \
```
Where:
- <registry_url>: URL of the container registry. For example, http://localhost:5000.
- <registry_username>: Registry username. Use TCS_REGISTRY_USERNAME to set the username with an environment variable.
- <registry_password>: Registry password. If you do not want to enter the password in plain text, use TCS_REGISTRY_PASSWORD to set the password with an environment variable.
  
  Note: The registry username and password are required only for registries that require authentication.
- <project_ID>: Project ID in Tenable Cloud Security. Use TCS_PROJECT_ID to set the project ID with an environment variable.
- <API_token>: API authentication token you generate from Tenable Cloud Security. Use TCS_TOKEN to set the API token with an environment variable. For more information, see Generate API Tokens.
- <images_to_scan>: Specify a comma-separated list of images that you want to scan. You can provide a pattern and only those images that match the pattern are scanned. This parameter supports wildcard characters. For example:
  - "*" : Scans all images
  - "foo:*" or "foo" : Scans images with the repository name as foo with any tag.
  - "*:bar": Scans images with the tag name as bar.
  - "*/foo:bar" : Scans all repositories with names that end with foo and have a tag named bar.
  - "foo/*/bar:baz": Scans all repositories with names that start with foo, end with bar and have a tag baz.
  - "*/foo/*:*" : Scans all repositories with names that have foo in the middle.
  Note: The CLI supports only complete string patterns, and not substrings.
- <images_to_skip>: Specify a comma-separated list of images that you want to skip during a scan. You can provide a pattern and the images that match the pattern are skipped.
  
  Note: If you specify both the --allowlist and --denylist parameters, the --denylist parameter takes precedence.
- --mode: (Optional) Specifies the mode of the scan. This parameter can take one of the following two values:
  - scan — Scans the registry for vulnerabilities. This is the default value.
  - dry-run — Creates a CSV report listing all the repositories and tags in the registry. For more information, see Generate a Report of Images in a Container Registry.
- <config_file_path>: Specify the configuration file location that you downloaded from Tenable Cloud Security, which contains the project ID and token. This option accepts absolute or relative file paths (defaults to ./config, then checks <HOMEDIR>/.accurics/config). For more information, see Download Configuration File.

Examples

Docker Hub

Copy

tcs consec registry https://hub.docker.com --username=<registry_username> --password=<registry_password> --project=<project_ID> --token=<API_token>

Harbor

Copy

tcs consec registry https://harbor-registry.service.example.com --username=<registry_username> --password=<registry_password> --project=<project_ID> --token=<API_token>

Nexus

Copy

tcs consec registry https://nexus.example.com:8483 --username=<registry_username> --password=<registry_password> --project=<project_ID> --token=<API_token>

After Tenable Cloud Security completes the registry scan, the CLI output shows a summary with number of images discovered, images newly added after previous scan with links to misconfigurations (violations) and vulnerabilities on the Tenable Cloud Security Console.

Copy

Registry Summary:
    Total images found    : 1
    New images found      : 1

    Violation details         : https://cloud.tenable.com/cns/issues/violations?project=<project_id>
    Vulnerability details     : https://cloud.tenable.com/cns/issues/vulnerabilities?project=<project_id>

Scan an Amazon Elastic Container Registry (ECR)

For an Amazon ECR, you can run a registry scan with the AWS ECR access keys instead of providing the registry username and password.

Before you begin:

If you are using an EC2 machine for scanning, add the AmazonEC2ContainerRegistryReadOnly policy to the IAM role used by the Amazon ECR instance.

To scan an Amazon ECR with ECR security credentials:

Set up the environment variables for connecting to the Amazon ECR:

export AWS_ACCESS_KEY_ID=<key_id>

export AWS_SECRET_ACCESS_KEY=<access_key>

export AWS_DEFAULT_REGION=<region>

Note: You need not export the AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY when running in an EC2 instance with the AmazonEC2ContainerRegistryReadOnly policy attached.

Run the container registry scan with the following command:

Copy

tcs consec registry <registry_url> --project=<project_ID> --token=<API_token>

Where:

<registry_url>: URL of the container registry. For example, https://<aws_account_id>.dkr.ecr.<region>.amazonaws.com.
<project_ID>: Project ID in Tenable Cloud Security. Use TCS_PROJECT_ID to set the project ID with an environment variable.
<API_token>: API authentication token you generate from Tenable Cloud Security. Use TCS_TOKEN to set the API token with an environment variable. For more information, see Generate API Tokens.

Scan a Quay Container Registry

Before you begin:

Set up a robot account with read permissions to the registries that you want to scan.

Use the credentials of this robot account for authenticating and scanning the Quay registry. For more information, see Robot Accounts in Red Hat Quay.io documentation.

To scan a Quay registry:

Scan the container registry with the tcs consec registry command.

Copy

tcs consec registry https://quay.io --username=<Quay_username> --password=<Quay_password> --project=<project_id> --token=<API_token>

Where:

<Quay_username>: Username of the robot account
<Quay_password>: Robot token

Scan a JFrog Container Registry

Before you begin:

Create an access token for JFrog container registry.

For more information, see Access Tokens in JFrog Platform Administration Documentation.

To scan a JFrog container registry:

Scan the container registry with the tcs consec command.

Copy

tcs consec registry https://test.jfrog.io/docker --username=<JFrog_username> --password=<JFrog_Password> --project=<project_id> --token=<API_token>

Note:The registry URL format is <jfrog_registry>/docker.

Where:

<JFrog_username>: JFrog username
<JFrog_password>: JFrog access token

Scan an Azure Container Registry

You can scan an Azure Container Registry either using a service principal or a managed entity.

Scan an Azure Container Registry Using Service Principal

Before you begin:

Create a service principal for your Azure registry and assign the AcrPull role to the service principal. For more information, see Azure Container Registry roles and permissions in Azure documentation.

The following JSON shows the permissions for the AcrPull role.

Copy

{
    "id": "/providers/Microsoft.Authorization/roleDefinitions/<ROLE_DEFINITION_ID>",
    "properties": {
        "roleName": "AcrPull",
        "description": "acr pull",
        "assignableScopes": [
            "/"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.ContainerRegistry/registries/pull/read"
                ],
                "notActions": [],
                "dataActions": [],
                "notDataActions": []
            }
        ]
    }
}

To scan an Azure Container Registry using service principal:

Scan the container registry with the tcs consec command.

Copy

./tcs consec registry https://<REGISTRY NAME>.azurecr.io \
  --project "<PROJECT_ID>" \
  --token "<TCS_TOKEN>" \
  --username ${USER_NAME} \
  --password ${PASSWORD}

Where:

<USER_NAME>: Azure Service Principal username
<PASSWORD>: Azure Service Principal password

Scan an Azure Container Registry Using Managed Entity

Before you begin:

Create a managed identity for your Azure registry and assign the AcrPull role to the managed identity. For more information, see Use an Azure managed identity to authenticate to an Azure container registry in Azure documentation.

To scan an Azure Container Registry using managed entity:

Assign the managed identity to an Azure virtual machine or authenticate the Azure CLI with the managed identity.

Scan the container registry with the tcs consec command without username or password.

Copy

./tcs consec registry https://<REGISTRY NAME>.azurecr.io \
  --project "<PROJECT_ID>" \
  --token "<TCS_TOKEN>"

Scan a Harbor Container Registry

You can access Harbor container registry with an admin account or a robot account.

Authentication Modes

Admin (Basic authentication)
- No additional configuration is required for scanning a container registry with this authentication.
Robot account (Basic authentication)

Configure the account with the following permissions:
- List Repository
- Pull Repository
- List Tag
For more information about creating a robot account, see Create Robot Accounts in Harbor documentation.

To scan a Harbor registry:

Scan the container registry with the tcs consec registry command.

Copy

tcs consec registry https://harbor-registry.service.example.com --username=<registry_username> --password=<registry_password> --project=<project_ID> --token=<API_token>

Where:

<registry_username>: Username of the admin or robot account.
<registry_password>: Password of the admin account or robot account token.

Generate a Report of Images in a Container Registry

To list the repositories and tags in a container registry and generate a CSV report:

Scan the container registry with the tcs consec command.

Copy

./tcs consec registry https://<REGISTRY NAME>.azurecr.io \
  --project <PROJECT_ID> \
  --token <TOKEN> \
  --username <USERNAME> \
  --password <PASSWORD> \
  --mode=dry-run

The following sample shows the console output :

Copy

2023-08-15T13:01:57.950+0200    info    Identified registry as: DEFAULT_V2
2023-08-15T13:01:57.951+0200    info    Beginning discovery of registry: <https://test.azurecr.io>
2023-08-15T13:01:57.952+0200    info    Beginning image discovery of registry registry=<https://test.azurecr.io>
2023-08-15T13:02:00.244+0200    info    Fetched image discovery details image=test.azurecr.io/hello-world:v1
2023-08-15T13:02:04.991+0200    info    Fetched image discovery details image=test.azurecr.io/hello-world:v2
2023-08-15T13:02:05.672+0200    info    Fetched image discovery details image=test.azurecr.io/hello-world:latest
2023-08-15T13:02:07.860+0200    info    Completed fetching image discoveries from registry=<https://test.azurecr.io>
2023-08-15T13:02:07.860+0200    info    Output report: test-azurecr-io-report.csv

The Output report line in the console output shows the name of the CSV report. The CSV file contains the following information:

repository — The repository and image name in the format <repository_name>/<image_name>.
tag — Image tag.
build_time — Build timestamp of the image.
skipped — Shows the status as false or true to indicate whether the image will be skipped during a vulnerability scan. Images are skipped based on the --allowlist or --denylist parameter as well as licensing limits.

The following example shows the content of a CSV file:

Copy

# test-azurecr-io-report.csv
repository,tag,build_time,skipped
test.azurecr.io/hello-world,v1,2019-01-01T01:29:27Z,false
test.azurecr.io/hello-world,v2,2019-01-01T01:29:27Z,false
test.azurecr.io/example/hello-world,latest,2019-01-01T01:29:27Z,true

Scan a Container Registry using Tenable Cloud Security Docker Image

To scan a container registry using the Tenable Cloud Security Docker image:

Verify that Docker Hub is accessible.
Pull the latest Tenable Cloud Security Tenable Cloud Security CLI image from Docker.

The location of the image is https://hub.docker.com/r/tenable/tcs.

Scan the container registry using the Tenable Cloud Security Docker image:

Copy

docker run --rm -t -u root -v /var/run/docker.sock:/var/run/docker.sock -v <report_file_directory> tenable/tcs:latest consec registry <registry_url> --project=<project_ID> --token=<API_token> --username=<registry_username> --password=<registry_password>

Where:

<report_file_directory>: Directory to save the Tenable Cloud Security scan reports.
<registry_url>: URL of the container registry. For example, http://localhost:5000.
<registry_username>: Registry username. Use TCS_REGISTRY_USERNAME to set the username with an environment variable.
<registry_password>: Registry password. If you do not want to enter the password in plain text, use TCS_REGISTRY_PASSWORD to set the password with an environment variable.
<project_ID>: Project ID in Tenable Cloud Security. Use TCS_PROJECT_ID to set the project ID with an environment variable.
<API_token>: API authentication token you generate from Tenable Cloud Security. Use TCS_TOKEN to set the API token with an environment variable. For more information, see Generate API Tokens.

Note:Container registry scan might take a long time to complete. The duration to complete a registry scan depends on the number of images in the repository.

What to do next:

Go to the link in the CLI output to view the misconfigurations and vulnerabilities on the Findings page. Tenable Cloud Security shows the vulnerabilities detected for the scanned container. For more information, see View Vulnerabilities.