CleverHans (aktuellste Version: v4.0.0)

Dieses Repository enthält den Quellcode für CleverHans, eine Python-Bibliothek zur Bewertung der Anfälligkeit von Machine-Learning-Systemen gegenüber adversarial examples. Mehr über solche Schwachstellen erfahren Sie im zugehörigen Blog.

Die CleverHans-Bibliothek wird kontinuierlich weiterentwickelt und freut sich stets über Beiträge der neuesten Angriffe und Abwehrmaßnahmen. Insbesondere freuen wir uns jederzeit über Hilfe bei der Lösung der derzeit offenen Issues.

Seit v4.0.0 unterstützt CleverHans 3 Frameworks: JAX, PyTorch und TF2. Wir priorisieren derzeit die Implementierung von Angriffen in PyTorch, freuen uns aber sehr über Beiträge für alle 3 Frameworks. In Versionen bis einschließlich v3.1.0 unterstützte CleverHans TF1; den Code für v3.1.0 finden Sie unter cleverhans_v3.1.0/ oder indem Sie eine frühere Github-Version auschecken.

Die Bibliothek konzentriert sich darauf, Referenzimplementierungen von Angriffen auf Machine-Learning-Modelle bereitzustellen, um beim Benchmarking von Modellen gegen adversarial examples zu helfen.

Die Verzeichnisstruktur ist wie folgt: cleverhans/ enthält die Angriffsimplementierungen, tutorials/ enthält Skripte, die die Funktionen von CleverHans demonstrieren, und defenses/ enthält Implementierungen von Abwehrmaßnahmen. Jedes Framework hat sein eigenes Unterverzeichnis in diesen Ordnern, z. B. cleverhans/jax.

Einrichtung von CleverHans

Abhängigkeiten

Diese Bibliothek verwendet Jax, PyTorch oder TensorFlow 2, um die von vielen Machine-Learning-Modellen durchgeführten Graphenberechnungen zu beschleunigen. Daher ist die Installation einer dieser Bibliotheken eine Voraussetzung.

Installation

Sobald die Abhängigkeiten berücksichtigt wurden, können Sie CleverHans mit pip installieren oder indem Sie dieses Github-Repository klonen.

pip-Installation

Wenn Sie CleverHans mit pip installieren, führen Sie den folgenden Befehl aus:

pip install cleverhans

Dadurch wird die letzte Version installiert, die auf Pypi hochgeladen wurde. Wenn Sie stattdessen die neueste Entwicklungsversion installieren möchten, verwenden Sie:

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

Installation für die Entwicklung

Wenn Sie eine bearbeitbare Installation von CleverHans vornehmen möchten, um die Bibliothek weiterzuentwickeln und Änderungen beizusteuern, forken Sie zunächst das Repository auf GitHub und klonen Sie dann Ihren Fork in ein Verzeichnis Ihrer Wahl:

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

Sie können das lokale Paket dann im „editable“-Modus installieren, um es zu Ihrem PYTHONPATH hinzuzufügen:

cd cleverhans
pip install -e .

Derzeit unterstützte Umgebungen

Obwohl CleverHans wahrscheinlich auf vielen anderen Maschinenkonfigurationen funktioniert, testen wir es derzeit mit Python 3.6, Jax 0.2, PyTorch 1.7 und Tensorflow 2.4 auf Ubuntu 18.04 LTS (Bionic Beaver).

Unterstützung erhalten

Wenn Sie eine Unterstützungsanfrage haben, stellen Sie bitte eine Frage auf StackOverflow, anstatt ein Issue im GitHub-Tracker zu eröffnen. Der GitHub-Issue-Tracker sollte nur verwendet werden, um Fehler zu melden oder Feature-Anfragen zu stellen.

Beitragen

Beiträge sind willkommen! Um den Code-Review-Prozess zu beschleunigen, bitten wir um Folgendes:

• Neue Vorhaben und Funktionen sollten auf dem Diskussionsforum abgestimmt werden.
• Wenn Sie Code zu CleverHans beitragen, sollten Sie in Ihren Pull-Requests den Black-Codestil befolgen.
• Wir akzeptieren keine Pull-Requests, die Git-Submodule hinzufügen, wegen der Probleme, die bei der Pflege von Git-Submodulen auftreten.

Fehlerbehebungen können über GitHub-Pull-Requests eingereicht werden.

Tutorials: Verzeichnis tutorials

Um Ihnen den Einstieg in die Funktionen dieser Bibliothek zu erleichtern, enthält der Ordner tutorials/ die folgenden Tutorials:

• MNIST mit FGSM und PGD (jax, tf2): dieses Tutorial behandelt, wie man ein MNIST-Modell trainiert und adversarial examples mit der Fast-Gradient-Sign-Methode und Projected Gradient Descent erzeugt.
• CIFAR10 mit FGSM und PGD (pytorch, tf2): dieses Tutorial behandelt, wie man ein CIFAR10-Modell trainiert und adversarial examples mit der Fast-Gradient-Sign-Methode und Projected Gradient Descent erzeugt.

HINWEIS: Die Tutorials werden sorgfältig gepflegt, in dem Sinne, dass wir kontinuierliche Integration verwenden, um sicherzustellen, dass sie weiterhin funktionieren. Sie gelten nicht als Teil der API und können sich jederzeit ohne Vorwarnung ändern. Sie sollten keinen Drittanbieter-Code schreiben, der die Tutorials importiert, und erwarten, dass die Schnittstelle nicht bricht. Nur die Hauptbibliothek unterliegt unserer Regel zur sechsmonatigen Ankündigung von Schnittstellenänderungen.

HINWEIS: Bitte starten Sie einen Thread im Diskussionsforum, bevor Sie ein neues Tutorial schreiben. Da jedes neue Tutorial im Vergleich zu den vorhandenen Tutorials eine große Menge an dupliziertem Code mit sich bringt und da jede Codezeile dauerhaft getestet und gepflegt werden muss, ziehen wir es im Allgemeinen vor, keine neuen Tutorials hinzuzufügen. Jedes Tutorial sollte eine extrem andere Art der Nutzung der Bibliothek demonstrieren. Allein einen anderen Angriff, ein anderes Modell oder einen anderen Datensatz aufzurufen, reicht nicht aus, um ein paralleles Tutorial zu rechtfertigen.

Beispiele: Verzeichnis examples

Der Ordner examples/ enthält zusätzliche Skripte, um verschiedene Verwendungszwecke der CleverHans-Bibliothek zu demonstrieren oder Ihnen den Einstieg in verschiedene Adversarial-Example-Wettbewerbe zu erleichtern. Wir bieten für dieses Verzeichnis bei weitem nicht so viel laufende Wartung oder Unterstützung an wie für den Rest der Bibliothek, und wenn Code hier beschädigt wird, löschen wir ihn möglicherweise einfach ohne Vorwarnung.

Da wir die Unterstützung für TF1 kürzlich eingestellt haben, ist der Ordner examples/ derzeit leer, aber Sie können Ihre Verwendungszwecke gerne per Pull-Request einreichen :)

Alte Beispiele für CleverHans v3.1.0 und früher finden Sie unter cleverhans_v3.1.0/examples/.

Berichterstattung von Benchmarks