Install Registry Scanner

Setup

Prerequisites

• Helm v3.6 or above

• A Kubernetes cluster managed with Helm

  • The registry scanner client will be installed here.

• A Sysdig Secure API token

  • Recommended: Set up a service account with minimal privileges, such as a Standard role.
  • Use a custom role with the following permissions for Sysdig Secure:
    • Scanning Image Results: read and create
    • Scanning: read

• Network access to the target registry for the installed components

• Outbound network access to the Sysdig backend to store results

  If behind a firewall, follow the outbound network rules for vulnerability scanning

• The Registry Scanner node must possess the capacity to execute a Docker pull from the node. Use the following command to confirm this:

   docker pull ${THE_REGISTRY}/${A_IMAGE}
  

Supported Vendors

• AWS Elastic Container Registry (ECR) Single Registry, Organizational
• JFrog Artifactory
  SaaS, OnPrem
• Azure Container Registry (ACR)
  Single Registry
• IBM Container Registry (ICR)
• Quay.io SaaS
• Harbor
• Google Artifact Registry (GAR), Container Registry (GCR)
  Single Registry
• Nexus

Known Limitations

• A new registry scanner must be installed per registry (except for AWS Organization).
• Public registries are not supported.
• Images that have been scanned and reported to Sysdig are rescanned only on the designated refresh cycle. Scans are refreshed on a scheduled Helm cron job, every Saturday at 6:00 AM by default. You can adjust the schedule.
• Check vendor-specific limitations given below.

Installation

Overview

1. Install the Registry Scanner Helm Chart:

   $ helm repo add sysdig https://charts.sysdig.com
   $ helm repo update
   

2. Prepare the Helm chart for your specific registry vendor. Provide:

   • <SYSDIG_SECURE_URL>: Region-dependent Sysdig Secure endpoint
   • <SYSDIG_SECURE_API_TOKEN>: See Prerequisites
     
     

3. Launch Helm instructions and allow some time for the first scan.

   • Note: Use the right-side navigation on this page to jump to particular vendors.
   • Optional: For first tests and troubleshooting, configure the Scan On Start or Manual Launch option to avoid waiting for the scheduled cron job.

4. Check results in the Sysdig Secure Vulnerabilities | Registry UI.

If no data is displayed, or you want to dig into the internals, check troubleshooting steps.

Upgrade

Perform regular helm chart upgrade procedure:

1. Upgrade the repository with helm repo update
2. Re-launch the helm upgrade --install with the values from the previous installation.

JFrog Artifactory

Prerequisites

Perform a pre-installation check to identify your Artifactory configuration. Identify the following configuration parameters:

• registryURL: The Registry URL corresponding to your Artifactory environment.
• registryApiUrl: The Registry API URL corresponding to your Artifactory environment.

Installation

Connect with an externally managed version of Jfrog Artifactory.

$ helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
--set config.secureBaseURL=<SYSDIG_SECURE_URL> \
--set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
--set config.registryType=artifactory \
--set config.registryUser=<JFROG_ARTIFACTORY_USER> \
--set config.registryPassword=<JFROG_ARTIFACTORY_PASSWORD>
--set config.registryURL=<JFROG_ARTIFACTORY_REGISTRY_URL> \
--set config.registryApiUrl=<JFROG_ARTIFACTORY_REGISTRY_API_URL>

Limitations

Multi-arch Docker manifest/packages are not supported.

AWS ECR Single Account

Use one of the following installation methods based on where the Kubernetes cluster is located:

Same AWS Account

If EKS and the registry are in the same account, launch the installation in that account with an AWS Elastic Kubernetes Service (EKS). No specific credential setup is required, since EKS already grants AmazonEC2ContainerRegistryReadOnly policy to the default nodes-eks-node-group-* role.

$ helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
--set config.secureBaseURL=<SYSDIG_SECURE_URL> \
--set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
--set config.registryType=ecr \
--set config.registryURL=<AWS_REGISTRY_URL> \
--set config.aws.region=<AWS_REGION>

