cloud-doctor

Un comando valuta l’intero account cloud — misconfigurazioni, mancanza di osservabilità e postura di sicurezza, classificati in base alle prime cinque cose da correggere.

Puntalo su AWS, Cloudflare, Vercel, Supabase, Render, Fly.io o Railway e restituisce un punteggio, cosa è rotto e una soluzione per ciascun problema — abbastanza autonomo da poter essere passato direttamente a un agente.

Avvio rapido

npx cloud-doctor

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

Questo seleziona un provider, risolve la tua identità (profilo AWS, token API, …) e avvia la scansione in modo interattivo. Per saltare direttamente a un provider:

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

Se ~/.npmrc ha impostato min-release-age (hardening della supply chain) e blocca le versioni recenti:

# =<numero>, 0 scelto come esempio
npm x --min-release-age=0 cloud-doctor -- aws profiles

Preferisci il bordo tagliente? Le build Alpha vengono pubblicate con il proprio tag: npx cloud-doctor@alpha.

Provider supportati

Provider	Comando	Autenticazione
AWS	cloud-doctor aws	Catena di credenziali AWS SDK — --profile, AWS_PROFILE, variabili d’ambiente, SSO, identità web
Cloudflare	cloud-doctor cloudflare	CLOUDFLARE_API_TOKEN
Vercel	cloud-doctor vercel	VERCEL_TOKEN (+ VERCEL_TEAM_ID opzionale)
Supabase	cloud-doctor supabase	SUPABASE_ACCESS_TOKEN
Render	cloud-doctor render	RENDER_API_KEY
Fly.io	cloud-doctor fly	FLY_API_TOKEN (+ FLY_ORG opzionale)
Railway	cloud-doctor railway	RAILWAY_API_TOKEN (token workspace/account)

I token di autenticazione possono essere impostati come variabili d’ambiente oppure puoi fornirli quando la TUI li richiede:

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

(non decodificare il token in base64)

oppure

$ npx cloud-doctor cloudflare

Le credenziali Cloudflare non sono impostate — inseriscile qui sotto.
Conservate solo per questa esecuzione, mai scritte su disco. Salta queste richieste: export CLOUDFLARE_API_TOKEN

  dashboard → My Profile → API Tokens
? Token API Cloudflare sola lettura › <input>

In arrivo: Google Cloud, Kubernetes e Database (Postgres, MySQL, Redis) — vedi Cosa c’è dopo.

Comandi

npx cloud-doctor                    # scegli provider (default AWS) → scegli identità → scansione
npx cloud-doctor aws                # percorso rapido AWS
npx cloud-doctor aws --profile prod # non interattivo quando non ambiguo
npx cloud-doctor aws --yes --json   # CI, output machine-readable
npx cloud-doctor aws --yes --json --fail-under 75  # gate CI sul punteggio

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

npx cloud-doctor aws profiles       # elenca i profili in ~/.aws/config
npx cloud-doctor aws whoami         # mostra l’identità AWS risolta

--yes salta le richieste (sicuro per CI); --json stampa un report stabile con versione dello schema invece della vista terminale; --verbose stampa ogni riscontro invece dei peggiori; --no-color disabilita l’output a colori.

Cosa ottieni

• Un punteggio (0–100): un rapporto di superamento ponderato per gravità su ogni regola effettivamente eseguita. Gli errori pesano più degli avvisi; i suggerimenti non influenzano mai il punteggio.
• Le prime 5 correzioni, ordinate per impatto sul punteggio, ciascuna con la risorsa interessata e una soluzione concreta.
• Una riga Controlli superati, con qualsiasi cosa disattivata (tramite configurazione) o non disponibile (permessi mancanti) divulgata anziché saltata silenziosamente — una lacuna di permessi non viene mai conteggiata come superata.
• Se qualcosa è rotto e ti trovi in un terminale interattivo, cloud-doctor può passare il report direttamente al tuo agente AI di codifica — Claude Code, Codex o Cursor, a seconda di quale sia installato — così può iniziare a correggere prima che tu abbia finito di leggere l’output.

I punteggi non sono mai falsi: se zero regole potessero essere eseguite, il punteggio è null con l’etichetta "Nessun controllo eseguito", mai un 100 vuoto.

Configurazione

Regola le regole per provider tramite doctor.config.ts (o doctor.config.json, o cloudDoctor in 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" disabilita una regola; "error" / "warning" ne sovrascrive la gravità. Le regole disabilitate vengono rimosse dal punteggio e segnalate come silenziate — mai sottratte silenziosamente.

Architettura

Una CLI leggera su un registro di plugin — ogni provider implementa lo stesso contratto, quindi la CLI non fa mai distinzioni tra uno e l’altro.

Pacchetto	Ruolo
packages/cloud-doctor	CLI (commander, prompts, ora) + API programmatica diagnose()
packages/core	Registro plugin, punteggio, caricamento configurazione, tipi condivisi
packages/plugin-*	Un pacchetto per provider — scoperta identità + regole
packages/plugins	Registro predefinito che collega tutti i provider

Ogni provider implementa CloudDoctorPlugin:

• discoverIdentities() — elenca profili/progetti/account per il selettore
• resolveIdentity() — mappa flag/env/config → identità, nessuna chiamata di rete
• validateIdentity() — dimostra che le credenziali funzionano (sts:GetCallerIdentity o equivalente)
• scan() — esegue le regole limitate, restituisce diagnostica + punteggio

I nuovi provider si registrano in packages/plugins/src/index.ts.

Cosa c’è dopo

gcloud, k8s e db sono in arrivo.

Sviluppo locale

pnpm install
pnpm build
pnpm typecheck
pnpm test

Per una verifica pratica delle regole senza toccare un account cloud reale, il repository include un harness http-mock e Moto/fab: (ps: fab è la CLI per generare l’ambiente su cui eseguire i test, attualmente privato; il progetto dipendente sarà reso open-source)

pnpm mock:up <scenario>                  # avvia un’istanza mock persistente
eval "$(pnpm -s mock:env <scenario>)"    # punta le variabili d’ambiente
pnpm mock:run <scenario>                 # esegui la CLI contro di esso

Licenza

MIT

---

Un ringraziamento a react-doctor