Minimal changes to trust/trust_sandbox docs #13912

IAL32 · 2021-11-30T19:04:04Z

Proposed changes

The current Docker Content Trust sandbox documentation "Play in a content trust sandbox" is WAY out of date.

There have been some PRs that address this problem, like PR#10078, but I felt like they were adding too much complexity to the system, or they were not working at all.

Here I propose a minimal amount of changes needed for the documentation to still be relevant, without any major changes to the page's content.

Related issues

Fixes #12192
Fixes #11539

Feedback is nevertheless much appreciated!

netlify · 2021-11-30T19:07:34Z

✅ Deploy Preview for docsdocker ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`b09d743`
🔍 Latest deploy log	https://app.netlify.com/sites/docsdocker/deploys/6305ecbc25a99000095c3686
😎 Deploy Preview	https://deploy-preview-13912--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

thirdgen88 · 2022-01-12T20:09:25Z

Thank you for this proposal, it was helpful for massaging the documented trust sandbox environment to a workable state. I have a couple points of feedback:

It looks like bash isn't available in the later registry:2.7 images, probably need suggest the same sh in the exec against sandboxregistry as is done for trustsandbox. (ref: step 2 of Test with malicious images)
I don't think we need the port publishes added, as the guide is designed to be conducted from within trustsandbox.

IAL32 · 2022-01-13T16:15:15Z

Thank you @thirdgen88 for the answer!

It looks like bash isn't available in the later registry:2.7 images, probably need suggest the same sh in the exec against sandboxregistry as is done for trustsandbox. (ref: step 2 of Test with malicious images)

I don't think we need the port publishes added, as the guide is designed to be conducted from within trustsandbox.

True! I will change these in a future commit. Thanks!

usha-mandya · 2022-02-11T10:44:54Z

@thaJeztah Could you PTAL?

usha-mandya · 2022-02-24T14:25:50Z

Close and reopen the PR to trigger CI checks

IAL32 · 2022-04-24T07:43:28Z

Any updates on the pr status?

matletix · 2022-08-14T23:54:36Z

@IAL32 Thank you ! You can also remove the port mapping for the server service (4443:4443)

matletix · 2022-08-23T20:00:32Z

Also the following command (here)

docker container exec -it sandboxregistry bash

should be :

docker container exec -it sandboxregistry sh

IAL32 · 2022-08-24T09:16:24Z

@matletix I have addressed these issues now 😄

