👉 Subscribe to our newsletter to get:
- Real stories from real AWS projects
- No-nonsense DevOps tactics
- Cost, security & compliance patterns that actually work
- Expert guidance from engineers in the field
=========================================================================
Minimal runtime base images for containerized apps. Each image is Google distroless Debian 13 with no shell and no package manager. It runs as the nonroot user (uid 65532) and adds lprobe for exec-form HEALTHCHECKs. The images are built for linux/amd64 and linux/arm64.
Using
secure-container-image-basefrom before November 2026? It moved from Alpine to Debian distroless, and its user changed from uid 2323 to 65532. See Migrating from the Alpine-Basedsecure-container-image-base, which includes a one-line rollback.
| Image | Built from | For |
|---|---|---|
ghcr.io/fivexl/secure-container-image-base |
gcr.io/distroless/static-debian13 |
Static binaries: Go with CGO_ENABLED=0, Rust with musl |
ghcr.io/fivexl/secure-container-image-base-python3 |
gcr.io/distroless/python3-debian13 |
Python 3.13 apps |
ghcr.io/fivexl/secure-container-image-base-nodejs |
gcr.io/distroless/nodejs26-debian13 |
Node.js 26 apps |
Every image sets WORKDIR /app, owned by uid 65532, and TMPDIR=/tmp. The Node.js image runs dumb-init as PID 1 with ENTRYPOINT ["/usr/bin/dumb-init", "--", "/nodejs/bin/node"], so CMD ["server.js"] works and SIGTERM reaches your app.
| Image | Tags | With the AWS RDS CA bundle | With a shell, for troubleshooting |
|---|---|---|---|
secure-container-image-base |
debian13 |
debian13-rds |
none |
secure-container-image-base-python3 |
python3.13-debian13 |
python3.13-debian13-rds |
python3.13-debian13-dev |
secure-container-image-base-nodejs |
node26-debian13 |
node26-debian13-rds |
node26-debian13-dev |
The matching latest, latest-rds and latest-dev aliases exist for compatibility only. Use the versioned tag, so that a move to a new Debian or runtime major is a change you make on purpose.
The -rds variants trust the AWS RDS global certificate bundle in addition to the system CAs. It is appended to /etc/ssl/certs/ca-certificates.crt and also kept on its own as /etc/ssl/certs/aws-rds.crt. For Node.js, the -rds variant sets NODE_EXTRA_CA_CERTS to that file, because Node.js ignores the system CA file by default. Use the plain tags unless your app connects to RDS over TLS.
The -dev variants are built from distroless :debug-nonroot and add a busybox shell at /busybox/sh. Use one only to troubleshoot: rebuild your app on it, swap it in, then swap back. It does not include the RDS CA bundle. The static base has no -dev variant; to debug a static binary, attach a debug container to it, for example with kubectl debug.
Every image carries the label io.fivexl.image.variant (production, rds or dev), so admission policies can tell variants apart, for example to reject dev in production.
CI rebuilds every image daily without cache, from floating upstream tags and unpinned packages, so each build includes the latest upstream security fixes. CI publishes a build only after it passes a Trivy scan (fixable HIGH and CRITICAL) and smoke tests on both platforms. Temporary scan exceptions live in .trivyignore.yaml, and each one expires on a set date.
All tags float. Follow a tag to get the daily patches. To freeze an image, pin its digest:
FROM ghcr.io/fivexl/secure-container-image-base:debian13@sha256:<digest>A floating base patches nothing until you rebuild and redeploy your image. Rebuild your app images on a schedule as well, daily or weekly, then test and redeploy them.
The container hardening guide quotes these tags, the uid and the variants. A pull request that changes any of them must update the guide within the same week. A scheduled workflow opens a review issue each quarter.
Before this change, secure-container-image-base was Alpine 3.18 files on scratch. The new image keeps the name and changes the contents:
| Before | Now | |
|---|---|---|
| User | app, uid 2323 |
nonroot, uid 65532 |
TMPDIR |
/app/tmp |
/tmp |
| RDS CA bundle | always included | only in debian13-rds |
| OS files | Alpine | Debian 13 distroless |
To migrate:
- In Dockerfiles, replace
--chown=app:appor--chown=2323with--chown=65532:65532, andUSER appwithUSER 65532. - In deployments, set
runAsUser: 65532, fix the ownership of persistent volumes, and mount a writable/tmp(for example anemptyDir) when the root filesystem is read-only. - If your app connects to RDS, switch to
debian13-rds.
To roll back, pin the last Alpine build:
FROM ghcr.io/fivexl/secure-container-image-base:legacy-alpineOld :<commit sha> tags stay in place.
CI signs each published image with keyless cosign and attaches a signed SPDX SBOM to each platform image. Verify with cosign v3 or newer; v2 reports "no signatures found".
cosign verify ghcr.io/fivexl/secure-container-image-base:debian13 \
--certificate-identity https://github.com/fivexl/secure-container-image/.github/workflows/family.yml@refs/heads/main \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
# The SBOM attestation is on the platform image, not on the multi-platform index.
image=ghcr.io/fivexl/secure-container-image-base
digest=$(docker buildx imagetools inspect "$image:debian13" --raw \
| jq -r '.manifests[] | select(.platform.architecture == "amd64") | .digest')
cosign verify-attestation --type spdxjson "$image@$digest" \
--certificate-identity https://github.com/fivexl/secure-container-image/.github/workflows/family.yml@refs/heads/main \
--certificate-oidc-issuer https://token.actions.githubusercontent.comEach image also carries BuildKit SBOM and provenance attestations:
docker buildx imagetools inspect ghcr.io/fivexl/secure-container-image-base:debian13 --format '{{json .Provenance}}'The examples directory holds one app per base and an Envoy proxy. CI builds them against the bases from the same commit, scans them and runs them with --read-only --cap-drop=ALL --security-opt=no-new-privileges. They are not published.
examples/go_app_example/Dockerfile.goapp: a static Go binary onsecure-container-image-base.examples/node_examples/Dockerfile.node-app: an Express 5 app onsecure-container-image-base-nodejs, installed withnpm ci --omit=dev.examples/python_examples/Dockerfile.py-app-uv: a uvicorn and pandas app onsecure-container-image-base-python3. The builder isdebian:13with its ownpython3, the same interpreter and ABI as the runtime, anduv sync --frozeninstalls the dependencies into/app/.venv.examples/envoy_example/Dockerfile.envoy: Envoy in front of an app, configured from environment variables by a Go entrypoint. See Entrypoints in Go, Not Bash.
Each example listens on port 8080, so it needs no NET_BIND_SERVICE capability. To build and smoke-test one family locally, use a docker-container builder; the default docker driver cannot pass a built base to the examples:
docker buildx create --name scimg --driver docker-container
docker buildx bake --builder scimg nodejs
scripts/smoke-test.sh base nodejs production local/nodejs-production:test
scripts/smoke-test.sh base nodejs rds local/nodejs-rds:test
scripts/smoke-test.sh base nodejs dev local/nodejs-dev:test
scripts/smoke-test.sh example nodejs local/nodejs-example:testReplace nodejs with static or python3 for the other families, and skip the dev line for static. The static family also builds the Envoy example, and its smoke test proxies to the Go example:
scripts/smoke-test.sh envoy local/static-envoy-example:test local/static-example:testImages often start with a shell script that reads environment variables, renders a config file with envsubst or sed, and then execs the real process. That needs a shell in the image, and unvalidated values can rewrite the config: an UPSTREAM_HOST containing a quote and a newline injects YAML.
The Envoy example replaces that script with a small Go program, examples/envoy_example/entrypoint. It:
- reads
LISTEN_PORT(default8080),UPSTREAM_HOST(defaultlocalhost) andUPSTREAM_PORT(default8081); - rejects anything that is not a port number, a host name or an IP address, and names every bad variable in one error;
- refuses the admin port
9901asLISTEN_PORT, and asUPSTREAM_PORTon a loopback host, so the admin API never reaches the public listener; - renders
envoy.yaml.tmplinto$TMPDIR/envoy.yaml(/tmpwhenTMPDIRis unset), with the admin listener on127.0.0.1:9901only; - replaces itself with Envoy through
syscall.Exec, so Envoy is PID 1 and receives signals directly. The entrypoint passes extra container arguments on to Envoy.
Docker runs the entrypoint's unit tests in the build stage. Envoy is linked against glibc, so the example runs on Envoy's own distroless image rather than on secure-container-image-base. The HEALTHCHECK uses lprobe against the admin /ready endpoint. Envoy resolves the upstream IPv4 first, so localhost reaches an app that listens on IPv4 only. CI reports Trivy findings in the Envoy image without failing, because its CVEs come from upstream Envoy and must not hold back a base.
Use a shell script when it is one line that execs the process. Write the entrypoint in Go once it validates input or renders config.
skills/secure-container is an Agent Skill that hardens a Dockerfile with these images, or writes a new one. It first inspects the app: runtime, native dependencies, subprocesses, signal handling, writable paths, ports and what the healthcheck proves. Then it proposes only the changes that apply, such as a multi-stage build, the -rds variant, lprobe, a Go entrypoint or an unprivileged port, and asks before it edits. The last step runs the image with the hardened flags until it is healthy, verifies the base with cosign and reports any check it could not run. When an app does not fit these bases, it says so and applies the hardening steps that still fit.
To install it, copy the directory into your agent's skill directory. For Claude Code:
git clone --depth 1 https://github.com/fivexl/secure-container-image.git
mkdir -p ~/.claude/skills
cp -R secure-container-image/skills/secure-container ~/.claude/skills/Then ask your agent to harden a Dockerfile.
These packages are no longer built. They stay pullable but get no fixes.
| Deprecated | Replacement |
|---|---|
secure-container-image-base-python3-distroless-debian-11 |
secure-container-image-base-python3 |
secure-container-image-base-nodejs20-distroless-debian-11 |
secure-container-image-base-nodejs |
secure-container-image-example-goapp, -example-node-app, -example-py-app-poetry, -example-py-app-poetry-no-venv |
build the matching example from examples/ |
You always have to balance security and productivity. These images have no shell or debug tools, so you cannot exec into a running container. First export logs and telemetry so developers do not need to exec. When there is no other way, rebuild the app on the matching -dev tag, swap it in, and require elevated permissions for that swap.