• <AWS_REGION>: Registry AWS region
• <AWS_REGISTRY_URL>: Registry URL e.g., 123456789012.dkr.ecr.us-east-1.amazonaws.com

Different Account or Kubernetes Not in AWS

Credentials are required in this case:

$ helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
--set config.secureBaseURL=<SYSDIG_SECURE_URL> \
--set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
--set config.registryType=ecr \
--set config.registryURL=<AWS_REGISTRY_URL> \
--set config.aws.region=<AWS_REGION> \
--set config.aws.accessKeyId=<AWS_ACCESS_KEY_ID> \
--set config.aws.secretAccessKey=<AWS_SECRET_ACCESS_KEY>

• <AWS_REGION>: Registry AWS region

• <AWS_REGISTRY_URL>: Registry URL. e.g., 123456789012.dkr.ecr.us-east-1.amazonaws.com

• <AWS_ACCESS_KEY_ID>, <AWS_SECRET_ACCESS_KEY> from an AWS user with the following permissions for the given registry to be scanned:

  ecr:GetAuthorizationToken
  ecr:BatchCheckLayerAvailability
  ecr:GetDownloadUrlForLayer
  ecr:GetRepositoryPolicy
  ecr:DescribeRepositories
  ecr:ListImages
  ecr:DescribeImages
  ecr:BatchGetImage
  ecr:GetLifecyclePolicy
  ecr:GetLifecyclePolicyPreview
  ecr:ListTagsForResource
  ecr:DescribeImageScanFindings    
  

Limitations

• The scanner for single-account will target a single registry (aka, the registry of one region). To scan several regions, either use the AWS Organizational scanner or set up one scanner per region.
• If the AWS Kubernetes cluster and the registry are in different accounts but under the same organization, use the AWS Organizational setup and allow listing a specific account.

AWS ECR Organizational

AWS organizational accounts have a management account with multiple member accounts and multiple registries or regions. This option allows scanning of all registries on any member account or the region of an AWS Organization. The Kubernetes cluster that the registry will scan may be inside or outside of AWS.

Process Overview

You will:

1. Set up roles and permissions in the AWS console to be used for registry scanning.
   • Optionally, validate the setup with a Sysdig test script
   • Optionally, add a configuration to the Helm chart to limit the member accounts that will be checked for scanning.
2. Install with the Helm chart in one of two ways:
   • Option 1: Access Key/Secret Key With an AWS IAM user security credentials, aimed for quick testing or a more simple setup.
   • Option 2: Service Account With AWS Kubernetes Service Account, aimed for a more productive scenario.

Set Up Permissions in AWS

In the AWS console, set up authentication roles to allow discoverability.

You will:

• Create one role in the management account (ORGANIZATION_MANAGEMENT_ROLE_ARN).
• A recommended step is to create a role name to be assigned to every targeted member account (ORGANIZATION_MEMBER_ACCOUNTS_ROLE_NAME). Otherwise, the default AWS member role name OrganizationAccountAccessRole will be used, which includes admin privileges.
  • Tip: To narrow the list of member accounts that will be checked during scanning, you can set the aws.AllowListMemberAccountIDs attribute option in the Registry Scanner Helm chart. This eliminates noisy error messages.
• Optionally, validate the setup using Sysdig’s test script.

Create Roles

• Management role: ORGANIZATION_MANAGEMENT_ROLE_ARN will be assumed and used to discover member accounts.
• Member role name: ORGANIZATION_MEMBER_ACCOUNTS_ROLE_NAME will be assumed on the member accounts to discover and scan their registries.

Providing Credentials to the Registry Scanner

The registry scanner requires three types of credentials to discover and read Amazon Elastic Container Registry (ECR) images from all member accounts and all regions within an AWS organization.

Kubernetes Job/Pod AWS Credentials

