SAFE

SAFE esegue una valutazione di sicurezza controllata e consapevole del repository dei risultati di Semgrep e Trivy negli artefatti di ricerca.

Supporta due compiti di classificazione indipendenti: la previsione binaria diretta (SECURITY_RELEVANT o NON_SECURITY) e la tassonomia contestuale dettagliata multiclasse (tre etichette — vedi Tre etichette). Ogni compito può essere eseguito in modalità zero-shot o agentica.

Richiede solo:

1. Un CSV di risultati delimitato da punto e virgola.
2. Una directory contenente una cartella di artefatti di ricerca per ogni artifact_id.
3. Opzionalmente, una raccolta di PDF/testi di articoli indicizzata per artifact_id.
4. Una chiave API OpenAI o accesso a un proxy LiteLLM dell'organizzazione.

Non si addestra né si ottimizza su alcun dato di valutazione etichettato. I dati etichettati vengono utilizzati solo dopo l'inferenza, per valutare le previsioni, e non vengono mai visti dal classificatore. SAFE non esegue mai il codice degli artefatti; il testo del repository viene trattato come prova non attendibile, non come istruzioni.

Questa release contiene il codice sorgente completo di safe_audit, la CLI e i test, oltre a una demo/ autonoma di tre artefatti di esempio completamente sintetici che puoi eseguire end-to-end senza alcun dato esterno. Esclude il corpus reale di artefatti di ricerca, le etichette di verità di base e i risultati di valutazione utilizzati nell'articolo.

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

cd path/to/safe-artifact-auditor
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Imposta la chiave API:

export OPENAI_API_KEY="your-key"

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/):

cd demo
safe-audit run --config demo-zero-shot.yaml
safe-audit run --config demo-agentic.yaml

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

project/
├── config.yaml
├── data/
│   └── findings.csv
└── artifacts/
    ├── artifact_001/
    ├── artifact_002/
    └── artifact_003/

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

Colonne CSV richieste:

artifact_id;tool;finding_id

Colonne opzionali:

artifact_id;tool;finding_id;category;severity_raw;file;line;message;package;version;cwe;cvss;scanner_applicable

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

Esempio:

artifact_id;tool;finding_id;category;severity_raw;file;line;message;package;version;cwe;cvss;scanner_applicable
artifact_001;semgrep;python.lang.security.audit.subprocess-shell-true;code;HIGH;src/probe.py;42;Shell command uses shell=True;;;;CWE-78;;yes
artifact_002;trivy;DEMO-CVE-0001;dependency;HIGH;;;Affected package (illustrative, not a real CVE);example-lib;1.2.0;CWE-502;8.1;yes

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):

pip install semgrep

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

sudo apt-get install wget gnupg
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
sudo apt-get update
sudo apt-get install trivy

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):

curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sudo sh -s -- -b /usr/local/bin

Verifica che entrambi siano su PATH prima di continuare:

semgrep --version
trivy --version

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

python scripts/run_scanners.py artifact_root --output scan-output
python scripts/build_findings_csv.py scan-output --output data/findings.csv