Set up security scanning in MSR¶
This page explains how to set up and enable Docker Security Scanning on an existing installation of Mirantis Secure Registry.
Prerequisites¶
These instructions assume that you have already installed Mirantis Secure Registry (MSR), and have access to an account on the MSR instance with administrator access.
Before you begin, make sure that you or your organization has purchased a MSR license that includes Docker Security Scanning, and that your Docker ID can access and download this license from the Docker Hub.
If you are using a license associated with an individual account, no
additional action is needed. If you are using a license associated with
an organization account, you may need to make sure your Docker ID is a
member of the Owners
team. Only Owners
team members can download
license files for an Organization.
If you will be allowing the Security Scanning database to update itself
automatically, make sure that the server hosting your MSR instance can
access both http://license.mirantis.com
and
https://dss-cve-updates.mirantis.com/
on the standard https port 443.
Get the security scanning license¶
If your MSR instance already has a license that includes Security Scanning, skip this section and proceed to Enable MSR security scanning.
Tip
To check if your existing MSR license includes scanning, navigate to the MSR Settings page, and click Security. If an Enable scannin toggle appears, the license includes scanning.
If your current MSR license doesn’t include scanning, you must first download the new license.
Search for an email from Mirantis Support with the subject Welcome to Mirantis’ CloudCare Portal, and follow the instructions for logging in.
If you did not receive the CloudCare Portal email, it is likely that you have not yet been added as a Designated Contact. To remedy this, contact your Designated Administrator.
Click Environments in the top navigation bar.
Click the Cloud Name associated with the license you want to download.
Scroll down to License Information and click the License File url. A new tab will open in your browser.
Click View file to download your license file.
Next, install the new license on the MSR instance.
Log in to your MSR instance using an administrator account.
Click Settings in the left-side navigation panel.
On the General tab click Apply new license.
A file browser dialog displays.
Navigate to where you saved the license key (
.lic
) file, select it, and click Open.
Enable MSR security scanning¶
To enable security scanning in MSR:
Log in to your MSR instance with an administrator account.
Click Settings in the left-side navigation panel.
Click the Security tab.
Click the Enable scanning toggle so that it turns blue and says “on”.
Next, provide a security database for the scanner. Security scanning will not function until MSR has a security database to use.
By default, security scanning is enabled in Online mode. In this mode, MSR attempts to download a security database from a Docker server. If your installation cannot access
https://dss-cve-updates.docker.com/
you must manually upload a.tar
file containing the security database.If you are using
Online
mode, the MSR instance will contact a Docker server, download the latest vulnerability database, and install it. Scanning can begin once this process completes.If you are using
Offline
mode, use the instructions in Update scanning database - offline mode to upload an initial security database.
By default when Security Scanning is enabled, new repositories will
automatically scan on docker push
. If you had existing repositories
before you enabled security scanning, you might want to change
repository scanning behavior.
Set repository scanning mode¶
Two modes are available when Security Scanning is enabled:
Scan on push & Scan manually
: the image is re-scanned on eachdocker push
to the repository, and whenever a user withwrite
access clicks the Start Scan links or Scan button.Scan manually
: the image is scanned only when a user withwrite
access clicks the Start Scan links or Scan button.
By default, new repositories are set to Scan on push & Scan manually
, but
you can change this setting during repository creation.
Any repositories that existed before scanning was enabled are set to
Scan manually
mode by default. If these repositories are still in
use, you can change this setting from each repository’s Settings
page.
Note
To change an individual repository scanning mode, you must have write
or admin
access to the repo.
To change an individual repository’s scanning mode:
Navigate to the repository, and click the Settings tab.
Scroll down to the Image scanning section.
Select the desired scanning mode.
Update the CVE scanning database¶
Docker Security Scanning indexes the components in your MSR images and compares them against a known CVE database. When new vulnerabilities are reported, Docker Security Scanning matches the components in new CVE reports to the indexed components in your images, and quickly generates an updated report.
Users with administrator access to MSR can check when the CVE database was last updated from the Security tab in the MSR Settings pages.
Update CVE database - online mode¶
By default Docker Security Scanning checks automatically for updates to the vulnerability database, and downloads them when available. If your installation does not have access to the public internet, use the Offline mode instructions below.
To ensure that MSR can access these updates, confirm that the host can reach
both http://license.mirantis.com
and
https://dss-cve-updates.mirantis.com/
on port 443 using https.
MSR checks for new CVE database updates at 3:00 AM UTC every day. If an update is found it is downloaded and applied without interrupting any scans in progress. Once the update is complete, the security scanning system looks for new vulnerabilities in the indexed components.
To set the update mode to Online:
Log in to MSR as a user with administrator rights.
Click Settings in the left-side navigation panel and click Security.
Click Online.
Your choice is saved automatically.
Note
MSR also checks for CVE database updates when scanning is first enabled, and when you switch update modes. If you need to check for a CVE database update immediately, you can briefly switch modes from online to offline and back again.
Update CVE database - offline mode¶
To update the CVE database for your MSR instance when connection to the update
server is not possible, download and install a .tar
file that contains
the database updates.
Downloading the CVE database¶
Run the following command to download the most recent CVE database:
Note
The example command specifies default values. It assumes that you want
the container to output the database file to ~/Downloads
and that the
volume should map from the local machine into the container. If the
destination for the database is in a separate directory, you must define
an additional volume.
docker run -it --rm \
-v ${HOME}/Downloads:/data \
-e CVE_DB_URL_ONLY=false \
-e CLOBBER_FILE=false \
-e DATABASE_OUTPUT="/data" \
-e DATABASE_SCHEMA=3 \
-e DEBUG=false \
-e VERSION_ONLY=false \
mirantis/get-dtr-cve-db:latest
Variable |
Default |
Override detail |
---|---|---|
CLOBBER_FILE |
|
Set to |
CVE_DB_URL_ONLY |
|
Set to |
DATABASE_OUTPUT |
|
Indicates the database download directory inside the container. |
DATABASE_SCHEMA |
|
|
DEBUG |
|
Set to |
VERSION_ONLY |
|
Set to |
Installing the CVE database¶
To manually update the MSR CVE database using the downloaded .tar
file:
Log in to MSR as a user with administrator rights.
Click Settings in the left-side navigation panel and click Security.
Click Upload .tar database file.
Browse to the latest
.tar
file that you received, and click Open.
MSR installs the new CVE database, and begins checking already indexed images for components that match new or updated vulnerabilities.
Note
The Upload button is unavailable while MSR applies CVE database updates.
Enable or disable automatic database updates¶
To change the update mode:
Log in to MSR as a user with administrator rights.
Click Settings in the left-side navigation panel and click Security.
Click Online/Offline.
Your choice is saved automatically.