Trend Micro logo

Deep Security Smart Check Deployment Guide

Deep Security™ Smart Check is a container image scanner from Trend Micro™. This guide describes how Smart Check works and how to use the Smart Check console. It contains:

About Deep Security Smart Check

Deep Security™ Smart Check performs pre-runtime scans of Docker™ images, enabling you to fix issues before they reach the orchestration environment (for example, Kubernetes®). Deep Security Smart Check provides the ability to:

Deep Security Smart Check receives up-to-date threat data from private Trend Micro endpoints. Smart Check obtains malware information from the Trend Micro Smart Protection Network™ and detects threats using Trend Micro XGen™ machine learning algorithms. Deep Security Smart Check will find vulnerabilities in these Linux® distributions:

How does Smart Check fit into a DevOps pipeline?

Deep Security Smart Check provides a valuable step in your continuous integration (CI) or continuous delivery (CD) pipeline.

For example, Jenkins® projects can automatically build, test, and then push Docker images to a Docker registry. Once pushed, the image may be instantly available to run in an orchestration environment. If malware or vulnerabilities exist in the image, then they become a risk when the image is run. Since images are intended to be immutable, the right time to scan the image is when it's first pushed to the registry.

That’s where Deep Security Smart Check fits in – it can scan Docker images in any registry that implements the Docker Registry V2 API. All Deep Security Smart Check operations are available through a documented collection of APIs to simplify integration into your CI/CD pipeline. Deep Security Smart Check APIs can be invoked automatically by your CI/CD system to start scans when an image is pushed to a Docker registry. Scan results are also available through the API. You can also scan images before they reach your production registry (see Configure pre registry scanning in the Smart Check wiki).

The Smart Check API includes a web hook facility that allows CI/CD components to register to receive notifications of scan events, including ‘scan-completed’, allowing you to automate workflows. For example, a Docker image signing service could register to receive scan results and then use those results to decide whether a particular image should be digitally signed and promoted to a “blessed” repository that is available to your orchestration environment. You could also set a web hook to call a receiver service that forwards scan results to a Slack™ channel or ServiceNow™ account.

Deep Security Smart Check also includes an administrator console that provides:

Supported registries

Deep Security Smart Check supports scanning Docker images in any registry that supports the Docker Registry V2 API and allows catalog listing. Tested registries include:

Note: Deep Security Smart Check requires a TLS connection to the registry.

To integrate Deep Security Smart Check into your pipeline, you may need to write integration logic to trigger scanning based on the event model of your registry. For example, Google Container Registry uses a pub/sub model to publish events about registry activity and Docker Trusted Registry uses a web hook model. If you use Jenkins, you can use the Deep Security Smart Check plugin for Jenkins for easy integration into your pipeline. You can also use our GitHub Action directly to integrate Smart Check into your CI workflows. See Deep Security Smart Check Scan Action for details.

System requirements

This release of Deep Security Smart Check requires:

Deep Security Smart Check is tested with Google Kubernetes Engine, using the following resource allocations:

By default, Deep Security Smart Check requires an 8 GB persistent volume when using the built-in database. If you install using an external database, Deep Security Smart Check does not require any persistent volumes.

Install Deep Security Smart Check

Deep Security Smart Check is supported on the Kubernetes platform and uses the Helm package manager for Kubernetes. You must have a running Kubernetes cluster in order to deploy Smart Check.

See the Deep Security Smart Check readme for up-to-date instructions on how to install Deep Security Smart Check: https://github.com/deep-security/smartcheck-helm. By default, the Helm deployment retrieves the Smart Check Docker images from DockerHub: https://hub.docker.com/r/deepsecurity/.

At the end of the install, you’ll see commands that enable you to get the URL of the Smart Check administrator console and to get the initial administrator user name and password. The commands are also provided in the sections below.

Get the URL of the Smart Check administrator console

To get the URL of the Smart Check administrator console, configure kubectl with your cluster credentials and run these commands:

$ export SERVICE_IP=$(kubectl get svc proxy –o jsonpath='{.status.loadBalancer.ingress[0].ip}')

$ echo https://$SERVICE_IP:443

Get the initial administrator user name and password

To get the user name and password that you will use to log in to the Smart Check application for the first time, configure kubectl with your cluster credentials and run these commands:

$ echo Username: $(kubectl get secrets -o jsonpath='{ .data.userName }' deepsecurity-smartcheck-auth | base64 --decode)

$ echo Password: $(kubectl get secrets -o jsonpath='{ .data.password }' deepsecurity-smartcheck-auth | base64 --decode)

Allow inbound and outbound connections

If you are using an HTTP proxy, Smart Check requires that you open one inbound port for HTTPS access to the proxy service. Details for determining the port information are provided during the Smart Check installation.

Smart Check also requires outbound access to these hosts over HTTPS (port 443):

First steps after installation

