Guia de Docker build secrets: desenvolvimento seguro de imagens de contêiner

Já vi inúmeras imagens Docker expostas sem querer, com chaves de API, senhas de banco e tokens de autenticação hardcoded nas camadas. Essas falhas de segurança costumam acontecer durante o processo de build, quando desenvolvedores precisam de acesso temporário a recursos privados, mas acabam incluindo credenciais na imagem final.

O problema é que abordagens tradicionais para lidar com credenciais em builds, como variáveis de ambiente ou argumentos de build, não foram feitas para uso efêmero. Elas deixam rastros permanentes nos metadados ou nas camadas da imagem, criando vulnerabilidades que persistem muito depois que o build termina. Surge então o dilema: como autenticar em recursos privados durante o build sem comprometer a segurança?

Docker build secrets resolvem esse desafio crítico ao permitir o uso de dados sensíveis durante o build sem deixar vestígios no artefato final. 

Neste tutorial, vou mostrar como implementar build secrets de forma eficaz, dos conceitos básicos à integração avançada com CI/CD, garantindo que seus builds de contêiner permaneçam seguros.

Se você é novo em Docker, recomendo fazer um dos nossos cursos, como Introduction to Docker, Containerization and Virtualization with Docker and Kubernetes ou Intermediate Docker. 

O que são Docker build secrets?

Vamos começar entendendo o que torna os build secrets diferentes de outras abordagens de gerenciamento de credenciais. Docker build secrets são informações sensíveis e efêmeras, disponibilizadas durante o processo de build, mas nunca armazenadas nas camadas ou no sistema de arquivos da imagem. Elas existem apenas em memória durante etapas específicas de build e desaparecem assim que essas etapas terminam.

A necessidade de build secrets vem dos fluxos modernos de desenvolvimento de aplicações. 

Com frequência você precisa autenticar em repositórios privados de pacotes, clonar repositórios Git privados, baixar softwares licenciados ou acessar APIs internas durante o build. 

Sem build secrets, desenvolvedores recorrem a gambiarras perigosas, como hardcode de credenciais em Dockerfiles, passagem de secrets como argumentos de build (que persistem nos metadados da imagem) ou criação de imagens base permissivas demais, com credenciais embutidas.

Os riscos de tratar secrets de forma inadequada são enormes. Credenciais expostas podem levar a acessos não autorizados a ambientes de produção, vazamento de dados, violações de compliance e danos reputacionais significativos. Cenários comuns de vazamento incluem chaves de API para gerenciadores de pacotes, chaves SSH para operações Git, tokens de autenticação para serviços internos e credenciais de banco para migrações em tempo de build.

Docker BuildKit: a base para build secrets seguros

Antes de implementar, é importante entender o BuildKit, o mecanismo moderno de build que viabiliza secrets com segurança. O BuildKit é o builder de próxima geração do Docker, que substituiu o mecanismo clássico, trazendo grandes avanços em performance, cache e segurança.

O BuildKit usa um modelo de execução baseado em grafo que rastreia dependências entre etapas. Essa arquitetura permite montar secrets como sistemas de arquivos temporários que existem apenas durante instruções RUN específicas, garantindo que nunca façam parte das camadas da imagem. 

Diferente dos builds clássicos do Docker, em que tudo no contexto de build entra no cache, o BuildKit trata secrets como recursos especiais que ignoram totalmente o cache de camadas.

Ativar o BuildKit é simples. No Docker 23.0 e superiores, ele já é o builder padrão. Em versões anteriores, defina a variável de ambiente DOCKER_BUILDKIT=1 antes de rodar comandos de build:

export DOCKER_BUILDKIT=1
docker build -t myapp .

Como alternativa, ative-o permanentemente configurando o daemon do Docker ou usando o Docker Buildx, que sempre utiliza o BuildKit. A diferença-chave entre builds clássicos e builds com BuildKit é que, nos clássicos, secrets persistem em camadas intermediárias se não forem bem gerenciados, enquanto o BuildKit garante que secrets sejam efêmeros e nunca gravados em disco como parte da imagem.

