Guida alla versione preliminare · 0.1.0

Come si compone CodeSecurity

Segui autorità sui sorgenti, job persistenti ed evidenze degli scanner attraverso il workbench locale.

Il riferimento API è in inglese.

CodeSecurity è un ambiente di sicurezza locale con due client: dashboard browser ed estensione VS Code. FastAPI serve l’applicazione React compilata e l’API di controllo. PostgreSQL conserva lo stato. Un worker separato esegue comandi persistenti verso scanner, updater dei dati e connettore Advisor facoltativo.

Segui una scansione dai sorgenti salvati alle evidenze conservate. Ogni servizio ha un ruolo ristretto e un proprio confine di autorità.

Segui una scansione nel sistema

Workbench locale / mappa dei serviziDiagramma

Client dell’operatore

Browser
Sessione operatore associata e workbench web.
VS Code
Un profilo approvato con capacità limitate.

Ingresso locale e stato persistente

Relay loopback
Pubblica l’endpoint TCP locale senza segreti runtime o mount persistenti.
FastAPI + React
Serve il workbench e verifica richieste di controllo. Non ha socket Docker.
PostgreSQL
Conserva stato, comandi, job, rilievi e policy.
Worker dei job
Acquisisce lavoro persistente e ne coordina il risultato.

Servizi di esecuzione limitata

Scanner
Legge sorgenti autorizzati e dati validati su una rete interna.
Updater
Recupera dati verificati senza mount dei sorgenti dei progetti.
Connettore Advisor
Esegue richieste facoltative con concessioni esatte.

Dati e provider facoltativo

Cache validata dello scanner
I lettori usano una generazione selezionata in sola lettura.
Provider Ollama autorizzato
Destinazione locale o remota autorizzata esplicitamente.

Connessioni

Browser a Relay loopback
Il browser entra dall’endpoint loopback.
VS Code a Relay loopback
L’editor usa lo stesso endpoint con autorità propria.
Relay loopback a FastAPI + React
Il relay inoltra traffico TCP al servizio di controllo.
FastAPI + React a PostgreSQL
Lo stato viene letto e modificato tramite operazioni ammesse.
Worker dei job a PostgreSQL
Lease ed esiti dei job persistono indipendentemente dalla pagina.
Worker dei job a Scanner
Il worker invia scansioni limitate e raccoglie risultati.
Worker dei job a Updater
La preparazione avviene separatamente dall’analisi dei sorgenti.
Scanner a Cache validata dello scanner
Lo scanner legge i dati validati selezionati.
Updater a Cache validata dello scanner
L’updater valida e seleziona una generazione completa.
Worker dei job a Connettore Advisor
Advisor riceve una concessione esatta del provider.
Connettore Advisor a Provider Ollama autorizzato
Si usano solo destinazione e ambito autorizzati.

Browser e VS Code sono client di un’installazione locale. API, worker persistente e servizi limitati hanno responsabilità diverse. Il traffico facoltativo dei provider usa il connettore Advisor.

L’operatore autorizza una radice ristretta o fornisce uno snapshot limitato supportato. Creare un progetto ne registra l’identità; non concede accesso ad altre directory host.
L’API verifica ambito e preflight correnti. Registra insieme scansione e job persistente.
Il worker acquisisce il job con un lease. Lo scanner rivalida l’accesso ed esegue gli strumenti abilitati sulla vista acquisita e sulla generazione dati validata.
L’output nativo diventa rilievi limitati, normalizzati e con dati sensibili oscurati. Il worker verifica manifest e pagine, poi conferma evidenze ammesse e checkpoint di recupero in PostgreSQL.
Solo dopo conferma allo scanner il risultato esatto, permettendo la rimozione dell’output temporaneo. L’evidenza completa può essere valutata con la policy del progetto.
I client aggiornano le risorse autorevoli quando cambiano job e rilievi. Consigli facoltativi e decisioni umane sono separati; non forniscono copertura mancante.

