Snyk Broker - Container Registry Agent

Support API docs Product updates Sign up for free
Search…
Feature availability
This feature is available with Enterprise plans. See pricing plans for more details.
Snyk can integrate to private container registries you host, and help you to better secure container images in those registries.
For this feature to work, you need two separate containers deployed in your infrastructure, creating two separate services.
To enable and configure your hosted container registry, contact our support team at [email protected]​
Note:
The integration pattern using the Broker with open source container registries from the list described in this section, is designed for users who require images to be scanned in their own environment, instead of inside the Snyk service.
If such a requirement is not relevant for you, you do not need the architecture described in this article, and can integrate to it in the standard way from the Integrations page on the Web UI.
Introduction
Integration with private container registries allows you to:
Keep sensitive data such as your access tokens inside your private network, never sharing that information with Snyk.
Provide controlled access to the network by Snyk, limiting Snyk access and the actions that Snyk can perform.
Self-hosted container registries solution components
Broker Server: running on the Snyk SaaS backend.
Broker Client & Container Registry Agent: two Docker images deployed in your infrastructure, creating two separate services, responsible for sampling your container registries in a secured manner and sending the allowed information to Snyk.
The Broker Client provides the Agent with the connection details. The Agent uses these details to connect to the container registry, scan the images, and send the scan results through the brokered communication using callbacks. The brokered communication happens when a Broker Client connects (using your Broker ID) to a Broker Server which runs in Snyk environment. See Snyk Broker documentation for more details.
Supported Container registries
Artifactory (type: artifactory-cr)
Harbor (type: harbor-cr)
Azure (type: acr)
GCR (type: gcr)
ECR (type: ecr)
Google Artifact Registry (type: google-artifact-cr)
Docker Hub (type: docker-hub)
Quay (type: quay-cr)
Nexus (type: nexus-cr)
GitHub (type: github-cr)
DigitalOcean (type: digitalocean-cr)
GitLab (type: gitlab-cr)
Settings prerequisites
Broker Client machine system requirements: 1 CPU, 256MB of RAM.
Container registry agent machine system requirements should be (given MAX_ACTIVE_OPERATIONS=1):
CPU: 1 vcpu
Memory: 2Gb (should be reflected in node memory setting)
Storage: 5Gb
Docker configured to pull components images from Docker Hub
Connection between broker and agent
HTTPS connection between the agent and the registry. Support for HTTP-only registries can be resolved by deploying a reverse proxy between the code agent and the SCM.
Broker Client image can be found for download here​
Container Registry Agent image can be found for download here​
Scaling to adjust scan capacity
With the above configuration of 1 vCPU and 2GB RAM, scanning capacity would be approximately 160 images of ~350MB in one go. You can scale this up based on your image sizes, and in case you have a specific use case that doesn't allow scaling and doesn't fit the limitations, contact our support team.
Set up the remote connection
Running the Broker Client
The Broker Client image can be pulled from Docker Hub using the link provided above in the settings prerequisites.
There are different environment variable that are required to configure the Broker Client:
Note:
For DigitalOcean, GCR, Google Artifact Registry and Artifactory, there are a few values to notice. For ECR, additional setup is required. Specifications to follow.
BROKER_TOKEN - The Snyk Broker token, obtained from your Container registry integration (provided by Snyk support).
BROKER_CLIENT_URL - The URL of your broker client (including scheme and port) used by the container registry agent to call back to Snyk through the brokered connection, for example: "http://my.broker.client:8000".
CR_AGENT_URL - The URL of your container registry agent, to which the broker client will route the requests, for example: "http://my.container-registry-agent".
CR_TYPE - The container registry type as listed in supporter registries, for example: "docker-hub", "gcr", "artifactory-cr".
CR_BASE - The hostname of the container registry api to connect to, for example: "cr.host.com".
CR_USERNAME - The username for authenticating to container registry api.
CR_PASSWORD - The password for authenticating to container registry api.
CR_TOKEN - Authentication token for DigitalOcean container registry.
PORT - The local port at which the Broker client accepts connections. Default is 7341.
Run the Broker Client container with relevant configuration:
docker run --restart=always \
       -p 8000:8000 \
       -e BROKER_TOKEN="<secret-broker-token>" \
       -e BROKER_CLIENT_URL="<broker-client-url>" \
       -e CR_AGENT_URL="<container-registry-agent-url>" \
       -e CR_TYPE="<container-registry-type>" \
       -e CR_BASE="<container-registry-hostname>" \
       -e CR_USERNAME="<username>" \
       -e CR_PASSWORD="<password>" \
       -e PORT=8000 \
       snyk/broker:container-registry-agent
Running the Container Registry Agent
The Container Registry Agent image can be pulled from Docker Hub using the link provided above in the settings prerequisites. To run the image you can use a single environment variable for specifying the port:
docker run --restart=always \
       -p 8081:8081 \
       -e SNYK_PORT=8081 \
       snyk/container-registry-agent:latest