You need to provide either an Access Key/Secret Key or a service account that has the necessary permissions.

• Access Key/Secret Key

  If you choose to provide an Access Key/Secret Key, use the <AWS_ACCESS_KEY_ID>, <AWS_SECRET_ACCESS_KEY> format. Then, you need to set the policy permissions required to allow these credentials to impersonate the ORGANIZATION_MANAGEMENT_ROLE_ARN.

  Use the following policy to allow the impersonation:

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "AllowAssumeManagementRole",
        "Effect": "Allow",
        "Action": "sts:AssumeRole",
        "Resource": "<ORGANIZATION_MANAGEMENT_ROLE_ARN>"
      }
    ]
  }
  

• Service Account

  For Amazon Elastic Kubernetes Service (EKS) clusters on AWS, you can configure the necessary permissions at the service account level.

  Important points:

  1. Create an IAM OIDC provider for your EKS cluster. Note: If you deployed the cluster with the EKS Terraform module, it was created automatically (check oidc_provider output).

  2. In the role associated with the service account (SERVICE_ACCOUNT_IAM_ROLE_ARN), create a policy to enable assuming the role of the management account.

     {
       "Statement": [
         {
           "Action": "sts:AssumeRole",
           "Effect": "Allow",
           "Resource": "<ORGANIZATION_MANAGEMENT_ROLE_ARN>",
           "Sid": ""
         }
       ],
       "Version": "2012-10-17"
     }
     

  3. In the role associated with the service account (SERVICE_ACCOUNT_IAM_ROLE_ARN), configure a trust relationship to allow the service account in Kubernetes to assume the role.

     • Default SERVICE_ACCOUNT_NAME will be registry-scanner, derived from the helm installation release name.

     {
         "Version": "2012-10-17",
         "Statement": [
             {
                 "Effect": "Allow",
                 "Principal": {
                   "Federated": "arn:aws:iam::<MANAGEMENT_ACCOUNT>:oidc-provider/<OIDC_PROVIDER>"
                 },
                 "Action": "sts:AssumeRoleWithWebIdentity",
                 "Condition": {
                   "StringEquals": {
                     "<OIDC_PROVIDER_URL>:sub": "system:serviceaccount:<NAMESPACE>:<SERVICE_ACCOUNT_NAME>",
                     "<OIDC_PROVIDER_URL>:aud": "sts.amazonaws.com"
                   }
                 }
             }
         ]
     }
     

  4. Save the role <SERVICE_ACCOUNT_IAM_ROLE_ARN> value associated with the Kubernetes service-account and use it during the installation.

Credentials for the Management Role

Provide credentials for the <ORGANIZATION_MANAGEMENT_ROLE_ARN> to discover registries for all member accounts and all regions. You must assign policy permissions and trust relationships to this role.

Assign Policy Permissions

Assign one of the following policy permissions to the management role:

• AWSOrganizationsReadOnlyAccess: AWS managed policy which Provides read-only access to AWS Organizations.

• Inline policy to allow the management role to assume member account roles:

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "AllowManagementRoleToAssumeMember",
        "Effect": "Allow",
        "Action": "sts:AssumeRole",
        "Resource": "arn:aws:iam::*:role/<ORGANIZATION_MEMBER_ACCOUNTS_ROLE_NAME>"
      }
    ]
  }
  

Assign the Trust Relationship

You must assign the trust relationship to allow this role to be assumed by the principal of the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY / service account configured in the previous step.

• Access Key/Secret Key

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "<AWS_ACCESS_USER_ARN>"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

• Service Account

  {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Effect": "Allow",
              "Principal": {
                "AWS": "<SERVICE_ACCOUNT_IAM_ROLE_ARN>"
              },
              "Action": "sts:AssumeRole"
          }
      ]
  }
  

Credentials for the Member Role Name

