Skip to main content

Integrate Proxy Scanner

Overview​

The Lacework proxy scanner integration allows Lacework to perform container vulnerability assessments for your on-premises Docker container image registries without exposing them to external connectivity. The Lacework proxy scanner assesses the images stored within registries, extracts image manifest data as necessary for assessment, and sends the application metadata to the Lacework platform. Additionally, the bandwidth transfer costs for container registry assessment are optimized when using the Lacework proxy scanner for vulnerability assessment.

After creating a proxy scanner integration through the Lacework Console settings, you deploy the proxy scanner as a Docker application or Kubernetes workload in your environment as a continuous running entity. The proxy scanner continuously fetches new images from your environment and collects the required image metadata for vulnerability assessments. Using the associated integration token that was created when you integrated the proxy scanner in the Lacework Console, the proxy scanner initiates an API request for assessment by Lacework. After the token is authorized, Lacework assesses the image meta data and provides risk assessments for the container images. You can view the results on the Vulnerability Assessment page in the Lacework Console.

Default Scanning Quotas​

  • The proxy scanner supports a maximum of 2000 image assessments per hour for each Lacework account.
  • For each integration, there is a maximum of 50 image assessments per hour for each repository.

Private Registry Scanning​

If your registry is not accessible from the internet, you must create a registry integration and then set up the Lacework Proxy Scanner in your environment to pull images from your network.

The Lacework Proxy Scanner supports the same methods as the Lacework Platform Scanner to scan a registry:

  • Registry notification: The registry sends an event to Lacework whenever a new image has been uploaded.
  • Auto-polling: Lacework automatically discovers the list of repositories and new images available in the registry.
  • On-demand: Manually request the scan of a container using the Lacework CLI.

Proxy Scanner Support​

The proxy scanner is currently packaged in Linux.

For information about package assessment, see the Package Assessment Support section.

The proxy scanner supports the following container registries and scan types.

RegistrySupport
Docker V2 API-compatible registries with these APIs:
/v2/_catalog
/v2/{name}/tags/list		Auto polling
On-demand scans
Amazon Elastic Container Registry (ECR)Auto polling
On-demand scans
Azure Container Registry (as Docker V2 Registry)Auto polling
Registry notification
On-demand scans
Docker HubRegistry notification
On-demand scans
Docker Trusted RegistryRegistry notification
On-demand scans
Docker V2-based authentication registriesRegistry notification
On-demand scans
GitHub Container RegistryRegistry notification
On-demand scans
Google Container Registry (GCR)Auto polling
On-demand scans
HarborRegistry notification
On-demand scans
JFrogRegistry notification
On-demand scans
Red Hat QuayAuto polling
On-demand scans

Multi-Architecture Image Support​

The Lacework proxy scanner supports multi-architecture container images during scans. Multi-architecture images are supported by scanning manifests that list multiple platform versions of the image.

An example of a manifest list for a multi-architecture image can be found here.

Lacework scans the first platform architecture version found in the following order:

  1. AMD64
  2. ARM64
  3. ARM32

Integration Setup Overview​

Integration setup consists of the following steps:

  1. Create a proxy scanner integration in the Lacework Console
  2. Create a configuration yaml file and configure it for:
  3. Deploy the proxy scanner
  4. (On-demand scans only) Run a curl command to initiate a scan.
  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 Proxy Scanner.
  5. Click Next.
  6. Follow the steps in the next section.

Create a Proxy Scanner Integration in Lacework​

Creating an integration in the Lacework Console is the first step in setting up a proxy scanner. To create an integration, follow these steps:

  1. Name the integration and complete any optional settings.
  2. Click Save.
    Do not download the proxy scanner from the provided URL; you can pull the image from Docker Hub as described in Deploy the Proxy Scanner.
  3. Click the Authorization Token’s copy to clipboard icon.
    This is the integration’s associated token. You need this to configure the proxy scanner.

After you save the integration, its name displays on the Integrations Container Registry page. For next steps, continue to Configure the Proxy Scanner.

Proxy Scanner Settings​

Setting NameDescription
NameSpecify a unique name to display for the integration in the Lacework Console.
CI / CD PoliciesAssociate Policies with a Registry Integration.
note

See Environment Variables for Auto Polling for additional options relating to scanning and tags. Only applicable if you are configuring the Proxy Scanner for Auto polling.

Configure the Proxy Scanner​

To configure the proxy scanner, you must create a configuration yaml file (config.yml). See the following sections for specific configuration information and examples for each scan type.

The config.yml configuration file contains the following fields:

