Hands-on Lab

Gestión de secretos en Docker (sin dejarlos en la imagen)

17 de julio de 2026 3 min

0 / 9

Chuleta

¿Te ha servido? No te pierdas el próximo lab

0:00 / 0:00

Escribimos el Dockerfile del antipatrón más común: ARG define una variable de compilación (por defecto changeme), ENV la promueve a variable de entorno persistente de la imagen, y el RUN la escribe además en un archivo dentro de una capa. Tres sitios distintos donde el mismo valor queda fosilizado y disponible después.

mkdir -p /lab/leaky && cd /lab/leaky && cat > Dockerfile <<'EOF'
FROM alpine:3.20
ARG API_TOKEN=changeme
ENV API_TOKEN=$API_TOKEN
RUN echo "using token: $API_TOKEN" > /app-info.txt
CMD ["cat", "/app-info.txt"]
EOF
cat Dockerfile

Lo hice yo

Construimos la imagen pasando el secreto como build-arg, exactamente como haría (mal) un pipeline de CI que intenta 'inyectar' una credencial en el build. Docker acepta el flag sin avisar de nada: no hay ningún error, solo una imagen que ya lleva el secreto dentro.

cd /lab/leaky && docker build --build-arg API_TOKEN=changeme -t leaky-app:1.0 .

Lo hice yo

Confirmamos la fuga con dos comandos de solo lectura: docker history muestra la capa RUN que usó el token en texto plano, y docker inspect revela que también quedó guardado como variable de entorno de la imagen. Cualquiera con acceso a leaky-app:1.0 —en un registry, en un backup, en un pull accidental— puede leer el secreto sin ejecutar el contenedor.

echo '--- docker history: capa que usó el token ---'; docker history --no-trunc leaky-app:1.0 | grep -i token; echo '--- docker inspect: token guardado como env de la imagen ---'; docker inspect leaky-app:1.0 --format '{{json .Config.Env}}'

Creamos el secreto como un archivo aparte, fuera de cualquier directorio de contexto de build, con permisos 600 para que solo root pueda leerlo. Es el mismo cambio 'changeme' del paso anterior, pero ahora vive en un archivo que decidimos nosotros cuándo y cómo exponer, en vez de quedar fijo dentro de una imagen.

mkdir -p /lab/secrets && printf '%s' 'changeme' > /lab/secrets/api_token && chmod 600 /lab/secrets/api_token && ls -l /lab/secrets/api_token

Lo hice yo

Comprobamos que el archivo existe con permisos 600 y 8 bytes de contenido, y que no está dentro de ningún directorio que vaya a copiarse a una imagen con COPY. Esta es la base sobre la que construimos las tres técnicas seguras que siguen.

stat -c '%a %s %n' /lab/secrets/api_token

La directiva # syntax=docker/dockerfile:1 activa la sintaxis extendida de BuildKit. RUN --mount=type=secret,id=api_token hace que el archivo esté disponible SOLO dentro de esa instrucción, en /run/secrets/api_token, sin registrarse como ARG ni ENV ni copiarse a ninguna capa: en cuanto el RUN termina, el montaje desaparece.

mkdir -p /lab/safe-build && cd /lab/safe-build && cat > Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
FROM alpine:3.20
RUN --mount=type=secret,id=api_token \
    test -s /run/secrets/api_token && \
    echo "build used a secret of $(wc -c < /run/secrets/api_token) bytes" && \
    echo "no secret baked into this layer" > /build-note.txt
CMD ["cat", "/build-note.txt"]
EOF
cat Dockerfile

Lo hice yo

--secret id=api_token,src=/lab/secrets/api_token le dice a BuildKit qué archivo del host montar bajo ese identificador, que debe coincidir con el id usado en el RUN --mount del Dockerfile. BuildKit es el builder por defecto desde Docker 23, así que no hace falta ninguna variable de entorno adicional.

cd /lab/safe-build && docker build --secret id=api_token,src=/lab/secrets/api_token -t safe-app:1.0 .

Lo hice yo

Ni docker history ni el array Env de la imagen contienen el token: el build sí lo usó de verdad —el mensaje del paso anterior confirma que leyó 8 bytes— pero nunca lo escribió en una capa. Compara esta salida limpia con la fuga del paso reveal-leak.

echo '--- docker history (sin coincidencias esperadas) ---'; docker history --no-trunc safe-app:1.0 | grep -i token; echo '--- docker inspect env (sin API_TOKEN esperado) ---'; docker inspect safe-app:1.0 --format '{{json .Config.Env}}'

Para un secreto que hace falta en tiempo de ejecución (no en el build), montamos el archivo del host directamente como :ro dentro del contenedor. El proceso lo lee como un archivo normal, nunca aparece en docker inspect como variable de entorno, y :ro impide que el contenedor lo modifique.

docker run --rm -v /lab/secrets/api_token:/run/secrets/api_token:ro alpine:3.20 sh -c 'echo "container read a secret of $(wc -c < /run/secrets/api_token) bytes from a mounted file"'

