CleverHans (ultima release: v4.0.0)

Questo repository contiene il codice sorgente di CleverHans, una libreria Python per valutare la vulnerabilità dei sistemi di machine learning agli esempi avversariali. Puoi saperne di più su queste vulnerabilità nel blog associato.

La libreria CleverHans è in continuo sviluppo e accoglie sempre contributi degli attacchi e delle difese più recenti. In particolare, accogliamo sempre volentieri aiuto per risolvere le issue attualmente aperte.

Dalla v4.0.0, CleverHans supporta 3 framework: JAX, PyTorch e TF2. Attualmente diamo priorità all'implementazione degli attacchi in PyTorch, ma accogliamo con piacere contributi per tutti e 3 i framework. Nelle versioni v3.1.0 e precedenti, CleverHans supportava TF1; il codice per la v3.1.0 si trova in cleverhans_v3.1.0/ oppure estraendo una release Github precedente.

La libreria si concentra sulla fornitura di implementazioni di riferimento di attacchi contro modelli di machine learning per aiutare a valutare i modelli rispetto agli esempi avversariali.

La struttura delle directory è la seguente: cleverhans/ contiene le implementazioni degli attacchi, tutorials/ contiene script che dimostrano le funzionalità di CleverHans e defenses/ contiene le implementazioni delle difese. Ogni framework ha la propria sottodirectory all'interno di queste cartelle, ad es. cleverhans/jax.

Configurazione di CleverHans

Dipendenze

Questa libreria usa Jax, PyTorch o TensorFlow 2 per accelerare i calcoli sui grafi eseguiti da molti modelli di machine learning. Pertanto, installare una di queste librerie è un prerequisito.

Installazione

Una volta gestite le dipendenze, puoi installare CleverHans usando pip o clonando questo repository Github.

Installazione tramite pip

Se stai installando CleverHans usando pip, esegui il seguente comando:

pip install cleverhans

Questo installerà l'ultima versione caricata su Pypi. Se invece desideri installare la versione più recente in sviluppo, usa:

pip install git+https://github.com/cleverhans-lab/cleverhans.git#egg=cleverhans

Installazione per lo sviluppo

Se vuoi effettuare un'installazione modificabile (editable) di CleverHans così da poter sviluppare la libreria e contribuire con le tue modifiche, prima crea un fork del repository su GitHub e poi clona il tuo fork in una directory a tua scelta:

git clone https://github.com/<your-org>/cleverhans

Puoi quindi installare il pacchetto locale in modalità "editable" per aggiungerlo al tuo PYTHONPATH:

cd cleverhans
pip install -e .

Configurazioni attualmente supportate

Sebbene CleverHans probabilmente funzioni su molte altre configurazioni di macchine, attualmente lo testiamo con Python 3.6, Jax 0.2, PyTorch 1.7 e Tensorflow 2.4 su Ubuntu 18.04 LTS (Bionic Beaver).

Supporto

Se hai una richiesta di supporto, ti preghiamo di fare una domanda su StackOverflow piuttosto che aprire una issue nel tracker GitHub. Il tracker delle issue di GitHub dovrebbe essere usato solo per segnalare bug o richiedere funzionalità.

Contribuire

I contributi sono benvenuti! Per velocizzare il processo di revisione del codice, chiediamo che:

• Nuovi sforzi e funzionalità vengano coordinati nella bacheca delle discussioni.
• Quando contribuisci al codice di CleverHans, dovresti seguire lo stile di codifica Black nelle tue pull request.
• Non accettiamo pull request che aggiungono sottomoduli git a causa dei problemi che sorgono quando si mantengono i sottomoduli git.

Le correzioni di bug possono essere proposte tramite pull request Github.

Tutorial: directory tutorials

Per aiutarti a iniziare con le funzionalità offerte da questa libreria, la cartella tutorials/ include i seguenti tutorial:

• MNIST con FGSM e PGD (jax, tf2: questo tutorial spiega come addestrare un modello MNIST e creare esempi avversariali usando il metodo del gradiente del segno veloce e discesa del gradiente proiettata.
• CIFAR10 con FGSM e PGD (pytorch, tf2): questo tutorial spiega come addestrare un modello CIFAR10 e creare esempi avversariali usando il metodo del gradiente del segno veloce e la discesa del gradiente proiettata.

NOTA: i tutorial sono mantenuti con cura, nel senso che usiamo l'integrazione continua per assicurarci che continuino a funzionare. Non sono considerati parte dell'API e possono cambiare in qualsiasi momento senza preavviso. Non dovresti scrivere codice di terze parti che importa i tutorial e aspettarti che l'interfaccia non si rompa. Solo la libreria principale è soggetta alla nostra regola di preavviso di deprecazione dell'interfaccia di sei mesi.

NOTA: ti preghiamo di aprire una discussione nella bacheca delle discussioni prima di scrivere un nuovo tutorial. Poiché ogni nuovo tutorial comporta una grande quantità di codice duplicato rispetto ai tutorial esistenti, e poiché ogni riga di codice richiede test e manutenzione continui a tempo indeterminato, generalmente preferiamo non aggiungere nuovi tutorial. Ogni tutorial dovrebbe mostrare un modo estremamente diverso di usare la libreria. Chiamare semplicemente un attacco, un modello o un dataset diverso non basta a giustificare il mantenimento di un tutorial parallelo.

Esempi: directory examples

La cartella examples/ contiene script aggiuntivi per mostrare diversi usi della libreria CleverHans o per aiutarti a iniziare a competere in diverse competizioni sugli esempi avversariali. Non offriamo manutenzione o supporto continui per questa directory quanto per il resto della libreria, e se il codice qui presente si rompe potremmo semplicemente eliminarlo senza preavviso.

Dato che recentemente abbiamo interrotto il supporto a TF1, la cartella examples/ è attualmente vuota, ma sei invitato a inviare i tuoi usi tramite una pull request :)

I vecchi esempi per CleverHans v3.1.0 e precedenti si trovano in cleverhans_v3.1.0/examples/.

Riportare i benchmark

Quando riporti i benchmark, ti preghiamo di:

• Usare una release versionata di CleverHans. Puoi trovare un elenco delle versioni rilasciate qui.
• Usare l'ultima versione oppure, se confronti con una pubblicazione precedente, usare la stessa versione di quella pubblicazione.
• Indicare quale metodo di attacco è stato usato.
• Segnalare le variabili di configurazione usate per determinare il comportamento dell'attacco.