このリポジトリには、機械学習システムの敵対的サンプルに対する脆弱性をベンチマークするためのPythonライブラリであるCleverHansのソースコードが含まれています。このような脆弱性の詳細については、付随するブログで学ぶことができます。
CleverHansライブラリは継続的に開発が進められており、最新の攻撃と防御の貢献を常に歓迎しています。特に、現在オープンしているissueの解決に向けた支援を常に歓迎しています。
v4.0.0以降、CleverHansはJAX、PyTorch、TF2の3つのフレームワークをサポートしています。現在はPyTorchでの攻撃の実装を優先していますが、3つのフレームワークすべてに対する貢献を大いに歓迎します。v3.1.0以前のバージョンでは、CleverHansはTF1をサポートしていました。v3.1.0のコードはcleverhans_v3.1.0/以下、または以前のGithubリリースをチェックアウトすることで確認できます。
このライブラリは、敵対的サンプルに対してモデルをベンチマークする際に役立つ、機械学習モデルに対する攻撃のリファレンス実装を提供することに焦点を当てています。
ディレクトリ構成は以下の通りです。cleverhans/には攻撃の実装が、tutorials/にはCleverHansの機能を示すスクリプトが、defenses/には防御の実装が含まれています。各フレームワークにはこれらのフォルダ内に独自のサブディレクトリがあり、例えばcleverhans/jaxのようになります。
このライブラリは、多くの機械学習モデルによって実行されるグラフ計算を高速化するために、Jax、PyTorch、またはTensorFlow 2を使用します。したがって、これらのライブラリのいずれかをインストールすることが前提条件です。
依存関係が整ったら、pipを使用するか、このGithubリポジトリをクローンしてCleverHansをインストールできます。
pipインストールpipを使用してCleverHansをインストールする場合は、次のコマンドを実行してください：
pip install cleverhans
これにより、Pypiにアップロードされた最新バージョンがインストールされます。代わりに開発中バージョンをインストールしたい場合は、次を使用してください：
pip install git+https://github.com/cleverhans-lab/cleverhans.git#egg=cleverhans
CleverHansの編集可能なインストールを作成して、ライブラリを開発し変更を貢献したい場合は、まずGitHubでリポジトリをフォークし、その後、フォークしたリポジトリを任意のディレクトリにクローンしてください：
git clone https://github.com/<your-org>/cleverhans
次に、ローカルパッケージを「editable」モードでインストールして、PYTHONPATHに追加できます：
cd cleverhans
pip install -e .
CleverHansは他の多くのマシン構成でも動作する可能性がありますが、現在はUbuntu 18.04 LTS（Bionic Beaver）上でPython 3.6、Jax 0.2、PyTorch 1.7、Tensorflow 2.4を使用してテストしています。
サポートが必要な場合は、GitHubトラッカーでissueを開くのではなく、StackOverflowで質問してください。GitHubのissueトラッカーは、バグの報告や機能リクエストにのみ使用してください。
貢献を歓迎します！コードレビューのプロセスを迅速化するために、以下をお願いしています：
Blackコーディングスタイルに従ってください。バグ修正はGithubのプルリクエストを通じて行えます。
tutorialsディレクトリこのライブラリが提供する機能の使い始めを支援するため、tutorials/フォルダには以下のチュートリアルが用意されています：
注：チュートリアルは、継続的インテグレーションを使用して動作し続けることを確認しているという意味で、慎重にメンテナンスされています。チュートリアルはAPIの一部とは見なされず、予告なくいつでも変更される可能性があります。チュートリアルをインポートするサードパーティのコードを書いて、そのインターフェースが壊れないと期待しないでください。6ヶ月のインターフェース廃止予告ルールが適用されるのはメインライブラリのみです。
注：新しいチュートリアルを作成する前に、ディスカッションボードでスレッドを開始してください。新しいチュートリアルはそれぞれ既存のチュートリアルと比較して大量の重複コードを伴い、またすべてのコード行は無期限に継続的なテストとメンテナンスを必要とするため、一般的に新しいチュートリアルの追加は望みません。各チュートリアルは、ライブラリの非常に異なる使用方法を示すものでなければなりません。単に異なる攻撃、モデル、またはデータセットを呼び出すだけでは、並行チュートリアルを維持する正当な理由にはなりません。
examplesディレクトリexamples/フォルダには、CleverHansライブラリのさまざまな用途を示す追加スクリプトが含まれており、さまざまな敵対的サンプルコンテストに参加するための手助けにもなります。このディレクトリに対しては、ライブラリの他の部分ほど継続的なメンテナンスやサポートを提供していません。ここにあるコードが壊れた場合、予告なく削除することがあります。
最近TF1のサポートを終了したため、現在examples/フォルダは空ですが、プルリクエストで使用例を提出することを歓迎します :)
CleverHans v3.1.0以前の古い例は、cleverhans_v3.1.0/examples/以下にあります。
ベンチマークを報告する際は、以下をお願いします：
例えば、次のように報告するかもしれません。「私たちはCleverHans v4.0.0を使用して、敵対的攻撃に対する私たちの手法の堅牢性をベンチマークしました。max-norm epsが0.3のFastGradientMethodによって修正されたテストセット上で、テストセット精度71.3%を得ました。」
学術研究でCleverHansを使用する場合、以下の論文を引用することを強く推奨します（必須ではありません）：
@article{papernot2018cleverhans,
title={Technical Report on the CleverHans v2.1.0 Adversarial Examples Library},
author={Nicolas Papernot and Fartash Faghri and Nicholas Carlini and
Ian Goodfellow and Reuben Feinman and Alexey Kurakin and Cihang Xie and
Yash Sharma and Tom Brown and Aurko Roy and Alexander Matyasko and
Vahid Behzadan and Karen Hambardzumyan and Zhishuai Zhang and
Yi-Lin Juang and Zhi Li and Ryan Sheatsley and Abhibhav Garg and
Jonathan Uesato and Willi Gierke and Yinpeng Dong and David Berthelot and
Paul Hendricks and Jonas Rauber and Rujun Long},
journal={arXiv preprint arXiv:1610.00768},
year={2018}
}
CleverHansという名前は、Bob Sturmによるプレゼンテーション『Clever Hans, Clever Algorithms: Are Your Machine Learnings Learning What You Think?』と、対応する論文『A Simple Method to Determine if a Music Information Retrieval System is a 'Horse'.』に由来しています。Clever Hans（賢いハンス）は、算数の質問に答えることを学習したように見えた馬ですが、実際には正しい答えを導くことを可能にする社会的シグナルを読み取ることを学習しただけでした。人々の顔を見ることができず、他のフィードバックも受け取れない統制された環境では、同じ質問に答えることができませんでした。Clever Hansの物語は、訓練データと同じ分布から抽出されたテストセットでは非常に高い精度を達成するかもしれないが、実際には根本的なタスクを理解しておらず、他の入力ではパフォーマンスが低下する機械学習システムの比喩です。
このライブラリは、University of TorontoのCleverHans Labによって共同でメンテナンスされています。現在の連絡先はJonas Guanです。以前はIan GoodfellowとNicolas Papernotによってメンテナンスされていました。
以下の著者が100行以上を貢献しました（GitHubのcontributorsページに従って順序付けられています）：
Copyright 2021 - Google Inc., OpenAI, Pennsylvania State University, University of Toronto.