Skip to content

Commit

Permalink
docs: update all documentation (project-copacetic#688)
Browse files Browse the repository at this point in the history 
Signed-off-by: ashnamehrotra <[email protected]>
  • Loading branch information
@ashnamehrotra
ashnamehrotra authored Jul 5, 2024
1 parent 9d5c9cc commit b1df0e9
Showing 1 changed file with 77 additions and 86 deletions.
163 changes: 77 additions & 86 deletions website/docs/quick-start.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Quick Start
---

This sample illustrates how to patch containers using vulnerability reports with `copa`.
This guide illustrates how to patch outdated containers with `copa`.

## Prerequisites

Expand All @@ -12,32 +12,13 @@ This sample illustrates how to patch containers using vulnerability reports with
* The `docker` daemon runs a buildkit service in-process. If you are using this for your buildkit instance, Docker must have the [containerd image store feature](https://docs.docker.com/storage/containerd/) enabled.
* If you are using a buildx instance, or using buildkitd directly, there is no need to enable the containerd image store. However, only images in a remote registry can be patched using these methods.
* [docker](https://docs.docker.com/desktop/linux/install/#generic-installation-steps) daemon running and CLI installed & pathed.
* [trivy CLI](https://aquasecurity.github.io/trivy/latest/getting-started/installation/) installed & pathed.
* Alternatively, see [scanner plugins](#scanner-plugins) for custom scanner support.
* Optional:
* [trivy CLI](https://aquasecurity.github.io/trivy/latest/getting-started/installation/) installed & pathed.
* Alternatively, see [scanner plugins](#scanner-plugins) for custom scanner support.

## Sample Steps
Copa can patch images in two ways:
- Update only vulnerable packages as detected by a supported scanner report.
- Update all outdated packages in a container, regardless of vulnerability status.

:::note
The update all functionality allows you to address discrepancies that may arise between scanners and the packages they flag as vulnerable. It is important to note, however, that some upgrades can introduce dependency or compatibility conflicts.
:::

### Patch with scanner report:
1. Scan the container image for patchable OS vulnerabilities, outputting the results to a JSON file:

```bash
trivy image --vuln-type os --ignore-unfixed -f json -o nginx.1.21.6.json docker.io/library/nginx:1.21.6
```

You can also see the existing patchable vulnerabilities in table form on the shell with:

```bash
trivy image --vuln-type os --ignore-unfixed docker.io/library/nginx:1.21.6
```

2. To patch the image, use the Trivy report and specify a buildkit instance to connect to:
1. Before patching your image, specify a buildkit instance to connect to:

By default copa will attempt to auto-connect to an instance in order:
1. Default docker buildkit endpoint (requires at least docker v24.0 with [containerd image store](https://docs.docker.com/storage/containerd/#enable-containerd-image-store-on-docker-engine) support enabled)
Expand All @@ -46,38 +27,95 @@ The update all functionality allows you to address discrepancies that may arise

If an instance doesn't exist or that instance doesn't support all the features copa needs the next will be attempted. Please see [custom buildkit addresses](custom-address.md) for more information.

After setting up the buildkit instance, run the following command to patch the image:

```bash
copa patch -r nginx.1.21.6.json -i docker.io/library/nginx:1.21.6
```

If you want to patch an image using the digest, run the following command instead:
3.
2. Scan the container image to check for patchable OS vulnerabilities:
```bash
copa patch -r nginx.1.21.6.json -i docker.io/library/nginx:1.21.6@sha256:25dedae0aceb6b4fe5837a0acbacc6580453717f126a095aa05a3c6fcea14dd4
$ export IMAGE=docker.io/library/nginx:1.21.6
$ trivy image --vuln-type os --ignore-unfixed $IMAGE
nginx:1.21.6 (debian 11.3)
==========================
Total: 207 (UNKNOWN: 0, LOW: 12, MEDIUM: 104, HIGH: 76, CRITICAL: 15)
...
```

In any of these cases, `copa` is non-destructive and exports a new image with the specified `1.21.6-patched` label to the local Docker daemon.
3. Patch the supplied image with Copa:

1. Update all outdated packages
By default, Copa will update all outdated packages in an image to the latest available versions.
:::note
Upgrading all packages may introduce compatibility issues or break existing functionality. Make sure to test the patched image to ensure stability.
:::

```bash
copa patch -i $IMAGE
```

:::tip
If you want to patch an image using the digest, run the following command instead:

```bash
export IMAGE=docker.io/library/nginx:1.21.6@sha256:25dedae0aceb6b4fe5837a0acbacc6580453717f126a095aa05a3c6fcea14dd4
copa patch -i $IMAGE
```
:::

2. Update only targeted packages
Alternatively, you can chose to have a targeted patching of your image by providing an optional vulnerability report. In the following commands, we are only updating packages marked vulnerable by Trivy:

2.1. Scan the container image for patchable OS vulnerabilities, outputting the results to a JSON file:
```bash
trivy image --vuln-type os --ignore-unfixed -f json -o $(basename $IMAGE).json $IMAGE
```

2.2. Supply the Trivy report as an additional argument to the Copa command to patch image.

```bash
copa patch -r $(basename $IMAGE).json -i $IMAGE
```

In both cases by default, Copa will produce a tag with a `-patched` suffix and export a new image with the specified `1.21.6-patched` label to the local Docker daemon.

:::note
If you're running this sample against an image from a private registry instead,ensure that the credentials are configured in the default Docker config.json before running `copa patch`, for example, via `docker login -u <user> -p <password> <registry>`.
:::
:::note
If you're scanning and patching an image that is local-only (i.e. built or tagged locally but not pushed to a registry), `copa` is limited to using `docker`'s built-in buildkit service, and must use the [`containerd image store`](https://docs.docker.com/storage/containerd/) feature. This is because only `docker`'s built-in buildkit service has access to the docker image store (see [Prerequisites](#prerequisites) for more information.)
If you're patching an image that is local-only (i.e. built or tagged locally but not pushed to a registry), `copa` is limited to using `docker`'s built-in buildkit service, and must use the [`containerd image store`](https://docs.docker.com/storage/containerd/) feature. This is because only `docker`'s built-in buildkit service has access to the docker image store (see [Prerequisites](#prerequisites) for more information.)
:::

4. Scan the patched image again and verify that the vulnerabilities have been patched:

3. Scan the patched image and verify that the vulnerabilities have been patched:
```bash
$ trivy image --vuln-type os --ignore-unfixed $IMAGE-patched
nginx:1.21.6-patched (debian 11.10)
===================================
Total: 0 (UNKNOWN: 0, LOW: 0, MEDIUM: 0, HIGH: 0, CRITICAL: 0)
```

5. Run the container to verify that the image has no regressions:

```bash
trivy image --vuln-type os --ignore-unfixed docker.io/library/nginx:1.21.6-patched
$ docker run -it --rm --name test $IMAGE-patched
/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
/docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh
10-listen-on-ipv6-by-default.sh: info: Getting the checksum of /etc/nginx/conf.d/default.conf
10-listen-on-ipv6-by-default.sh: info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf
/docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh
/docker-entrypoint.sh: Configuration complete; ready for start up
2024/01/22 23:32:54 [notice] 1#1: using the "epoll" event method
2024/01/22 23:32:54 [notice] 1#1: nginx/1.21.6
2024/01/22 23:32:54 [notice] 1#1: built by gcc 10.2.1 20210110 (Debian 10.2.1-6)
2024/01/22 23:32:54 [notice] 1#1: OS: Linux 6.2.0-1018-azure
2024/01/22 23:32:54 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1048576:1048576
2024/01/22 23:32:54 [notice] 1#1: start worker processes
```
You can stop the container by opening a new shell instance and running: `docker stop test`
You can also inspect the structure of the patched image with `docker history` to see the new patch layer appended to the image:
6. You can inspect the structure of the patched image with `docker history` to see the new patch layer appended to the image:
```bash
$ docker history docker.io/library/nginx:1.21.6-patched
$ docker history $IMAGE-patched
IMAGE CREATED CREATED BY SIZE COMMENT
262dacfeb193 About a minute ago mount / from exec sh -c apt install --no-ins… 41.1MB buildkit.exporter.image.v0
<missing> 20 months ago /bin/sh -c #(nop) CMD ["nginx" "-g" "daemon… 0B
Expand All @@ -96,50 +134,3 @@ The update all functionality allows you to address discrepancies that may arise
<missing> 20 months ago /bin/sh -c #(nop) CMD ["bash"] 0B
<missing> 20 months ago /bin/sh -c #(nop) ADD file:134f25aec8adf83cb… 91.8MB
```

4. Run the container to verify that the image has no regressions:

```bash
$ docker run -it --rm --name nginx-test docker.io/library/nginx:1.21.6-patched
/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
/docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh
10-listen-on-ipv6-by-default.sh: info: Getting the checksum of /etc/nginx/conf.d/default.conf
10-listen-on-ipv6-by-default.sh: info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf
/docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh
/docker-entrypoint.sh: Configuration complete; ready for start up
2024/01/22 23:32:54 [notice] 1#1: using the "epoll" event method
2024/01/22 23:32:54 [notice] 1#1: nginx/1.21.6
2024/01/22 23:32:54 [notice] 1#1: built by gcc 10.2.1 20210110 (Debian 10.2.1-6)
2024/01/22 23:32:54 [notice] 1#1: OS: Linux 6.2.0-1018-azure
2024/01/22 23:32:54 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1048576:1048576
2024/01/22 23:32:54 [notice] 1#1: start worker processes
```
You can stop the container by opening a new shell instance and running: `docker stop nginx-test`
### Patch all outdated packages:
1. Run Copa with a buildkit connection as described above, and omit the report flag:
```bash
copa patch -i docker.io/library/nginx:1.21.6
```
2. Run the container to verify that the image has no regressions:
```bash
$ docker run -it --rm --name nginx-test docker.io/library/nginx:1.21.6-patched
/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
/docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh
10-listen-on-ipv6-by-default.sh: info: Getting the checksum of /etc/nginx/conf.d/default.conf
10-listen-on-ipv6-by-default.sh: info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf
/docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh
/docker-entrypoint.sh: Configuration complete; ready for start up
2024/01/22 23:32:54 [notice] 1#1: using the "epoll" event method
2024/01/22 23:32:54 [notice] 1#1: nginx/1.21.6
2024/01/22 23:32:54 [notice] 1#1: built by gcc 10.2.1 20210110 (Debian 10.2.1-6)
2024/01/22 23:32:54 [notice] 1#1: OS: Linux 6.2.0-1018-azure
2024/01/22 23:32:54 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1048576:1048576
2024/01/22 23:32:54 [notice] 1#1: start worker processes
```
You can stop the container by opening a new shell instance and running: `docker stop nginx-test`

0 comments on commit b1df0e9

Please sign in to comment.