Il capitolo su job ed evidenze segue errori e recuperi di questi passi.

Colloca l’autorità a ogni confine

Compose espone un indirizzo loopback tramite un relay TCP non privilegiato. Il relay inoltra all’API e non ha mount persistenti o configurazione di segreti runtime. L’API non ha socket Docker. Sessioni browser e capacità editor entrano dallo stesso confine con regole d’autenticazione diverse.

Componente	Letture e scritture	Ruolo
API di controllo	PostgreSQL, snapshot limitati e artefatti ammessi	Autorizza comandi, serve risorse e registra stato persistente. Non monta sorgenti di progetto.
Worker	PostgreSQL e artefatti; snapshot in sola lettura	Gestisce esecuzione, lease, avanzamento, annullamento e persistenza.
Scanner	Sorgenti autorizzati, snapshot e cache validata in sola lettura; spazio temporaneo privato e output artefatti	Esegue strumenti fissati e pubblica un protocollo di risultati limitato.
Updater dei dati	Cache scrivibile; fonti di download verificate	Prepara e attiva generazioni complete senza mount dei sorgenti.
Connettore Advisor	Autorizzazione dedicata e percorsi provider approvati	Esegue lavoro Ollama locale o remoto con permessi ristretti.

Lo scanner usa una rete interna. Updater e connettore hanno reti d’uscita separate. Il worker chiama il connettore per richieste locali e remote; non invia prompt direttamente a Ollama. Sono confini definiti dal codice di distribuzione. Immagini, mount effettivi ed egress reale richiedono ancora verifica nell’installazione esaminata.

Consulta autorità di sorgenti e client per le decisioni e servizi interni per i protocolli.

Mantieni distinti i tipi di stato

Domanda	Stato autorevole	Cosa non implica
Il comando è stato accettato?	Identità persistente di job e comando	Che sia iniziato o riuscito.
La scansione è completa?	Stato, esiti degli strumenti e copertura	Che sia stata controllata ogni vulnerabilità possibile.
Come è stato rivisto un rilievo?	Decisione, motivo e revisione	Che un file modificato sia verificato o che una nuova scansione erediti la decisione.
L’evidenza soddisfa la policy?	Decisione del gate su evidenze complete	Che la protezione sia installata o un push autorizzato.
Questo push protetto può procedere?	Autorità corrente, alberi in uscita, evidenze e policy	Che l’hook locale non sia aggirabile.

La separazione rende visibile una scansione incompleta anche se tutti i rilievi sono soppressi. Impedisce anche di sostituire i controlli sui commit precedenti con un esito positivo del working tree. Leggi rilievi, gate e protezione Git per i flussi operativi.

Comprendi cosa persiste

PostgreSQL conserva progetti, scansioni, rilievi normalizzati, policy e job. Volumi nominati mantengono artefatti ammessi, dati e snapshot. Report nativi e spool di trasporto dello scanner hanno vite temporanee limitate. Aprire o chiudere una pagina non governa la durata del job.

È un progetto persistente, non una garanzia di disaster recovery. Il codice documenta un helper di backup sperimentale, non atomico e disabilitato per default. Una procedura di recupero provata richiede evidenze e input esatti propri.

I profili facoltativi di monitoraggio, proxy Git locale e amministrazione database sono disattivati per default. Non fanno parte dell’autorità dell’API principale e non trasformano il workbench in un servizio ospitato.

Leggi l’implementazione per responsabilità

Area	Punto di partenza
Servizi, mount e reti	Compose
Controllo e persistenza	Applicazione API, modello dati
Esecuzione e preparazione	Architettura delle scansioni
Aggiornamenti browser ed editor	Eventi e riconciliazione
Contributi	Punti di estensione

La policy di sicurezza definisce le ipotesi di fiducia. CodeSecurity non è una sandbox per repository ostili. Superare un gate è un risultato di policy su evidenze ammesse, non una garanzia di codice sicuro.