You need to provide credentials for the <ORGANIZATION_MEMBER_ACCOUNTS_ROLE_NAME> that is available in all scoped member accounts of the organization with access to discover and read registries within. This role will be assumed by the ORGANIZATION_MANAGEMENT_ROLE_ARN to impersonate each member account.

By default, the scanner uses the AWS-created administration role OrganizationAccountAccessRole. Using this role will work fine; however, if you need it, you can create a lower-permission role.

(Optional) Least-Privilege-Access Permissions

Create a role in all accounts and assign the following least-privilege-access permissions to it.

The permissions must be assigned to all roles in all accounts that will be scanned.

• AmazonEC2ContainerRegistryReadOnly: AWS managed policy that Provides read-only access to Amazon EC2 Container Registry repositories. Assign the following least-privilege-access permissions to the member role name:

• Custom permissions to allow region discovery:

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "CustomPolicyAllowDescribeRegions",
        "Effect": "Allow",
        "Action": "EC2:DescribeRegions",
        "Resource": "*"
      }
    ]
  }
  

• The member role must be assumable by the ORGANIZATION_MANAGEMENT_ROLE_ARN, so you must assign the following trust relationship to the new role:

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "AWS": "<ORGANIZATION_MANAGEMENT_ROLE_ARN>"
        },
        "Action": "sts:AssumeRole"
      }
    ]
  }
  

Also, the ORGANIZATION_MANAGEMENT_ROLE_ARN must be configured to allow assuming the ORGANIZATION_MEMBER_ACCOUNTS_ROLE_NAME you just created in all accounts. You must assign the following policy permission to the management role, which will allow it to assume the member role in all accounts:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowManagementRoleToAssumeMember",
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": "arn:aws:iam::*:role/<ORGANIZATION_MEMBER_ACCOUNTS_ROLE_NAME>"
    }
  ]
}

Optionally, if you want to test the role with the validation script of the next section you will need to add the following permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CustomPolicyAllowDescribeRegions",
      "Effect": "Allow",
      "Action": "iam:SimulatePrincipalPolicy",
      "Resource": "*"
    }
  ]
}

(Optional) Validate Setup with Test Script

Sysdig provides the test script aws-org-test-credentials.sh to check the created roles and permissions, along with validating the discoverables registries throughout the organization.

Launch the script from a shell. Use the AWS authentication credentials for the member account where the Registry Scanner will be deployed. Note: If you’re running it with some other credentials from the member account, remember that a trust relationship must exist with the Management Account Role (see Step2. Assign Trust Reslationsip)

./aws-org-test-credentials.sh <ORGANIZATION_MANAGEMENT_ROLE_ARN> <ORGANIZATION_MEMBER_ACCOUNTS_ROLE_NAME>

Sample output:

> using *** as member accountID
> Organization accountID: *** with discovered member account IDs
***
-------------------------
> Starting registry discovery and permission checkup

> Account ***
Checking AWS registry permissions
Discovering registries
...
-------------------------
> Discovered Registries
***.dkr.ecr.eu-central-1.amazonaws.com
***.dkr.ecr.eu-west-1.amazonaws.com
...

Install with Helm Chart

Use one of the following installation options depending on the credential format used:

Access Key/Secret Key

Suitable for testing or if your Kubernetes cluster is outside AWS.

<AWS_ACCESS_KEY_ID>, <AWS_SECRET_ACCESS_KEY> from the AWS user

$ helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
--set config.secureBaseURL=<SYSDIG_SECURE_URL> \
--set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
--set config.registryType=ecr \
--set config.aws.accessKeyId=<AWS_ACCESS_KEY_ID> \
--set config.aws.secretAccessKey=<AWS_SECRET_ACCESS_KEY> \
--set config.aws.managementAccountRoleARN=<ORGANIZATION_MANAGEMENT_ROLE_ARN> \
--set config.aws.memberAccountsRoleName=<ORGANIZATION_MEMBER_ACCOUNTS_ROLE_NAME>

