Avvio rapido: dopo l'Installazione, esegui la Demo — funziona immediatamente senza configurazione dei dati. config.example.yaml, trattato più avanti in Configurazione, è un modello per i tuoi risultati/artefatti e non verrà eseguito finché non lo modifichi.

Installazione

Imposta la chiave API:

Per un proxy LiteLLM dell'organizzazione, usa config.litellm.example.yaml — è commentato inline. Le credenziali e i valori degli header personalizzati vengono letti dalle variabili d'ambiente e non vengono mai memorizzati nella configurazione di SAFE o nei file dei risultati.

Demo

demo/ contiene tre piccoli artefatti di esempio completamente sintetici — nessuno derivato o corrispondente a un reale artefatto di ricerca pubblicato — uno per etichetta della tassonomia, così i revisori possono esercitare l'intera pipeline senza alcun dato esterno:

• demo-contextual-risk/ — un aggregatore di checkpoint di federated learning giocattolo che deserializza un checkpoint scaricato da un URL fornito dal chiamante con torch.load. Un input non attendibile proveniente dalla rete raggiunge un sink di deserializzazione non sicura, che SAFE dovrebbe classificare come CONTEXTUAL_RISK.
• demo-hardening-recommendation/ — un harness di benchmark giocattolo che esegue subprocess.run(..., shell=True) su righe di comando che sono tutte letterali Python hardcoded, senza input controllato dal chiamante. SAFE dovrebbe classificare questo come HARDENING_RECOMMENDATION: il pattern di shell è reale e merita di essere segnalato, ma nulla di esterno può raggiungerlo o influenzarlo.
• demo-false-positive/ — un generatore di fixture di test ancorato a una versione precedente di Pillow con un avviso ipotetico di bomba di decompressione. Il codice crea solo nuove immagini in memoria e non apre mai dati esterni, quindi il percorso di codice effettivo dell'avviso non viene mai raggiunto. SAFE dovrebbe classificare questo come FALSE_POSITIVE.

demo/findings.csv contiene un risultato per artefatto, e demo/demo-zero-shot.yaml / demo/demo-agentic.yaml sono configurazioni pronte all'uso (artifact_root: . si risolve relativamente al file di configurazione, quindi esegui dall'interno di demo/):

I risultati finiscono rispettivamente in demo/runs/demo-zero-shot/ e demo/runs/demo-agentic/ (vedi Output).

Tre etichette

• CONTEXTUAL_RISK
• HARDENING_RECOMMENDATION
• FALSE_POSITIVE

Non viene utilizzata alcuna categoria aggiuntiva né regola deterministica di cambio etichetta. Un meccanismo di ricerca/sicurezza documentato e isolato nel codice dell'artefatto viene classificato come HARDENING_RECOMMENDATION, poiché la pratica sottostante è comunque reale anche quando l'isolamento limita l'effettiva sfruttabilità.

Classi binarie

• SECURITY_RELEVANT: un rischio contestuale valido o una preoccupazione di hardening, incluso il comportamento di ricerca sulla sicurezza intenzionale e isolato.
• NON_SECURITY: un risultato falso, non corrispondente, non applicabile, assente o dimostrabilmente inutilizzato relativo alla funzionalità interessata.

Il valutatore deriva anche una vista binaria dalle previsioni multiclasse: FALSE_POSITIVE diventa NON_SECURITY; ogni altra etichetta multiclasse diventa SECURITY_RELEVANT. I risultati binari diretti e derivati rimangono esplicitamente separati.

Struttura di input

La corrispondenza è esatta: artifact_id = artifact_001 si risolve in artifacts/artifact_001/.

Colonne CSV richieste:

Colonne opzionali:

Una colonna indice iniziale senza nome viene ignorata. Le colonne aggiuntive vengono preservate dal modello di input.

Esempio:

Genera risultati da un nuovo codebase

scripts/run_scanners.py e scripts/build_findings_csv.py producono il findings.csv e il layout degli artefatti descritti sopra direttamente dal tuo codice, usando Semgrep e Trivy.