After installing Smart Check:

  1. Log in to the Smart Check administrator console
  2. Configure Smart Check users
  3. Add or edit a registry
  4. Start a scan

Log in to the Smart Check administrator console

  1. Go to the URL provided at the end of the installation. If you don’t have the URL, see Get the URL of the Smart Check administrator console.
  2. Enter the initial administrator username and password and click LOGIN. If you don't have the user credentials, see Get the initial administrator user name and password.

The Deep Security Smart Check administrator console appears.

The first time you log in, you are prompted to change the password for the default administrator.

Configure Smart Check users

Deep Security Smart Check has a default administrator account, but you can add other user accounts.

Tip: You can also enable SAML single sign-on in Deep Security Smart Check, so that users in your organization can sign in to Smart Check with their existing organization account. You can also use your identity provider to implement user authentication access control features like password strength or change enforcement,  one-time passwords (OTP), and  two-factor or multi-factor authentication (2FA / MFA). For instructions, see Implement SAML single sign-on on the Smart Check helm wiki.

Add or edit a user

  1. On the left side of the Smart Check administrator console, click User icon Users.
  2. On the Users page, click + CREATE to add a user or click an existing user to edit.
  3. On the Add/Edit User page, enter the User ID that the user will use to log in to Deep Security Smart Check. The User ID has a maximum of 64 characters.
  4. Enter the user’s full name.
  5. Enter a password and confirm the password.
  6. We recommend that you select Require user to change password on next login when adding a new user.
  7. Select a role to assign to the user. Smart Check has three types of roles:
    • Administrator: Full control
    • User: Can request scans and has read-only access to users, roles, registries, content rules, identity providers, and overrides.
    • Auditor: Read-only access
  8. Click SAVE.

Delete a user

  1. On the left side of the Smart Check administrator console, click User icon Users.
  2. On the Users page, click the user you want to remove.
  3. On the Edit User page, click DELETE.

Note: You must have at least one user with the administrator role. If you have only one administrator, you cannot delete that user until you add another administrator.

Add or edit a registry

Before Smart Check can scan your images, it needs to know which registries contain the images that you want to scan. You can add one or more registries (up to a maximum of 4 with a trial or basic license) to Deep Security Smart Check.

Before adding a registry

When you add a registry, you must provide authentication credentials that Deep Security Smart Check will use to access your repository. Depending on the type of registry, you can provide AWS credentials, a username and password, or a JSON key file.

If you are using Google Cloud Registry, create a service account and use its JSON key file. The service account must have at least the Storage Object Viewer role and both the Google Cloud Resource Manager API and Google Container Registry API must be enabled. Google provides an overview and detailed instructions for creating service accounts.

Add a registry

  1. On the left side of the Smart Check administrator console, click Registries icon Registries.
  2. Click + CREATE to add a registry.
  3. On the Create Registry page, in the Name field, enter a descriptive name for the registry. This name does not necessarily need to match the namespace of your Docker registry. If you plan to add multiple registries, you’ll use this name to tell them apart in the Smart Check administrator console. The name should be short but meaningful, with a maximum of 256 characters.
  4. In the Description field, enter an optional description of the registry. This is useful if you need to capture a bit more information than the Name field allows.
  5. In the Registry Type field, select the type of registry you're adding:
    • Google Cloud Registry
    • Amazon Elastic Cloud Registry
    • Generic Registry
  6. For a Google Cloud Registry, enter:
    • Registry Host: Hostname or IP address of the Docker registry you want to scan
    • JSON key file: JSON key that Smart Check will use to access your repository
  7. For an Amazon Elastic Cloud Registry, enter:
    • Region: AWS region identifier where your registry it located
    • Registry ID: (Optional) If you want to scan a registry in another account, enter the account ID here. If you do not specify an account, Smart Check will use the default registry.
    • Use cross-account role: Select this option if you want to scan a registry in another account.
    • Authentication method: Select either Instance Role or Access Key ID & Secret. Specifying access keys is discouraged because the keys need to be updated periodically (for security reasons), which creates management overhead.
  8. For a Generic Registry, enter:
    • Registry Host: Hostname or IP address of the Docker registry you want to scan
    • Registry User: Username that Smart Check will use to access your repository
    • Password: Password that Smart Check will use to access your repository
    • HTTPS Configuration:
      • Skip registry certificate validation (insecure): By default, Smart Check validates the TLS certificate associated with your registry. This validation requires that Smart Check trust the certificate of the CA that issued the registry certificate. If you don’t have the CA certificate, you can select Skip registry certificate validation (insecure).
      • Trust: Deep Security Smart Check has a built-in set of certificate authorities that it trusts. If your registry has a certificate that was issued by a well-known certificate authority, then you should not need to do anything for Smart Check to trust your registry. If the registry certificate was issued by a private certificate authority, you can upload the certificate authority's certificate (.pem file).
  9. If Start scan when registry is created is selected, a scan starts as soon as you click Create Registry.
  10. If Perform scan periodically is selected, Smart Check automatically performs a scan every day at midnight UTC.
  11. Click + ADD FILTER to include or exclude images based on any segment of their fully qualified name in the form <repository>/<image>:<tag>. For example, the include filter *latest* would match smartcheck/scan:latest and smartcheck/auth:latest. The default include filter of * will select all images in the registry.
  12. Click CREATE REGISTRY.

