Todos os artigos
176 artigos · atualizado semanalmente Veja nossas Ferramentas
Todos os artigos
Tutoriais

Boas práticas de Dockerfile: imagem segura em produção

Usuário não-root, base fixada por digest, segredos fora da imagem, scan de CVEs e multi-stage: um checklist de Dockerfile seguro para produção.

Boas práticas de Dockerfile: imagem segura em produção
COVER · Tutoriais

O Dockerfile funcionava, o build passava, a imagem subia. Aí alguém rodou docker history --no-trunc na imagem publicada e lá estava, em texto puro, o token do registry privado de pacotes: tinha entrado por um ARG NPM_TOKEN e um rm .npmrc que dava a falsa sensação de limpeza. Reproduzi o erro para este post: o token aparece no histórico da camada e ainda no docker inspect, porque também tinha virado ENV. Quem tem acesso de leitura à imagem tem o token.

Este post é sobre segurança de Dockerfile em produção: com qual usuário o processo roda, onde os segredos passam, qual base usar e como manter a imagem sem CVEs conhecidas. Tamanho de imagem tem post próprio, como reduzir o tamanho de imagens Docker; aqui ele só aparece quando ajuda a segurança. Se você ainda está no primeiro container, comece pelo Docker para iniciantes.

Por que segurança começa no Dockerfile

Cada pacote dentro da imagem é código que pode ter vulnerabilidade, e cada privilégio que o processo tem é um privilégio que o atacante herda se explorar a aplicação. O Dockerfile decide as duas coisas antes de qualquer firewall entrar em cena. É o princípio do menor privilégio, o mesmo de segurança da informação básica, aplicado à imagem: só o que roda em produção entra, e o que entra roda com o mínimo de poder.

Todos os Dockerfiles abaixo foram construídos e executados com Docker 29.7.2 em 09/11/2026, numa API Express em TypeScript, e escaneados com Trivy 0.76.2.

A imagem base: LTS suportada, fixada por digest

A base define o piso de vulnerabilidades. Três regras:

Use uma versão com suporte. O Node 20 chegou ao fim de vida em 30/04/2026; uma imagem node:20 não recebe mais correção de segurança do Node. Pelo calendário oficial de releases, o 26 é o LTS ativo desde 28/10/2026 (suporte até 30/04/2029) e o 24 está em manutenção até 30/04/2028.

Comece pela variante -slim. Debian enxuto, com glibc, compatível com quase toda dependência nativa. Alpine é menor, mas a troca de glibc por musl tem pegadinhas que o post de tamanho detalha.

Fixe por digest. Uma tag como node:26-slim é móvel: aponta para outra imagem a cada release. Para builds reproduzíveis e auditáveis, fixe o digest:

docker buildx imagetools inspect node:26-slim
# Digest: sha256:5adad64f9a1fca2d51972caa65983634c8a774eb300d72b20f7f2a0f60368072
FROM node:26-slim@sha256:5adad64f9a1fca2d51972caa65983634c8a774eb300d72b20f7f2a0f60368072

O digest acima é o de 09/11/2026 e vai mudar. Fixar não significa congelar: significa atualizar de propósito, com um PR que troca o digest (o Dependabot e o Renovate fazem isso sozinhos), em vez de herdar mudanças sem perceber.

Se quiser ir além do -slim, há bases endurecidas: as distroless do Google (gcr.io/distroless/nodejs26-debian13, sem shell nem gerenciador de pacotes, com tag :nonroot), as Docker Hardened Images, que a Docker tornou gratuitas e open source (Apache 2.0) em 17/12/2025, e as imagens da Chainguard. O preço comum a todas é não ter shell para debugar.

Multi-stage: ferramenta de build não vai para produção

Compilador, TypeScript, devDependencies e o código-fonte servem para construir, não para rodar. Com multi-stage, eles ficam num estágio que é descartado, e só o resultado entra na imagem final. Para segurança, o ganho é direto: o atacante que entrar não encontra gcc, make nem o seu src/. O Dockerfile completo está na seção de checklist; a mecânica detalhada de multi-stage está no post de tamanho.

Não rode como root

