mirror of https://github.com/docker/docs.git
admin and non-admin dtr scanning docs
Signed-off-by: LRubin <lrubin@docker.com>
This commit is contained in:
LRubin
Joao Fernandes
parent
2ecac649b8
commit
4b2db2b1be
|
|
@ -5,4 +5,8 @@ title: Configure optional DTR features
|
|||
---
|
||||
|
||||
|
||||
Foo bar baz
|
||||
The topics in this section explain how to configure optional features of Docker
|
||||
Trusted Registry. Some of these features, for example LDAP authentication, might
|
||||
be required for the installation to work correctly in _your_ environment, but are not required for basic installation.
|
||||
|
||||
<!-- TODO: add topic list -->
|
||||
|
|
|
|||
|
|
@ -0,0 +1,170 @@
|
|||
---
|
||||
description: Enable and configure Docker Security Scanning for Docker Trusted Registry.
|
||||
keywords: docker, registry, high-availability, backup, recovery
|
||||
title: Set up Security Scanning in DTR
|
||||
---
|
||||
|
||||
This page explains how to set up and enable Docker Security Scanning on an existing installation of Docker Trusted Registry. If you have not yet installed Docker Trusted Registry, you can find the installation guide [here](../install/).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
These instructions assume that you have already installed Docker Trusted
|
||||
Registry, and have access to an account on the DTR instance with `administrator`
|
||||
credentials.
|
||||
|
||||
Before you begin, make sure that you or your organization has purchased a DTR
|
||||
license that includes Docker Security Scanning, and that your Docker ID can
|
||||
access and download this license from the Docker Store.
|
||||
|
||||
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 module to update itself
|
||||
automatically, make sure that the server hosting your DTR instance can access
|
||||
`https://dss-cve-updates.docker.com/` on the standard https port 443.
|
||||
|
||||
## Get the security scanning license.
|
||||
|
||||
If your DTR instance already has a license that includes Security Scanning, skip
|
||||
this step and proceed to [enable DTR Security Scanning](#enable-dtr-security-scanning).
|
||||
|
||||
> **Tip**: To check if your existing DTR license includes scanning, navigate to the DTR **Settings** page, and click **Security**. If an "Enable scanning" toggle appears, the license includes scanning.
|
||||
|
||||
If your current DTR license doesn't include scanning, you must first download the new license.
|
||||
|
||||
1. Log in to the Docker Store using a Docker ID with access to the license you need.
|
||||
2. In the top right corner, click your user account icon, and select **Subscriptions**.
|
||||
3. If necessary, select an organization account from the **Accounts** menu at the upper right.
|
||||
4. Locate Docker Datacenter in the **Subscriptions** list.
|
||||
5. Click **Subscription Details** and select **Setup instructions**.
|
||||
6. Click **License key** below the Docker Datacenter logo.
|
||||
The license key (a `.lic` file) is downloaded to your local computer.
|
||||
|
||||
Next, install the new license on the DTR instance.
|
||||
|
||||
7. Log in to your DTR instance using an administrator account.
|
||||
8. Click **Settings** in the left navigation.
|
||||
9. On the **General** tab click **Apply new license**.
|
||||
|
||||
A file browser dialog appears.
|
||||
|
||||
10. Navigate to where you saved the license key (`.lic`) file, select it, and click **Open**.
|
||||
|
||||
Proceed to [enable DTR Security Scanning](#enable-dtr-security-scanning).
|
||||
|
||||
## Enable DTR security scanning
|
||||
|
||||
To enable security scanning in DTR:
|
||||
|
||||
1. Log in to your DTR instance with an administrator account.
|
||||
2. Click **Settings** in the left navigation.
|
||||
3. Click the **Security** tab.
|
||||
|
||||
> **Note**: If you see a message on this tab telling you to contact your Docker sales representative, then the license installed on this DTR instance does not include Docker Security Scanning. Check that you have purchased Security Scanning, and that the DTR instance is using the latest license file.
|
||||
|
||||
4. Click the **Enable scanning** toggle so that it turns blue and says "on".
|
||||
5. Next, provide a security database for the scanner. **Security scanning will not function until DTR has a security database to use.**
|
||||
|
||||
By default, security scanning is enabled in **Online** mode. In this mode,
|
||||
DTR 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 DTR instance will contact a Docker server, download the latest vulnerability database, and install it. Scanning can begin once this process completes.<!--(TODO: no completion or confirmation message?) -->
|
||||
- If you are using `Offline` mode, use the instructions in [Update scanning database - offline mode](#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).
|
||||
|
||||
## Set repository scanning mode
|
||||
|
||||
Two modes are available when Security Scanning is enabled:
|
||||
|
||||
- `Scan on push & Scan manually`: the image is re-scanned on each `docker push` to the repository, and whenever a user with `write` access clicks the **Start Scan** links or **Scan** button.
|
||||
- `Scan manually`: the image is scanned only when a user with `write` access clicks the **Start Scan** links or **Scan** button.
|
||||
|
||||
**New** repositories are set to `Scan on push & Scan manually` by default, 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. You can change this setting from the repository
|
||||
settings if the repositories are still in use.
|
||||
|
||||
> **Note**: To change an individual repository's scanning mode, you must have
|
||||
`write` or `administrator` access to the repo.
|
||||
|
||||
To change the repository scanning mode:
|
||||
|
||||
1. Navigate to the repository, and click the **Settings** tab.
|
||||
2. Scroll down to the **Image scanning** section.
|
||||
3. Select the desired scanning mode.
|
||||
|
||||
## Update the CVE scanning database
|
||||
|
||||
Docker Security Scanning indexes the components in your DTR 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 DTR can check when the CVE database was last updated from the **Security** tab in the DTR **Settings** pages.
|
||||
|
||||
### Update scanning 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](TODO).
|
||||
|
||||
To ensure that DTR can access these updates, make sure that the host can reach
|
||||
`https://dss-cve-updates.docker.com/` on port 443 using https.
|
||||
|
||||
DTR 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:
|
||||
|
||||
1. Log in to DTR as a user with administrator rights.
|
||||
2. Click **Settings** in the left navigation and click **Security**.
|
||||
3. Click **Online**.
|
||||
|
||||
Your choice is saved automatically.
|
||||
|
||||
> **Tip**: DTR 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 scanning database - offline mode
|
||||
|
||||
To update the CVE database for your DTR instance when it cannot contact the update server you will download and install a `.tar` file. This file contains the database updates. Contact your Docker Support representative for an updated database file.
|
||||
|
||||
<!-- TODO: update when Store updates available.
|
||||
1. Log in to the Docker Store.
|
||||
|
||||
If you are a member of an Organization managing licenses using Docker Store,
|
||||
make sure your account is a member of the `Owners` team. Only Owners can
|
||||
view and manage licenses and other entitlements for Organizations from the
|
||||
Docker Store.
|
||||
|
||||
2. In the top right corner, click your user account icon, and select **Subscriptions**.
|
||||
3. If necessary, select an organization account from the **Accounts** menu at the upper right.
|
||||
4. Locate Docker Datacenter in the **Subscriptions** list.
|
||||
5. Click ...-->
|
||||
|
||||
To manually update the DTR CVE database from a `.tar` file:
|
||||
|
||||
1. Log in to DTR as a user with administrator rights.
|
||||
2. Click **Settings** in the left navigation and click **Security**.
|
||||
4. Click **Upload .tar database file**.
|
||||
5. Browse to the latest `.tar` file that you received, and click **Open**.
|
||||
|
||||
DTR installs the new CVE database, and begins checking already indexed images
|
||||
for components that match new or updated vulnerabilities.
|
||||
|
||||
## Enable or disable automatic database updates
|
||||
|
||||
To change the update mode:
|
||||
|
||||
1. Log in to DTR as a user with administrator rights.
|
||||
2. Click **Settings** in the left navigation and click **Security**.
|
||||
3. Click **Offline**.
|
||||
|
||||
Your choice is saved automatically.
|
||||
|
|
@ -10,7 +10,7 @@ High availability in DTR depends on having overlay networking working in UCP.
|
|||
To manually test that overlay networking is working in UCP run the following
|
||||
commands on two different UCP machines.
|
||||
|
||||
```
|
||||
```none
|
||||
docker run -it --rm --net dtr-ol --name overlay-test1 --entrypoint sh docker/dtr
|
||||
docker run -it --rm --net dtr-ol --name overlay-test2 --entrypoint ping docker/dtr -c 3 overlay-test1
|
||||
```
|
||||
|
|
|
|||
|
|
@ -0,0 +1,134 @@
|
|||
---
|
||||
description: Docker Security Scanning for Docker Trusted Registry.
|
||||
keywords: docker, registry, high-availability, backup, recovery
|
||||
title: Docker Security Scanning in DTR
|
||||
---
|
||||
|
||||
Docker Trusted Registry can scan images in your repositories to verify that they
|
||||
are free from known security vulnerabilities or exposures, using Docker Security
|
||||
Scanning. The results of these scans are reported for each image tag.
|
||||
|
||||
Docker Security Scanning is available as an add-on to Docker Trusted Registry,
|
||||
and an administrator configures it for your DTR instance. If you do not see
|
||||
security scan results available on your repositories, your organization may not
|
||||
have purchased the Security Scanning feature or it may be disabled.
|
||||
|
||||
> **Tip**: Only users with write access to a repository can manually start a scan. Users with read-only access can view the scan results, but cannot start a new scan.
|
||||
|
||||
## Security scan on push
|
||||
|
||||
By default, Docker Security Scanning runs automatically on `docker push` to an
|
||||
image repository.
|
||||
|
||||
If your DTR instance is configured in this way, you do not need to do anything
|
||||
once your `docker push` completes. The scan runs automatically, and the results
|
||||
are reported in the repository's **Images** tab after the scan finishes.
|
||||
|
||||
## Manual scanning
|
||||
|
||||
If your administrator enabled Docker Security Scanning but disabled automatic
|
||||
scanning, you can manually start a scan for images in repositories to which you
|
||||
have `write` access.
|
||||
|
||||
To start a security scan:
|
||||
|
||||
1. Navigate to the repository.
|
||||
2. Click the **Images** tab.
|
||||
3. Locate the image tag that you want to scan.
|
||||
3. In the **Vulnerabilities** column, click **Start a scan**.
|
||||
|
||||
DTR begins the scanning process. You may need to refresh the page to see the results once the scan is complete.
|
||||
|
||||
## Change the scanning mode
|
||||
|
||||
You can change the scanning mode for each individual repository at any time. You
|
||||
might want to disable scanning if you are pushing an image repeatedly during
|
||||
troubleshooting and don't want to waste resources scanning and re-scanning, or
|
||||
if a repository contains legacy code that is not used or updated frequently.
|
||||
|
||||
> **Note**: To change an individual repository's scanning mode, you must have
|
||||
`write` or `administrator` access to the repo.
|
||||
|
||||
To change the repository scanning mode:
|
||||
|
||||
1. Navigate to the repository, and click the **Settings** tab.
|
||||
2. Scroll down to the **Image scanning** section.
|
||||
3. Select the desired scanning mode.
|
||||
|
||||
## View security scan results
|
||||
|
||||
Once DTR has run a security scan for an image, you can view the results.
|
||||
|
||||
The **Images** tab for each repository includes a summary of the most recent
|
||||
scan results for each image.
|
||||
|
||||
- A green shield icon with a check mark indicates that the scan did not find any vulnerabilities.
|
||||
- A red or orange shield icon indicates that vulnerabilities were found, and the number of vulnerabilities is included on that same line.
|
||||
|
||||
From the **Images** tab you can click **View details** for a specific tag to see
|
||||
the full scan results. The top of the page also includes metadata about the
|
||||
image, including the SHA, image size, date last pushed and user who last pushed,
|
||||
the security scan summary, and the security scan progress.
|
||||
|
||||
The scan results for each image include two different modes so you can quickly
|
||||
view details about the image, its components, and any vulnerabilities found.
|
||||
|
||||
- The **Layers** view lists the layers of the image in order as they are built
|
||||
by the Dockerfile.
|
||||
|
||||
This view can help you find exactly which command in the build introduced
|
||||
the vulnerabilities, and which components are associated with that single
|
||||
command. Click a layer to see a summary of its components. You can then
|
||||
click on a component to switch to the Component view and get more details
|
||||
about the specific item.
|
||||
|
||||
> **Tip**: The layers view can be long, so be sure
|
||||
to scroll down if you don't immediately see the reported vulnerabilities.
|
||||
|
||||
- The **Components** view lists the individual component libraries indexed by the scanning system, in order of severity and number of vulnerabilities found, most vulnerable first.
|
||||
|
||||
Click on an individual component to view details about the vulnerability it
|
||||
introduces, including a short summary and a link to the official CVE
|
||||
database report. A single component can have multiple vulnerabilities, and
|
||||
the scan report provides details on each one. The component details also
|
||||
include the license type used by the component, and the filepath to the
|
||||
component in the image.
|
||||
|
||||
### What do I do next?
|
||||
|
||||
If you find that an image in your registry contains vulnerable components, you
|
||||
can use the linked CVE scan information in each scan report to evaluate the
|
||||
vulnerability and decide what to do.
|
||||
|
||||
If you discover vulnerable components, you should check if there is an updated
|
||||
version available where the security vulnerability has been addressed. If
|
||||
necessary, you might contact the component's maintainers to ensure that the
|
||||
vulnerability is being addressed in an a future version or patch update.
|
||||
|
||||
If the vulnerability is in a `base layer` (such as an operating system) you
|
||||
might not be able to correct the issue in the image. In this case, you might
|
||||
switch to a different version of the base layer, or you might find an
|
||||
equivalent, less vulnerable base layer. You might also decide that the
|
||||
vulnerability or exposure is acceptable.
|
||||
|
||||
Address vulnerabilities in your repositories by updating the images to use
|
||||
updated and corrected versions of vulnerable components, or by using a different
|
||||
components that provide the same functionality. When you have updated the source
|
||||
code, run a build to create a new image, tag the image, and push the updated
|
||||
image to your DTR instance. You can then re-scan the image to confirm that you
|
||||
have addressed the vulnerabilities.
|
||||
|
||||
## The Docker Security Scan process
|
||||
|
||||
Scans run either on demand when a user clicks the **Start Scan** links or **Scan** button, or automatically on any `docker push` to the repository.
|
||||
|
||||
Most scans complete within an hour, however larger repositories may take longer
|
||||
to scan depending on your system resources. The scan traverses each layer of the
|
||||
image, identifies the software components in each layer, and indexes the SHA of
|
||||
each component.
|
||||
|
||||
The scan compares the SHA of each component against the Common Vulnerabilities
|
||||
and Exposures (CVE®) database installed on your DTR instance. The CVE database
|
||||
is a "dictionary" of known information security vulnerabilities. When the CVE
|
||||
database is updated, the service reviews the indexed components for any that
|
||||
match newly discovered vulnerabilities.
|
||||
Loading…
Reference in New Issue