Service Account

If you’re using AWS Elastic Kubernetes Service (EKS), you must assign an IAM role (SERVICE_ACCOUNT_IAM_ROLE_ARN) to a Service Account, with which the scanner will run.

$ helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
--set config.secureBaseURL=<SYSDIG_SECURE_URL> \
--set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
--set config.registryType=ecr \
--set serviceAccount.annotations.eks\\.amazonaws\\.com/role-arn=<SERVICE_ACCOUNT_IAM_ROLE_ARN> \    
--set config.aws.managementAccountRoleARN=<ORGANIZATION_MANAGEMENT_ROLE_ARN> \
--set config.aws.memberAccountsRoleName=<ORGANIZATION_MEMBER_ACCOUNTS_ROLE_NAME>

Additional Helm Configuration

Limit Registry Accounts to Scan

Optionally, limit the scoped registry accounts using the allowListMemberAccountIDs Helm chart attribute. This approach is preferred for initial testing, when the ORGANIZATION_MEMBER_ACCOUNTS_ROLE_NAME may be provisioned only on select accounts and having the scanner check the rest of the member accounts in the organization would generate noisy error messages.

Set the attributes:

--set config.aws.allowListMemberAccountIDs[0]='<ORG_MEMBER_ACCOUNT_ID_1>' \
--set config.aws.allowListMemberAccountIDs[1]='<ORG_MEMBER_ACCOUNT_ID_2>' \

Limitations

• The scanner for AWS Organizational accounts does not support ECRs hosted in the management account, as per AWS Guidelines best practices for management accounts
• Public registries are not supported.

Harbor

To run the scanner in Harbor, you must have the registry URL and the user credentials with the Administrator profile.

$ helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
--set config.secureBaseURL=<SYSDIG_SECURE_URL> \
--set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
--set config.registryType=harbor \
--set config.registryURL=<HARBOR_REGISTRY_URL> \
--set config.registryUser=<HARBOR_USER> \
--set config.registryPassword=<HARBOR_PASSWORD>

• <HARBOR_USER> \ <HARBOR_PASSWORD>: User credentials with Administrator flag activated (Project Admin role is not currently supported)
• <HARBOR_REGISTRY_URL>: Harbor registry URL
  e.g., core.harbor.domain

Quay.io

To run the scanner in your Quay.io repository, you need the user and password with admin permissions.

$ helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
--set config.secureBaseURL=<SYSDIG_SECURE_URL> \
--set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
--set config.registryType=quay \
--set config.registryURL=quay.io \
--set config.registryUser=<QUAY_USER> \
--set config.registryPassword=<QUAY_PASSWORD>

• <QUAY_USER>: CLI user for Quay.io.
• <QUAY_PASSWORD>: CLI password for Quay.io. It must be generated through the account settings.

IBM Container Registry

To run the scanner in IBM Container Registry (ICR), you must have the URL, an API key, and the account ID of the registry.

$ helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
--set config.secureBaseURL=<SYSDIG_SECURE_URL> \
--set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
--set config.registryType=icr \
--set config.registryURL=<ICR_REGISTRY_URL> \
--set config.registryUser=iamapikey \
--set config.registryPassword=<ICR_APIKEY> \
--set config.registryAccountId=<ICR_ACCOUNT_ID>

• <ICR_REGISTRY_URL>: The ICR registry URL.
  For example, https://us.icr.io
• <ICR_ACCOUNT_ID>: The ICR account ID where the registry is located.

Azure Container Registry

Use one of the following installation options, depending on the credential format used:

Authentication Using Registry Token

To run the scanner in Azure Container Registry (ACR) using a registry token, you must have a token with _repositories_admin scope map to read the full registry.

$ helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
--set config.secureBaseURL=<SYSDIG_SECURE_URL> \
--set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
--set config.registryType=acr \
--set config.registryURL=<ACR_REGISTRY_URL> \
--set config.registryUser=<ACR_TOKEN_NAME> \
--set config.registryPassword=<ACR_TOKEN_PASSWORD>