scan_public_registries: Enter true (or omit the field) if you want to scan images from public registries. Enter false if not.
static_cache_location: The static file mount location. The recommended path is /opt/lacework.
disable_expand_env: Enter true (or omit the field) if you want to allow special characters to be used in the config (such as $).
default_registry: Provide the default registry. This must match the domain value.
lacework:
  account_name: Lacework account name.
  integration_access_token: The integration's access token from the Lacework Console.
    existingSecret: Only relevant if using Kubernetes Helm Charts. See relevant section below for details.
      key: The Kubernetes secret key for Inline Scanner, for example: "lw-scanner-token".
      name: The Kubernetes secret name for Inline Scanner, for example: "lw-scanner-secret".
registry_secret_name: Only relevant if using Kubernetes Helm Charts. See relevant section below for details.
registries:
  - domain: The registry domain using one of these formats: IP:Port, Domain:Port, or a public domain.
    image_filter: Limit scanning to a specified list of repositories/images that you want to assess. See relevant section below for details.
    name: Unique registry name
    auth_header_name: Provide NoAuth if the registry does not require authentication. Not required for public registries.
    auth_type: Enter gcr|ecr/quay if the registry type is GCR, ECR, or Quay respectively.
    is_public: Enter true if the registry does not require credentials.
    ssl: Whether the registry uses SSL, enter true|false.
    auto_poll: If supported, whether to auto poll the registry, enter true|false.
    credentials: This field varies depending on the type of authentication required for the registry.
    poll_frequency_minutes: Polling frequency to fetch new images, 20 is the minimum value. Not used for registry notification or on-demand scans.
    disable_non_os_package_scanning: Whether the scanner will search for non-OS library packages. Enter true|false.
    go_binary_scanning: Whether the scanner will search for Go binary executables.
      enable: true|false
      scan_directory_path: Restrict Go binary scanning to a specified directory in the image, for example: "/usr/bin".
    notification_type: If using registry notification, enter the notification type: acr|dtr|ghcr|hub|jfrog|v2_registry.

The sections below provide more detail on how to use these fields.

Amazon ECR integrations

If you are running the Proxy Scanner on an EC2/ECS instance, see Automated Configuration for Private Amazon ECRs as only minimal configuration is required.

scan_public_registries​

Set scan_public_registries: true if you are scanning images from registries that are publicly accessible (the default is true if the field is omitted).

This will allow for anonymous pulling of images unless is_public: false.

static_cache_location​

The static file mount location used by the Proxy Scanner. The recommended path is /opt/lacework.

disable_expand_env​

Set disable_expand_env: true if you want to use special characters (such as $) within the config.yml.

For example, if your user_name is "$robotci", you must include this config property and set it to true.

default_registry​

Specify a default registry if you don't want to include the registry in curl commands for on-demand scans.

note

The default_registry and domain values need to match.

Example
static_cache_location: /opt/lacework
default_registry: index.docker.io
lacework:
  account_name: myAccountName
  integration_access_token: MyAccessToken
registries:
  - domain: index.docker.io
    name: myRegistry
    ssl: true
    is_public: true
    auto_poll: false
    disable_non_os_package_scanning: false
    go_binary_scanning:
      enable: true

account_name​

account_name specifies your Lacework account in the format: customer.availabilityzone. For this configuration field, customer is the identifier for your account and the availabilityzone specifies the logical data center for that region.

For example, a company named Specialized Software hosted in Frankfurt has the account name specializedsoftware.fra.

tip