Com a base segura do BuildKit estabelecida, vamos explorar os tipos de secrets que ele suporta e como implementar cada um com eficácia.

Tipos e implementação de Docker build secrets

O BuildKit suporta três mecanismos principais para lidar com secrets durante os builds, cada um pensado para casos de uso específicos. Entender quando usar cada tipo garante segurança e funcionalidade ideais.

Secret mounts: dados sensíveis de uso geral

Secret mounts oferecem a abordagem mais flexível para lidar com dados sensíveis durante o build. Eles permitem montar secrets como arquivos em caminhos específicos durante instruções RUN, disponibilizando credenciais para comandos de build sem persistir nas camadas.

O processo tem duas etapas: passar o secret para o comando de build e montá-lo no Dockerfile. Primeiro, crie um arquivo de secret localmente ou use uma variável de ambiente. Depois, faça referência a ele durante o build:

docker build --secret id=api_key,src=./api_key.txt -t myapp .

No Dockerfile, monte o secret na instrução RUN que precisa dele:

RUN --mount=type=secret,id=api_key \
    API_KEY=$(cat /run/secrets/api_key) && \
    curl -H "Authorization: Bearer $API_KEY" https://api.example.com/package > /app/data.json

Por padrão, os secrets são montados em /run/secrets/<id>, mas você pode definir um destino customizado usando o parâmetro target. 

Boas práticas: monte secrets apenas nas RUN que realmente precisam deles, nunca copie secrets para o sistema de arquivos da imagem e use builds multi-stage para separar as etapas que exigem secrets da imagem final. 

A fonte pode ser um caminho de arquivo, ou use env para passar secrets de variáveis de ambiente: --secret id=token,env=API_TOKEN.

Para montar um secret como variável de ambiente em vez de arquivo, use a opção env:

RUN --mount=type=secret,id=db_user,env=DB_USER \
    --mount=type=secret,id=db_password,env=DB_PASSWORD \
    ./setup-database.sh

Você pode usar as opções target e env juntas para montar um secret tanto como arquivo quanto como variável de ambiente. 

Boas práticas: monte secrets apenas nas RUN necessárias, nunca copie secrets para o filesystem da imagem e utilize multi-stage para separar etapas com secrets das imagens finais.

SSH mounts: acesso seguro a recursos privados

SSH mounts lidam especificamente com autenticação via SSH, principalmente para acessar repositórios Git privados durante o build. Em vez de copiar chaves SSH para a imagem (um pesadelo de segurança), SSH mounts fornecem acesso temporário ao seu agente SSH durante o build.

Para usar SSH mounts, garanta que seu agente SSH esteja rodando localmente com as chaves necessárias carregadas. Depois, referencie o mount SSH no Dockerfile:

RUN --mount=type=ssh \
    git clone git@github.com:myorg/private-repo.git /app

Faça o build com o encaminhamento SSH habilitado:

docker build --ssh default -t myapp .

Para múltiplos hosts com chaves diferentes, você pode especificar mounts SSH nomeados:

RUN --mount=type=ssh,id=github \
    git clone git@github.com:myorg/repo.git

Depois, forneça chaves específicas durante o build:

docker build --ssh github=$HOME/.ssh/github_key -t myapp .

Você vai perceber que essa abordagem mantém a segurança ao nunca expor chaves privadas na imagem, enquanto permite acesso autenticado a repositórios privados durante o processo de build.

Autenticação Git para contextos remotos

Quando seu build do Docker precisa acessar repositórios Git privados, seja como o próprio contexto de build ou ao buscar dependências, é preciso autenticar sem embutir credenciais. Isso é comum ao construir a partir de uma URL de repositório privado ou usar ADD para buscar código privado.

O BuildKit fornece dois secrets predefinidos para autenticação Git: GIT_AUTH_TOKEN e GIT_AUTH_HEADER. Eles são secrets de "pré-checagem", que autenticam o builder antes de qualquer instrução do Dockerfile executar, protegendo o fetch inicial do repositório.