Installa Semgrep (funziona allo stesso modo su qualsiasi sistema operativo, incluso Linux):

Installa Trivy su Linux — tramite il repository apt (Debian/Ubuntu):

oppure lo script di installazione ufficiale, che funziona su qualsiasi distribuzione Linux e installa una release binaria in /usr/local/bin (non richiede pacchetti root oltre a sudo per quella directory):

Verifica che entrambi siano su PATH prima di continuare:

Poi organizza una directory per artefatto sotto un artifact_root/ ed esegui:

Il primo comando esegue Semgrep e Trivy (scansione vulnerabilità e segreti) su ogni directory di artefatti e salva il JSON grezzo degli scanner. Il secondo analizza quel JSON in un findings.csv compatibile con SAFE (le colonne corrispondono a Struttura di input; file viene riportato in modo relativo a ciascuna directory di artefatti). Passa --skip-semgrep/--skip-trivy a uno dei due script per eseguire un solo strumento. --config su run_scanners.py fissa un ruleset Semgrep specifico invece del auto predefinito, che è comodo ma non riproducibilmente fissato.

Configurazione

Questa sezione riguarda l'esecuzione di SAFE sui tuoi CSV di risultati e cartelle di artefatti (vedi Struttura di input sopra). Se vuoi solo vedere SAFE in esecuzione, usa la Demo — config.example.yaml qui sotto è un modello e non verrà eseguito così com'è.

Copia config.example.yaml:

Poi modifica input_csv e artifact_root (e opzionalmente paper_root) per puntare ai tuoi dati prima di eseguire.

Impostazioni chiave:

• model / provider: identificatore esatto del modello OpenAI (o alias LiteLLM), e openai o litellm con URL del proxy e nome della variabile d'ambiente per le credenziali.
• analysis_mode: zero_shot o agentic.
• classification_task: binary o multiclass; indipendente da analysis_mode.
• max_agent_steps: richiesto solo in una configurazione agentica.
• max_workers / max_output_tokens / max_schema_retries: concorrenza, tetto di output per risposta e budget di nuovi tentativi di chiamata al modello per risposte non valide rispetto allo schema.
• resume / resume_policy: incomplete ritenta i fallimenti, gli artefatti mancanti e i risultati non tentati; failed_only ritenta solo i fallimenti mantenendo i successi registrati.
• cost: contabilità dei costi live opzionale e terminazione max_run_cost_usd.

Il modello predefinito è gpt-5.6-sol. Cambialo esplicitamente se disponibilità, costi o requisiti di latenza differiscono.

Esegui l'analisi

Oppure senza installare il comando console:

Per un confronto eseguibile e abbinato con i dati sintetici inclusi, vedi Demo (demo/demo-zero-shot.yaml e demo/demo-agentic.yaml). Differiscono solo in analysis_mode e run_name. La modalità zero-shot effettua una chiamata al modello sulle prove di base. La modalità agentica parte dalle stesse prove e può chiamare strumenti di repository di sola lettura limitati prima di restituire lo stesso risultato strutturato.

Output

results.csv è pensato per l'analisi. results.jsonl preserva i record strutturati completi. Le prove e gli output grezzi del modello supportano l'audit e l'analisi degli errori. Entrambi sono canonici: contengono solo il record più recente per ogni risultato, mentre logs/result_attempts.jsonl è append-only e preserva ogni esito storico.

Al ripristino, SAFE prima ri-analizza le risposte grezze salvate di ogni risultato fallito con il parser rigoroso corrente; una classificazione unicamente valida viene recuperata senza una chiamata API. Solo i fallimenti non recuperabili vengono pianificati per l'inferenza del modello. Per una continuazione solo-fallimenti di un run parzialmente completato, mantieni lo stesso output_root e run_name e imposta:

Per valutare le previsioni rispetto a un CSV gold etichettato (con una colonna security_label o security_class):

Test

La suite di test usa un provider fittizio e quindi non richiede una chiave API.