• <ACR_REGISTRY_URL>: The Azure registry URL
  For example, testregistryscanner.azurecr.io
• <ACR_TOKEN_NAME>: The Azure registry token name
• <ACR_TOKEN_PASSWORD>: The Azure registry token password

Limitations

The registry token must use the _repositories_admin scope map. For more information, see the Azure ACR documentation.

Authentication by Service Principal

To run the scanner in Azure Container Registry (ACR) using Service Principal, follow the Azure ACR instructions to create Service Principal with acrpull role and scoped to your registry.

$ helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
--set config.secureBaseURL=<SYSDIG_SECURE_URL> \
--set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
--set config.registryType=acr \
--set config.registryURL=<ACR_REGISTRY_URL> \
--set config.registryUser=<SP_ID> \
--set config.registryPassword=<SP_PASSWORD>

• <ACR_REGISTRY_URL>: The Azure registry URL.
  For example, testregistryscanner.azurecr.io
• <SP_ID>: The Azure Service Principal ID.
• <SP_PASSWORD>: The Azure Service Principal password.

Google Artifact Registry

To run the scanner in Google Artifact Registry (GAR), you need to create a Service Account within one of the projects and assign the required roles of Project Viewer and Artifact Registry Reader to that service account.

$ helm repo add sysdig https://charts.sysdig.com
$ helm repo update
$ helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
--set config.secureBaseURL=<SYSDIG_SECURE_URL> \
--set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
--set config.registryType=gar \
--set config.registryURL=<GAR_REGISTRY_URL> \
--set config.registryPassword=<GAR_REGISTRY_PASSWORD>

• <GAR_REGISTRY_PASSWORD>: Base64 encoded Service Account JSON access key. To encode JSON key file to base64, use the following command: --set config.registryPassword="$(cat <GAR_SA_FILE_NAME>.json | base64)"
• <GAR_REGISTRY_URL>: Google Artifact Registry URL
  for example, us-docker.pkg.dev

Google Container Registry

To run the scanner in Google Container Registry (GCR), you need to create a Service Account within one of the projects and assign the required role of Project Viewer to that service account.

$ helm repo add sysdig https://charts.sysdig.com
$ helm repo update
$ helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
--set config.secureBaseURL=<SYSDIG_SECURE_URL> \
--set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
--set config.registryType=gcr \
--set config.registryURL=<GCR_REGISTRY_URL> \
--set-file config.registryPassword=<GCR_SERVICE_ACCOUNT_KEY>

• <GCR_SERVICE_ACCOUNT_KEY>: Path to an unencoded Service Account JSON access key.
  for example, sa-3b0c7dec5ea0.json
• <GCR_REGISTRY_URL>: Google Container Registry URL
  for example, gcr.io or us.gcr.io

Nexus

To run the scanner in Nexus, you must have the registry URL and the user credentials with the nx-admin role.

$ helm upgrade --install registry-scanner sysdig/registry-scanner --version=1 \
--set config.secureBaseURL=<SYSDIG_SECURE_URL> \
--set config.secureAPIToken=<SYSDIG_SECURE_API_TOKEN> \
--set config.registryType=nexus \
--set config.registryURL=<NEXUS_REGISTRY_URL> \
--set config.registryUser=<NEXUS_USER> \
--set config.registryPassword=<NEXUS_PASSWORD>

• <NEXUS_USER> \ <NEXUS_PASSWORD>: User credentials with nx-admin role assigned.
• <NEXUS_REGISTRY_URL>: Nexus registry URL
  for example, nexus.your.domain

Refresh Cycle

Every time the Registry scanner is launched, it will perform a full end-to-end scan of all the container images that are matched by the filter with following particularities.

