From f075a85670cc2f4675005bbe1589f27bda46303d Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Wed, 28 Jan 2026 11:40:24 -0800 Subject: [PATCH 1/2] dhi: add debug methods Signed-off-by: Craig Osterhout --- content/manuals/dhi/how-to/debug.md | 79 +++++++++++++++++++++++++---- 1 file changed, 69 insertions(+), 10 deletions(-) diff --git a/content/manuals/dhi/how-to/debug.md b/content/manuals/dhi/how-to/debug.md index a05d29428490..da2d3fffd931 100644 --- a/content/manuals/dhi/how-to/debug.md +++ b/content/manuals/dhi/how-to/debug.md @@ -14,12 +14,13 @@ Debug](../../../reference/cli/docker/debug.md), a secure workflow that temporarily attaches an ephemeral debug container to a running service or image without modifying the original image. -This guide shows how to debug Docker Hardened Images locally during -development. You can also debug containers remotely using the `--host` option. +This guide shows how to debug Docker Hardened Images locally during development. +With Docker Debug, you can also debug containers remotely using the `--host` +option. -The following example uses a mirrored `python:3.13` image, but the same steps apply to any image. +## Use Docker Debug -## Step 1: Run a container from a Hardened Image +### Step 1: Run a container from a Hardened Image Start with a DHI-based container that simulates an issue: @@ -41,7 +42,7 @@ You'll see: exec: "sh": executable file not found in $PATH ``` -## Step 2: Use Docker Debug to inspect the container +### Step 2: Use Docker Debug to inspect the container Use the `docker debug` command to attach a temporary, tool-rich debug container to the running instance. @@ -57,17 +58,75 @@ For example, to check running processes: $ ps aux ``` -Exit the debug session with: +Type `exit` to leave the container when done. + +## Alternative debugging approaches + +In addition to using Docker Debug, you can also use the following approaches for +debugging DHI containers. + +### Use the -dev variant + +Docker Hardened Images offer a `-dev` variant that includes a such as a shell +and a package manager to install debugging tools. Simply replace the image tag +with `-dev`: + +```console +$ docker run -it --rm dhi.io/python:3.13-dev sh +``` + +Type `exit` to leave the container when done. Note that using the `-dev` variant +increases the attack surface and it is not recommended as a runtime for +production environments. + +### Mount debugging tools with image mounts + +You can use the image mount feature to mount debugging tools into your container +without modifying the base image. + +#### Step 1: Run a container from a Hardened Image + +Start with a DHI-based container that simulates an issue: ```console -$ exit +$ docker run -d --name myapp dhi.io/python:3.13 python -c "import time; time.sleep(300)" ``` +#### Step 2: Mount debugging tools into the container + +Run a new container that mounts a tool-rich image (like `busybox`) into +the running container's namespace: + +```console +$ docker run --rm -it --pid container:myapp \ + --mount type=image,source=busybox,destination=/dbg,ro \ + dhi.io/python:3.13 /dbg/bin/sh +``` + +This mounts the BusyBox image at `/dbg`, giving you access to its tools while +keeping your original container image unchanged. Since the hardened Python image +doesn't include standard utilities, you need to use the full path to the mounted +tools: + +```console +$ /dbg/bin/ls / +$ /dbg/bin/ps aux +$ /dbg/bin/cat /etc/os-release +``` + +Type `exit` to leave the container when done. + ## What's next -Docker Debug helps you troubleshoot hardened containers without compromising the -integrity of the original image. Because the debug container is ephemeral and -separate, it avoids introducing security risks into production environments. +This guide covered three approaches for debugging Docker Hardened Images: + +- Docker Debug: Attach an ephemeral debug container without modifying the original image +- `-dev` variants: Use development images that include debugging tools +- Image mount: Mount tool-rich images like BusyBox to access debugging utilities + +Each method helps you troubleshoot hardened containers while maintaining +security. Docker Debug and image mounts avoid modifying your production images, +while `-dev` variants provide convenience during development. If you encounter issues related to permissions, ports, missing shells, or package managers, see [Troubleshoot Docker Hardened Images](../troubleshoot.md) From 87b6bb011fd8b2ccd86a585927a168f51f722037 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Thu, 29 Jan 2026 08:12:14 -0800 Subject: [PATCH 2/2] Update content/manuals/dhi/how-to/debug.md Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> --- content/manuals/dhi/how-to/debug.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/dhi/how-to/debug.md b/content/manuals/dhi/how-to/debug.md index da2d3fffd931..8c277cc620df 100644 --- a/content/manuals/dhi/how-to/debug.md +++ b/content/manuals/dhi/how-to/debug.md @@ -67,7 +67,7 @@ debugging DHI containers. ### Use the -dev variant -Docker Hardened Images offer a `-dev` variant that includes a such as a shell +Docker Hardened Images offer a `-dev` variant that includes a shell and a package manager to install debugging tools. Simply replace the image tag with `-dev`: