Login Inscreva-se
3 min de leitura

PATs Granulares do GitLab: Como Limitar o Raio de Explosão de Tokens Vazados com Privilégios Mínimos

Compartilhar
a close up of a typewriter with a paper reading edge computing
Photo by Markus Winkler on Unsplash

Um único token vazado pode expor centenas de projetos. O GitLab acaba de lançar PATs granulares que limitam o dano a um único repositório. Aqui está como usar essa nova camada de defesa.

Dashboard de escopo de PATs granulares no GitLab

O Fim do Token Superprivilegiado

Até agora, um Personal Access Token (PAT) no GitLab vinha com escopos como api ou read_api — permissões que abrangiam todos os projetos acessíveis pelo usuário. Um vazamento em logs de CI, dependências contaminadas ou forks maliciosos significava exposição total.

Os novos fine-grained PATs (em beta) quebram esse padrão. Eles permitem definir exatamente a qual projeto, grupo e ação o token tem acesso. Se vazar, o atacante só consegue operar dentro daquele perímetro restrito.

Disponibilidade: A funcionalidade cobre cerca de 75% dos endpoints REST no momento. O suporte a GraphQL está em desenvolvimento.

Como Funciona a Granularidade

Diferente do modelo binário anterior, agora você combina três camadas de controle:

1. Escopo por Recurso

  • Projetos específicos — apenas os que você selecionar
  • Grupos — todos os projetos dentro de um grupo
  • Todos os projetos acessíveis — equivalente ao escopo antigo, mas agora com permissões individuais

2. Permissões por Ação (CRUD)

Para cada recurso — Issues, Merge Requests, Pipelines, Repositórios, Container Registry — você escolhe entre Read, Create, Update e Delete.

3. Auditoria Visual

A nova tabela de tokens exibe o escopo exato de cada token, incluindo projetos vinculados e permissões habilitadas. Isso elimina a necessidade de adivinhar o que um token pode fazer.

Redução Radical do Raio de Explosão

O princípio do menor privilégio ganha uma implementação prática e imediata. Compare:

  • Antes: Um job que apenas cria Issues usava um token com escopo api completo. Vazamento = acesso a todos os projetos e ações.
  • Agora: Token com escopo apenas para o Projeto X, permissão Create em Issues. Vazamento = apenas criação de Issues naquele projeto.
“A diferença entre um incidente controlado e um desastre é um PAT granular bem configurado.”
Dimensão Impacto
Segurança Redução drástica do raio de explosão em vazamentos
Auditoria Tabela de tokens permite identificar rapidamente superprivilegiados
CI/CD Jobs com tokens dedicados eliminam o uso indiscriminado de tokens totais
Concorrência GitLab se posiciona à frente de GitHub e Bitbucket nesse nível de granularidade
Adoção Empresas com requisitos de compliance (SOX, PCI-DSS) ganham argumento forte para migrar

Cuidados com o Beta: Ainda existem ~25% de endpoints REST sem granularidade; GraphQL ausente. O GitLab alerta para possíveis quebras de retrocompatibilidade. Use em produção com cautela.

Passo a Passo para Migração

Criar um Token Granular

  1. Acesse Settings → Access Tokens.
  2. Selecione Fine-grained token (beta).
  3. Defina nome, expiração e escopo de recurso: projetos pessoais, selecionados ou todos.
  4. Nas permissões, marque apenas as ações necessárias.

Exemplo prático: um job de deploy que só lê o Container Registry e aciona pipelines:

Escopo: Projeto X
Permissões:
  - Container Registry: Read
  - Pipelines: Read + Update

Usar em um Job de CI

Substitua o token antigo por uma variável protegida no .gitlab-ci.yml:

job-deploy:
  variables:
    GITLAB_TOKEN: ${CI_JOB_TOKEN}
  script:
    - curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/123/pipelines"

Nunca hardcode tokens. Prefira CI_JOB_TOKEN para operações intra-pipeline. O token granular é ideal para ações inter-projeto ou chamadas externas.

Auditar e Substituir Gradualmente

Use a nova tabela para identificar tokens com escopos amplos (api, read_api). Monte uma planilha de mapeamento para cada automação: recurso acessado e permissão mínima necessária.

Estratégia de adoção:

  • Fase 1: Tokens granulares apenas para novos jobs.
  • Fase 2: Substituição gradual de tokens antigos, começando pelos jobs menos críticos.
  • Fase 3: Migração total após GA (cobertura completa dos endpoints).

O Futuro da Gestão de Credenciais

A transição para PATs granulares reflete um movimento maior: segurança incorporada ao fluxo, não adicionada depois. O que esperar:

  • Automação inteligente: Ferramentas que analisam logs de CI e sugerem o menor escopo para cada job.
  • Policy-as-Code: Bloqueio automático de tokens com escopos excessivos no nível organizacional.
  • Métrica de Blast Radius Exposto: Dashboards que mostram a exposição máxima por projeto, incentivando a adoção.

Resumo prático: Empresas que adotarem essa granularidade desde o beta saem na frente. Um token vazado com acesso apenas a Issues é um susto. Um token com escopo total é um desastre. A escolha é sua.

Comece hoje. Crie um token granular para o seu job mais simples, com permissões mínimas. Depois expanda. Sua segurança futura agradece.

Published by:

Guilherme Zanini de Sá