fix(secrets): name the provenance, not just docker history

The skill told readers that `ARG` secrets persist in `docker history` and
to use a secret mount. For a multi-stage build the first half is false in
the way that matters: a credential passed into a builder stage never
reaches the shipped layers, so `docker history` is clean — and the value
is public anyway, because buildx records every build argument verbatim in
the SLSA provenance attestation it attaches to the pushed image.

Following the old line means running the one check that cannot see the
leak. A public GHCR package was found carrying a live GitLab token in the
attestation of 1461 published versions this way.

The reference adds the inspect command, the fix, and the verification
trap: grep for the credential pattern, never for the argument name — the
attestation embeds the push's commit messages and RUN command lines, so
the name matches your own commit text and reports a leak that is not
there.

SKILL.md is at its 500-word cap, so the added line and reference row are
paid for by tightening prose the adjacent code blocks already state.

Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>

Author: CybotTM

skills/docker-development/SKILL.md

@@ -18,14 +18,12 @@ allowed-tools:
 
 # Docker Development
 
-Patterns for building, testing, and deploying Docker containers.
-
 ## Core Principles
 
 1. **Minimal** -- Alpine/distroless, multi-stage
 2. **Secure** -- Non-root USER, no layer secrets, pin versions
-3. **Testable** -- CI-verifiable: entrypoint bypass, DNS mocking
-4. **Cache-efficient** -- deps first, clean in same layer
+3. **Testable** -- entrypoint bypass, DNS mocking
+4. **Cache-efficient** -- deps first, clean in-layer
 
 ## Quick Reference
 
@@ -78,15 +76,16 @@ RUN npm ci
 COPY . .
 ```
 
-Manifests before source keeps install layers cached on source-only changes.
+Manifests before source keeps install layers cached.
 
 ### BuildKit Secrets
 
 ```dockerfile
 RUN --mount=type=secret,id=ssh_key,dst=/root/.ssh/id_rsa git clone git@github.com:org/repo.git
 ```
 
-`ENV`/`ARG`/`COPY` secrets persist in `docker history`. Use `--mount=type=secret`.
+`ARG` leaks via `docker history` **and** the pushed image's SLSA provenance --
+`references/build-secret-leaks.md`
 
 ### Docker Bake (Multi-Platform)
 
@@ -115,7 +114,7 @@ target "app" {
 1. **Bypass entrypoint**: `docker run --rm --entrypoint php myimage -v`
 2. **Mock upstream DNS**: `docker run --rm --add-host backend:127.0.0.1 nginx-image nginx -t`
 3. **Compose validation**: `cp .env.example .env` before `docker compose config`
-4. **Secret scanning**: Exclude `.env.example`, README, docs from scanners
+4. **Secret scanning**: exclude `.env.example`, README, docs
 5. **Root-owned artifacts**: root-owned bind-mount dirs (`EACCES`) -- `references/bind-mount-ownership.md`
 
 ## .dockerignore
@@ -125,12 +124,13 @@ Exclude: `.git`, `node_modules`/`vendor`, `.env*`, `*.pem`, `*.key`
 ## Compose Essentials
 
 - startup ordering: `depends_on.condition: service_healthy` + `healthcheck` `start_period`
-- `networks.internal: true` isolates databases from external access
-- `profiles: [debug]`: services start only with `--profile debug`
+- `networks.internal: true` isolates databases
+- `profiles: [debug]`: start only with `--profile debug`
 
 ## References
 
 - `references/ci-testing.md` -- CI testing patterns for Docker images
 - `references/dind-testing-patterns.md` -- Docker-in-Docker testing patterns
 - `references/bind-mount-ownership.md` -- root-owned bind-mount artifacts
 - `references/gpg-verification.md` -- gpgv patterns; stale keybox locks
+- `references/build-secret-leaks.md` -- `ARG` lands in SLSA provenance

skills/docker-development/references/build-secret-leaks.md

@@ -0,0 +1,63 @@
+# Where a build credential actually leaks
+
+`docker history` is the check everyone runs, and for a multi-stage build it is
+the wrong one. A credential passed as `ARG` into a builder stage never reaches
+the shipped layers — that stage is not in the final image — so the history is
+clean while the credential is public anyway.
+
+buildx attaches an SLSA provenance attestation to every pushed image and records
+the build arguments in it **verbatim**:
+
+```bash
+docker buildx imagetools inspect <ref> --format '{{json .Provenance}}' \
+  | jq -r '.[].SLSA.buildDefinition.externalParameters.request.args | keys[]'
+# build-arg:COMPOSER_AUTH   <- the value sits right there, in cleartext
+```
+
+Measured case (2026-08-12): a public GHCR package carried a working GitLab
+`glpat-` token in the attestation of **1461** published versions. The `ARG` was
+in a `composer-builder` stage that is never shipped.
+
+## Verify it, with a check that can fail
+
+Grep for the **credential pattern**, never for the argument name. The
+attestation embeds the push's commit messages and the `RUN` command lines, so
+the name matches your own commit text and reports a leak that is not there —
+that false positive cost a round of "still broken" in the session that found
+this.
+
+```bash
+for ref in "$OLD_TAG" "$NEW_TAG"; do
+  n=$(docker buildx imagetools inspect "$ref" --format '{{json .Provenance}}' \
+      | grep -oE 'glpat-[A-Za-z0-9_-]{10,}|ghp_[A-Za-z0-9]{20,}' | sort -u | wc -l)
+  echo "$ref: $n credential values"
+done
+```
+
+A pre-fix tag returning `1` and a post-fix tag returning `0` is the proof. A
+single post-fix `0` on its own proves nothing about the check.
+
+## The fix
+
+```dockerfile
+RUN --mount=type=secret,id=composer_auth \
+    COMPOSER_AUTH="$(cat /run/secrets/composer_auth 2>/dev/null || true)" \
+    composer install --no-dev
+```
+
+```hcl
+target "app" {
+  secret = ["type=env,id=composer_auth,env=COMPOSER_AUTH"]
+}
+```
+
+`type=env` reads the variable the CI already exports, so the calling workflow
+usually needs no change at all. Tolerate a missing secret (`|| true`): forks and
+local builds have no credential and should still resolve public dependencies
+rather than fail.
+
+## After a leak
+
+Rotation is the only remedy that acts on what is already published — the
+attestations of existing versions keep their copy of the value forever, or until
+someone deletes those package versions. Rotate first, fix the build second.