O padrão mais comum usa GIT_AUTH_TOKEN para autenticação HTTPS baseada em token:

GIT_AUTH_TOKEN=$(cat ~/.github-token) docker build \
    --secret id=GIT_AUTH_TOKEN \
    https://github.com/myorg/private-repo.git

Isso funciona perfeitamente com instruções ADD que buscam repositórios privados:

FROM alpine
ADD https://github.com/myorg/private-configs.git /configs

Em ambientes efêmeros de CI/CD, injete tokens do cofre de secrets da sua plataforma:

- name: Build from private repo
  env:
    GIT_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    docker build --secret id=GIT_AUTH_TOKEN https://github.com/myorg/app.git

O secret GIT_AUTH_HEADER oferece uma alternativa para esquemas de autenticação customizados quando o token padrão não é suficiente.

Como usar Docker build secrets

Agora que vimos os tipos de build secrets, vamos explorar como implementá-los de forma eficaz em cenários reais.

Criando e organizando secrets para o build

Uma preparação adequada é crucial para a segurança. Armazene secrets em arquivos fora do contexto de build do Docker, garanta que estejam no .gitignore e .dockerignore e use permissões restritivas (600 ou 400).

Para múltiplos secrets, crie um diretório dedicado:

mkdir -p .secrets
echo "my-api-key" > .secrets/api_key
chmod 600 .secrets/*

Depois, referencie-os durante os builds:

docker build \
    --secret id=api_key,src=.secrets/api_key \
    --secret id=db_password,src=.secrets/db_password \
    -t myapp .

Para secrets baseados em variáveis de ambiente, comuns em CI/CD:

docker build \
    --secret id=api_key,env=API_KEY \
    --secret id=db_pass,env=DB_PASSWORD \
    -t myapp .

Integração com builds multi-stage

Builds multi-stage ficam ainda mais poderosos com build secrets. Use secrets nas primeiras etapas para buscar dependências e depois copie apenas os artefatos necessários para a etapa final:

# Etapa de build - secrets usados aqui
FROM python:3.11 AS builder
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=secret,id=api_key \
    API_KEY=$(cat /run/secrets/api_key) && \
    curl -H "Authorization: Bearer $API_KEY" https://api.company.com/data.json -o data.json && \
    pip install -r requirements.txt

# Etapa final - sem secrets
FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY --from=builder /app/data.json ./data.json
COPY . .
CMD ["python", "app.py"]

Isso garante que os secrets existam apenas durante a etapa builder e nunca apareçam na imagem final.

Builds multi-stage lidam muito bem com um único secret, mas aplicações reais costumam exigir mais complexidade. 

Vamos ver como gerenciar cenários com múltiplos secrets ou requisitos de build mais intrincados

Lidando com múltiplos secrets e cenários complexos

Builds complexos muitas vezes exigem vários secrets na mesma instrução RUN. O BuildKit suporta montar múltiplos secrets simultaneamente:

RUN --mount=type=secret,id=api_key \
    --mount=type=secret,id=db_password \
    API_KEY=$(cat /run/secrets/api_key) && \
    DB_PASS=$(cat /run/secrets/db_password) && \
    ./configure.sh

Para cenários que exigem secrets em múltiplos comandos, combine-os em uma única RUN para minimizar mounts de secrets enquanto mantém limites de segurança.

Boas práticas de segurança para Docker build secrets

Implementar build secrets corretamente requer seguir práticas consolidadas de segurança. Compartilho aqui os padrões que considero mais eficazes para manter a segurança durante todo o processo de build.

Prevenindo exposição e vazamento de secrets

Depois de construir a imagem, verifique se não houve vazamento inspecionando as camadas:

docker history myapp:latest
docker save myapp:latest | tar -x

Examine as camadas extraídas em busca de dados sensíveis. Além disso, diferencie secrets de build (temporários, usados no build) de secrets de runtime (necessários quando os contêineres rodam). Nunca use build secrets para credenciais de runtime. Em vez disso, use Docker secrets, secrets do Kubernetes ou variáveis de ambiente injetadas em runtime.

Sempre adicione arquivos de secret ao .gitignore:

# .gitignore
.secrets/
*.key

E ao .dockerignore para evitar inclusão acidental no contexto de build:

# .dockerignore
.secrets/
*.key
.env

Gerenciando secrets em ambientes de CI/CD

Plataformas de CI/CD oferecem gerenciamento nativo de secrets que se integra perfeitamente aos Docker build secrets. No GitHub Actions:

- name: Build Docker image
  env:
    API_KEY: ${{ secrets.API_KEY }}
  run: |
    docker build \
      --secret id=api_key,env=API_KEY \
      -t myapp .

O princípio é usar os cofres de secrets da plataforma, e não armazená-los em repositórios. Secrets de CI/CD são injetados como variáveis de ambiente, que o BuildKit consome diretamente via tipo de fonte env.

Permissões e controle de acesso de secrets

Ao construir como usuário não root, garanta que os arquivos de secret tenham permissões de leitura adequadas. Se o seu Dockerfile usa USER para alternar para um usuário não root, monte secrets em locais acessíveis a esse usuário:

FROM python:3.11-slim
RUN useradd -m appuser
USER appuser

RUN --mount=type=secret,id=token,uid=1000 \
    cat /run/secrets/token > /dev/null

Para reforçar a conformidade, implemente estratégias de rotação de secrets. Use tokens de curta duração sempre que possível, automatize a rotação nos pipelines de CI/CD e mantenha trilhas de auditoria do uso de secrets. 

Considere secrets com data de expiração e processos de renovação automática para reduzir janelas de exposição.

Até aqui, focamos em builds de um único contêiner, mas aplicações modernas costumam ter vários serviços. Veja como o Docker Compose amplia as capacidades de build secrets para arquiteturas multi-serviço.

Integrando build secrets com Docker Compose

O Docker Compose simplifica o gerenciamento de build secrets em aplicações com múltiplos serviços. No docker-compose.yml, defina secrets no nível superior e faça referência a eles nas configurações de build do serviço:

services:
  app:
    build:
      context: .
      secrets:
        - api_key
        - db_password
  
secrets:
  api_key:
    file: ./.secrets/api_key
  db_password:
    environment: DB_PASSWORD

Depois, no Dockerfile, monte os secrets como de costume:

RUN --mount=type=secret,id=api_key \
    --mount=type=secret,id=db_password \
    ./setup.sh

Faça o build com o Compose:

docker-compose build

Esse padrão escala bem para aplicações com vários serviços que exigem secrets diferentes, mantendo o gerenciamento centralizado e preservando os limites de segurança entre serviços.

Ao implementar build secrets nos seus projetos, é provável que você encontre alguns problemas. Vamos abordar os desafios mais comuns e suas soluções para ajudar você a fazer troubleshooting com eficiência.

Desafios comuns e troubleshooting

Mesmo com a implementação correta, alguns desafios vão aparecer. Aqui estão os problemas mais comuns e como resolvê-los.

Erros de sintaxe e problemas na declaração de mounts

A sintaxe de --mount é rígida. Erros comuns incluem vírgulas ausentes entre parâmetros, nomes incorretos de parâmetros e tipos de mount errados. A sintaxe correta é:

RUN --mount=type=secret,id=secret_name,target=/path \
    command

Se o build falhar com "secret not found", verifique se o BuildKit está habilitado e se o ID no Dockerfile corresponde ao --secret id no comando de build.

Secrets indisponíveis ou não encontrados

Quando os secrets não estão acessíveis, verifique se o arquivo de origem existe e tem leitura:

cat .secrets/api_key
docker build --secret id=api_key,src=.secrets/api_key .

Para variáveis de ambiente, confirme se estão definidas:

echo $API_KEY
docker build --secret id=api_key,env=API_KEY .

Confusão entre variável de ambiente e arquivo

Com build secrets, por padrão os secrets são montados como arquivos em /run/secrets/<id>. Para usá-los como variáveis de ambiente, leia o conteúdo do arquivo:

RUN --mount=type=secret,id=token \
    export TOKEN=$(cat /run/secrets/token) && \
    curl -H "Authorization: Bearer $TOKEN" https://api.example.com

Nunca use argumentos de build (ARG) para secrets, pois eles persistem nos metadados da imagem.

Persistência e problemas de cache de camadas

Secrets não persistem entre instruções RUN por design. Se múltiplas RUN precisarem do mesmo secret, combine os comandos ou remonte o secret:

RUN --mount=type=secret,id=token \
    command1

RUN --mount=type=secret,id=token \
    command2

O BuildKit garante que secrets nunca entrem no cache de camadas.

Depois de dominar o básico e o troubleshooting comum, você pode se deparar com cenários que exigem abordagens mais sofisticadas. Vamos ver casos de uso avançados e edge cases que vão além do padrão.

Usos avançados de Docker build secrets

Para cenários de implantação complexos, você vai precisar considerar pontos adicionais além da implementação básica.

Secrets em pipelines de CI/CD complexos

Pipelines multi-stage de CI/CD frequentemente exigem secrets em estágios distintos. Implemente secrets específicos por estágio em vez de compartilhar credenciais. Use os recursos de escopo de secrets da plataforma de CI/CD, limitando quais estágios podem acessar quais secrets. Automatize a limpeza após os builds para reduzir janelas de exposição.

Secrets com builders que não são Docker

Builders alternativos como Buildah e Kaniko têm níveis diferentes de suporte à sintaxe de secrets do BuildKit. O Buildah suporta montagem semelhante via --secret flags. O Kaniko, pensado para Kubernetes, usa mecanismos distintos, tipicamente secrets do Kubernetes montados como volumes. Ao usar builders não Docker, consulte a documentação específica, pois as implementações variam bastante.

Secrets e conformidade de segurança

Build secrets estão alinhados a frameworks de conformidade por fornecer acesso a credenciais de forma auditável e efêmera. 

Para GDPR, garanta que secrets não vazem informações pessoais nas camadas. Requisitos SOC2 se beneficiam de trilhas de auditoria de secrets — registre quando os secrets são usados e por quem. Mantenha registros de acesso para auditorias de conformidade.

Rotação e atualização de secrets

Estabeleça processos para rotacionar secrets sem interromper os builds. Use arquivos versionados de secrets ou convenções de nomes de variáveis que permitam alternar entre versões. 

Implemente rotação automatizada nos pipelines de CI/CD, onde secrets são atualizados a partir de cofres centrais. Para tokens com data de expiração, monitore o vencimento e automatize o processo de renovação.

Conclusão: boas práticas e recomendações

Docker build secrets representam um avanço essencial de segurança para o desenvolvimento de aplicações conteinerizadas. Ao longo deste tutorial, vimos como implementar secrets com segurança, de mounts básicos a integrações complexas com CI/CD.

Os principais pontos são simples: sempre use os mecanismos de montagem de secrets do BuildKit em vez de argumentos de build ou credenciais hardcoded, implemente builds multi-stage para isolar etapas que usam secrets das imagens finais, aproveite o gerenciamento de secrets da sua plataforma de CI/CD para automatizar fluxos e audite regularmente as imagens para verificar se nenhum secret vazou para as camadas.

Para organizações que vão adotar essas práticas, comece com uma política de gerenciamento de secrets definindo quais precisam de acesso em tempo de build, estabeleça cronogramas de rotação automatizada, implemente testes abrangentes para verificar que secrets não persistem nas imagens e treine os times de desenvolvimento sobre os padrões corretos de manuseio. Ao tratar build secrets como um componente crítico de segurança, você reduz significativamente a superfície de ataque e constrói aplicações conteinerizadas mais seguras.

Para continuar aprendendo, recomendo estes recursos:

• Docker for Data Science Cheat Sheet
• Run a Docker Image as a Container: A Practical Beginner’s Guide
• Top 18 Docker Commands to Build, Run, and Manage Containers
• Containerization: Docker and Kubernetes for Machine Learning