fix(docs): update docs on build secrets for legibility

coder · SasSwart · Nov 4, 2024 · Oct 31, 2024 · Oct 31, 2024 · Oct 31, 2024
commit 2fcd340c01430bd1eef4463dceb6b5270ef3817e
diff --git a/docs/build-secrets.md b/docs/build-secrets.md
@@ -19,17 +19,22 @@ Then, prepare the files to build our container.
 ```bash
 mkdir test-build-secrets
 cd test-build-secrets
-printf 'FROM alpine:latest\n\nRUN --mount=type=secret,id=TEST_BUILD_SECRET_A,env=TEST_BUILD_SECRET_A echo -n $TEST_BUILD_SECRET_A | sha256sum > /foo_secret_hash.txt\nRUN --mount=type=secret,id=TEST_BUILD_SECRET_B,dst=/tmp/bar.secret cat /tmp/bar.secret | sha256sum > /bar_secret_hash.txt\n' > Dockerfile
-printf '{"build": { "dockerfile": "Dockerfile"}}\n' > devcontainer.json
+cat << EOF > Dockerfile
+FROM alpine:latest
+
+RUN --mount=type=secret,id=TEST_BUILD_SECRET_A,env=TEST_BUILD_SECRET_A echo -n \$TEST_BUILD_SECRET_A | sha256sum > /foo_secret_hash.txt
+RUN --mount=type=secret,id=TEST_BUILD_SECRET_B,dst=/tmp/bar.secret cat /tmp/bar.secret | sha256sum > /bar_secret_hash.txt
+EOF
+cat << EOF > devcontainer.json
+{
+    "build": { 
+        "dockerfile": "Dockerfile"
+    }
+}
+EOF
 ```
 
-Inspect the Dockerfile and devcontainer.json files in the new directory.
-```bash
-cat devcontainer.json
-cat Dockerfile
-```
-
-Note that the Dockerfile requires two secrets: `TEST_BUILD_SECRET_A` and `TEST_BUILD_SECRET_B`. Their values are arbitrarily set to `secret-foo` and `secret-bar` by the command below. Building the container image writes the checksums for these secrets to disk. This illustrates that the secrets can be used in the build to enact side effects without exposing the secrets themselves.
+The Dockerfile requires two secrets: `TEST_BUILD_SECRET_A` and `TEST_BUILD_SECRET_B`. Their values are arbitrarily set to `secret-foo` and `secret-bar` by the command below. Building the container image writes the checksums for these secrets to disk. This illustrates that the secrets can be used in the build to enact side effects without exposing the secrets themselves.
 
 Execute the build using this command:
 ```bash
@@ -43,21 +48,60 @@ docker run -it --rm \
 ```
 
 This will result in a shell session inside the built container.
-You can now verify three things:
-* The secrets provided to build are not available once the container is running. They are no longer on disk, nor are they in the process environment, or in `/proc/self/environ`. 
+You can now verify two things:
+
+Firstly, the secrets provided to build are not available once the container is running. They are no longer on disk, nor are they in the process environment, or in `/proc/self/environ`: 
 ```bash
 cat /proc/self/environ | tr '\0' '\n'
 printenv
 ```
-* The secrets were still useful during the build. The following commands show that the secrets had side effects inside the build, without remaining in the image:
+Expected output:
+```bash
+/workspaces/empty # cat /proc/self/environ | tr '\0' '\n'
+HOSTNAME=c0b0ee3d5564
+SHLVL=2
+HOME=/root
+TERM=xterm
+PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+DEVCONTAINER_CONFIG=/workspaces/empty/devcontainer.json
+ENVBUILDER=true
+TS_DEBUG_TRIM_WIREGUARD=false
+PWD=/workspaces/empty
+DEVCONTAINER=true
+/workspaces/empty # printenv
+HOSTNAME=c0b0ee3d5564
+SHLVL=2
+HOME=/root
+TERM=xterm
+PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+DEVCONTAINER_CONFIG=/workspaces/empty/devcontainer.json
+ENVBUILDER=true
+TS_DEBUG_TRIM_WIREGUARD=false
+PWD=/workspaces/empty
+DEVCONTAINER=true
+/workspaces/empty # 
+```
+
+Finally, the secrets were still useful during the build. The following commands show that the secrets had side effects inside the build, without remaining in the image:
 ```bash
 echo -n "secret-foo" | sha256sum
 cat /foo_secret_hash.txt
 echo -n "secret-bar" | sha256sum
 cat /bar_secret_hash.txt
 ```
 
-Notice that the first two checksums match and that the last two checksums match.
+Notice that the first two checksums match and that the last two checksums match. Expected output:
+```
+/workspaces/empty # echo -n "secret-foo" | sha256sum
+9a888f08a057159d2ea8fb69d38c9a25e367d7ca3128035b7f6dee2ca988c3d8  -
+/workspaces/empty # cat /foo_secret_hash.txt
+9a888f08a057159d2ea8fb69d38c9a25e367d7ca3128035b7f6dee2ca988c3d8  -
+/workspaces/empty # echo -n "secret-bar" | sha256sum
+fb1c9d1220e429b30c60d028b882f735b5af72d7b5496d9202737fe9f1d38289  -
+/workspaces/empty # cat /bar_secret_hash.txt
+fb1c9d1220e429b30c60d028b882f735b5af72d7b5496d9202737fe9f1d38289  -
+/workspaces/empty # 
+```
 
 Finally, exit the container:
 ```bash
@@ -103,10 +147,10 @@ Build secrets are meant for use cases where the secret should not be accessible
 Build secrets are only protected if they are not copied or moved from their location as designated in the `RUN` directive. If a build secret is used, care should be taken to ensure that it is not copied or otherwise persisted into an image layer beyond the control of Envbuilder.
 
 ### Who should be able to access build secrets, when and where?
-The secure way to use build secrets with Envbuilder is to deny users access to the platform that hosts Envbuilder. Only grant access to the Envbuilder container once it has concluded its build, using a trusted non-platform channel like ssh or the coder agent running inside the container. Once control has been handed to such a runtime container process, Envbuilder will have cleared all secrets that it set from the container.
-
 Anyone with sufficient access to attach directly to the container (eg. using `kubectl`), will be able to read build secrets if they attach to the container before it has concluded its build. Anyone with sufficient access to the platform that hosts the Envbuilder container will also be able to read these build secrets from where the platform stores them. This is true for other build systems, and containerised software in general.
 
+The secure way to use build secrets with Envbuilder is to deny users access to the platform that hosts Envbuilder. Only grant access to the Envbuilder container once it has concluded its build, using a trusted non-platform channel like ssh or the coder agent running inside the container. Once control has been handed to such a runtime container process, Envbuilder will have cleared all secrets that it set from the container.
+
 If secrets should be accessible at runtime, do not use build secrets. Rather, mount the secret data using a volume or environment variable. Envbuilder will not include mounted volumes in the image that it pushes to any cache repositories, but they will still be available to users that connect to the container.
 
 ### Container Management beyond Envbuilder's control