Skip to content

dhi: add deb hsp #25155

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
craig-osterhout wants to merge 2 commits into
base: main
Choose a base branch
from
+161 −13
Open

dhi: add deb hsp #25155

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
51de76e
dhi: add deb hsp
craig-osterhout May 22, 2026
bdaa93f
agent feedback
craig-osterhout May 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions content/manuals/dhi/how-to/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,15 +201,23 @@ For a complete reference of all YAML fields, see
{{< summary-bar feature_name="Docker Hardened Images Enterprise" >}}

Generate authentication credentials for accessing the enterprise hardened
package repository. This is used when configuring your package manager to
install compliance-specific packages in your own images. For detailed
package repository. These credentials are used when configuring your package
manager to install compliance-specific packages in your own images. For detailed
Copy link
Copy Markdown
Contributor

@dvdksn dvdksn May 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not introduced in this PR, but I just saw this in passing; "compliance-specific packages" sounds a bit strange.

instructions, see [Enterprise
repository](./hardened-packages.md#enterprise-repository).

For Alpine-based images:

```console
$ docker dhi auth apk
```

For Debian-based images:

```console
$ docker dhi auth deb
```

### Monitor customization builds

{{< summary-bar feature_name="Docker Hardened Images" >}}
Expand Down
162 changes: 151 additions & 11 deletions content/manuals/dhi/how-to/hardened-packages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Use Hardened System Packages
linkTitle: Use hardened packages
weight: 32
keywords: hardened images, DHI, hardened packages, packages, alpine
keywords: hardened images, DHI, hardened packages, packages, alpine, apk, debian, apt
description: Learn how to use and verify Docker's hardened system packages in your images.
---

Expand Down Expand Up @@ -51,15 +51,19 @@ repositories. This lets you install hardened packages in your own images.

#### Public repository

To use Docker's public hardened package repository in your own images, configure
the Alpine package manager in your Dockerfile.
To use Docker's public hardened package repository in your own images,
configure your package manager in your Dockerfile to install the DHI signing
key and add the DHI repository.

The configuration process involves three steps:

1. Install the [signing key](https://github.com/docker-hardened-images/keyring)
2. Configure the package repository
3. Update and install packages

{{< tabs group="os" >}}
{{< tab name="Alpine" >}}

The following example shows how to configure the Alpine package manager in your
Dockerfile to use Docker's public hardened package repository:

Expand Down Expand Up @@ -96,6 +100,57 @@ https://dhi.io/apk/alpine/v3.23/main

This ensures all packages are installed from Docker's hardened repository.

{{< /tab >}}
{{< tab name="Debian" >}}

The following example shows how to configure the Debian package manager in your
Dockerfile to use Docker's public hardened package repository:

```dockerfile
FROM debian:trixie-slim

# Install the signing key
RUN apt-get update && apt-get install -y --no-install-recommends \
ca-certificates curl gnupg \
&& rm -rf /var/lib/apt/lists/*
RUN curl -fsSL https://dhi.io/keyring/dhi-deb-gpg.D46852F6925E9F71.key \
| gpg --dearmor -o /usr/share/keyrings/dhi-deb.gpg

# Add the hardened package repository
RUN echo "deb [signed-by=/usr/share/keyrings/dhi-deb.gpg] https://dhi.io/deb/debian/main trixie main" \
> /etc/apt/sources.list.d/dhi.list

# Update and install packages
RUN apt-get update && apt-get install -y jq \
&& rm -rf /var/lib/apt/lists/*
```

To verify the configuration, build and run the image:

```console
$ docker build -t myapp:latest .
$ docker run -it myapp:latest bash
```

Inside the container, check the configured repository:

```console
root@myapp:/# cat /etc/apt/sources.list.d/dhi.list
deb [signed-by=/usr/share/keyrings/dhi-deb.gpg] https://dhi.io/deb/debian/main trixie main
```

When the DHI repository carries a hardened version of a package, `apt` prefers
it over the upstream Debian version automatically. You can confirm this with
`apt-cache policy <package>`, which shows a candidate with a `+dhi` or `dhi`
version suffix sourced from `https://dhi.io/deb/debian/main`.

Not every Debian package is available as a hardened system package. When a
package is not in the DHI repository, `apt` transparently falls back to the
upstream Debian mirrors configured in the base image.

{{< /tab >}}
{{< /tabs >}}

All packages installed from the Docker Hardened Images repository are built from
source by Docker and include full provenance.

Expand All @@ -109,16 +164,14 @@ as well as additional security patches.

The configuration process involves five steps:

1. Install the [signing key](https://github.com/docker-hardened-images/keyring)
1. Install the [signing keys](https://github.com/docker-hardened-images/keyring)
2. Configure the base package repository
3. Install the enterprise configuration package
3. Add the enterprise security repository
4. Configure package installation with authentication
5. Build the image passing credentials as a secret using the DHI CLI

> [!NOTE]
>
> You must have the Docker Hardened Images CLI installed and configured. For
> more information, see [Use the DHI CLI](./cli.md).
{{< tabs group="os" >}}
{{< tab name="Alpine" >}}

The following example shows how to configure the Alpine package manager in your
Dockerfile to use Docker's enterprise hardened package repository:
Expand Down Expand Up @@ -147,14 +200,61 @@ RUN --mount=type=secret,id=http_auth \
Build the image with authentication passed securely as a build secret:

```console
$ dhictl auth apk > http_auth.txt
$ docker dhi auth apk > http_auth.txt
$ docker build --secret id=http_auth,src=http_auth.txt -t myapp-enterprise:latest .
$ rm http_auth.txt
```

The `--secret` flag securely mounts the authentication credentials during build
without storing them in the image layers or metadata.

{{< /tab >}}
{{< tab name="Debian" >}}

The following example shows how to configure the Debian package manager in your
Dockerfile to use Docker's enterprise hardened package repository. Mount
credentials at `/etc/apt/auth.conf.d/dhi.conf`; `apt` reads files in
`/etc/apt/auth.conf.d/` automatically when they have mode `0600`:

```dockerfile
FROM debian:trixie-slim

# Install the signing keys
RUN apt-get update && apt-get install -y --no-install-recommends \
ca-certificates curl gnupg \
&& rm -rf /var/lib/apt/lists/*
RUN curl -fsSL https://dhi.io/keyring/dhi-deb-gpg.D46852F6925E9F71.key \
| gpg --dearmor -o /usr/share/keyrings/dhi-deb.gpg
RUN curl -fsSL https://dhi.io/keyring/dhi-deb-sec-gpg.D46852F6925E9F71.key \
| gpg --dearmor -o /usr/share/keyrings/dhi-deb-sec.gpg

# Add the hardened package repository and the enterprise security repository
RUN echo "deb [signed-by=/usr/share/keyrings/dhi-deb.gpg] https://dhi.io/deb/debian/main trixie main" \
> /etc/apt/sources.list.d/dhi.list
RUN echo "deb [signed-by=/usr/share/keyrings/dhi-deb-sec.gpg] https://dhi.io/deb/debian/security trixie main" \
> /etc/apt/sources.list.d/dhi-sec.list

# Install packages from the security repository with authentication
RUN --mount=type=secret,id=netrc,target=/etc/apt/auth.conf.d/dhi.conf,mode=0600 \
apt-get update && apt-get install -y openssl \
&& rm -rf /var/lib/apt/lists/*
```

Build the image, passing credentials securely as a build secret through an
environment variable:

```console
$ NETRC=$(docker dhi auth deb) docker build \
--secret id=netrc,env=NETRC \
-t myapp-enterprise:latest .
```

The `--secret id=netrc,env=NETRC` form securely mounts the authentication
credentials during build without storing them in the image layers or metadata.

{{< /tab >}}
{{< /tabs >}}

## Verify packages

Every hardened package is cryptographically signed and includes metadata that
Expand All @@ -164,12 +264,25 @@ infrastructure.

### View package metadata

To view information about a hardened package, including its provenance:
To view information about a hardened package:

{{< tabs group="os" >}}
{{< tab name="Alpine" >}}

```console
$ apk info -L <package-name>
```

{{< /tab >}}
{{< tab name="Debian" >}}

```console
$ dpkg -L <package-name>
Comment thread
craig-osterhout marked this conversation as resolved.
```

{{< /tab >}}
{{< /tabs >}}

This shows the files included in the package and its metadata.

### Verify package signatures
Expand All @@ -188,16 +301,43 @@ verifiable metadata and cryptographic signatures.

To view this metadata for an installed package:

{{< tabs group="os" >}}
{{< tab name="Alpine" >}}

```console
$ apk info -a <package-name>
```

{{< /tab >}}
{{< tab name="Debian" >}}

```console
$ apt-cache show <package-name>
Comment thread
craig-osterhout marked this conversation as resolved.
```

{{< /tab >}}
{{< /tabs >}}

Or to view metadata for a package before installing:

{{< tabs group="os" >}}
{{< tab name="Alpine" >}}

```console
$ apk fetch --stdout <package-name> | tar -xzO .PKGINFO
```

{{< /tab >}}
{{< tab name="Debian" >}}

```console
$ apt-get download <package-name>
$ dpkg-deb -I <package-name>_*.deb
```

{{< /tab >}}
{{< /tabs >}}

The package signing keys ensure that packages haven't been tampered with after
being built. When you install the signing key and configure your package manager,
all packages are automatically verified before installation.
Expand Down