The current Docker Content Trust sandbox documentation ["Play in a content trust sandbox"](https://docs.docker.com/engine/security/trust/trust_sandbox/) is WAY out of date. There have been some PRs that address this problem, like [PR#10078](docker#10078), but I felt like they were adding too much complexity to the system, or they were not working at all. Here I propose a minimal amount of changes needed for the documentation to still be relevant, without any major changes to the page's content. Feedback is nevertheless much appreciated!

Changed from `bash` to `sh`, as registry:2.7 does not have bash

dockertopia

@IAL32 thanks for this suggestion, I'll be reviewing this with the team.

glours

LGTM
Just few nit to address before merging.
The example works as expected, if @justincormack or @thaJeztah could double check as I'm not an expert of notarisation and registries 😅

engine/security/trust/trust_sandbox.md

netlify · 2022-10-20T13:13:19Z

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	`ff6e04a`
🔍 Latest deploy log	https://app.netlify.com/sites/docsdocker/deploys/638733bdd546a70009f79902
😎 Deploy Preview	https://deploy-preview-13912--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

glours

👍

thaJeztah · 2022-10-20T14:40:11Z

Looks like I started a review a long time ago, but never submitted (I may have been looking at the technical side of Notary); let me submit the review, but have a look if all comments (still) make sense 😅

engine/security/trust/trust_sandbox.md

IAL32 · 2022-10-20T15:53:30Z

I have implemented many of the changes from @thaJeztah , thanks!
I have also updated some of the outputs.

let me know! 😄

docker-robott · 2022-11-26T01:00:14Z

Thanks for the pull request. We'd like to make our product docs better, but haven’t been able to review all the suggestions.
As our docs have also diverged, we do not have the bandwidth to review and rebase old pull requests.

If the updates are still relevant, review our contribution guidelines and rebase your pull request against the latest version of the docs, then mark it as fresh with a /remove-lifecycle stale comment.
If not, this pull request will be closed in 30 days. This helps our maintainers focus on the active pull requests.

Prevent pull requests from auto-closing with a /lifecycle frozen comment.

/lifecycle stale

IAL32 · 2022-11-30T10:43:28Z

/remove-lifecycle stale

usha-mandya · 2022-11-30T11:24:44Z

@thaJeztah could you PTAL?

IAL32 · 2022-12-12T21:03:17Z

Any updates? Belated happy 1 year for my PR 🥳 @thaJeztah @usha-mandya @glours

thaJeztah

Sorry for the long delay (again). I had to get my head around some of the examples.

See my comments; looks like there's a very odd example on this page, that doesn't relate to Docker Content Trust at all. 🤔 🙈 🤷‍♂️

I did a quick update of the compose file (removing bits we don't need, and added the DOCKER_CONTENT_TRUST_SERVER env-var);

services:
  notaryserver:
    image: notary:server-0.7.0
    networks:
      - sandbox
    depends_on:
      - notarysigner
    volumes:
      - ./notary/fixtures:/fixtures/
    command: |-
      sh -c "notary-server -config=/fixtures/server-config-local.json"

  notarysigner:
    image: notary:signer-0.7.0
    networks:
      - sandbox
    volumes:
      - ./notary/fixtures:/fixtures/
    command: |-
      sh -c "notary-signer -config=/fixtures/signer-config-local.json"

  trustsandbox:
    image: docker:23.0-dind
    networks:
      - sandbox
    volumes:
      - ./notary/fixtures:/fixtures/
    privileged: true
    environment:
      # configure the sandbox to use our local notary server if content trust is enabled.
      - DOCKER_CONTENT_TRUST_SERVER=https://notaryserver:4443
    entrypoint: ""
    command: |-
        sh -c '
            cp /fixtures/root-ca.crt /usr/local/share/ca-certificates/root-ca.crt &&
            update-ca-certificates &&
            dockerd-entrypoint.sh --insecure-registry sandboxregistry:5000'

  sandboxregistry:
    image: registry:2
    networks:
      - sandbox

networks:
  sandbox:
    external: false

I didn't have time yet to rewrite the examples with my comments in place, but with the above, the steps would be to;

Clone the git repo, and create the compose-file, then run it:

docker compose up -d

Open an exec into the trustsandbox:

docker compose exec trustsandbox sh

Pull an image (I replaced the docker/trusttest image, because it looks like that hadn't been updated for a long time, and was still using the "v1" schema, and hello-world is smaller);

docker pull hello-world
Using default tag: latest
latest: Pulling from library/hello-world
7050e35b49f5: Pull complete
Digest: sha256:ffb13da98453e0f04d33a6eee5bb8e46ee50d08ebe17735fc0779d0349e889e9
Status: Downloaded newer image for hello-world:latest
docker.io/library/hello-world:latest

Tag the image under two names ("unsigned" and "signed");

docker tag hello-world sandboxregistry:5000/test/trusttest:unsigned
docker tag hello-world sandboxregistry:5000/test/trusttest:signed

Push the "unsigned" image: this image is pushed without Docker Content Trust enabled (so won't be signed);

$ docker push sandboxregistry:5000/test/trusttest:unsigned
The push refers to repository [sandboxregistry:5000/test/trusttest]
efb53921da33: Pushed
unsigned: digest: sha256:432f982638b3aefab73cc58ab28f5c16e96fdb504e8c134fc58dff4bae8bf338 size: 525

Enable Docker Content Trust (DOCKER_CONTENT_TRUST=1) and push the "signed" image. (Set up passwords)

$ export DOCKER_CONTENT_TRUST=1
$ docker push sandboxregistry:5000/test/trusttest:signed

The push refers to repository [sandboxregistry:5000/test/trusttest]
efb53921da33: Layer already exists
signed: digest: sha256:432f982638b3aefab73cc58ab28f5c16e96fdb504e8c134fc58dff4bae8bf338 size: 525
Signing and pushing trust metadata
You are about to create a new root signing key passphrase. This passphrase
will be used to protect the most sensitive key in your signing system. Please
choose a long, complex passphrase and be careful to keep the password and the
key file itself secure and backed up. It is highly recommended that you use a
password manager to generate the passphrase and keep it safe. There will be no
way to recover this key. You can find the key in your config directory.
Enter passphrase for new root key with ID a3cc84a:
Repeat passphrase for new root key with ID a3cc84a:
Enter passphrase for new repository key with ID 94622b9:
Repeat passphrase for new repository key with ID 94622b9:
Finished initializing "sandboxregistry:5000/test/trusttest"
Successfully signed sandboxregistry:5000/test/trusttest:signed

Remove the local images

docker image prune -af
Deleted Images:
untagged: hello-world:latest
untagged: hello-world@sha256:ffb13da98453e0f04d33a6eee5bb8e46ee50d08ebe17735fc0779d0349e889e9
untagged: sandboxregistry:5000/test/trusttest:signed
untagged: sandboxregistry:5000/test/trusttest:unsigned
untagged: sandboxregistry:5000/test/trusttest@sha256:432f982638b3aefab73cc58ab28f5c16e96fdb504e8c134fc58dff4bae8bf338
deleted: sha256:46331d942d6350436f64e614d75725f6de3bb5c63e266e236e04389820a234c4
deleted: sha256:efb53921da3394806160641b72a2cbd34ca1a9a8345ac670a85a04ad3d0e3507

Total reclaimed space: 9.136kB

Verify that the images were removed

$ docker image ls
REPOSITORY   TAG       IMAGE ID   CREATED   SIZE

With Docker Content Trust still enabled (DOCKER_CONTENT_TRUST=1), pull the signed image:

$ docker pull sandboxregistry:5000/test/trusttest:signed
Pull (1 of 1): sandboxregistry:5000/test/trusttest:signed@sha256:432f982638b3aefab73cc58ab28f5c16e96fdb504e8c134fc58dff4bae8bf338
sandboxregistry:5000/test/trusttest@sha256:432f982638b3aefab73cc58ab28f5c16e96fdb504e8c134fc58dff4bae8bf338: Pulling from test/trusttest
7050e35b49f5: Pull complete
Digest: sha256:432f982638b3aefab73cc58ab28f5c16e96fdb504e8c134fc58dff4bae8bf338
Status: Downloaded newer image for sandboxregistry:5000/test/trusttest@sha256:432f982638b3aefab73cc58ab28f5c16e96fdb504e8c134fc58dff4bae8bf338
Tagging sandboxregistry:5000/test/trusttest@sha256:432f982638b3aefab73cc58ab28f5c16e96fdb504e8c134fc58dff4bae8bf338 as sandboxregistry:5000/test/trusttest:signed
sandboxregistry:5000/test/trusttest:signed

Now try to pull the unsigned image: notice that pulling is blocked by Docker Content Trust, because it's not signed:

# docker pull sandboxregistry:5000/test/trusttest:unsigned
No valid trust data for unsigned

Disable content trust, and try pulling it again. This time pulling succeeds, because Docker Content Trust is disabled:

$ DOCKER_CONTENT_TRUST=0 docker pull sandboxregistry:5000/test/trusttest:unsigned
unsigned: Pulling from test/trusttest
Digest: sha256:432f982638b3aefab73cc58ab28f5c16e96fdb504e8c134fc58dff4bae8bf338
Status: Downloaded newer image for sandboxregistry:5000/test/trusttest:unsigned
sandboxregistry:5000/test/trusttest:unsigned

You can also inspect the trust information for both images. Notice that the unsigned image shows "No signatures for...";

$ docker trust inspect --pretty sandboxregistry:5000/test/trusttest:unsigned

No signatures for sandboxregistry:5000/test/trusttest:unsigned

Administrative keys for sandboxregistry:5000/test/trusttest:unsigned

  Repository Key:	94622b9baaa29e49cdde94e63d020f739bb3f00df0b4a647639ed6d9cd78897a
  Root Key:	58d6702e1dd9845c711f70219ebd2475403c1e44f7c665391d357f6c8d6af525

$ docker trust inspect --pretty sandboxregistry:5000/test/trusttest:signed

Signatures for sandboxregistry:5000/test/trusttest:signed

SIGNED TAG   DIGEST                                                             SIGNERS
signed       432f982638b3aefab73cc58ab28f5c16e96fdb504e8c134fc58dff4bae8bf338   (Repo Admin)

Administrative keys for sandboxregistry:5000/test/trusttest:signed

  Repository Key:	94622b9baaa29e49cdde94e63d020f739bb3f00df0b4a647639ed6d9cd78897a
  Root Key:	58d6702e1dd9845c711f70219ebd2475403c1e44f7c665391d357f6c8d6af525

thaJeztah · 2023-04-10T15:19:32Z

engine/security/trust/trust_sandbox.md

+    4f4fb700ef54: Pull complete 
+    error pulling image configuration: download failed after attempts=6: unexpected EOF
+    ```

-      The pull did not complete because the trust system couldn't verify the
-      image.
+    The pull did not complete because the trust system couldn't verify the
+    image.


Really curious now why this example was written in the first place (not your fault, because this example already existed). Because I don't think this is related to content trust in any way (it's just a malformed image).

In this case, docker content trust isn't even enabled (it was set in earlier steps with export, but that doesn't persist between docker (compose) exec sessions;

env | grep DOCKER DOCKER_VERSION=20.10.20 DOCKER_TLS_CERTDIR=/certs DOCKER_BUILDX_VERSION=0.9.1 DOCKER_COMPOSE_VERSION=2.12.2

I think this example can be fully replaced, because it does not relate to Docker Content Trust validation (validation elsewhere at most, but in this case it looks like the pull is just failing because there's no valid JSON)

thaJeztah · 2023-04-10T16:19:06Z

engine/security/trust/trust_sandbox.md

+        depends_on:
+          - notarysigner
+        volumes:
+          - ./notary:/notarydir


I think we would only need the fixtures directory from the repo (Ideally we should look at creating those files instead, but for now it's probably okay to take those fixtures from the notary repository).

thaJeztah · 2023-04-10T16:20:05Z

engine/security/trust/trust_sandbox.md

+          sh -c "/notarydir/migrations/migrate.sh &&
+          cd /notarydir/fixtures &&
+          notary-server -config=/notarydir/fixtures/server-config-local.json"


As this is a fresh install / sandbox, I guess we can omit the migrate.sh. We probably only need the notary-server line (specifying which config to use)

thaJeztah · 2023-04-10T16:20:35Z

engine/security/trust/trust_sandbox.md

+          - ./notary:/notarydir
+        command: |-
+          sh -c "/notarydir/migrations/migrate.sh &&
+          cd /notarydir/fixtures &&
+          notary-signer -config=/notarydir/fixtures/signer-config-local.json"


Same here (only needs the fixtures, and we can skip the migrate.sh)

thaJeztah · 2023-04-10T16:20:53Z

engine/security/trust/trust_sandbox.md

+          notary-signer -config=/notarydir/fixtures/signer-config-local.json"
+
+      trustsandbox:
+        image: docker:20.10.20-dind


We should probably update this to docker:23.0-dind now 🙈

thaJeztah · 2023-04-10T16:21:48Z

engine/security/trust/trust_sandbox.md

        volumes:
-          notarycerts:
-            external: false
+          - ./notary:/notary


This also only needs the fixtures (looks like the root-ca.crt is the only thing we use).

thaJeztah · 2023-04-10T16:22:50Z

engine/security/trust/trust_sandbox.md

+                dockerd-entrypoint.sh --insecure-registry sandboxregistry:5000'
+
+      sandboxregistry:
+        image: registry:2.8.1


Might be okay here to use registry:2 to get the latest minor+patch release of registry v2. For some cases, pinning to a "patch" release, but in this case we just need a registry for testing.

thaJeztah · 2023-04-10T16:26:07Z

engine/security/trust/trust_sandbox.md

+      trustsandbox:
+        image: docker:20.10.20-dind
+        networks:
+          - sandbox


To simplify the examples, we can set the DOCKER_CONTENT_TRUST_SERVER=https://notaryserver:4443. Then the example only has to enable/disable content trust DOCKER_CONTENT_TRUST=1)

thaJeztah · 2023-04-10T16:30:07Z

engine/security/trust/trust_sandbox.md

-        Digest: sha256:d149ab53f8718e987c3a3024bb8aa0e2caadf6c0328f1d9d850b2a2a67f2819a
-        Status: Downloaded newer image for docker/trusttest:latest
+    ```console
+    /# docker pull docker/trusttest


We should probably replace this with another image, because this image looks to be very old, and is still using the "v1" format (which is deprecated).

docker pull docker/trusttest Using default tag: latest latest: Pulling from docker/trusttest Image docker.io/docker/trusttest:latest uses outdated schema1 manifest format. Please upgrade to a schema2 image for better future compatibility. More information at https://docs.docker.com/registry/spec/deprecated-schema-v1/ aac0c133338d: Pull complete a3ed95caeb02: Pull complete Digest: sha256:50c0cdd0577cc7ab7c78e73a0a89650b222f6ce2b87d10130ecff055981b702f Status: Downloaded newer image for docker/trusttest:latest docker.io/docker/trusttest:latest

For the examples on this page, "any" image should do, so we could just use hello-world, which is small, and part of the Docker official images.

thaJeztah · 2023-04-10T16:39:34Z

I guess the malicious image section could still be useful in some form or another, but it's mostly to illustrate that Docker verifies the content when pulling (if the content's digest doesn't match it would reject the image)

docker-robot · 2023-07-09T01:00:02Z

Thanks for the pull request. We'd like to make our product docs better, but haven’t been able to review all the suggestions.
As our docs have also diverged, we do not have the bandwidth to review and rebase old pull requests.

If the updates are still relevant, review our contribution guidelines and rebase your pull request against the latest version of the docs, then mark it as fresh with a /remove-lifecycle stale comment.
If not, this pull request will be closed in 30 days. This helps our maintainers focus on the active pull requests.

Prevent pull requests from auto-closing with a /lifecycle frozen comment.

/lifecycle stale

usha-mandya added the area/engine Issue affects Docker engine/daemon label Dec 1, 2021

usha-mandya closed this Feb 24, 2022

usha-mandya reopened this Feb 24, 2022

matletix mentioned this pull request Aug 14, 2022

Trust sandbox are outdated and not working #11539

Open

IAL32 requested review from dockertopia and usha-mandya as code owners August 24, 2022 09:16

IAL32 and others added 3 commits August 24, 2022 11:17

Removed unnecessary port exposure

f2ec88d

Changed from `bash` to `sh`, as registry:2.7 does not have bash

Fixed a couple of things

b09d743

IAL32 force-pushed the patch-1 branch from 0875985 to b09d743 Compare August 24, 2022 09:17

dockertopia reviewed Sep 2, 2022

View reviewed changes

dockertopia added the status/2-tech review label Sep 2, 2022

usha-mandya requested a review from glours October 18, 2022 10:20

glours previously approved these changes Oct 20, 2022

View reviewed changes

Bumping version and suggestions from @glours

de6f51a

IAL32 dismissed glours’s stale review via de6f51a October 20, 2022 13:13

IAL32 requested review from glours and removed request for usha-mandya October 20, 2022 13:13

glours previously approved these changes Oct 20, 2022

View reviewed changes

thaJeztah reviewed Oct 20, 2022

View reviewed changes

Suggestions from @thaJeztah

81ad9e8

IAL32 dismissed glours’s stale review via 81ad9e8 October 20, 2022 15:51

IAL32 requested a review from thaJeztah October 20, 2022 15:51

IAL32 added 2 commits October 20, 2022 17:55

Last fix

09ef9d9

Using Notary v0.7.0

c713717

IAL32 requested a review from dvdksn as a code owner October 27, 2022 19:58

docker-robott added the lifecycle/stale label Nov 26, 2022

Merge branch 'master' into patch-1

ff6e04a

docker-robott removed the lifecycle/stale label Nov 30, 2022

usha-mandya requested a review from glours November 30, 2022 11:24

dvdksn removed the status/2-tech review label Dec 14, 2022

glours approved these changes Feb 27, 2023

View reviewed changes

thaJeztah requested changes Apr 10, 2023

View reviewed changes

docker-robot bot added the lifecycle/stale label Jul 9, 2023

thaJeztah added lifecycle/frozen and removed lifecycle/stale labels Jul 9, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Minimal changes to trust/trust_sandbox docs #13912

Minimal changes to trust/trust_sandbox docs #13912

IAL32 commented Nov 30, 2021 •

edited

Loading

netlify bot commented Nov 30, 2021 •

edited

Loading

thirdgen88 commented Jan 12, 2022 •

edited

Loading

IAL32 commented Jan 13, 2022

usha-mandya commented Feb 11, 2022

usha-mandya commented Feb 24, 2022

IAL32 commented Apr 24, 2022

matletix commented Aug 14, 2022

matletix commented Aug 23, 2022

IAL32 commented Aug 24, 2022

dockertopia left a comment

glours left a comment

netlify bot commented Oct 20, 2022 •

edited

Loading

glours left a comment

thaJeztah commented Oct 20, 2022

IAL32 commented Oct 20, 2022

docker-robott commented Nov 26, 2022

IAL32 commented Nov 30, 2022

usha-mandya commented Nov 30, 2022

IAL32 commented Dec 12, 2022

thaJeztah left a comment

thaJeztah Apr 10, 2023

thaJeztah Apr 10, 2023

thaJeztah Apr 10, 2023

thaJeztah Apr 10, 2023

thaJeztah Apr 10, 2023

thaJeztah Apr 10, 2023

thaJeztah Apr 10, 2023

thaJeztah Apr 10, 2023

thaJeztah Apr 10, 2023

thaJeztah commented Apr 10, 2023

docker-robot bot commented Jul 9, 2023

Minimal changes to trust/trust_sandbox docs #13912

Are you sure you want to change the base?

Minimal changes to trust/trust_sandbox docs #13912

Conversation

IAL32 commented Nov 30, 2021 • edited Loading

Proposed changes

Related issues

netlify bot commented Nov 30, 2021 • edited Loading

✅ Deploy Preview for docsdocker ready!

thirdgen88 commented Jan 12, 2022 • edited Loading

IAL32 commented Jan 13, 2022

usha-mandya commented Feb 11, 2022

usha-mandya commented Feb 24, 2022

IAL32 commented Apr 24, 2022

matletix commented Aug 14, 2022

matletix commented Aug 23, 2022

IAL32 commented Aug 24, 2022

dockertopia left a comment

Choose a reason for hiding this comment

glours left a comment

Choose a reason for hiding this comment

netlify bot commented Oct 20, 2022 • edited Loading

✅ Deploy Preview for docsdocker ready!

glours left a comment

Choose a reason for hiding this comment

thaJeztah commented Oct 20, 2022

IAL32 commented Oct 20, 2022

docker-robott commented Nov 26, 2022

IAL32 commented Nov 30, 2022

usha-mandya commented Nov 30, 2022

IAL32 commented Dec 12, 2022

thaJeztah left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thaJeztah commented Apr 10, 2023

docker-robot bot commented Jul 9, 2023

IAL32 commented Nov 30, 2021 •

edited

Loading

netlify bot commented Nov 30, 2021 •

edited

Loading

thirdgen88 commented Jan 12, 2022 •

edited

Loading

netlify bot commented Oct 20, 2022 •

edited

Loading