CAOS — Sistema Operativo per l'Assurance dei Clienti

Rispondi ai questionari di sicurezza che i tuoi clienti ti inviano, una volta sola.

Ogni azienda che gestisce dati dei clienti riceve in continuazione le stesse richieste: questionari di sicurezza, valutazioni sulla privacy, revisioni del rischio dei fornitori, due diligence negli acquisti, richieste di evidenze. La maggior parte delle organizzazioni risponde a mano — un foglio di calcolo inviato dal cliente, una cartella di policy, una conversazione email e la memoria di qualcuno su ciò che era stato detto l'ultima volta.

CAOS trasforma tutto questo in un sistema di registrazione. I questionari diventano lavoro strutturato e compilabile. Le risposte completate e i tuoi documenti di conformità diventano un corpus ricercabile e citabile. Il questionario successivo parte da ciò che hai già detto, con ogni affermazione riconducibile al documento o alla risposta precedente da cui proviene.

È self-hosted. Le tue policy, le tue risposte e i questionari dei tuoi clienti restano sulla tua infrastruttura.

Stato: v0. CAOS è in produzione, ma questo repository è stato reso pubblico solo di recente. Interfacce, schema e configurazione sono ancora in evoluzione. I contributi esterni non sono ancora aperti — vedi Come contribuire.

Cosa fa

Legge i questionari senza tirare a indovinare. Carica l'XLSX di un cliente e CAOS lo riproduce fedelmente — fogli, righe, celle, colonne nascoste, menu a tendina di validazione. Poi segni quali righe sono compilabili e quali celle riempire, per intervalli piuttosto che una alla volta. Non esiste un parser per singolo cliente, perché non esiste uno standard: una riga in grassetto può essere una domanda, una colonna vuota può essere la destinazione della risposta, e ogni euristica che interpreta correttamente una cartella di lavoro ne interpreta con sicurezza un'altra in modo sbagliato.

Costruisce un corpus dal lavoro che hai già completato. Chiudere un questionario pubblica le righe compilate come Q&A riutilizzabili. Le policy, le certificazioni e i report caricati diventano brani citabili. Entrambi sono versionati in modo immutabile, così una risposta inviata lo scorso trimestre si spiega ancora da sola rispetto al documento che era in vigore in quel momento.

Trova la risposta precedente giusta. Il recupero esegue ricerca lessicale e semantica insieme, fonde le loro classifiche e riordina i migliori candidati. Il linguaggio della conformità richiede entrambe: token esatti come "SOC 2 Type II" che gli embedding sfumano, e parafrasi che la ricerca per parole chiave perde del tutto.

Redige risposte fondate su fonti. Opzionale. Il modello cerca nel tuo corpus tramite strumenti limitati e in lista consentita e redige una bozza di risposta con citazioni — più un'etichetta che indica da dove deriva la sua autorevolezza: Knowledge grounded, Mixed, General guidance o Based on current answer. Una risposta General guidance non fa alcuna affermazione sulla tua organizzazione, e lo dichiara.

Risponde in Google Chat. Un comando slash /ciso interroga lo stesso corpus fondato su fonti, con un link che riporta a una conversazione persistente nell'app web.

Esporta di nuovo nella cartella di lavoro del cliente. Le risposte vengono scritte nella struttura del file originale, nelle celle che hai mappato — non in un'approssimazione plasmata da CAOS.

Registra tutto. Un log di audit append-only con immutabilità imposta dal database, che conserva i valori esatti delle risposte prima e dopo.

Moduli

CAOS è organizzato in nove moduli di dominio. Tre di essi — Evidence, Knowledge e Tasks — sono globali: non appartengono ai progetti, perché il loro valore deriva dal fatto di attraversare più incarichi.

Architettura

                          Internet
                             │
                       ┌─────┴─────┐
                       │   nginx   │   TLS · static frontend · /api proxy
                       └─────┬─────┘
              ┌──────────────┼──────────────┐
              │              │              │
        ┌─────┴─────┐  ┌─────┴─────┐  ┌─────┴──────┐
        │ Frontend  │  │    API    │  │  Taskiq    │
        │  React    │  │  FastAPI  │  │  workers   │
        │  static   │  │  :18800   │  │            │
        └───────────┘  └─────┬─────┘  └─────┬──────┘
                             │              │
                       ┌─────┴──────────────┴─────┐
                       │                          │
                 ┌─────┴──────┐            ┌──────┴─────┐
                 │ PostgreSQL │            │   Redis    │
                 │  pgvector  │            │ queue+cache│
                 └────────────┘            └────────────┘
                             │
                       ┌─────┴─────┐
                       │ Providers │   Bedrock · local models · Google Chat
                       └───────────┘

Backend — Python 3.12+, FastAPI, SQLAlchemy 2 async, PostgreSQL con pgvector, Redis, worker Taskiq. Ogni modulo si suddivide in domain → application → infrastructure → presentation, con dipendenze unidirezionali. domain non dipende da nulla.

Frontend — React 19, TypeScript, Vite, Tailwind v4, shadcn/ui, Zustand. Lo stato di sessione e della shell dell'intera app vive in src/app; lo stato delle feature e della cache del server vive nei feature store; i workflow di pagina a lunga esecuzione vivono nei feature controller.

Entrambi i canali di recupero vivono in PostgreSQL. Non esiste un database vettoriale separato — un unico archivio significa un unico confine transazionale e un unico backup.

