Integrate a Docker V2 Registry

Container Registry Support

The Docker V2 registry integration is for private Docker V2 registries only. For Docker Hub, ECR, GCR, and GitHub Container Registry, use their corresponding container registry types to integrate with Lacework. Docker V2 registry integration supports the following container registries and scan types.

Registry	Versions	Support
Azure Container Registry (ACR)	n/a	Registry notification On-demand scans
Docker V2 Registry	n/a	Registry notification On-demand scans
GitLab	On-premises 12.8 and cloud	On-demand scans
JFrog Artifactory JFrog Platform	On prem 7.2.1 and cloud	Registry notification On-demand scans
Nexus	n/a	On-demand scans
Other Docker V2-based authentication registries	n/a	On-demand scans

note

Registry notifications are also available for GitLab On-premises.

Integration Setup Overview

To set up integration:

1. Create a container registry integration in the Lacework Console.
2. Choose one of the following options:
   1. Add registry notification.
   2. Set up image assessment through the Lacework API.

Prerequisites for Azure Container Registry (ACR) Integrations

When configuring the Docker V2 integration for Azure, an Azure Active Directory (AD) service principal is needed to authenticate with your container registry.

Azure provides a script that can automate the creation of the service principal in the following article: https://docs.microsoft.com/en-us/azure/container-registry/container-registry-auth-service-principal#create-a-service-principal

You can also use an existing service principal, but you must assign the AcrPull role to it for the relevant container registry in Azure.

How to Use the Azure Service Principal during a Lacework Integration

• When providing the Username during the registry integration steps, use the Application (Client) ID of the service principal.

• When providing the Password during the registry integration steps, use the Client Secret of the service principal.

  note

  When the service principal is initially created, the Client Secret is a one-time viewable UUID string. If it is not known, see Authenticate with the service principal for guidance on how to regenerate the Client Secret.

Navigate to Docker V2 Registry Integration

1. Log in to the Lacework Console with an account with admin permissions.
2. Navigate to Settings > Integrations > Container registries.
3. Click + Add New.
4. Click Docker V2 Registry.
5. Click Next.
6. Follow the steps in the next section.

Integrate with a Docker V2 Registry

To integrate a Docker V2 registry with Lacework, follow these steps:

1. Configure the registry and complete any optional settings.
2. Click Save. The integration status displays Integration Successful only after its first assessment completes.
3. If you subscribed to notifications, go to Registry Notification and follow the steps for your registry.
   Otherwise, go to Set Up Image Assessment through the API to set up on-demand scans.

Configure Registry

Setting Name	Description
Name	Specify a unique name for the container registry in the Lacework Console.
Username	Specify a user that has permissions to pull the images (that will be assessed) from the container registry. NOTE: See Prerequisites for Azure Container Registry (ACR) Integrations for guidance if setting up an ACR integration.
Password	Specify the password for the specified user.
SSL	Select True if the registry uses SSL. You can use either a valid SSL certificate issued by a trusted Certificate Authority (CA) or a self-signed certificate. If you select False, you use an unencrypted communication channel. Known Issue for JFrog: JFrog Cloud integrations must be SSL-enabled due to a known issue.
Registry Domain	If you use docker login <YourDomain>:<YourPort>, specify the domain as <YourDomain>:<YourPort>. If you use docker login <YourDomain>, specify the domain as: <YourDomain>. If you use docker login <YourIp>:<YourPort> specify the domain as: <YourIp>:<YourPort>.
Subscribe to Registry Notifications	If the container registry supports notifications, you can optionally select True.

Optional Settings

Setting Name	Description
Limit Image Tags	If you do not want to assess all images in this registry, specify text from an image tag so that only images with matching tag text will be assessed. To change which images you want to assess, update this field so the change is captured during the next polling period. You can input multiple tags. If you specify tag and label limits, they function as an AND. Single wildcards are also supported and can be used to match multiple image tags (for example: abc* or *xyz).
Limit Image Labels	If you do not want to assess all images in this registry, specify key:value pairs so that only images with matching label key:value pairs will be assessed. To change which images you want to assess, update this field so the change is captured during the next polling period. Supported field input: key:value. If you specify tag and label limits, they function as an AND.
Non-OS Package Support	This feature is enabled by default. Select No if you want to disable scanning of language libraries.

Registry Notification