• Images that were already known, will be evaluated with the latest vulnerability feed updates, matching newly found vulnerabilities (if any)
• Policies will also be re-evaluated at this point, taking into account any new vulnerabilities or the updates of the policy itself
• In case a new Registry scanner iteration is launched overlapping with another execution in progress, the new iteration will be aborted, allowing the pre-existing one to continue until finished without overlapping.

Governed by the Helm chart parameter cronjob.schedule, defaulted to 0 6 * * 6, registry scanning iteration will be launched every Saturday at 6:00 AM, by default.

This value must be adapted to your registry size and the full scanning required time.

Recommendation: run a first scan, evaluate the time required, and adapt the schedule to benefit from shorter cycles.

Reporting

You can create a scheduled report to produce a periodic inventory of all the vulnerabilities contained in your registry images, using different filters and scope conditions, and check the registry reporting documentation.

Configuration Options

The Registry Scanner Helm Chart Configuration describes all the configuration options available. This section highlights the most common ones.

Scan on Start

Launch a job to scan on start for testing purposes. This job will be launched only once, in contrast to the default scheduled cronjob.

--set scanOnStart.enabled=true

Manual Launch

Alternatively to scanOnStart, you can also launch scans manually:

$ kubectl create job --from=cronjob/registry-scanner registry-scanner-manual-test

Enable More Logs

Available levels: trace, debug, info, error To increase the number of log messages:

--set config.logging=debug

Store Scan Results Locally

After the scanning is performed, the results are shown in the logs. You can save these in a Kubernetes volume using the reportToPersistentVolumeClaim.

Helm configuration:

--set reportToPersistentVolumeClaim=<KUBERNETES_PVC>

Filter Configurations

The registry scanner sets several filters to avoid longer iteration times and cluttering the interface with obsolete image versions or unnecessary scans.

Notes:

• config.filter.include has more priority than config.filter.exclude, thus, if an image name is matched by both filters, it will be included
• Filtering options will not lower the time needed before the scan. In order to filter, first all repositories must be detected (discovery phase on logs) and repository image metadata must be gathered (metadata fetching phase on logs), in order to contrast it with the filters, and opt-out specific images. Then scan will start.
• For additional information check config.filter.* on the registry scanner chart

Quick Scan Use Case

If you quickly want to check the registry connection and the results appear in the Sysdig UI, you would want something that excludes all the images except a select group:

config.filter.include: "base/alpine:.*"
config.filter.exclude: ".*"
config.filter.maxTagsPerRepository: 2

Kubernetes Cluster Setup

For the correct sizing of the Kubernetes cluster specs and scanning performance, consider:

• Optimize scanner-to-registry outbound network connection proximity.
  Preferably, keep the Kubernetes cluster close to the registry. For example, an AWS Kubernetes cluster housed in the same AWS region where the onprom JFrog Artifactory server is.

• Use config.maxWorkers to determine the maximum number of images that can be scanned in parallel. These workers are created per image, and not re-used. Default: 5

• Use config.scan.jobs.resources to define CPU and memory request and limits of the scanning workers. Default values are:

  resources:
      limits:
          memory: 2Gi
      requests:
          cpu: 500m
          memory: 500Mi
  

For reporting to work successfully registry scan MUST be performed in less than 7 days
We recommend trying a full scan of the registry with the default settings. If the total required time is greater than 7 days, and your cluster allows it, start by increasing the number of config.maxWorkers.

Sample case: For an AWS-hosted JFrog Artifactory Onprem registry, an EKS cluster was used within the same AWS region. For a registry with 30K legitimate images to be scanned (after filtering), a t3.medium (4GB ram 2vCPU) 8 node cluster was used, with 25 workers. With the default resources, the registry was scanned in less than 3 days.

Networking

The Registry Scanner interacts with two external services: your image registry and the Sysdig backend. If your Registry Scanner is installed behind a proxy or a firewall, you must ensure that it has the necessary permissions to connect with these services:

Sysdig Backend