Container Registry Specific Configurations
The following container Registries require specific environment variables and/or setup.
DigitalOcean
To set up Broker Client for DigitalOcean,CR_USERNAME and CR_PASSWORD are not required. Instead, you need to specify CR_TOKEN - authentication token for DigitalOcean container registry.
GCR and Google Artifact Registry
To set up the Broker Client for those container registries, all the above applies. The only thing to note is that CR_USERNAME value is permanent and should be _json_key, and the CR_PASSWORD value should be the JSON key used to authenticate to google.
Artifactory
In case you are using Repository path as your Docker access method, the container registry hostname in CR_BASE variable should be set in this structure: **** <your artifactory host>/artifactory/api/docker/<artifactory-repo-name>
ECR
A high-level architecture of the brokered ECR integration
Required AWS Resource
ECR setup requires two kinds of IAM resources to be created:
Container Registry Agent IAM Role / IAM User: an IAM Role / IAM User the Container Registry Agent uses to assume a cross-account role with access to ECR. It should have the following permissions: "sts:AssumeRole"
Snyk ECR Service Role: an IAM Role with access to ECR which is assumed by the Container Registry Agent IAM Role / IAM User to gain read-only access to ECR.
It should have the following permissions:
[
  "ecr:GetLifecyclePolicyPreview",
  "ecr:GetDownloadUrlForLayer",
  "ecr:BatchGetImage",
  "ecr:DescribeImages",
  "ecr:GetAuthorizationToken",
  "ecr:DescribeRepositories",
  "ecr:ListTagsForResource",
  "ecr:ListImages",
  "ecr:BatchCheckLayerAvailability",
  "ecr:GetRepositoryPolicy",
  "ecr:GetLifecyclePolicy"
]
Setup steps for ECR
The above resources can be used as follows, so that a single Container Registry Agent instance can access ECR repositories located in different accounts:
1.(Run this step once only) Create the Container Registry Agent IAM Role / IAM User and use it to run the Container Registry Agent. The IAM Role / IAM User could be provided to the Container Registry Agent using one of the methods described here.
Run the following steps for each of your ECR accounts, using a separate broker instance for each ECR account:
2.In the AWS account where your ECR reside, create the Snyk ECR Service Role with read access to your ECR, and edit the trust relationship to allow this role to be assumed only by the specific Container Registry Agent IAM Role / IAM User created in the previous step.
3.Restrict the Container Registry Agent IAM Role / IAM User to only be allowed to assume the your Snyk ECR Service Role(s).
4.Provide the Broker Client with the Role ARN of the Snyk ECR Service Role together with the ECR region. The Broker Client passes this Role ARN to the Container Registry Agent, and the Container Registry Agent will assume it, to access your ECR. The following environment variables are needed:
CR_ROLE_ARN=<the role ARN of SnykEcrServiceRole>
CR_REGION=<AWS Region of ECR>
CR_EXTERNAL_ID=<Optional. An external ID found in the trust relationship condition>
​Get more information about the brokered ECR setup.
Configuring and using system check
You can use the /systemcheck endpoint to verify connectivity between the Broker Client, the Container Registry Agent, and your container registry.
In order to use it, provide the following environment variable to the broker client:
BROKER_CLIENT_VALIDATION_URL=<agent-url>/systemcheck
When calling the /systemcheck endpoint of the broker client, it will use the BROKER_CLIENT_VALIDATION_URL to make a request to the /systemcheck endpoint Container Registry Agent's, with the credentials provided to the broker client. The Container Registry Agent will then make a request to the container registry to validate connectivity.
Note:
The /systemcheck endpoint is not mandatory for the brokered integration to function. More information can be found here: https://github.com/snyk/broker#systemcheck​
Debugging Methods
The LOG_LEVEL environment variable can be set to the desired level (debug/info/warn/error), in order to change the level of the Container Registry Agent and Broker Client logs.
For more verbose debugging, the Container Registry Agent can be run with the DEBUG=* environment variable. This allows printing the logs of the Node Debug package. The Debug package is used by several packages in the Container Registry Agent, among them is the Needle package, which is used for making HTTP requests. Printing debug logs specifically from Needle can be done by setting DEBUG=needle.
Warning:
Using the debugging options of third-party tools is not recommended for production environments, as it may result in logging sensitive information in logs that are not maintained by Snyk. For example, header information of HTTP requests.
Secure your images:
You can now start scanning your container images directly from your private registry. See scanning images from container registry (Artifactory example) for more details.
Step 6: Testing the Code Agent – Snyk Broker Setup
Setting up the Container Registry Agent for a brokered ECR integration
Last modified 7d ago
Export as PDF
Copy link
Edit on GitHub
On this page
Introduction
Self-hosted container registries solution components
Set up the remote connection
Running the Broker Client
Running the Container Registry Agent
Container Registry Specific Configurations
Configuring and using system check
Debugging Methods