vitwit/portão-de-segurança-de-implantação

Portão de segurança de implantação

Esta skill impõe uma lista de verificação: nenhuma chave é jamais exposta, e nenhuma falha única derruba o produto. Ela funciona em três passadas:

1. Uma varredura automatizada com scripts/scan.py, que é rápida, determinística e somente leitura.
2. Uma revisão de código de cada integração detectada, guiada por references/integrations.md.
3. Um portão manual para tudo que não pode ser visto no repositório, como painéis de provedores, rotação, backups e testes de recuperação. Esses itens vêm de references/checklist.md.

A varredura sozinha não é uma aprovação. Ela cobre aproximadamente um terço da lista de verificação. O valor desta skill está em percorrer todas as três passadas e ser honesto sobre o que foi verificado e o que ainda precisa de confirmação humana.

Fluxo de trabalho

1. Escopo

Descubra o que está sendo enviado:

• a raiz do repositório
• a saída da build de frontend ou mobile, se houver
• o destino da implantação, como contêineres, serverless ou Kubernetes
• se esta é uma primeira implantação, uma nova integração ou manutenção de rotina

Se o usuário nomeou uma alteração específica, como "adicionando Stripe", concentre a revisão nela. Ainda assim, execute a varredura completa, porque um vazamento em outro lugar bloqueia a liberação da mesma forma.

2. Executar a varredura

python3 <skill-dir>/scripts/scan.py <repo> --history

• Adicione --build-dir <dir> para cada bundle compilado (dist, .next/static, um APK/IPA descompactado). Bundles enviados é onde chaves "públicas" se revelam secretas. Diretórios de build comuns são detectados automaticamente; compile o aplicativo primeiro se nenhum existir.
• --entropy adiciona uma passada de alta entropia que captura segredos personalizados que nenhum padrão nomeado conhece (severidade baixa; verifique cada um antes de relatar).
• --format json ou --format sarif fornecem saída legível por máquina; SARIF pode ser enviado para varredura de código do GitHub. --fail-on high|medium|low|never controla o código de saída, que é útil em CI.
• Falsos positivos confirmados podem ser suprimidos com um comentário inline # security-gate: allow ou um arquivo .security-gate-ignore na raiz do repositório (veja o README). Prefira suprimir descobertas específicas a diminuir --fail-on.
• A varredura mascara valores secretos. Mantenha isso em tudo que você escrever: nunca ecoe uma chave completa no chat, arquivos, commits ou texto de PR, porque isso cria um segundo vazamento.

A varredura verifica:

• padrões de segredos (AWS, Anthropic, OpenAI, OpenRouter, Groq, xAI, Perplexity, Replicate, fal, chaves de API do Google e segredos OAuth, chaves ao vivo do Stripe e segredos de webhook, Razorpay, GitHub, GitLab, tokens do Slack e tokens de aplicativos, contas de serviço do GCP, npm, PyPI, SendGrid, Hugging Face, DigitalOcean, New Relic, Shopify, Square, Databricks, Doppler, PlanetScale, Linear, chaves de armazenamento do Azure, Mailgun, Telegram, webhooks do Discord, JWTs, chaves privadas, URLs de banco de dados com senhas, atribuições de *_SECRET / *_TOKEN / *_SERVICE_ROLE codificadas — citadas (incluindo JSON/configs MCP) ou não citadas) na árvore de trabalho, saída da build e histórico do git
• com --entropy, strings de alta entropia que não correspondem a nenhum formato conhecido (segredos personalizados ou novos)
• arquivos .env commitados e uma entrada gitignore ausente
• variáveis de aparência secreta por trás de prefixos expostos ao cliente (NEXT_PUBLIC_, VITE_, REACT_APP_, EXPO_PUBLIC_ e similares), e chamadas LLM diretas do código do cliente
• source maps na saída da build
• workflows do GitHub Actions: ações fixadas por tag, pull_request_target, bloco permissions: ausente, segredos ecoados, segredos escritos em arquivos ou $GITHUB_ENV / $GITHUB_OUTPUT, chaves estáticas de nuvem em vez de OIDC, e instalações que executam scripts de ciclo de vida
• Dockerfiles: segredos em ARG/ENV, arquivos .env copiados, e execução como root
• manipuladores de webhook de pagamento sem verificação de assinatura
• acesso de leitura do agente de codificação a arquivos .env
• as integrações em uso, além de dicas de provedor único (ponto único de falha) para IA e pagamentos

3. Triagem das descobertas

A varredura funciona por correspondência de padrões, então confirme cada descoberta lendo o código antes de relatá-la.

• Segredo ativo encontrado (na árvore, histórico ou um bundle): trate como vazado mesmo se o repositório for privado. Siga references/leaked-key-runbook.md, onde revogar vem primeiro e a limpeza vem depois. Revogar ou rodar uma chave altera a produção, então diga ao usuário exatamente qual chave, onde foi encontrada e a etapa de revogação. Deixe que eles façam, ou confirme antes de fazer qualquer coisa você mesmo.
• Falso positivo (um fixture de teste, uma chave pública documentada): diga por que é seguro e siga em frente.
• Descobertas heurísticas (verificação de webhook, chamada LLM do lado do cliente): abra o arquivo e verifique o fluxo de controle real. A verificação pode estar em middleware em outro lugar.

4. Revisar cada integração detectada

Para cada integração que a varredura listou, ou que você encontrar no código, leia a seção correspondente de references/integrations.md e verifique o código em relação a ela. Esta etapa captura o que os padrões não conseguem, como:

• um proxy de backend que é um relay aberto
• um nome de modelo obtido do corpo da requisição
• valores calculados no cliente
• chamadas de ferramenta que são executadas com credenciais de administrador
• PII enviada para análises
• consultas RAG sem um filtro de locatário
• injeção de prompt indireta: documentos, páginas web, transcrições ou resultados de ferramentas que o modelo lê sendo tratados como instruções (lista de verificação 3.17)
• uploads de arquivos analisados sem verificações de tipo/tamanho/arquivo compactado ou um sandbox (3.18)
• SSRF: um *_url que o modelo ou uma ferramenta busca sem bloqueio para endereços privados ou de metadados (3.19)

As verificações de webhook, cliente-LLM e segredo são heurísticas: a varredura sinaliza candidatos, mas pode perder um controle escrito à mão ou um layout não padrão. Sempre confirme lendo o código — um webhook verificado com createHmac + timingSafeEqual, ou um backend que por acaso está em src/, está ok mesmo se uma ferramenta sinalizar ou perder.

5. Verificar pontos únicos de falha

Use a seção 10 da lista de verificação e procure no código e IaC por:

• um provedor LLM sem fallback
• clientes HTTP para fornecedores sem timeout ou retry
• chamadas de fornecedor no caminho da requisição que bloqueiam quando a análise está fora do ar
• um banco de dados de região ou zona única
• uma busca de segredos sem cache
• uma pessoa que sozinha detém acesso root ou proprietário, de acordo com o que o usuário lhe disser

6. Portão manual

Muitos itens da lista de verificação não podem ser verificados a partir de um repositório, por exemplo:

• limites de gastos em painéis de provedores
• cronogramas de rotação
• SSO e MFA em contas de fornecedores
• testes de restauração de backup
• testes de failover
• DPAs
• inventário de script PCI em páginas de pagamento

Liste esses como Precisa de confirmação, cada um com uma pergunta de uma linha para o proprietário. Nunca os marque como aprovados por suposição. Um portão que silenciosamente aprova itens não verificados é pior do que nenhum portão.

7. Relatório

Use esta estrutura para que os resultados sejam comparáveis entre versões:

# Portão de segurança: <produto / alteração> — <GO | NO-GO | GO COM EXCEÇÕES>

## Bloqueadores (devem ser corrigidos antes de implantar)
- [id da verificação] arquivo:linha — o que está errado — a correção

## Deve corrigir (nesta sprint)
- ...

## Integrações revisadas
| Integração | Apenas no servidor | Chave com escopo + limite de gasto | Webhooks/saídas verificados | Fallback | Observações |

## Precisa de confirmação (manual)
- [ ] <pergunta para o proprietário> (lista de verificação §n)

## Aprovado (verificado)
- <item> — como foi verificado

Regra de veredito:

• NO-GO: qualquer descoberta ALTA confirmada, que cobre um segredo ativo, uma chave secreta exposta ao cliente, um webhook de pagamento não verificado ou um segredo em logs de CI.
• GO COM EXCEÇÕES: apenas descobertas médias ou baixas permanecem, e o usuário as aceita com um proprietário e uma data.
• GO: nada em aberto, e cada item manual foi confirmado.

Corrigindo problemas

Quando o usuário pedir para corrigir descobertas, prefira estas soluções, que abordam a causa raiz em vez do sintoma:

• Chave no código: substitua por uma busca em tempo de execução, seja de env injetado pelo gerenciador de segredos ou através do SDK do provedor. Adicione um placeholder a .env.example. Nunca escreva o valor real em lugar nenhum. Diga ao usuário que a chave ainda precisa ser revogada, porque removê-la do código não a desvaza.
• Segredo alcançando o cliente: mova a chamada para uma rota de backend ou gateway de IA que autentique o usuário, limite a taxa por usuário e locatário, coloque modelos e operações na lista de permissões e detenha a chave. Mantenha apenas chaves publicáveis no cliente.
• Webhook não verificado: verifique a assinatura no corpo bruto com o SDK do provedor. Rejeite timestamps obsoletos, desduplique por ID de evento e busque novamente o objeto do provedor antes de alterar o estado.
• Problemas de CI: fixe ações a SHAs de commit (resolva o SHA com git ls-remote, mantenha a tag em um comentário). Adicione permissions: contents: read. Substitua chaves estáticas de nuvem por OIDC. Use npm ci --ignore-scripts.
• Problemas de Docker: use RUN --mount=type=secret do BuildKit para segredos em tempo de build e um USER não root.
• Acesso do agente: adicione entradas permissions.deny Read(./.env) e Read(./.env.*) a .claude/settings.json. Recomende injeção em tempo de execução (doppler run, infisical run, op run) para que nenhum arquivo de texto simples exista.

Uso contínuo

Sugira conectar a varredura ao CI para que o portão seja executado em todo PR, não apenas na implantação:

- run: python3 tools/deploy-security-gate/scripts/scan.py . --fail-on high

Sugira também uma revisão recorrente na cadência da seção 12 da lista de verificação.

Arquivos de referência

• references/checklist.md: a lista de verificação completa (seções 1–14), com cada item marcado como [auto] (varredura), [code] (revisão de código) ou [manual] (proprietário confirma). Leia para as etapas 5–6 e sempre que precisar do controle exato.
• references/integrations.md: como é a aparência do bom para gateways de IA e provedores LLM, servidores MCP, pagamentos, análises e autenticação, com padrões a serem procurados. Leia as seções para as integrações no escopo.
• references/leaked-key-runbook.md: a resposta passo a passo quando uma chave ativa é encontrada, com ponteiros de revogação por provedor.