The Registry Scanner node needs to be able to access the Sysdig Backend from the node. Validate this by using the curl command as follows:

curl --header "Authorization: Bearer ${SECURE_API_TOKEN}" ${SECURE_URL}/api/registryscanner/v1/images

A successful connection will be confirmed by an HTTP 200 OK response.

Troubleshooting

Review the Installation Details

1. Verify the Helm installation output. Example:

   Release "registry-scanner" does not exist. Installing it now.
   NAME: registry-scanner
   LAST DEPLOYED: Mon Dec 19 13:50:58 2022
   NAMESPACE: default
   STATUS: deployed
   REVISION: 1
   TEST SUITE: None
   NOTES:
   #
   # Cronjob 'registry-scanner' with schedule: "0 6 * * 6" has been created to perform a periodical scan.
   # For troubleshooting, check the status of the jobs and logs of the 'registry-scanner' pods that are created on every execution.
   #
   

2. Verify the chart status is deployed.

   $ helm list | grep registry
   
   NAME                NAMESPACE    REVISION    UPDATED                                    STATUS      CHART                     APP VERSION
   registry-scanner    default      1           2022-12-19 13:50:58.260434687 +0100 CET    deployed    registry-scanner-0.1.3    0.2.0    
   

3. Verify the scan started.

   $ kubectl get jobs  -l app.kubernetes.io/instance=registry-scanner
   NAME                          COMPLETIONS   DURATION   AGE
   registry-scanner-start-test   0/1           30s        30s
   

   Remember that due to the cronjob being scheduled, for initial tests, you can launch an out of order scan manually or force it to scan on start

4. Check the final logs of the scanner orchestrator, one of which shows the total number of images scanned (N), including the success (X), failed (Y), and skipped (Z) due to the maximum limit of scans being reached.

   $ kubectl logs  -l app.kubernetes.io/instance=registry-scanner
   ...
   {"level":"info","component":"report-builder","message":"Total: N = Success: X + Failed: Y + Skipped: Z"}
   

5. You can also verify the final status, Error or Completed.

   $ kubectl get pods -l app.kubernetes.io/instance=registry-scanner -ojsonpath --template='{.items[*].status.containerStatuses[*].state.terminated.reason}'
   

6. If the scan had errors, move to debugging.

Debugging

Note that the Kubernetes log rotation lifecycle may not allow fetching all the full logs from a long scan; you may need a backend logging platform (log aggregator) to fetch them. If you’re using a cloud-provided cluster, make use of the cloud log services, such as CloudWatch on EKS.

Two kinds of logs are available, based on scanning architecture:

1. orchestrator logs

• one job/pod will be spawned for the whole scanning

2. scan worker logs

• named registry-scanner-worker-*
• one non-reusable job/pod will be scanned per image to be scanned

To check the registry logs after it runs, get logs in the spawned job:

$ kubectl get jobs -l app.kubernetes.io/instance=registry-scanner
$ kubectl logs -f sysdig job/<REGISTRY_JOB_NAME>

Target for level: error logs:

$ kubectl logs -f sysdig job/<REGISTRY_JOB_NAME> | grep error

Logs should be descriptive enough to understand why an image scan has failed. Common pitfalls for failed scans are:

• Incorrect Sysdig Secure credentials
• Image type to be scanned is not supported

To dig deeper into the logs, use the Enable more logs parameter.

JFrog Can’t Scope Multiple Repositories

Multi-registry support is a current limitation due to JFrog Artifactory’s naming that differs from industry standards, using ‘repository’ instead of ‘registry’, and ‘package’ instead of ‘repository’.

Other DockerV2-Compliant Vendor Registries

Docker Hub is not supported.

Vendors that are not yet officially supported: Google Container Registry, Oracle Container Registry, Openshift internal, OCR, Gitlab and Github.

Next Steps

Review scan results in the Sysdig Secure UI.

Create scanning reports.