Lo hice yo

Intentamos escribir sobre el montaje de solo lectura desde dentro del contenedor, incluso como root. La escritura falla con un error del sistema de archivos y un código de salida distinto de cero: el flag :ro se aplica a nivel de montaje, no de permisos de usuario, así que el archivo original en el host queda intacto.

docker run --rm -v /lab/secrets/api_token:/run/secrets/api_token:ro alpine:3.20 sh -c 'echo overwritten > /run/secrets/api_token; echo "write attempt exit code: $?"'

Creamos un .env con el secreto y lo excluimos del contexto de build con .dockerignore, así una COPY . nunca lo empaquetaría por accidente. Levantamos un contenedor de fondo con --env-file .env para inspeccionarlo en el siguiente paso: este patrón es habitual en desarrollo local, pero tiene un matiz importante que vamos a comprobar ahora mismo.

cd /lab/safe-build && printf 'API_TOKEN=changeme\n' > .env && printf '.env\n' > .dockerignore && docker run -d --name envfile-demo --env-file .env alpine:3.20 sleep 300

Lo hice yo

Este es el matiz: el .env mantiene el secreto fuera de la IMAGEN, pero docker inspect sobre el CONTENEDOR en marcha lo sigue mostrando en texto plano dentro de Env. Es más seguro que ARG/ENV en el Dockerfile, pero más débil que el montaje de archivo o los secrets de Compose frente a cualquiera con acceso al socket de Docker.

docker inspect envfile-demo --format '{{json .Config.Env}}'

El bloque secrets: de Compose es file-based y funciona con un docker compose up normal, sin Swarm: monta /lab/secrets/api_token como /run/secrets/api_token dentro del servicio app, en solo lectura, y nunca pasa por un ARG ni un ENV. -d lo deja corriendo en segundo plano para inspeccionarlo en el siguiente paso.

mkdir -p /lab/compose-secrets && cd /lab/compose-secrets && cat > compose.yaml <<'YAML'
services:
  app:
    image: alpine:3.20
    command: 'sh -c "echo secret length: $(wc -c < /run/secrets/api_token) && sleep 60"'
    secrets:
      - api_token
secrets:
  api_token:
    file: /lab/secrets/api_token
YAML
cd /lab/compose-secrets && docker compose up -d

Lo hice yo

Dos comprobaciones a la vez: los logs muestran que el servicio leyó el secreto sin problema (secret length: 8), y docker inspect sobre ese mismo contenedor no tiene ni rastro de API_TOKEN en Env, al contrario que en el envfile-demo del paso anterior. El secreto llegó al proceso solo como archivo montado.

cd /lab/compose-secrets && sleep 2 && docker compose logs app && CID=$(docker compose ps -q app) && docker inspect "$CID" --format '{{json .Config.Env}}'

Retiramos todo lo que creó el lab: el contenedor envfile-demo, el stack de Compose con sus volúmenes (-v), las dos imágenes leaky-app y safe-app, y el directorio de trabajo /lab entero, para no dejar ningún secreto ni ninguna imagen comprometida en este host desechable.

docker rm -f envfile-demo >/dev/null 2>&1; cd /lab/compose-secrets && docker compose down -v >/dev/null 2>&1; docker rmi -f leaky-app:1.0 safe-app:1.0 >/dev/null 2>&1; rm -rf /lab; echo 'cleanup done'

Lo hice yo

Confirmamos el estado final: ni docker ps ni docker images muestran nada de este lab, y /lab ya no existe. El host queda exactamente como estaba antes de empezar, sin ningún secreto de demostración pendiente en disco.

echo '--- contenedores restantes ---'; docker ps -a --format '{{.Names}}' | grep -E 'envfile-demo|compose-secrets'; echo '--- imagenes restantes ---'; docker images --format '{{.Repository}}:{{.Tag}}' | grep -E 'leaky-app|safe-app'; echo '--- directorio /lab ---'; ls /lab 2>/dev/null || echo '/lab removed, all clean'

¿Te ha sido útil este lab? Puntúalo:

Click to rate this post!

[Total: 0 Average: 0]

La gestión de secretos en Docker no es opcional

La gestión de secretos en Docker empieza por asumir que cualquier valor que pase por un ARG, un ENV o un COPY del Dockerfile queda escrito para siempre en las capas de la imagen y en su metadata, visible con docker history o docker inspect por cualquiera que descargue esa imagen. En este lab lo demostramos primero fabricando la fuga y luego la corregimos con cuatro técnicas que sí mantienen el secreto fuera de la imagen: un build secret de BuildKit, un archivo montado en solo lectura, un env-file bien acotado y los secrets nativos de Docker Compose sin necesidad de Swarm.

Qué técnica usar según el momento

