Skip to content

runbook.md

Latest commit

 

History

History
109 lines (72 loc) · 3.71 KB

runbook.md

File metadata and controls

109 lines (72 loc) · 3.71 KB

Runbook

Guida operativa breve per la v0 attuale.

Radar

python scripts/radar_check.py --dry-run
python scripts/radar_check.py

Usa radar quando la domanda è:

  • la fonte risponde?
  • ci sono problemi di timeout, SSL, DNS o HTTP?
  • il registry è sano?

Output:

Scheduling v0:

  • run giornaliero via GitHub Actions (radar-scheduled.yml)
  • workflow_dispatch disponibile per run manuali
  • il modello v0 è report-only: aggiorna STATUS.md e sources_registry.yaml
  • nessuna issue automatica o alerting complesso in questa fase

Manutenzione del Registry:

  • Se una fonte è stabilmente giù, verificare manualmente l'URL.
  • Se l'URL è cambiato, aggiornare data/radar/sources_registry.yaml.
  • Se la fonte è definitivamente rimossa, valutare la disattivazione o rimozione nel registry.

Boundary:

Catalog-watch

Output correnti:

Usa catalog-watch quando la domanda è:

  • l'inventario è cambiato?
  • c'è drift strutturale?
  • c'è un follow-up candidate che merita revisione umana?

Modello v0:

  • i segnali vengono prodotti automaticamente dal workflow schedulato catalog-inventory.yml
  • il follow-up resta human-run: il report non sostituisce la review umana sui cambi rilevanti
  • il run manuale va usato quando serve un check metodologicamente difendibile fuori schedule
  • gli output canonici restano CATALOG_WATCH_REPORT.md e catalog_signals.json
  • problemi di connessione/HTTP vanno letti in radar_summary.json, non in catalog_signals.json

Catalog inventory

python scripts/build_catalog_inventory.py
python scripts/build_catalog_inventory.py --workers 3  # parallelo, sperimentale

Usa catalog inventory quando la domanda è:

  • quali item sono oggi enumerabili nei cataloghi osservati?
  • quali fonti catalog-watch producono un inventario riusabile per scouting?
  • il perimetro pubblico resta coerente con le esclusioni dichiarate?

Output (non versionati nel repo):

  • data/catalog_inventory/generated/catalog_inventory_latest.parquet
  • data/catalog_inventory/generated/catalog_inventory_report.json

Per ottenere l'ultimo output senza rieseguire: artifact del workflow catalog-inventory su GitHub Actions, oppure GCS se configurato.

Disciplina:

  • il perimetro segue le fonti catalog-watch del registry
  • una fonte può restare osservata in SO ma non essere inventariabile
  • anac oggi resta escluso dall'inventory automatico per vincoli WAF
  • l'upload su GCS è opzionale e richiede secret espliciti
  • in assenza di GCS il workflow resta valido: usa baseline locale vuota e salta i passaggi opzionali di storage/diff
  • il workflow gira ogni lunedì (schedule) ed è disponibile anche via workflow_dispatch

Portal scout

Il workflow portal-scout.yml ha tre esiti operativi per lo scout strutturale:

  • ok se portal_scout.py completa il run
  • degraded se lo script esce con errore ma produce comunque JSON utilizzabili in scout_results/
  • failed se lo script non produce output utilizzabile; in questo caso il job fallisce

skip_discovery=true richiede GCS configurato, perché il parquet di discovery viene recuperato da storage invece di essere ricostruito via DDG.

Ordine consigliato

  1. esegui radar
  2. leggi catalog-watch
  3. decidi se esiste davvero un follow-up umano giustificato

Disciplina

  • tieni l'universo piccolo
  • preferisci segnali leggibili alla copertura larga