Come eseguire open-kritt su un VPS in sicurezza
Configura open-kritt con Docker Compose, blocca una release, usa il tunnel SSH verso la UI sulla porta 5173 e imposta il budget del provider prima della scansione.
Perché eseguire open-kritt su un VPS e non sul laptop
Esegui open-kritt su un server che puoi eliminare e ricreare. Lo strumento esegue i propri agenti di analisi come root all'interno di container di job temporanei, assegna a ciascuno una copia scrivibile del codice e l'accesso diretto a Internet, quindi monta il socket Docker dell'host nel servizio engine. Questo compromesso è ragionevole su una macchina dedicata al job. È una scelta rischiosa sulla macchina che contiene le tue chiavi SSH.
Quattro caratteristiche della configurazione predefinita motivano questa raccomandazione, e tutte e quattro provengono dal README e dal file compose del progetto.
Gli agenti devono avere ampi privilegi. Il README specifica che gli agenti con strumenti eseguono i propri processi come root all'interno di container di job temporanei, con copie scrivibili dei repository e accesso diretto a Internet. In questo modo possono installare strumenti, compilare i target, eseguire test e creare proof of concept. Una scansione non è un linter che legge i file. È esecuzione arbitraria di codice richiesta da te. L'accesso a Internet comporta rischi in entrambe le direzioni: qualsiasi contenuto scaricato da un agente durante l'analisi di un target è testo non attendibile che entra nel suo prompt. È la stessa esposizione che accetti quando affidi a un agente le proprie ricerche sul Web.
L'engine contiene il socket Docker. docker-compose.yml monta il socket Docker dell'host nel servizio engine, perché l'engine crea e avvia un container di scansione per ogni job. Qualsiasi processo che può raggiungere quel socket può avviare un container con il filesystem dell'host montato. Di fatto, quindi, l'engine dispone dei privilegi di root sull'host su cui viene eseguito.
Non esiste una schermata di accesso. Il backend viene distribuito senza autenticazione applicativa. Chiunque possa accedere alla porta può accedere ai risultati delle scansioni e al credito del tuo provider.
Il codice analizzato spesso non è tuo. Indicare agli agenti un repository di terze parti significa eseguire la build di quel repository sulla tua macchina, come root e con accesso alla rete.
Se hai letto perché gli agenti di coding devono essere eseguiti in una VM temporanea, questo è lo stesso modello di minaccia, ma più severo. Dedica a open-kritt un VPS su cui non eseguire altro e gestisci quel VPS tramite un account utente separato con privilegi minimi, invece di usare root.
Cosa fa effettivamente open-kritt
open-kritt (il repository è Kritt-ai/open-kritt ed è distribuito con licenza AGPL-3.0) suddivide la ricerca delle vulnerabilità in piccole attività, esegue queste attività in parallelo tramite agenti AI, quindi elimina i duplicati e assegna una priorità ai risultati. Si definisce un workflow come una catena di prompt mirati e ogni passaggio riceve il contesto strutturato prodotto dai passaggi precedenti. L'obiettivo della scansione è un repository git remoto o locale. Il motore di analisi è Codex o Claude Code. Quando viene individuato un candidato, gli script post-analisi opzionali possono tentare di convalidarlo o creare una prova di concetto. La progettazione di questa catena è una normale attività con agenti, non un'attività di sicurezza. Se prompt, strumenti e passaggio del contesto non sono ancora familiari, scoprire come si compongono gli agenti sarà più utile per ottenere risultati migliori di qualsiasi impostazione descritta in questa guida.
Al termine si ottiene un elenco classificato di candidati. Usalo come coda di triage, non come un report.
Prerequisiti
- Una VPS con Ubuntu 24.04, Debian 12 o Rocky Linux 9. La documentazione di installazione indica queste distribuzioni come quelle testate, su x86_64 e ARM64.
- Docker Engine con il plugin Compose.
- Node.js 20 o versioni successive sull'host, perché la CLI
./krittviene eseguita sull'host e non all'interno di un container. - Un provider di modelli: un accesso Codex oppure
OPENAI_API_KEY,CODEX_API_KEY,ANTHROPIC_API_KEYoOPENROUTER_API_KEY. GITHUB_TOKENsolo se prevedi di analizzare repository privati. Il file.env.exampleincluso lo specifica chiaramente: un token GitHub da solo non è sufficiente per eseguire le scansioni.
Installare prima Docker e Node 20
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USERDisconnettersi e accedere di nuovo per applicare la nuova appartenenza al gruppo, quindi verificare che il plugin Compose sia presente.
docker compose versionUna stringa di versione indica che Compose è installato come plugin. docker: 'compose' is not a docker command indica invece che è presente il vecchio binario autonomo docker-compose, mentre open-kritt richiama docker compose. L'appartenenza al gruppo docker equivale all'accesso root sull'host, quindi aggiungere a questo gruppo solo l'account che esegue open-kritt. Per la procedura completa, vedere eseguire Docker su un VPS.
Ubuntu 24.04 include Node 18 nel proprio repository, ma la CLI si interrompe con qualsiasi versione precedente alla 20. Node 20 ha inoltre raggiunto la fine del ciclo di vita e non riceve più aggiornamenti, quindi installare Node 22 da NodeSource. Soddisfa lo stesso controllo che richiede la versione 20 o successiva.
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node -vnode -v deve stampare v22. in questo punto; qualsiasi versione inferiore a v20. verrà rifiutata dalla CLI. Su Rocky Linux 9, l'equivalente è sudo dnf module enable nodejs:22 -y seguito da sudo dnf install -y nodejs.
Clonare open-kritt e bloccare una release contrassegnata
git clone https://github.com/Kritt-ai/open-kritt
cd open-kritt
git fetch --tags
git tag --list
git checkout v1.4.1main si sposta insieme al repository. Un tag non cambia. Al 12 ottobre 2026, il tag più recente è v1.4.1, pubblicato il 16 agosto 2026, mentre git tag --list mostra ciò che esiste nel giorno in cui si esegue il clone. v1.4.0 (12 agosto 2026) ha aggiunto l'ammissione dei runner basata sulla memoria descritta nella sezione sul dimensionamento, mentre v1.4.1 ha corretto un bug per cui il ranker ignorava le regole di ranking fornite dall'utente. Il checkout di un tag lascia il repository nello stato detached HEAD, che in questo caso è corretto: questo clone viene trattato come un deployment bloccato a una versione specifica, non come un branch su cui eseguire commit. Per eseguire in seguito un aggiornamento, leggere le note di rilascio, quindi eseguire git fetch --tags, fare il checkout del nuovo tag ed eseguire nuovamente ./kritt start, perché start ricostruisce le immagini.
Non eseguire ./kritt con sudo. La documentazione lo specifica chiaramente. La CLI gestisce le directory locali delle credenziali del progetto in .data/, quindi un'esecuzione come root lascia tali directory di proprietà di root e l'esecuzione successiva come utente normale non può scrivervi.
Configura l'accesso ai modelli con ./kritt setup
./kritt setupIl comando crea .env da .env.example se non esiste, visualizza lo stato di ogni credenziale e consente di impostarle o rimuoverle. Non stampa mai i valori nel terminale. Sia .env sia il file delle credenziali del motore vengono scritti con modalità 0600.
Se preferisci eseguire la configurazione manualmente:
cp .env.example .env
chmod 600 .env
mkdir -p .data/codex
chmod 700 .data/codexInserisci quindi la chiave del provider in .env e lascia il file con modalità 0600. In entrambi i casi, sul server è ora presente una credenziale funzionante del provider. Questo è un motivo in più per non ospitare altro su quel server. Crea una chiave dedicata esclusivamente a questo progetto, in modo che la sua revoca non interrompa nulla di importante. Tenere i secret fuori dalla portata degli agenti AI descrive questa buona pratica in modo più ampio.
Impostare un limite di spesa del provider prima della prima scansione
open-kritt è progettato per distribuire il carico, e questa distribuzione determina i costi. I valori predefiniti in .env.example alla versione v1.4.1 sono prudenti: ENGINE_WORKER_COUNT=2, descritto nel file come valore predefinito prudente per una macchina con 2 vCPU, e ENGINE_MAX_CONCURRENT_SCANS=1. A questi si aggiungono ENGINE_WORKERS_PER_ACCOUNT=15, il numero massimo di chiamate simultanee al modello root consentite su un account del provider, e ENGINE_CODEX_MAX_SUBAGENTS_PER_SESSION=5, perché una sessione Codex può eseguire fino a cinque agenti figlio. Se aumenti il numero di worker su un VPS più grande, aumenta di conseguenza anche il numero di chiamate al modello in corso.
Nel repository non esiste alcun limite alla spesa. In .env.example non è presente un'impostazione per il budget. Le condizioni di arresto interne al motore sono costituite dai limiti dei worker e da ENGINE_HARNESS_TIMEOUT_SECONDS, che per ogni esecuzione dell'harness è impostato per impostazione predefinita su 7200 secondi. In questo contesto, l'harness è il ciclo che continua a chiamare il modello con strumenti e contesto finché una condizione non termina l'esecuzione. Il timeout è quindi un limite di tempo reale per il programma che avvolge il modello e non limita quanto il modello può spendere al suo interno. Il limite massimo deve quindi essere impostato presso il provider. Apri la console del provider e imposta un limite mensile rigido prima della prima scansione, non dopo. Controllare quanto costa un agente AI su un VPS illustra le impostazioni specifiche dei singoli provider.
È disponibile anche un blocco locale. Impostando ENGINE_WORKER_COUNT=0, sospendi il prelievo di nuovi job. Gli stessi valori dei worker possono essere modificati nella schermata Settings dopo l'avvio dello stack.
Questa guida non indica un prezzo per scansione, perché il costo dipende dalle dimensioni del repository, dal workflow che costruisci e dal modello utilizzato. Esegui una scansione su un repository piccolo, quindi consulta la pagina dei consumi del provider prima di eseguire scansioni su repository di grandi dimensioni.
Avviare lo stack e verificarne lo stato
./kritt startQuesto controlla .env e almeno una credenziale, quindi esegue docker compose up --build. La prima build è lenta perché crea le immagini del frontend, del backend, dell'engine, della vista dell'executor e del database. Inoltre, l'esecuzione avviene in primo piano: se si chiude la sessione SSH, lo stack viene arrestato. Avviarlo all'interno di tmux oppure eseguirlo in modalità detached dopo il completamento della prima build. Nessuna delle due modalità riavvia automaticamente lo stack dopo un reboot. Se si vuole riattivare lo stack dopo il riavvio del server, il modello di unità systemd descritto in mantenere in esecuzione un agent self-hosted dopo i reboot si applica direttamente.
docker compose up -d --build
docker compose psdocker compose ps dovrebbe elencare open-kritt-frontend, open-kritt-backend, open-kritt-engine, open-kritt-executor-view e open-kritt-db. Verificare quindi che il backend risponda dal server stesso.
curl -s http://127.0.0.1:3002/api/healthUna risposta JSON indica che il backend è attivo. Failed to connect to 127.0.0.1 port 3002: Connection refused indica che non lo è, mentre docker compose logs backend mostra il motivo. Arrestare tutto con docker compose down dalla directory del repository.
Un'ultima opzione: docker compose exec backend npm run seed carica dati dimostrativi. È un modo semplice per esaminare l'interfaccia prima di sostenere costi per una scansione reale.
Raggiungere l'interfaccia sulla porta 5173 tramite un tunnel SSH
Ogni servizio nel file compose si associa a 127.0.0.1 per impostazione predefinita: il frontend sulla porta 5173, il backend sulla porta 3002, la vista dell'executor sulla porta 8090 e Postgres sulla porta 5432. Lascia invariati questi binding e inoltra la porta tramite SSH dal tuo computer.
ssh -N -L 5173:127.0.0.1:5173 you@your-server-ipApri http://localhost:5173 nel browser locale mentre il comando è in esecuzione. -N indica che la connessione esegue il forwarding e non apre una shell. Aggiungi un secondo -L 8090:127.0.0.1:8090 allo stesso comando quando vuoi includere anche la vista dell'executor.
La tentazione è impostare FRONTEND_BIND_ADDRESS=0.0.0.0 e saltare il tunnel. Non farlo. Il backend non ha una schermata di accesso, quindi chiunque raggiunga quella pagina può avviare scansioni e consumare il credito del tuo provider. Al contrario, Vaultwarden è progettato per essere esposto a Internet e metterlo in sicurezza dipende comunque dal token amministrativo e dal file di backup, cioè da controlli che open-kritt non mette a disposizione. C'è anche un secondo problema: una porta pubblicata dal container viene gestita prima che si applichi la policy predefinita di ufw, quindi una regola ufw deny 5173 sembra corretta ma non blocca nulla. Le porte Docker che bypassano ufw mostra la catena di regole che lo determina.
Dimensionamento del VPS
ENGINE_MIN_FREE_STORAGE_GB è impostato su 20 per impostazione predefinita e il motore rifiuta di avviare un nuovo container di scansione per singolo job quando lo spazio di archiviazione libero scende al di sotto di questo valore. Le immagini compilate, la cache del checkout, i dati di Postgres e gli spazi di lavoro dei job si trovano tutti sullo stesso disco, quindi un VPS da 20 GB non avvia mai una scansione. Considera 40 GB come valore minimo e aumenta lo spazio se esegui la scansione di repository di grandi dimensioni. Non cercare di recuperare il costo del server affiancandogli un servizio che richiede molto spazio di archiviazione, perché i requisiti minimi misurati di RAM e disco in questo confronto tra PhotoPrism e Immich mostrano quanto rapidamente una libreria multimediale consumerebbe il margine necessario a una scansione. Lo stesso vale per gli extra ornamentali che sembrano irrilevanti accanto a uno scanner: un frontend browser che ridisegna una libreria Jellyfin come un videonoleggio degli anni 90 richiede comunque un intero media server e i relativi transcode sul disco sottostante, quindi assegnagli un host diverso.
La memoria segue un calcolo semplice e le impostazioni che lo regolano sono state introdotte nella v1.4.0, quindi si applicano al tag indicato sopra ma non alle versioni precedenti. ENGINE_MEMORY_RESERVE_GB=2 riserva memoria per il motore, il database, l'API e il sovraccarico temporaneo. Ogni runner di scansione ha quindi una prenotazione soft di ENGINE_SCAN_RUNNER_MEMORY_RESERVATION_MB=1536 e un limite hard di ENGINE_SCAN_RUNNER_MEMORY_MB=1536. Due worker richiedono pertanto circa 5 GB prima dell'avvio di qualsiasi altro componente. Il motore ammette soltanto i runner che rientrano nel budget rimanente, quindi su un server di dimensioni ridotte le scansioni vengono accodate invece di fallire. È un comportamento molto più sicuro rispetto all'intervento dell'out-of-memory killer. Lo stesso calcolo determina il minimo necessario per qualsiasi strumento che assegna un container a ogni unità di lavoro. Per questo il container e il browser dedicati a ogni collaboratore AI di OpenBot raggiungono un limite di RAM molto prima di un limite di CPU.
Due impostazioni di pulizia hanno come valore predefinito true: ENGINE_AUTO_PRUNE_DOCKER_BUILD_CACHE e ENGINE_AUTO_PRUNE_UNUSED_DOCKER_IMAGES. Al termine di un'attività, il motore rimuove la cache di compilazione inutilizzata, le immagini inutilizzate e i container di scansione arrestati. Le immagini utilizzate da un container, i container dei servizi, i bind mount, i dati del database, le credenziali e i volumi vengono conservati. È un ulteriore motivo per non condividere l'host: un processo di pulizia che non hai configurato opera su quel Docker daemon.
Le impostazioni del motore che la maggior parte degli utenti finisce per modificare
ENGINE_WORKER_COUNT: numero totale di slot worker condivisi tra le fasi di scansione e il post-processing. Impostalo su 0 per sospendere il prelievo di nuovi job.ENGINE_MAX_CONCURRENT_SCANS: numero di scansioni ammesse contemporaneamente. Le scansioni accodate attendono finché il pool attivo non è vuoto.ENGINE_MAX_WORKERS_PER_SCAN: 0 distribuisce gli slot aggregati in modo uniforme tra le scansioni.ENGINE_HARNESS_TIMEOUT_SECONDS: 7200 per impostazione predefinita. È la durata massima di un singolo job fuori controllo. Il motore accetta valori da 60 a 86400; qualsiasi valore al di fuori di questo intervallo, incluso 0, viene ricondotto a 7200.ENGINE_MIN_FREE_STORAGE_GB: soglia minima di spazio di archiviazione.ENGINE_IGNORE_LOW_STORAGE=truedisabilita la protezione e il file avvisa che il disco dell'host potrebbe riempirsi.ENGINE_SCAN_RUNNER_MEMORY_MB: limite hard di memoria per ogni runner. 0 rimuove il limite.ENGINE_SCAN_RUNNER_MEMORY_RESERVATION_MB: prenotazione soft per ogni runner, conteggiata durante l'ammissione. Ridurla sovrascrive la memoria inattiva, mentre il limite hard continua a contenere i picchi.
Analizzare un repository locale senza esporlo
LOCAL_REPOS_PATH è impostato per impostazione predefinita su ./local_repos e viene montato in sola lettura tramite bind mount nei container backend ed engine. Un repository copiato in quella directory sull'host diventa quindi immediatamente visibile nei container. Usa un clone nuovo, non la directory di lavoro. Il container del job riceve una copia scrivibile, dispone dell'account root al proprio interno e ha accesso a Internet in uscita. Di conseguenza, qualsiasi elemento presente in quella copia può essere modificato o inviato all'esterno del server. Rimuovi i file .env e le chiavi private prima di copiare il progetto.
Cosa viene restituito e cosa non viene restituito
Vengono restituiti i risultati candidati classificati. Non vengono restituite vulnerabilità verificate. La classificazione e la deduplicazione determinano l’ordine della coda di triage. Non dimostrano che una voce sia reale. Gli script post-esecuzione possono tentare la validazione e creare una proof of concept. Questo è il segnale più forte offerto dallo strumento. Tuttavia, se uno script post-esecuzione non riesce, ciò non dimostra che il risultato sia falso. Una persona deve comunque esaminare ogni candidato. Questa differenza tra un candidato e una prova spiega perché vale la pena riprendere l’approccio descritto in chiedere a un agente prove che si possano rieseguire autonomamente: un risultato che si può riprodurre su richiesta vale più di un risultato classificato che si deve accettare senza verificarlo.
Questa guida non afferma quanti bug reali trovi open-kritt, perché non lo abbiamo misurato. Chiunque riporti un tasso di rilevamento per il vostro codebase non lo ha eseguito sul vostro codebase. Eseguite inizialmente la scansione di un repository che conoscete già bene: i risultati che potete valutare autonomamente sono il metodo di calibrazione meno costoso disponibile.
L’autorizzazione è più importante in questo contesto che con la maggior parte degli strumenti self-hosted. Gli agenti compilano ed eseguono codice e raggiungono la rete, quindi una fase di proof of concept può interagire con sistemi in produzione. Indicate codice di vostra proprietà o per il quale avete un incarico di test, e definite per iscritto l’ambito di destinazione prima di eseguire qualsiasi operazione. Se configurate ANTHROPIC_API_KEY e usate il motore Claude Code, le pratiche di sandboxing descritte in eseguire Claude Code in sicurezza su un VPS si applicano anche a questi agenti.
FAQ
Perché open-kritt richiede un VPS dedicato?
Perché i suoi agenti di analisi vengono eseguiti come root all'interno di container di job temporanei, con copie scrivibili del codice e accesso diretto a Internet. Inoltre, il servizio engine monta il socket Docker dell'host per poter avviare un container per ogni job. Qualsiasi processo che raggiunge quel socket può avviare un container con il filesystem dell'host montato. Per questo motivo, l'intero stack deve essere considerato equivalente a root sull'host. Su un VPS dedicato questo compromesso è accettabile e la ricostruzione del server non comporta costi. Sulla workstation che usi ogni giorno, invece, le chiavi SSH e i profili del browser rientrano nello stesso perimetro di attendibilità del codice sottoposto ad analisi.
Posso esporre la porta 5173 invece di usare un tunnel SSH?
No. Il backend viene distribuito senza autenticazione applicativa. La porta è quindi l'unica barriera tra Internet e i risultati delle analisi e il credito del provider. Per questo il file compose associa ogni servizio a 127.0.0.1. Esegui invece ssh -N -L 5173:127.0.0.1:5173 you@your-server-ip e apri http://localhost:5173 in locale. Una regola ufw non è un sostituto sufficiente, perché una porta pubblicata da Docker viene gestita prima che si applichi la policy predefinita di ufw.
Come posso impedire a open-kritt di spendere più del previsto?
Imposta un limite rigido nella console del provider del modello prima della prima analisi, perché open-kritt non dispone di un'impostazione interna per il budget. Per le prime esecuzioni, mantieni i valori predefiniti di concorrenza distribuiti con il prodotto, ENGINE_WORKER_COUNT=2 e ENGINE_MAX_CONCURRENT_SCANS=1. Tieni presente che, per impostazione predefinita, un account del provider consente fino a 15 chiamate simultanee al modello root, mentre una sessione Codex può eseguire fino a cinque agenti figlio. ENGINE_WORKER_COUNT=0 sospende il prelievo di nuovi job ed è il modo più rapido per interrompere l'elaborazione locale.
Quale versione devo estrarre?
Un tag, mai main. git fetch --tags seguito da git tag --list mostra i tag disponibili. v1.4.1, pubblicato il 16 agosto 2026, è il più recente al 12 ottobre 2026. Fissare la versione garantisce che una ricostruzione eseguita mesi dopo produca lo stesso stack. Inoltre, l'aggiornamento diventa una scelta da effettuare dopo aver letto le note di rilascio, invece di essere una conseguenza involontaria della clonazione in un giorno diverso.
Un'analisi non viene mai avviata. Che cosa devo controllare?
Controlla prima lo spazio libero su disco, perché engine non avvia il container di analisi dedicato al job quando lo spazio disponibile è inferiore a ENGINE_MIN_FREE_STORAGE_GB, il cui valore predefinito è 20 GB. Verifica quindi che ENGINE_WORKER_COUNT non sia impostato su 0, perché quel valore sospende il prelievo di nuovi job. Infine, conferma che sia configurata una credenziale per il modello eseguendo ./kritt setup, perché un GITHUB_TOKEN da solo non può eseguire analisi. docker compose logs engine indica il motivo per cui il job è stato ignorato.