Si el secreto solo hace falta durante la construcción de la imagen (una clave privada para clonar un repositorio, un token para descargar una dependencia), docker build --secret lo monta en /run/secrets/ únicamente durante esa instrucción RUN y nunca llega a una capa. Si el secreto lo necesita el proceso en tiempo de ejecución, un archivo montado como :ro o el bloque secrets: de Compose evitan que aparezca en el Env del contenedor, algo que sí ocurre con --env-file. Para equipos que gestionan credenciales a mayor escala merece la pena dar el salto a un gestor dedicado como Vault de HashiCorp, y en clústeres reales con Docker Swarm existe además docker secret create, cifrado en el Raft log del clúster.

Para seguir

Repasa también nuestra guía de variables de entorno y secretos en Docker Compose y, si aún no tienes Docker instalado, la guía para instalar Docker en Debian. Más plantillas reproducibles en la categoría Herramientas y en el resto de laboratorios prácticos. La referencia oficial de RUN --mount=type=secret está en la Dockerfile reference de Docker, el detalle de los secrets de Compose en la Compose Specification, y un repaso más amplio de buenas prácticas en la Docker Security Cheat Sheet de OWASP.

Preguntas frecuentes

¿Por qué no debo poner un secreto en ARG o ENV del Dockerfile?

Porque ambos quedan grabados en las capas y en la metadata de la imagen para siempre: cualquiera que ejecute docker history o docker inspect sobre esa imagen puede leerlo, incluso si lo «borras» en una instrucción posterior, la capa anterior sigue ahí.

¿Qué es un build secret de BuildKit y en qué se diferencia de ARG?

docker build –secret monta un archivo en /run/secrets/ solo durante la instrucción RUN que lo pide y nunca lo escribe en una capa ni en el historial. ARG, en cambio, queda registrado como parte de la metadata de compilación de la imagen.

¿Es seguro usar –env-file con docker run?

Es mejor que ARG/ENV en el Dockerfile porque el secreto nunca toca la imagen, pero sigue siendo visible con docker inspect sobre el contenedor en marcha. Para procesos en ejecución, un archivo montado en solo lectura o los secrets de Compose son más seguros.

¿Necesito Docker Swarm para usar los secrets de Compose?

No. El bloque secrets: de nivel superior con un driver file: funciona con un docker compose up normal en un único host. docker secret create y el cifrado en el Raft log sí requieren un clúster iniciado con docker swarm init.

Chuleta

mkdir -p /lab/leaky && cd /lab/leaky && cat > Dockerfile <<'EOF'
FROM alpine:3.20
ARG API_TOKEN=changeme
ENV API_TOKEN=$API_TOKEN
RUN echo "using token: $API_TOKEN" > /app-info.txt
CMD ["cat", "/app-info.txt"]
EOF
cat Dockerfile

cd /lab/leaky && docker build --build-arg API_TOKEN=changeme -t leaky-app:1.0 .

mkdir -p /lab/secrets && printf '%s' 'changeme' > /lab/secrets/api_token && chmod 600 /lab/secrets/api_token && ls -l /lab/secrets/api_token

mkdir -p /lab/safe-build && cd /lab/safe-build && cat > Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
FROM alpine:3.20
RUN --mount=type=secret,id=api_token \
    test -s /run/secrets/api_token && \
    echo "build used a secret of $(wc -c < /run/secrets/api_token) bytes" && \
    echo "no secret baked into this layer" > /build-note.txt
CMD ["cat", "/build-note.txt"]
EOF
cat Dockerfile

cd /lab/safe-build && docker build --secret id=api_token,src=/lab/secrets/api_token -t safe-app:1.0 .

docker run --rm -v /lab/secrets/api_token:/run/secrets/api_token:ro alpine:3.20 sh -c 'echo "container read a secret of $(wc -c < /run/secrets/api_token) bytes from a mounted file"'

cd /lab/safe-build && printf 'API_TOKEN=changeme\n' > .env && printf '.env\n' > .dockerignore && docker run -d --name envfile-demo --env-file .env alpine:3.20 sleep 300

mkdir -p /lab/compose-secrets && cd /lab/compose-secrets && cat > compose.yaml <<'YAML'
services:
  app:
    image: alpine:3.20
    command: 'sh -c "echo secret length: $(wc -c < /run/secrets/api_token) && sleep 60"'
    secrets:
      - api_token
secrets:
  api_token:
    file: /lab/secrets/api_token
YAML
cd /lab/compose-secrets && docker compose up -d

docker rm -f envfile-demo >/dev/null 2>&1; cd /lab/compose-secrets && docker compose down -v >/dev/null 2>&1; docker rmi -f leaky-app:1.0 safe-app:1.0 >/dev/null 2>&1; rm -rf /lab; echo 'cleanup done'

¿Te ha servido? No te pierdas el próximo lab

Suscríbete a la newsletter

La gestión de secretos en Docker no es opcional

Qué técnica usar según el momento

Para seguir

Preguntas frecuentes

¿Por qué no debo poner un secreto en ARG o ENV del Dockerfile?

¿Qué es un build secret de BuildKit y en qué se diferencia de ARG?

¿Es seguro usar –env-file con docker run?

¿Necesito Docker Swarm para usar los secrets de Compose?

Chuleta