Lacework can receive notifications that the registry sends in response to events that happen within the registry. When Lacework receives manifest push notifications, Lacework performs an assessment. Lacework ignores pull notifications and media types that are not manifests.

You can subscribe to notifications and perform automatic assessments for the following registries:

• Registries with the same notification format described in https://docs.docker.com/registry/notifications/ - see Add Notification to Docker Registry
• Azure Container Registry (ACR) - see Add a Webhook to ACR
• JFrog - see Add a Webhook to JFrog

Obtain an Access Token for Registry Notifications

When you create the integration, if you select Subscribe to Registry Notifications, the Lacework Console provides an authorization token (integration token) and a listener URL that you can download.

The authorization token is an integration-specific, long running server token.

The listener URL and token are available on the Container Registry page.

Click the integration name and copy both the listener URL and token from the details pane. These are required when adding notifications or a webhook in the Docker registry.

Each integration can have one token. If the integration unsubscribes from notifications and then subscribes again, Lacework uses the same token.

Add Notification to Docker Registry

To use this procedure, your registry’s notification format must be the same as described in https://docs.docker.com/registry/notifications/.

To subscribe to notifications, you must add the registry notification listener URL and authorization token to the notification section of the container registry’s config.yml file.

Locate (or add) the notifications section in config.yml, as illustrated in the following example.

notifications:
  endpoints:
    - name: lacework_listener
      url: https://YourLacework.lacework.net/api/v2/Webhooks/ServerTokens/{type}
      headers:
      Authorization: [${lacework_server_token_for_registry_notification}]
      timeout: 120s
      threshold: 10
      backoff: 120s
      ignoredmediatypes:
        - application/octet-stream
      ignore:
        actions:
           - pull

For the endpoints structure, provide these required parameter values.

• url - Paste the registry notification listener URL that you copied from the Lacework Console.
  For US, it is: https://YourLacework.lacework.net/api/v2/Webhooks/ServerTokens/DockerV2
  For European Union (EU), it is: https://YourLacework.fra.lacework.net/api/v2/Webhooks/ServerTokens/DockerV2

• headers - Add the following
  Authorization: [${lacework_server_token_for_registry_notification}]
  Replace [${lacework_server_token_for_registry_notification}] with the authorization token copied from the Lacework Console.

Restart the registry for your changes to take effect.

Add a Webhook to Azure Container Registry (ACR)

To subscribe to notifications, you must add a webhook to the container registry and then add the registry notification listener URL and authorization token to the webhook.

1. In Azure, navigate to the container registry where you want to create a webhook.
2. Under Services, select Webhooks.
3. In the webhook toolbar, click Add.
4. Complete the Create webhook form with the following information from Lacework:
   • Webhook name: Lacework_webhook
   • Service URL: Paste the registry notification listener URL that you copied from the Lacework Console.
     https://YourLacework.lacework.net/api/v2/Webhooks/ServerTokens/AzureCR
   • Custom headers: Enter the following authorization header required by API server
     Authorization: Bearer [${lacework_server_token_for_registry_notification}]
     Replace [${lacework_server_token_for_registry_notification}] with the authorization token copied from the Lacework Console.
   • Actions: push

For additional information, see Microsoft documentation https://docs.microsoft.com/en-us/azure/container-registry/container-registry-webhook.

Add a Webhook to JFrog

To subscribe to notifications, you must add a webhook to the container registry and then add the registry notification listener URL and authorization token to the webhook.

1. In JFrog, navigate to Administration Module > General > Webhooks.

2. Click New Webhook.

3. Complete the Create new webhook form with the following information from Lacework:

   • URL: Paste the registry notification listener URL that you copied from the Lacework Console. https://YourLacework.lacework.net/api/v2/Webhooks/ServerTokens/JFrog

     If you are using virtual repositories, enter the following URL: https://YourLacework.lacework.net/api/v2/Webhooks/ServerTokens/JFrog

   • Events: Select Docker > Docker tag was pushed.

   • Custom Headers: key: Authorization, value: paste the authorization token copied from the Lacework Console.

Set Up Image Assessment through the API

If you did not subscribe to notifications, you can, for example, make an API call each time an image is built so that Lacework assesses it:

​POST https://YourLacework.lacework.net/api/v2/Webhooks/ServerTokens/{type}

For information about setting up container image assessment, see the Vulnerabilities section in the Lacework API (v2) documentation.