To edit a registry, go to the Registries page, click the registry, and then click Edit icon.

To refresh the list of images in a registry, go to the Registries page, click the registry, and then click Sync icon.

Start a scan

When Smart Check receives a scan request, it pulls the image(s) specified in the registry being scanned, unpacks each layer, and inspects the content for malware, vulnerabilities, secrets and keys, and compliance problems.

There are several ways that a scan can be triggered:

Manually start a scan

  1. In the Registries section of the Dashboard icon Dashboard page or on the Registries icon Registries page, click the name of the registry that you want to scan.
  2. Click Scan now icon.
  3. A confirmation message appears. Click OK.

To confirm that scans are running, on the left side of the Smart Check administrator console, click Scans icon Scans. Running scans have a spinning icon next to them.

See scan results

There are several ways to get scan results:

Add custom content rules

Deep Security Smart Check ships with a built-in collection of rules that detect some common items that should never be included in images. You can also write your own rules, using the YARA language. For information on writing rules, see Create custom content rules in the Smart Check wiki.

Individual rules are bundled into rulesets, and rulesets are grouped in collections. Deep Security Smart Check can have only one active collection at a time, so you can either add new rulesets to the default Deep Security Smart Check Collection, or create a new collection to use instead. Within a collection, you can enable or disable individual rulesets.

You can use the API or the UI to manage collections and rulesets. The UI is described in the following sections.

Create a new content ruleset collection

If you don't want to use the built-in Deep Security Smart Check Collection, you can make your own collection.

  1. On the left side of the Smart Check administrator console, click Content rule icon Content Rules.
  2. On the Content Rules page, click + CREATE
  3. In the pop-up that appears, enter a name for the new collection and click ADD. A new, empty ruleset collection appears on the Content Rules page.
  4. Add some rulesets to the collection, and enable those rulesets
  5. When you're ready to being using the new collection, click Activate icon to activate the collection. This also deactivates any other collections.

Change the name of a content ruleset collection

  1. On the Content Rules page, click Edit icon for the ruleset collection that you want to rename.
  2. In the pop-up that appears, edit the name and click UPDATE.

Add rulesets to a collection

  1. On Content Rules page, click Add icon in the ruleset collection where you want to add the ruleset.
  2. In the pop-up that appears:
    1. Enter a name for the ruleset.
    2. The ruleset is enabled by default, or you can slide the toggle to disable it.
    3. Add the rule files by dragging and dropping them or clicking in the area provided. Files can be a maximum of 8 KB.
    4. Click ADD.

Access the API documentation

Everything you can do in the Smart Check administrator console (and more) is available as an API operation. You can use the API and web hooks to integrate Deep Security Smart Check with a variety of other products.

You can find the API documentation in the Smart Check administrator console. On the left side of the console, click API icon API Documentation.

Or go to https://deep-security.github.io/smartcheck-docs/api/index.html.

Frequently asked questions

Does Smart Check only find vulnerabilities in packages that are installed with a package manager?

Smart Check scans both the installed package list as well as a set of applications commonly installed by copying them directly to the file system. Our labs team provides an active feed with up-to-date information about the supported applications.

Does Smart Check get automatic security updates, or do I need to upgrade to get security updates?

Deep Security Smart Check updates its malware details and vulnerability definitions automatically. You will need to upgrade to get software updates, including new feature and security updates.

How do I scan images before they reach my production registry?

See Configure pre registry scanning in the Smart Check wiki for instructions.

How do I override a vulnerability or content scan finding (CVE whitelisting)?

If a scan finds a vulnerability or content scan issue but you know it's not a concern, you can override it using the Smart Check API. For details, see the Overrides section of the API.

How do I check whether images meet common PCI-DSS compliance requirements?

You can use the checklist feature in the Smart Check API to verify whether a scanned image complies with common PCI requirements. The checklist feature is currently supported for CentOS and Red Hat images only. For details, see the Scans section of the API.

How do I use an external database with Smart Check?

By default, Deep Security Smart Check configures a database pod in your Kubernetes cluster. This is convenient for demonstration purposes, but for production you should use an external database. For instructions, see Use an external database in the Smart Check wiki.

How do I replace the self-signed Smart Check service certificate?

See Replace the service certificate in the Smart Check wiki for instructions.

How do I secure Smart Check web hooks?

See Secure web hooks in the Smart Check wiki for instructions.

I'm locked out! How do I recover my administrator account?

See Recreate an administrator user in the Smart Check wiki for instructions.