Por padrão, o processo do container roda como root (UID 0). Se a aplicação tiver uma falha de execução de código, o atacante começa com o máximo de privilégio dentro do container, e qualquer erro de configuração do host (socket do Docker montado, --privileged, volume sensível) vira caminho de fuga.

A imagem oficial do Node já tem um usuário sem privilégio, node (UID 1000). Não precisa criar outro:

COPY --from=build /app/dist ./dist
RUN mkdir -p /app/uploads && chown node:node /app/uploads
USER node

Repare no que não está aí: um chown -R na pasta inteira. Os arquivos copiados pertencem a root com permissão de leitura para todos (drwxr-xr-x), e isso é bom: o processo node lê o código e o node_modules, mas não consegue alterá-los. Testei: touch /app/dist/x falha com Permission denied. Só o diretório onde a aplicação escreve de verdade (aqui, uploads) pertence ao usuário.

O erro comum é o contrário, RUN chown -R app:app /app depois dos COPY. Além de dar ao processo permissão de reescrever o próprio código, ele duplica os arquivos numa nova camada: no meu teste, essa linha sozinha criou uma camada de 32 MB, cópia do node_modules. Quando um arquivo copiado precisa mesmo ser do usuário, use COPY --chown=node:node, que define o dono na própria cópia, sem camada extra. Para entender dono, grupo e bits de permissão, veja chmod, chown e umask; se o diretório gravável for um volume, a armadilha de UID está em volumes Docker.

No docker run (ou no Compose/Kubernetes), dá para fechar mais: --read-only monta o filesystem como somente leitura (aí uploads precisa ser um volume e /tmp um --tmpfs), --cap-drop ALL remove as capabilities do kernel e --security-opt no-new-privileges impede escalar via binários setuid. A API de teste rodou normalmente com os três.

Segredos nunca em ARG, ENV ou COPY

A documentação do Docker é explícita: build args e variáveis de ambiente não servem para segredos, porque persistem na imagem final. No meu teste com ARG NPM_TOKEN:

docker history --no-trunc api:ruim
# RUN |1 NPM_TOKEN=FAKE-TOKEN-123 /bin/sh -c echo "//npm.acme.example/:_authToken=${NPM_TOKEN}" > .npmrc ...

docker inspect api:ruim --format '{{.Config.Env}}'
# [... NPM_TOKEN=FAKE-TOKEN-123]

O rm .npmrc no fim do RUN não adianta nada: o valor já está gravado no metadado da camada. COPY .npmrc é pior ainda, porque o arquivo vai inteiro para uma camada. O jeito certo é o secret mount do BuildKit, que monta o arquivo só durante aquele RUN e não grava em lugar nenhum:

RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    npm ci
docker build --secret id=npmrc,src=$HOME/.npmrc -t api:segura .

Sem target, o segredo aparece em /run/secrets/<id>; com env=NOME, vira variável de ambiente só naquele comando. Conferi a imagem resultante como root: /root/.npmrc não existe e o token não aparece no histórico. Complete com um .dockerignore que exclua .env, .npmrc e .git, para nenhum COPY . . levar segredo junto. Segredo de runtime (senha do banco, chave de API) também não vai na imagem: entra por variável de ambiente ou secret do orquestrador na hora de subir o container.

Escaneie a imagem e atualize a base

Imagem segura hoje acumula CVEs amanhã. Scan na pipeline, com o Trivy rodando no próprio Docker:

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  aquasec/trivy image --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 api:segura

O --exit-code 1 quebra o build quando há achado; o --ignore-unfixed filtra o que ainda não tem correção publicada, para o alarme ser acionável. Os números de 09/11/2026 mostram por que a base importa:

Imagem HIGH/CRITICAL Com correção disponível
node:26 (completa) 286 10
api:segura (node:26-slim) 54 8
api:distroless (nodejs26-debian13:nonroot) 0 0

Nos 8 corrigíveis da imagem slim, 2 eram do zlib do Debian e 6 do undici e do brace-expansion empacotados dentro do próprio npm, que a imagem de runtime nem usa. É o argumento mais concreto que conheço para distroless: ela não traz npm. O Docker Scout faz o mesmo papel (docker scout cves), mas exige login no Docker Hub.

A outra metade é rebuild periódico. Correção de CVE na base só chega na sua imagem quando você reconstrói: docker build --pull semanal no CI, ou o PR automático de digest do Renovate, resolvem.