I fornitori esterni sono tenuti a debita distanza. Ogni integrazione separa un Platform Protocol (ciò che CAOS si aspetta, nel linguaggio del prodotto), un Adapter Protocol e una Vendor Implementation — l'unico livello che importa l'SDK. È per questo che embedding e reranking girano su modelli locali a versione fissa oppure su Bedrock, senza che alcun codice applicativo sappia quale dei due.

Dettaglio: architettura · confini di integrazione

Come fluiscono i dati

Un documento diventa recuperabile. Caricamento → versione immutabile → job di acquisizione durevole → commit → invio a un worker → estrazione di brani di ≤1.500 caratteri, ciascuno con un localizzatore di citazione (pagina PDF, paragrafo DOCX, foglio/riga/cella XLSX) → generazione degli embeddings → ricercabile. Il job esegue il commit prima dell'invio, così un guasto della coda diventa uno stato visibile e riprovabile invece di una riga in attesa invisibile.

Un questionario diventa lavoro compilato. Caricamento → viste fedeli delle righe → mappi le righe e le destinazioni delle risposte → un elemento del workspace per ogni riga compilabile, ciascuno che punta alle sue celle di origine esatte → bozze con salvataggio automatico → completamento esplicito con un compare-and-set basato sulla revisione attesa, così una scheda obsoleta riceve 409 invece di sovrascrivere un collega.

Il lavoro completato diventa Knowledge. Chiudere un questionario (o un progetto, che li chiude tutti) pubblica le righe compilate come Q&A riutilizzabili. Le righe non compilate non pubblicano nulla. La cartella di lavoro grezza non viene mai acquisita — è lavoro operativo, non materiale su cui fondare le risposte.

Una domanda diventa una risposta fondata su fonti. Il recupero lessicale e semantico gira in parallelo → la Reciprocal Rank Fusion combina i loro rank → boost dei tag → filtri di esclusione → riordino di una finestra limitata di 50 candidati → il modello cerca, ispeziona e cerca di nuovo entro un budget fisso → una bozza con citazioni che puntano a versioni immutabili delle fonti, e un'etichetta di fondatezza.

Ogni fase degrada verso una modalità più debole ma onesta: reranker fuori uso significa ordine fuso e nessun indicatore di confidenza; embeddings fuori uso significa fallback lessicale, segnalato come tale.

Dettaglio: flusso dei dati

Avvio rapido

Prerequisiti: Docker con Compose. Per il lavoro sul frontend, Node.js >=22.22.0 e pnpm 11.9.0. Lo sviluppo del backend usa anche uv.

Non servono un account AWS né un provider LLM — la generazione è disattivata di default e tutto ciò che segue funziona senza.

git clone https://github.com/DigiCred-OSS/caos-os.git
cd caos-os/backend
cp .env.example .env

Sostituisci il segnaposto BACKEND_USERS_SECRET in backend/.env con almeno 32 byte casuali:

python3 -c 'import secrets; print(secrets.token_urlsafe(48))'

Avvia PostgreSQL, Redis, l'API e i worker. Le migrazioni vengono eseguite automaticamente tramite il servizio migrator:

cd backend && docker compose up --build

Al primo avvio vengono scaricati ~500 MB di artefatti dei modelli a versione fissa. L'API è quindi su http://localhost:18800, Swagger su /api/docs, PostgreSQL sulla porta host 15432.

CAOS non ha una pagina di registrazione — crea il primo amministratore dall'host:

./caos-cli user create-superadmin --email [email protected]

cd frontend && pnpm install && pnpm dev

Apri http://localhost:5173.

Usa localhost in modo coerente sia per il frontend sia per l'API. I cookie di sessione sono limitati all'host, quindi mescolare localhost e 127.0.0.1 fa perdere la sessione in silenzio — il problema più comune nella configurazione locale.

Poi: il tutorial per iniziare ti accompagna da qui fino a un questionario compilato ed esportato.

Valori predefiniti da conoscere

• Embeddings e reranking puntano di default a local in Compose (Nomic a versione fissa e un cross-encoder MiniLM, inclusi nell'immagine). In produzione il default è AWS Bedrock. Il runtime non scarica mai modelli.
• La generazione delle risposte è disattivata. Imposta sia BACKEND_KNOWLEDGE_GENERATION_PROVIDER sia _MODEL per abilitarla.
• Google Chat è disattivato e richiede Google SSO per essere abilitato in produzione.

Ogni impostazione è documentata inline in backend/.env.example e raggruppata nel riferimento di configurazione.

Sviluppo

cd backend && uv sync --locked
uv run ruff check caos
uv run mypy caos

cd frontend && pnpm install && pnpm lint && pnpm build

Questa distribuzione pubblicata non include la suite di test interna di CAOS. Lint, type checking e una build pulita sono i controlli di verifica in questo contesto.

Usa ./caos-cli per tutto il lavoro di migrazione invece di invocare direttamente Alembic — seleziona l'ambiente, il container e il database giusti.

Le convenzioni di progetto che non sono evidenti dal codice sono in AGENTS.md, con regole specifiche per ogni modulo nel rispettivo AGENTS.md.

Documentazione

docs/ segue Diátaxis — ogni pagina è un tutorial, un how-to, un riferimento o una spiegazione, e le quattro sono tenute distinte.

Sicurezza

Per favore, non aprire issue pubbliche per le vulnerabilità. Vedi SECURITY.md per la segnalazione privata.

Come contribuire

CAOS è open source, ma non è ancora aperto ai contributi esterni. Prevediamo di accettare pull request esterne nel 2027. Fino ad allora, le segnalazioni di bug e le domande tramite le issue sono benvenute e davvero utili — vedi CONTRIBUTING.md.

Licenza

Apache License 2.0. Copyright 2026 DigiCred Technologies Pvt Ltd.