cloud-doctor

Un solo comando evalúa toda tu cuenta en la nube: configuraciones incorrectas, falta de observabilidad y postura de seguridad, clasificadas por las cinco cosas que arreglar primero.

Apúntalo a AWS, Cloudflare, Vercel, Supabase, Render, Fly.io o Railway y devuelve una puntuación, lo que está mal y una solución para cada problema, todo lo suficientemente autocontenido como para pasarlo directamente a un agente.

Inicio rápido

npx cloud-doctor

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

Eso elige un proveedor, resuelve tu identidad (perfil de AWS, token de API, …) y ejecuta el escaneo de forma interactiva. Para ir directamente a un proveedor:

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

Si ~/.npmrc tiene configurado min-release-age (protección de la cadena de suministro) y bloquea versiones recién publicadas:

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

¿Prefieres lo más reciente? Las compilaciones alfa se publican bajo su propia etiqueta: npx cloud-doctor@alpha.

Proveedores compatibles

Los tokens de autenticación se pueden establecer como variables de entorno o puedes proporcionarlos cuando la TUI lo solicite:

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

(no decodifiques el token en base64)

o

$ npx cloud-doctor cloudflare

Cloudflare credentials are not set — enter them below.
Kept for this run only, never written to disk. Skip these prompts: export CLOUDFLARE_API_TOKEN

  dashboard → My Profile → API Tokens
? Cloudflare read-only API token › <input>

Próximamente: Google Cloud, Kubernetes y Bases de datos (Postgres, MySQL, Redis) — consulta Próximos pasos.

Comandos

npx cloud-doctor                    # elegir proveedor (por defecto AWS) → elegir identidad → escanear
npx cloud-doctor aws                # ruta rápida de AWS
npx cloud-doctor aws --profile prod # no interactivo cuando no hay ambigüedad
npx cloud-doctor aws --yes --json   # CI, salida legible por máquina
npx cloud-doctor aws --yes --json --fail-under 75  # puerta de CI según la puntuación

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

npx cloud-doctor aws profiles       # listar perfiles de ~/.aws/config
npx cloud-doctor aws whoami         # mostrar la identidad de AWS resuelta

--yes omite las indicaciones (seguro para CI); --json imprime un informe estable con versión de esquema en lugar de la vista de terminal; --verbose imprime cada hallazgo en lugar de los principales infractores; --no-color desactiva la salida de color.

Lo que obtienes

• Una puntuación (0–100): una tasa de aprobados ponderada por gravedad sobre cada regla que realmente se ejecutó. Los errores tienen más peso que las advertencias; las sugerencias nunca afectan la puntuación.
• Las 5 mejores correcciones, clasificadas por impacto en la puntuación, cada una con el recurso afectado y una corrección concreta.
• Una línea de comprobaciones superadas, donde cualquier regla silenciada (deshabilitada mediante configuración) o no disponible (falta de permisos) se revela en lugar de omitirse en silencio — una brecha de permiso nunca cuenta como aprobado.
• Si algo está roto y estás en un terminal interactivo, cloud-doctor puede pasar el informe directamente a tu agente de codificación de IA — Claude Code, Codex o Cursor, el que esté instalado — para que empiece a arreglarlo antes de que termines de leer la salida.

Las puntuaciones nunca son falsas: si no se pudo ejecutar ninguna regla, la puntuación es null con la etiqueta "No se ejecutaron comprobaciones", nunca un 100 vacío.

Configuración

Ajusta las reglas por proveedor mediante doctor.config.ts (o doctor.config.json, o cloudDoctor en 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" deshabilita una regla; "error" / "warning" anula su gravedad. Las reglas deshabilitadas se eliminan de la puntuación y se revelan como silenciadas, nunca restadas en silencio.

Arquitectura

Una CLI delgada sobre un registro de plugins — cada proveedor implementa el mismo contrato, por lo que la CLI nunca trata a uno de manera especial sobre otro.

Cada proveedor implementa CloudDoctorPlugin:

• discoverIdentities() — lista perfiles/proyectos/cuentas para el selector
• resolveIdentity() — mapea indicadores/variables de entorno/config → identidad, sin llamadas de red
• validateIdentity() — demuestra que las credenciales funcionan (sts:GetCallerIdentity o equivalente)
• scan() — ejecuta las reglas evaluadas, devuelve diagnósticos + puntuación

Los nuevos proveedores se registran en packages/plugins/src/index.ts.

Próximos pasos

gcloud, k8s y db llegarán pronto.

Desarrollo local

pnpm install
pnpm build
pnpm typecheck
pnpm test

Para verificación práctica de reglas sin tocar una cuenta real en la nube, el repositorio incluye un conjunto de simulacros http-mock y Moto/fab: (ps: fab la CLI para generar el entorno contra el que ejecutar, actualmente privado; el proyecto dependiente también se hará de código abierto)

pnpm mock:up <scenario>                  # iniciar una instancia simulada persistente
eval "$(pnpm -s mock:env <scenario>)"    # apuntar variables de entorno hacia ella
pnpm mock:run <scenario>                 # ejecutar la CLI contra ella

Licencia

MIT

Agradecimientos a react-doctor