CleverHans (latest release: v4.0.0)

This repository contains the source code for CleverHans, a Python library to benchmark machine learning systems' vulnerability to adversarial examples. You can learn more about such vulnerabilities on the accompanying blog.

The CleverHans library is under continual development, always welcoming contributions of the latest attacks and defenses. In particular, we always welcome help towards resolving the issues currently open.

Since v4.0.0, CleverHans supports 3 frameworks: JAX, PyTorch, and TF2. We are currently prioritizing implementing attacks in PyTorch, but we very much welcome contributions for all 3 frameworks. In versions v3.1.0 and prior, CleverHans supported TF1; the code for v3.1.0 can be found under cleverhans_v3.1.0/ or by checking out a prior Github release.

The library focuses on providing reference implementation of attacks against machine learning models to help with benchmarking models against adversarial examples.

The directory structure is as follows: cleverhans/ contain attack implementations, tutorials/ contain scripts demonstrating the features of CleverHans, and defenses/ contains defense implementations. Each framework has its own subdirectory within these folders, e.g. cleverhans/jax.

Setting up CleverHans

Dependencies

This library uses Jax, PyTorch or TensorFlow 2 to accelerate graph computations performed by many machine learning models. Therefore, installing one of these libraries is a pre-requisite.

Installation

Once dependencies have been taken care of, you can install CleverHans using pip or by cloning this Github repository.

pip installation

If you are installing CleverHans using pip, run the following command:

pip install cleverhans

This will install the last version uploaded to Pypi. If you'd instead like to install the bleeding edge version, use:

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

Installation for development

If you want to make an editable installation of CleverHans so that you can develop the library and contribute changes back, first fork the repository on GitHub and then clone your fork into a directory of your choice:

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

You can then install the local package in "editable" mode in order to add it to your PYTHONPATH:

cd cleverhans
pip install -e .

Currently supported setups

Although CleverHans is likely to work on many other machine configurations, we currently test it with Python 3.6, Jax 0.2, PyTorch 1.7, and Tensorflow 2.4 on Ubuntu 18.04 LTS (Bionic Beaver).

Getting support

If you have a request for support, please ask a question on StackOverflow rather than opening an issue in the GitHub tracker. The GitHub issue tracker should only be used to report bugs or make feature requests.

Contributing

Contributions are welcomed! To speed the code review process, we ask that:

• New efforts and features be coordinated on the discussion board.
• When making code contributions to CleverHans, you should follow the Black coding style in your pull requests.
• We do not accept pull requests that add git submodules because of the problems that arise when maintaining git submodules.

Bug fixes can be initiated through Github pull requests.

Tutorials: tutorials directory

To help you get started with the functionalities provided by this library, the tutorials/ folder comes with the following tutorials:

• MNIST with FGSM and PGD (jax, tf2: this tutorial covers how to train an MNIST model and craft adversarial examples using the fast gradient sign method and projected gradient descent.
• CIFAR10 with FGSM and PGD (pytorch, tf2): this tutorial covers how to train a CIFAR10 model and craft adversarial examples using the fast gradient sign method and projected gradient descent.

NOTE: the tutorials are maintained carefully, in the sense that we use continuous integration to make sure they continue working. They are not considered part of the API and they can change at any time without warning. You should not write 3rd party code that imports the tutorials and expect that the interface will not break. Only the main library is subject to our six month interface deprecation warning rule.

NOTE: please start a thread on the discussion board before writing a new tutorial. Because each new tutorial involves a large amount of duplicated code relative to the existing tutorials, and because every line of code requires ongoing testing and maintenance indefinitely, we generally prefer not to add new tutorials. Each tutorial should showcase an extremely different way of using the library. Just calling a different attack, model, or dataset is not enough to justify maintaining a parallel tutorial.

Examples : examples directory

The examples/ folder contains additional scripts to showcase different uses of the CleverHans library or get you started competing in different adversarial example contests. We do not offer nearly as much ongoing maintenance or support for this directory as the rest of the library, and if code in here gets broken we may just delete it without warning.

Since we recently discontinued support for TF1, the examples/ folder is currently empty, but you are welcome to submit your uses via a pull request :)

Old examples for CleverHans v3.1.0 and prior can be found under cleverhans_v3.1.0/examples/.

Reporting benchmarks

When reporting benchmarks, please:

• Use a versioned release of CleverHans. You can find a list of released versions here.
• Either use the latest version, or, if comparing to an earlier publication, use the same version as the earlier publication.
• Report which attack method was used.
• Report any configuration variables used to determine the behavior of the attack.

For example, you might report "We benchmarked the robustness of our method to adversarial attack using v4.0.0 of CleverHans. On a test set modified by the FastGradientMethod with a max-norm eps of 0.3, we obtained a test set accuracy of 71.3%."

Citing this work

If you use CleverHans for academic research, you are highly encouraged (though not required) to cite the following paper: