cloud-doctor

Um único comando avalia toda a sua conta na nuvem — configurações incorretas, falta de observabilidade e postura de segurança, classificando as cinco coisas para corrigir primeiro.

Aponte para AWS, Cloudflare, Vercel, Supabase, Render, Fly.io ou Railway e ele retorna uma pontuação, o que está quebrado e uma correção para cada item — autossuficiente o suficiente para ser passado diretamente para um agente.

Início rápido

npx cloud-doctor

https://github.com/user-attachments/assets/60b610ab-7aee-4c3a-8d9e-83f045c8cc56

Isso escolhe um provedor, resolve sua identidade (perfil AWS, token de API, …) e executa a verificação interativamente. Para ir diretamente a um provedor:

npx cloud-doctor aws --profile prod
npx cloud-doctor cloudflare --yes
npx cloud-doctor vercel --yes

Se ~/.npmrc tiver min-release-age configurado (proteção da cadeia de suprimentos) e bloquear lançamentos recentes:

# =<número>, 0 usado como exemplo
npm x --min-release-age=0 cloud-doctor -- aws profiles

Prefere a versão mais recente? As versões alfa são publicadas com sua própria tag: npx cloud-doctor@alpha.

Provedores suportados

Os tokens de autenticação podem ser definidos como variáveis de ambiente ou você pode fornecê-los quando a interface TUI solicitar:

CLOUDFLARE_API_TOKEN=cfut_aHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g/dj1kUXc0dzlXZ1hjUQ== npx cloud-doctor cloudflare

(não decodifique o token em base64)

ou

$ npx cloud-doctor cloudflare

As credenciais do Cloudflare não estão definidas — insira-as abaixo.
Mantidas apenas para esta execução, nunca gravadas em disco. Pule estes prompts: export CLOUDFLARE_API_TOKEN

  dashboard → Meu Perfil → Tokens de API
? Token da API Cloudflare somente leitura › <input>

Em breve: Google Cloud, Kubernetes e Bancos de Dados (Postgres, MySQL, Redis) — veja O que vem a seguir.

Comandos

npx cloud-doctor                    # escolher provedor (padrão AWS) → escolher identidade → verificar
npx cloud-doctor aws                # caminho rápido para AWS
npx cloud-doctor aws --profile prod # não interativo quando não ambíguo
npx cloud-doctor aws --yes --json   # CI, saída legível por máquina
npx cloud-doctor aws --yes --json --fail-under 75  # porta de CI baseada na pontuação

npx cloud-doctor cloudflare --yes   # precisa de CLOUDFLARE_API_TOKEN
npx cloud-doctor vercel --yes       # precisa de VERCEL_TOKEN (+ VERCEL_TEAM_ID)
npx cloud-doctor supabase --yes     # precisa de SUPABASE_ACCESS_TOKEN
npx cloud-doctor render --yes       # precisa de RENDER_API_KEY
npx cloud-doctor fly --yes          # precisa de FLY_API_TOKEN (+ FLY_ORG)
npx cloud-doctor railway --yes      # precisa de RAILWAY_API_TOKEN

npx cloud-doctor aws profiles       # listar perfis em ~/.aws/config
npx cloud-doctor aws whoami         # mostrar identidade AWS resolvida

--yes pula prompts (seguro para CI); --json imprime um relatório estável e versionado por esquema em vez da visualização no terminal; --verbose imprime cada descoberta em vez dos principais problemas; --no-color desativa a saída colorida.

O que você recebe

• Uma pontuação (0–100): uma taxa de aprovação ponderada por severidade sobre todas as regras que realmente foram executadas. Erros têm mais peso do que avisos; sugestões nunca afetam a pontuação.
• As 5 principais correções, classificadas por impacto na pontuação, cada uma com o recurso afetado e uma correção concreta.
• Uma linha de verificações aprovadas, com qualquer item silenciado (desabilitado via configuração) ou indisponível (permissões ausentes) divulgado em vez de omitido silenciosamente — uma lacuna de permissão nunca é contada como aprovada.
• Se algo estiver quebrado e você estiver em um terminal interativo, o cloud-doctor pode passar o relatório diretamente para seu agente de codificação de IA — Claude Code, Codex ou Cursor, o que estiver instalado — para que ele comece a corrigir antes mesmo de você terminar de ler a saída.

As pontuações nunca são falsificadas: se zero regras puderem ser executadas, a pontuação é null com o rótulo "Nenhuma verificação foi executada", nunca um 100 vazio.

Configuração

Ajuste as regras por provedor via doctor.config.ts (ou doctor.config.json, ou cloudDoctor em package.json):

import { defineConfig } from "cloud-doctor/api";

export default defineConfig({
  defaultProvider: "aws",
  aws: {
    profile: "prod",
    regions: ["us-east-1", "eu-west-1"],
    account: "123456789012",
  },
  rules: {
    "aws/s3-unencrypted-bucket": "off",
    "aws/iam-user-access-key": "error",
  },
});

"off" desabilita uma regra; "error" / "warning" substitui sua severidade. Regras desabilitadas são removidas da pontuação e divulgadas como silenciadas — nunca subtraídas silenciosamente.

Arquitetura

Uma CLI leve sobre um registro de plugins — cada provedor implementa o mesmo contrato, então a CLI nunca trata um provedor de forma especial em relação a outro.

Cada provedor implementa CloudDoctorPlugin:

• discoverIdentities() — listar perfis/projetos/contas para o seletor
• resolveIdentity() — mapear flags/env/config para identidade, sem chamadas de rede
• validateIdentity() — provar que as credenciais funcionam (sts:GetCallerIdentity ou equivalente)
• scan() — executar as regras restritas, retornar diagnósticos + pontuação

Novos provedores são registrados em packages/plugins/src/index.ts.

O que vem a seguir

gcloud, k8s e db estão chegando em breve.

Desenvolvimento local

pnpm install
pnpm build
pnpm typecheck
pnpm test

Para verificação prática de regras sem acessar uma conta real na nuvem, o repositório inclui uma estrutura de simulação http-mock e Moto/fab: (ps: fab é a CLI para gerar o ambiente de execução, atualmente privada; o projeto de dependência também será tornado código aberto)

pnpm mock:up <cenário>                  # iniciar uma instância de simulação persistente
eval "$(pnpm -s mock:env <cenário>)"    # apontar variáveis de ambiente para ela
pnpm mock:run <cenário>                 # executar a CLI contra ela

Licença

MIT

Um agradecimento especial para react-doctor