Checklist de Dockerfile seguro

O Dockerfile que construí, rodei e escaneei:

# syntax=docker/dockerfile:1
FROM node:26-slim AS build
WORKDIR /app
COPY package*.json ./
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    npm ci
COPY . .
RUN npm run build

FROM node:26-slim AS runtime
ENV NODE_ENV=production
WORKDIR /app
COPY package*.json ./
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    npm ci --omit=dev && npm cache clean --force
COPY --from=build /app/dist ./dist
RUN mkdir -p /app/uploads && chown node:node /app/uploads
USER node
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD ["node", "-e", "fetch('http://localhost:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
CMD ["node", "dist/server.js"]

O HEALTHCHECK usa o fetch do próprio Node porque a imagem slim não tem curl; depois de 30 segundos o docker ps mostrou (healthy). Em produção, troque as duas linhas FROM pela versão com digest. O checklist:

  1. Base em versão LTS com suporte, variante -slim ou endurecida.
  2. Base fixada por digest, atualizada por PR automático.
  3. Multi-stage: build tools e código-fonte fora da imagem final.
  4. USER não-root (node já existe na imagem oficial).
  5. Código pertencente a root e só leitura; COPY --chown apenas no que a aplicação escreve; nada de chown -R.
  6. Segredos de build só com RUN --mount=type=secret; nunca ARG, ENV ou COPY.
  7. .dockerignore com .env, .npmrc, .git.
  8. Scan com Trivy ou Docker Scout no CI, quebrando o build em HIGH/CRITICAL corrigível.
  9. Rebuild periódico com --pull.
  10. No runtime: --read-only, --cap-drop ALL, no-new-privileges quando a aplicação aguentar.

Perguntas frequentes

Como passar segredos no build do Docker?

Com o secret mount do BuildKit: RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci no Dockerfile e docker build --secret id=npmrc,src=$HOME/.npmrc . na linha de comando. O arquivo existe só durante aquele RUN e não fica em nenhuma camada. ARG e ENV ficam gravados no histórico e no metadado da imagem, mesmo que você apague o arquivo depois.

Por que não devo rodar o container como root?

Porque qualquer falha explorável na aplicação entrega ao atacante privilégio máximo dentro do container, o que facilita alterar o código em execução e explorar erros de configuração do host. Com USER node e arquivos de código pertencentes a root, o processo nem consegue reescrever a própria aplicação.

Distroless ou slim?

Slim para começar: tem shell, então dá para debugar com docker exec. Distroless quando a imagem estabilizar e você quiser zerar a superfície: no meu teste, foi de 54 achados HIGH para nenhum. Para debugar distroless existe a tag :debug, com um shell busybox, que você usa só fora de produção.

Fixar por digest não me impede de receber correções de segurança?

Impede de recebê-las sem saber, que é o objetivo. A tag móvel também não atualiza sozinha uma imagem já construída; ela só muda o que o próximo build puxa, sem registro. Com digest, cada atualização é um PR com diff visível, e o scan da pipeline diz se ela resolveu alguma CVE.

Imagem segura é a que roda com o mínimo

Segurança de Dockerfile se resume a tirar coisas: tirar o root do processo, tirar os segredos das camadas, tirar as ferramentas de build da imagem final, tirar a base sem suporte. O que sobra precisa ser vigiado, com scan no CI e rebuild periódico, porque a CVE de amanhã aparece numa imagem que hoje está limpa. Comece pelo USER node e pelo secret mount, que custam duas linhas, e coloque o Trivy na pipeline antes de pensar em distroless.

O conteúdo editorial termina aqui. Quando preciso decidir o modo de um diretório gravável no container (750? 770?) e conferir o que cada bit libera para dono, grupo e outros, uso a calculadora chmod do Quick Tools.

RD
Autor
Rafael Duarte
Desenvolvedor backend com passagem por fintech e SaaS B2B — trabalhou em times que escalaram APIs de zero a milhões de requisições. Carrega cicatrizes de produção suficientes para ter opiniões fortes sobre ferramentas, padrões e decisões de arquitetura. Não é acadêmico: leu a RFC do UUID quando precisou escolher entre v4 e v7 para uma tabela de alta escrita.
Ver perfil