Install Registry Scanner
Setup
Prerequisites
A Kubernetes cluster managed with Helm
- The registry scanner client will be installed here.
- Recommended: Set up a service account with minimal priviledge, such as a
Standard
role. - Or: Use a custom role with the following permissions for Sysdig Secure:
- Scanning Image Results:
read
andcreate
- Scanning:
read
- Scanning Image Results:
- Recommended: Set up a service account with minimal priviledge, such as a
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
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
Known Limitations
At this time:
- 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 below.
Installation
Legacy scanning engine: If you still use the legacy scanning engine and want to keep running that version, pin the Helm chart version to 0.1.39. If you deploy a greater version, the current vulnerability management engine will replace the legacy installation.
Overview
Install the Registry Scanner Helm Chart:
$ helm repo add sysdig https://charts.sysdig.com $ helm repo update
Prepare the Helm chart for your specific registry vendor. Provide:
<SYSDIG_SECURE_URL>
: Region-dependent Sysdig Secure endpoint<SYSDIG_SECURE_API_TOKEN>
: See Prerequisites
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.
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.
JFrog Artifactory SaaS/Cloud
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.registryURL=<JFROG_ARTIFACTORY_REGISTRY_URL> \
--set config.registryApiUrl=<JFROG_ARTIFACTORY_REGISTRY_API_DOCKER_URL> \
--set config.registryUser=<JFROG_ARTIFACTORY_USER> \
--set config.registryPassword=<JFROG_ARTIFACTORY_PASSWORD>
<JFROG_ARTIFACTORY_URL>
: JFrog Artifactory url.
e.g.https://<JFROG-ACCOUNT-NAME>.jfrog.io/<REGISTRY-NAME>
<JFROG_ARTIFACTORY_REGISTRY_API_DOCKER_URL>
: JFrog Artifactory Cloud registry docker API endpoint.
e.g.,https://<JFROG-ACCOUNT-NAME>/artifactory/api/docker/<REGISTRY-NAME>
Limitations
- Multi-arch Docker manifest/packages are not supported.
JFrog Artifactory On-Prem
Connect with a version of Jfrog Artifactory that is installed on your premises.
JFrog On-Prem has three configuration options: subdomain
, repository path
, and port
.
Check your configuration in JFrog administration console, under Administration > Services > 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.registryURL=<JFROG_ARTIFACTORY_REGISTRY_URL> \
--set config.registryApiUrl=<JFROG_ARTIFACTORY_REGISTRY_API_DOCKER_URL> \
--set config.registryUser=<JFROG_ARTIFACTORY_USER> \
--set config.registryPassword=<JFROG_ARTIFACTORY_PASSWORD>
For Subdomain:
<JFROG_ARTIFACTORY_REGISTRY_URL
>: JFrog Artifactory Cloud registry URL.
e.g.,<REGISTRY_NAME>.host.mycompany.com
<JFROG_ARTIFACTORY_REGISTRY_API_DOCKER_URL>
: JFrog Artifactory registry docker API endpoint.
e.g.,host.mycompany.com/artifactory/api/docker/<REGISTRY_NAME>
For Repository Path or Port
<JFROG_ARTIFACTORY_REGISTRY_URL>
: JFrog Artifactory Cloud registry URL.
e.g.,host.mycompany.com
<JFROG_ARTIFACTORY_REGISTRY_API_DOCKER_URL>
: JFrog Artifactory registry docker API endpoint.
e.g.,host.mycompany.com/artifactory/api/docker/<REGISTRY_NAME>
Limitations
- Multi-arch docker manifest/packages are not supported.
AWS ECR Single Account
Use the single account AWS ECR installation to target one registry per installation.
To onboard an entire organization containing several member accounts, check the AWS ECR Organizational setup
There are two installation methods, based on where the Kubernetes cluster is located:
Option 1: 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
Option 2: 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 AWS Kubernetes cluster and the registry are in different accounts but under same organization, use the AWS Organizational setup and allow listing an 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 region of an AWS Organization. The Kubernetes cluster that the registry will scan may be inside or outside of AWS.
Process Overview
You will:
- 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.
- 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 nameOrganizationAccountAccessRole
will be used, which includesadmin
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.
- Tip: To narrow the list of member accounts that will be checked during scanning, you can set the
- 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.
Step 1. Kubernetes Job/Pod AWS Credentials
You need to provide either an Access Key/Secret Key or a service account that has the necessary permissions.
Option 1: Access Key/Secret Key
If you choose to provide 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 on theORGANIZATION_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>" } ] }
Option 2: Service Account
For Amazon Elastic Kubernetes Service (EKS) clusters on AWS, you can configure the necessary permissions at the service account level.
Important points:
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).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" }
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 beregistry-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" } } } ] }
- Default
Save the role
<SERVICE_ACCOUNT_IAM_ROLE_ARN>
value associated with the Kubernetes service-account and use it during the installation.
Step 2: 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 whichProvides 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.
- Option 1: Access Key/Secret Key
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "<AWS_ACCESS_USER_ARN>"
},
"Action": "sts:AssumeRole"
}
]
}
Option 2: Service Account
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "<SERVICE_ACCOUNT_IAM_ROLE_ARN>" }, "Action": "sts:AssumeRole" } ] }
Step 3: 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 on 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 thatProvides 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": "*"
}
]
}
Step 4 (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 accountIDs
***
-------------------------
> 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
There are two installation options, depending on the credential format used.
Install Option 1: 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>
Install Option 2: 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 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=harbor \
--set config.registryURL=<HARBOR_REGISTRY_URL> \
--set config.registryUser=<HARBOR_ARTIFACTORY_USER> \
--set config.registryPassword=<HARBOR_ARTIFACTORY_PASSWORD>
<HARBOR_REGISTRY_URL>
: Harbor registry URL
e.g.,core.harbor.domain
Quay.io
To run the scanner in Quay.io, you must have the registry URL and 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_REGISTRY_URL> \
--set config.registryUser=<QUAY_ARTIFACTORY_USER> \
--set config.registryPassword=<QUAY_ARTIFACTORY_PASSWORD>
<QUAY_REGISTRY_URL>
: Quay.io registry URL.
e.g.,quay.io
<QUAY_ARTIFACTORY_PASSWORD>
: CLI password for Quay.io. It must be generated through the account settings.
IBM ICR
To run the scanner in IBM Container Registry (ICR), you must have the URL 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=<ICR_ARTIFACTORY_USER> \
--set config.registryPassword=<ICR_ARTIFACTORY_PASSWORD> \
--set config.registryAccountID=<ICR_ACCOUNT_ID>
<ICR_REGISTRY_URL>
: ICR registry URL.
e.g.,https://us.icr.io
<ICR_ACCOUNT_ID>
: ICR account ID where the registry is located.
Azure ACR
To run the scanner in Azure Container Registry (ACR), you must have a token with _repositorie_admin scope map to be able 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>
: Azure registry URL
e.g.,testregistryscanner.azurecr.io
<ACR_TOKEN_NAME>
: Azure registry token name<ACR_TOKEN_PASSWORD>
: Azure registry token password
Limitations
- The registry token must use _repositories_admin scope-map.
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 finish 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, 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
Registry scanner sets several filters to avoid longer iteration times and cluttering the interface with obsolete image versions or unnecessary scans.
filter | default value | maximum value | notes |
---|---|---|---|
config.filter.include | .* | - | A string, or list of strings, containing regular expressions. Each image in the registry will be matched against these regular expressions. If any of the entries in the list matches the registry-name/repository/image:tag , then that image will be included for scanning, regardless other filtering options (exclude, maxAgeDays, maxTagsPerRepository). The regular expression will match an expression like this, e.g.: sysdig.artifactory.com/my-repo/my-image:latest |
config.filter.exclude | - | - | A string, or list of strings, containing regular expressions. Any image in the registry matching any of these regular expressions will be excluded for scanning. |
config.filter.maxAgeDays | 90 | 365 | Any image which is older than the specified number of days (by creation date) will be excluded for scanning |
config.filter.maxTagsPerRepository | 5 | 50 | Only the most N recent tags (by creation date) for each repository will be scanned. The rest of the tags will be exclude |
config.filter.maxRepositoriesPerRegistry | 500 | 10000 | - |
Notes:
config.filter.include
has more priority thanconfig.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, just want to check registry connection and that 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. This workers are created per image, and not re-used. Default: 5Use
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 to try a full scan of the registry with the default settings. If 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, registry was scanned in less than 3 days.
Troubleshooting
Review the Installation Details
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. #
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
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
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 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"}
You can also verify the final status,
Error
orCompleted
.$ kubectl get pods -l app.kubernetes.io/instance=registry-scanner -ojsonpath --template='{.items[*].status.containerStatuses[*].state.terminated.reason}'
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 kind of logs are available, based on scanning architecture
- orchestrator logs
- one job/pod will be spawned for the whole scanning
- 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, Sonatype Nexus, OCR, Gitlab and Github
Next Steps
Review scan results in the Sysdig Secure UI
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.