This can be found as part of the URL used to access your Lacework Console (for example: https://specializedsoftware.fra.lacework.net). However, do not include the .lacework.net portion when entering the account name.

integration_access_token​

The integration_access_tokenis available in the Lacework Console after Creating a Proxy Scanner Integration.

existingSecret​

important

This is an optional field for when you don't want the access token details displayed in plain text in the config.yml file.

This field is only relevant when using Kubernetes Helm Charts to deploy the Proxy Scanner.

Optionally, store the Lacework access token outside of Helm by using the existingSecret fields to reference the Kubernetes secrets for the Inline Scanner.

  1. Create your Kubernetes Secret by creating a Config file to contain the necessary data.

    Example contents of Kubernetes Secret Config file for lw-scanner-token
    apiVersion: v1
    kind: Secret
    metadata:
      name: lw-scanner-secret
      namespace: default
    type: Opaque
    data:
      lw-scanner-token: _123456789abcdef123456789abcd

  2. Use an existing secret in your Lacework Helm charts by choosing one of the following options:

    1. Enter a command such as:

      Example for Combined Helm Charts
      --set proxy-scanner.config.lacework.integration_access_token.existingSecret.key="lw-scanner-token"
      --set proxy-scanner.config.lacework.integration_access_token.existingSecret.name="lw-scanner-secret"
      Example for Separate Helm Charts
      --set config.lacework.integration_access_token.existingSecret.key="lw-scanner-token"
      --set config.lacework.integration_access_token.existingSecret.name="lw-scanner-secret"

    2. Add the key and name values into the Proxy Scanner config:

      Example
      lacework:
        account_name: YourLaceworkAccount
        integration_access_token:
          existingSecret:
            key: lw-scanner-token
            name: lw-scanner-secret

      Examples of Proxy Scanner configurations for Kubernetes Admission Controller using:

registry_secret_name​

important

This is an optional field for when you don't want the registry details displayed in plain text in the config.yml file.

This field is only relevant when using Kubernetes Helm Charts to deploy the Proxy Scanner.

Store all configuration information in registries in a base64 string and then create a Kubernetes secrets to contain this info.

This can then be referenced in the Proxy Scanner config as a Kubernetes secret (instead of listing registry details and credentials in plain text).

  1. Create the registries section for your Proxy Scanner config. The example below has details for two different registries.

    Example for registries
    - domain: gcr.io
      name: test-gcr
      ssl: true
      auth_type: gcr
      credentials:
        client_email: my@emailaddress.iam.gserviceaccount.com
        client_id: 123
        private_key_id: 12345
        private_key: 12345
      go_binary_scanning:
        enable: true
    - domain: 12345.dkr.ecr.us-west-2.amazonaws.com
      name: test-ecr
      ssl: true
      auth_type: ecr
      credentials:
        access_key_id: 12345
        secret_access_key: 12345
      go_binary_scanning:
        enable: true

  2. Convert the registries section to base64.

    Example
    cat <registries-config> | base64

    Use the output for the Kubernetes Secret in the next step.

  3. Create your Kubernetes Secret. One way to do this is by creating a Config file to contain the necessary data.

    Example contents of Kubernetes Secret Config file for registries
    apiVersion: v1
    kind: Secret
    metadata:
      name: scanner-registry-secrets
      labels:
        tier: monitoring
        app: lacework-proxy-scanner
    type: Opaque
    data:
      registries: <b64 encoded string from previous step>
    important

    The key within data has to be named registries for the configuration to be correctly applied.

    Save this as a YAML file to be referenced in the next step.

  4. Run the following command to apply the configuration.

    Example
    kubectl apply -f <secret-config-file-for-registries>.yaml

  5. Set your Proxy Scanner config to reference the registries secret (scanner-registry-secrets in this case):

    note

    These examples also use the existingSecret option for the Lacework Access Token.

    Example for Combined Helm Chart
    proxy-scanner:
      config:
        static_cache_location: /opt/lacework
        default_registry:
        lacework:
          account_name: myLaceworkAccount
          integration_access_token:
            existingSecret:
              key: lw-scanner-token
              name: lw-scanner-secret
        registry_secret_name: scanner-registry-secrets
    Example for Separate Helm Charts
    config:
      static_cache_location: /opt/lacework
      default_registry:
      lacework:
        account_name: myLaceworkAccount
        integration_access_token:
          existingSecret:
            key: lw-scanner-token
            name: lw-scanner-secret
      registry_secret_name: scanner-registry-secrets

    See also the following examples for Proxy Scanner configurations for Kubernetes Admission Controller using:

registries​

You can add more registries by repeating the series of fields under registries:. Each defined registry can use a different scan type.

note

Accessing multiple registries by using the same domain name (domain: xyz) is not supported.

To access multiple registries within the same domain, set up separate config files and Proxy Scanner deployments.

Example for two private registries with auto polling and on-demand scans configured respectively
scan_public_registries: false
static_cache_location: /opt/lacework
lacework:
  account_name: YourLaceworkAccount
  integration_access_token: _123456789abcdef123456789abcd
registries:
  - domain: FirstDomain:8080
    name: Registry1
    ssl: true
    is_public: false
    auto_poll: true
    credentials:
      user_name: "UserName1"
      password: "Password1"
    poll_frequency_minutes: 20
    disable_non_os_package_scanning: false
    go_binary_scanning:
      enable: true
  - domain: SecondDomain:8080
    name: Registry2
    ssl: true
    is_public: false
    auto_poll: false
    credentials:
      user_name: "UserName2"
      password: "Password2"
    poll_frequency_minutes: 20    
    disable_non_os_package_scanning: false
    go_binary_scanning:
      enable: true

domain​

The registry domain in one of these formats:

  • IP:Port
  • Domain:Port
  • A Public Domain (for example: index.docker.io)

image_filter​

If you do not want to assess all images in this registry, use the image filter option to specify a list of repositories/images, tags, and/or labels to discover and assess.

Example
...
- domain: index.docker.io
  image_filter:
    repository:
      - myRepository/image_to_scan
      - myRepository/another_image_to_scan
    tags:
      - prod
    labels:
      - key: env
        value: prod
...

repository​

Specify a list of repositories/images to discover and assess.

Repository example
...
- domain: index.docker.io
  image_filter:
    repository:
      - myRepository/image_to_scan
      - myRepository/another_image_to_scan
...

tags​

Specify a list of image tags to discover and assess.

Tags example
...
- domain: index.docker.io
  image_filter:
    tags:
      - prod
...

labels​

Specify a list of image labels to discover and assess.

Labels example
...
- domain: index.docker.io
  image_filter:
    labels:
      - key: env
        value: prod
...

name​

The registry name available in the specified domain.

auth_header_name​

important

If connecting to a public registry, use the scan_public_registries: true field and value instead of this.

If you are not providing credentials, some registries may require the following value set for the auth_header_name:

auth_header_name: NoAuth

Omit the field from the configuration if you are providing credentials or if the registry does not require a NoAuth header.

auth_type​

Provide this field if you are integrating with Amazon ECR (public or private), GCR (private only), or Red Hat Quay.

The value for this field depends on the registry type:

  • For Amazon ECR, use auth_type: ecr.
  • For GCR, use auth_type: gcr.
  • For Red Hat Quay, use auth_type: quay.

Provide credentials for your registry type when including this field, unless is_public: true has been set.

is_public​

Enter is_public: true if you are integrating with a registry that doesn't require credentials (the default is false if this field is omitted).

Set to false or omit this field if you are providing credentials.

ssl​

Whether the registry domain uses SSL/TLS (https://), enter true or false.

auto_poll​

Set to true if you are configuring for Auto Polling. Default is false.

Check that your registry type supports Auto Polling.

credentials​

This field will vary depending on the registry type and the authentication method(s) supported by the registry.

Basic Authentication​

For basic authentication methods (such as for Docker V2 or Red Hat Quay authentication), use the following template:

    credentials:
      user_name: User name to connect to the registry
      password: Password to connect to the registry

Ensure to encase the values in double quotes:

Example
    credentials:
      user_name: "MyUsername"
      password: "MyPassword"

GCR Authentication​

important

Ensure auth_type has been set to gcr.

For GCR authentication, use the following template:

    credentials:
      client_email: Google Cloud email address for GCR access
      client_id: Google Cloud ID for GCR access
      private_key_id: Private Key ID for GCR access
      private_key: Base64 encoded private key for GCR access
Format for private_key

The private_key value must be in base64 format.

For GCP service account keys, the JSON can be converted to the correct base64 format by using the following command:

cat <gcp-service-account-key-file>.json | jq -r ".private_key" | base64

Use this value for the private_key: field.

Ensure to encase the values in double quotes:

Example
    credentials:
      client_email: "my-service-account@project-id.iam.gserviceaccount.com"
      client_id: "112233445566778899001"
      private_key_id: "1a2b3c4d5f6a7b3x4mp132a3b4c5d6e7f0a1b2c"
      private_key: "BASE64_ENCODED_STRING"

Amazon ECR Authentication​

important

Ensure auth_type has been set to ecr.

tip

If you are running the Proxy Scanner on an EC2/ECS instance, see Automated Configuration for Private Amazon ECRs before proceeding with this section.

Access and Secret Keys​

For access and secret keys, use the following template:

    credentials:
      access_key_id: AWS Access Key for Amazon ECR access
      secret_access_key: AWS Secret Key for Amazon ECR access

Ensure to encase the values in double quotes:

Example
    credentials:
      access_key_id: "MYACCESSKEYIDEXAMPLE"
      secret_access_key: "c0nt3ntMYSECRETKEYEXAMPLEc0nt3ntc0nt3ntc"
Local Profile Credentials​

For local profile credentials, use the following template:

    credentials:
      use_local_credentials: true
      credentials_profile: AWS credentials profile name
Example
    credentials:
      use_local_credentials: true
      credentials_profile: default

poll_frequency_minutes​

Polling frequency to fetch new images in minutes, 20 is the minimum value.

Only applicable for Auto Polling (not used for registry notification or on-demand scans).

disable_non_os_package_scanning​

Set the disable_non_os_package_scanning field to true if you want to disable the scanning of programming language libraries. When this field is omitted, the default value is false.

See Language Libraries Support for details on what is scanned.

note

This field replaced scan_non_os_packages in v4.42.

go_binary_scanning​

Enable or disable Go binary scanning by using the fields as demonstrated in the examples below:

Enable Go binary scanning
    go_binary_scanning:
      enable: true
Disable Go binary scanning
    go_binary_scanning:
      enable: false

scan_directory_path​

Restrict Go binary scanning to a specified directory in images by using the following field:

      scan_directory_path: ""

In the example below, only Go binaries located in the /usr/bin directory will be scanned for vulnerabilities.

Example
    go_binary_scanning:
      enable: true
      scan_directory_path: "/usr/bin"

notification_type​

The following table lists the value required for each type of registry:

Registry TypeValue
Azure Container Registryacr
Docker Trusted Registrydtr
GitHub Container Registryghcr
Docker Hubhub
JFrogjfrog
Docker V2-based authentication registryv2_registry

Omit this field if not using registry notification.

Automated Configuration for Private Amazon ECRs​

If you configure the Proxy Scanner to run on an Amazon EC2/ECS instance, it will attempt to automatically discover and authenticate with the private ECR available to the local IAM role (attached to the instance).

  1. Ensure that the local user running the Proxy Scanner has local profile credentials configured. The local profile should be automatically created once an IAM role is attached to an EC2 instance. This role allows you to read the private ECR repositories associated with the account.

  2. A minimal config.yml is still required to deploy the Proxy Scanner:

    Example
    static_cache_location: /opt/lacework
    lacework:
      account_name: myAccountName
      integration_access_token: MyAccessToken

  3. Once you have created the config.yml, proceed to Deploy the Proxy Scanner.

  4. After deployment, you can then start using curl commands to carry out scans on-demand.

Example Configurations for Different Authentication Types​

These are some examples of the config.yml file for different authentication methods that use the auth_header_name, auth_type, is_public, and credentials fields.

note

Each example is configured for on-demand scans.

Public Registries Example​

This example applies to many public registries that allow anonymous access, such as index.docker.io, mcr.microsoft.com, gcr.io, public.ecr.aws, etc.

static_cache_location: /opt/lacework
default_registry: index.docker.io
lacework:
  account_name: myLaceworkAccount
  integration_access_token: _123456789abcdef123456789abcd
registries:
  - domain: index.docker.io
    name: myPublicRegistry
    is_public: true
    ssl: true
    auto_poll: false
    disable_non_os_package_scanning: false
    go_binary_scanning:
      enable: true

Private Docker Hub Example​

scan_public_registries: false
static_cache_location: /opt/lacework
lacework:
  account_name: myLaceworkAccount
  integration_access_token: _123456789abcdef123456789abcd
registries:
  - domain: index.docker.io
    name: myPrivateRegistry
    is_public: false
    ssl: true
    auto_poll: false
    credentials:
      user_name: "myUserName"
      password: "myPassword"
    disable_non_os_package_scanning: false
    go_binary_scanning:
      enable: true

Private Red Hat Quay Example​

scan_public_registries: false
static_cache_location: /opt/lacework
lacework:
  account_name: myLaceworkAccount
  integration_access_token: _123456789abcdef123456789abcd
registries:
  - domain: quay.io
    name: myPrivateRegistry
    is_public: false
    ssl: true
    auto_poll: false
    credentials:
      user_name: "myUserName"
      password: "myPassword"
    disable_non_os_package_scanning: false
    go_binary_scanning:
      enable: true

Private Google Container Registry (GCR) Example​

scan_public_registries: false
static_cache_location: /opt/lacework
lacework:
  account_name: myLaceworkAccount
  integration_access_token: _123456789abcdef123456789abcd
registries:
  - domain: gcr.io
    name: myPrivateRegistry
    auth_type: gcr
    is_public: false
    ssl: true
    auto_poll: false
    credentials:
      client_email: "my-service-account@project-id.iam.gserviceaccount.com"
      client_id: "112233445566778899001"
      private_key_id: "1a2b3c4d5f6a7b3x4mp132a3b4c5d6e7f0a1b2c"
      private_key: "BASE64_ENCODED_STRING"
    disable_non_os_package_scanning: false
    go_binary_scanning:
      enable: true
note

For the private_key value, see GCR Authentication for guidance on the correct formatting.

Private Amazon Elastic Container Registry (ECR) Examples​

Amazon ECR integrations

If you are running the Proxy Scanner on an EC2/ECS instance, see Automated Configuration for Private Amazon ECRs as only minimal configuration is required.

Example with Access/Secret Keys
scan_public_registries: false
static_cache_location: /opt/lacework
lacework:
  account_name: myLaceworkAccount
  integration_access_token: _123456789abcdef123456789abcd
registries:
  - domain: <aws_account_id>.dkr.ecr.<region>.amazonaws.com
    name: myPrivateRegistry
    auth_type: ecr
    is_public: false
    ssl: true
    auto_poll: false
    credentials:
      access_key_id: "MYACCESSKEYIDEXAMPLE"
      secret_access_key: "c0nt3ntMYSECRETKEYEXAMPLEc0nt3ntc0nt3ntc"
    disable_non_os_package_scanning: false
    go_binary_scanning:
      enable: true
Example with Local Profile Credentials
scan_public_registries: false
static_cache_location: /opt/lacework
default_registry: 
lacework:
  account_name: myLaceworkAccount
  integration_access_token: _123456789abcdef123456789abcd
registries:
  - domain: <aws_account_id>.dkr.ecr.<region>.amazonaws.com
    name: myPrivateRegistry
    auth_type: ecr
    is_public: false
    ssl: true
    auto_poll: false
    credentials:
      use_local_credentials: true
      credentials_profile: default
    disable_non_os_package_scanning: false
    go_binary_scanning:
      enable: true

Kubernetes Admission Controller Using Combined Helm Chart Examples​

Example with Existing Secret
proxy-scanner:
  config:
    default_registry: index.docker.io
    static_cache_location: /opt/lacework
    lacework:
      account_name: myLaceworkAccount
      integration_access_token: 
        existingSecret:
          key: lw-scanner-token
          name: lw-scanner-secret
    registries:
      - domain: index.docker.io
        name: myRegistry
        ssl: true
        auto_poll: false
        is_public: true
        poll_frequency_minutes: 20
        disable_non_os_package_scanning: false
        go_binary_scanning:
          enable: true
Example with Existing Secret and Registry Secret Name
proxy-scanner:
  config:
    static_cache_location: /opt/lacework
    lacework:
      account_name: myLaceworkAccount
      integration_access_token:
        existingSecret:
          key: lw-scanner-token
          name: lw-scanner-secret
    registry_secret_name: scanner-registry-secrets
Example with Access Token
proxy-scanner:
  config:
    default_registry: index.docker.io
    static_cache_location: /opt/lacework
    lacework:
      account_name: myLaceworkAccount
      integration_access_token: _123456789abcdef123456789abcd
    registries:
      - domain: index.docker.io
        name: myRegistry
        ssl: true
        auto_poll: false
        is_public: true
        poll_frequency_minutes: 20
        disable_non_os_package_scanning: false
        go_binary_scanning:
          enable: true

Kubernetes Admission Controller Using Separate Helm Charts Examples​

Example with Existing Secret
config:
  default_registry: index.docker.io
  static_cache_location: /opt/lacework
  lacework:
    account_name: myLaceworkAccount
    integration_access_token: 
      existingSecret:
        key: lw-scanner-token
        name: lw-scanner-secret
  registries:
    - domain: index.docker.io
      name: myRegistry
      ssl: true
      auto_poll: false
      is_public: true
      poll_frequency_minutes: 20
      disable_non_os_package_scanning: false
      go_binary_scanning:
        enable: true
Example with Existing Secret and Registry Secret Name
config:
  static_cache_location: /opt/lacework
  lacework:
    account_name: myLaceworkAccount
    integration_access_token:
      existingSecret:
        key: lw-scanner-token
        name: lw-scanner-secret
  registry_secret_name: scanner-registry-secrets
Example with Access Token
config:
  default_registry: index.docker.io
  static_cache_location: /opt/lacework
  lacework:
    account_name: myLaceworkAccount
    integration_access_token: _123456789abcdef123456789abcd
  registries:
    - domain: index.docker.io
      name: myRegistry
      ssl: true
      auto_poll: false
      is_public: true
      poll_frequency_minutes: 20
      disable_non_os_package_scanning: false
      go_binary_scanning:
        enable: true

Configure for Auto Polling​

You can configure the proxy scanner for auto polling of new images from the registry if your registry is Docker V2 API-compatible. This means your registry must have the following APIs available:

  • /v2/_catalog
  • /v2/{name}/tags/list

If your registry doesn't have either of the previous APIs, you can configure the proxy scanner for registry notification or on-demand scans.

Environment Variables for Auto Polling​

The Proxy Scanner has certain environment variables that can be set to increase or decrease scanning performance. These are listed in the table below:

Environment VariableDescriptionDefault Value
COOL_OFF_AFTER_TAG_COUNTThe amount of time in milliseconds before the Proxy Scanner will retry scanning the registry for tags.1
COOL_OFF_MILLISECONDSThe amount of time in milliseconds before the Proxy Scanner will retry scanning the registry.10
MAX_CONCURRENT_SCANSThe maximum amount of concurrent scans that the Proxy Scanner will perform on the registry.20
MAX_BOOT_TIME_TAGSThe maximum number of new tags that will be scanned when the Proxy Scanner starts up.5
MAX_TAGS_PER_REPOThe maximum number of new tags per repository that are scanned by the Proxy Scanner.50

The environment variables can be set on the Proxy Scanner host. Use the -e, --env, and --env-file flags to set these environment variables in the proxy scanner container. See the docker run document for more details.

Example
export COOL_OFF_AFTER_TAG_COUNT=1 \
export COOL_OFF_MILLISECONDS=10 \
export MAX_CONCURRENT_SCANS=20 \
export MAX_BOOT_TIME_TAGS=5 \
export MAX_TAGS_PER_REPO=50

CPU and Memory Requirements for MAX_CONCURRENT_SCANS and Image Sizes​

When setting the MAX_CONCURRENT_SCANS value, and depending on your image sizes, the Proxy Scanner service on the host should be allocated the recommended CPU and Memory requirements.

Here are some examples for the CPU and Memory requirements:

MAX_CONCURRENT_SCANS ValueImage Size RangeCPU & Memory Recommendations
20100MB - 1.5GBCPU = 2 Cores, Memory = 4GB
30100MB - 3GBCPU = 2 Cores, Memory = 6.5GB
20100MB - 6GBCPU = 2 Cores, Memory = 8.5GB
Memory Calculation​

Maximum image size + n + 500MB additional headroom.

The value of n is:

  • 1 if MAX_CONCURRENT_SCANS is set to 10 or less.
  • 2 if MAX_CONCURRENT_SCANS is set between 10 and 20.
  • 3 if MAX_CONCURRENT_SCANS is set between 20 and 30.

Example: 3GB + 3 + 0.5GB = 6.5GB Memory

CPU Calculation​

Maximum of two core CPU is sufficient for most workloads.

For better performance when MAX_CONCURRENT_SCANS exceeds 30, add one additional core CPU.

Example config.yml for Auto Polling​

Example for auto polling
scan_public_registries: false
static_cache_location: /opt/lacework
default_registry: 
lacework:
  account_name: YourLaceworkAccount
  integration_access_token: _123456789abcdef123456789abcd
registries:
  - domain: YourDomain:8080
    name: YourRegistry
    ssl: true
    is_public: false
    auto_poll: true
    credentials:
      user_name: "YourUserName"
      password: "Password1"
    poll_frequency_minutes: 20
    disable_non_os_package_scanning: false
    go_binary_scanning:
      enable: true
for mac OS

Depending on where you are binding from, Docker might not have permission to access the directory. You can change this by adding Docker under macOS Settings > Security & Privacy > Privacy > Full Disk Access. You must also add the directory to be bind mounted under Docker Settings Resources > File Sharing.

After configuration, deploy the proxy scanner. The proxy scanner scans images and sends the manifest to Lacework for assessment. Within 10 to 15 minutes the Lacework Console displays assessment results.

Configure for Registry Notification​

Registry notification is supported for the following registries:

  • Azure Container Registry
  • Docker Hub
  • Docker Trusted Registry
  • Docker V2-based authentication registries
  • GitHub Container Registry
  • Harbor
  • JFrog

To use registry notifications:

  • You must configure the webhook from your registry, which is different for each supported registry.
  • Webhook endpoint URL for proxy scanner: <ProxyScannerHost>:8080/v1/notification?registry_name=<RegistryNameFromYourConfig.yml>.
  • Http only - Https is not supported.
  • SSL verification is not required.
  • Configure the webhook to trigger when new images are pushed.

After configuration, Lacework Proxy Scanner can receive notifications that the registry sends in response to the configured image events that happen within the registry. When Lacework Proxy Scanner receives the webhook notifications, it sends the image details to the Lacework cloud to perform an assessment.

Example config.yml for Registry Notification​

Example for registry notification
scan_public_registries: false
static_cache_location: /opt/lacework
default_registry: 
lacework:
  account_name: YourLaceworkAccount
  integration_access_token: _123456789abcdef123456789abcd
registries:
  - domain: YourDomain:8080
    name: YourRegistry
    ssl: true
    is_public: false
    auto_poll: false
    credentials:
      user_name: "YourUserName"
      password: "Password1"
    # Define the notification type acr|dtr|ghcr|hub|jfrog|v2_registry|harbor that corresponds to your registry
    notification_type: harbor
    disable_non_os_package_scanning: false
    go_binary_scanning:
      enable: true

_YourRegistry_ is the name of the registry and folder name of the image. For example, if your registry path is docker-hub-remote/library/YourImageName/ the value for _YourRegistry_ is docker-hub-remote/YourImageName/.

After configuration, deploy the proxy scanner.

Configure for On-Demand Scans​

To use on-demand scans, you must create a configuration yaml file, deploy the Proxy Scanner, and use a curl command to initiate a scan.

Example config.yml for On-Demand Scans​

Example for on-demand scans
scan_public_registries: false
static_cache_location: /opt/lacework
default_registry: 
lacework:
  account_name: YourLaceworkAccount
  integration_access_token: _123456789abcdef123456789abcd
registries:
  - domain: YourDomain:8080
    name: YourRegistry
    ssl: true
    is_public: false
    auto_poll: false
    credentials:
      user_name: "YourUserName"
      password: "Password1"
    disable_non_os_package_scanning: false
    go_binary_scanning:
      enable: true

_YourRegistry_ is the name of the registry and the folder name of the image. For example, if your registry path is docker-hub-remote/library/YourImageName/ the value for _YourRegistry_ is docker-hub-remote/YourImageName/.

Deploy the Proxy Scanner for On-Demand Scans​

Deploy the Proxy Scanner as instructed in this section.

Curl command for On-Demand Scans​

Once you have configured and deployed the Proxy Scanner, use a curl command to carry out scans on-demand.

Example curl command
curl --location --request POST 'YourHost:8080/v1/scan' \
--header 'Content-Type: application/json' \
--data-raw '{
    "registry": "YourRegistry",
    "image_name": "YourRepository/YourImage",
    "tag": "YourValue"
}'

Replace the _Your_ placeholders with your values. Replace YourHost:8080 with your environment's host and port. For example, if you deploy the proxy scanner within EC2, use the IP address provided by AWS.

info

If you are using the default_registry field in the config.yml, and you are making a call to that registry, you can omit "registry": "YourRegistry", from the command.

After configuration, you can make an API call whenever an image is built so Lacework can assess it. Within 10 to 15 minutes the Lacework Console displays assessment results.

Response codes:

  • 200 - successful scan
  • 204 - already scanned
  • non 2xx - failure

Deploy the Proxy Scanner​

Before you deploy the proxy scanner, ensure that you set up a host machine with Docker installed.

  1. Using the Docker client [cli], pull the Lacework image: 

    docker pull lacework/lacework-proxy-scanner:latest

  2. Create a writeable container layer and start the image:

    info

    If using local profile credentials for Amazon ECR, adjust the deploy command as shown in the section below.

    docker run \
    --mount type=bind,source="$(pwd)"/cache,target=/opt/lacework/cache \
    -v `pwd`/config.yml:/opt/lacework/config/config.yml \
    -p 8080:8080 \
    lacework/lacework-proxy-scanner

    where
    "$(pwd)"/cache is the persistent storage location where you want to store cache
    `pwd`/config.yml is your configuration file location

    Example
    docker run \
    --mount type=bind,source=/YourHostDirectoryPath/cache,target=/opt/lacework/cache \
    -v /YourHostDirectoryPath/config.yml:/opt/lacework/config/config.yml \
    -p 8080:8080 \
    lacework/lacework-proxy-scanner:latest

    For debugging purposes, add -e LOG_LEVEL=debug:

    docker run -e LOG_LEVEL=debug -d --mount ...

    Available LOG_LEVEL options = error|warn|debug

Using Amazon ECR Local Profile Credentials​

If you are using local profile credentials for Amazon ECR, add an additional volume mount for the AWS credentials file:

Example
docker run -d \
--mount type=bind,source="$(pwd)",target=/opt/lacework/cache \
-v "$(pwd)"/config.yml:/opt/lacework/config/config.yml \
-v ~/.aws/credentials:/root/.aws/credentials \
-p 8080:8080 \
lacework/lacework-proxy-scanner:latest

Troubleshoot​

Scanning Registry Failed with Error 504 Instead of 2xx​

important

These troubleshooting steps only apply to a Proxy Scanner configured for Auto Polling.

If the Proxy Scanner log reports errors when trying to scan a registry (such as 504 meaning service not available), you can slow down the polling rate of the Proxy Scanner requests by using environment variables for auto polling.

The environment variables can be set on the Proxy Scanner host:

Example
export COOL_OFF_AFTER_TAG_COUNT=10 \
export COOL_OFF_MILLISECONDS=100 \
export MAX_CONCURRENT_SCANS=10

Scan Java Images Offline​

By default, the Proxy Scanner accesses https://search.maven.org/solrsearch/select when searching for Maven Java dependencies/jars. If this Maven site is down, the Proxy Scanner can fail with EOF and 504 timeouts.

Use the following environment variable if you want to stop the Proxy Scanner from accessing https://search.maven.org/solrsearch/select for Maven Java dependencies:

JAVA_OFFLINE_MODE=true