How it Works
CleverHans is a Python library designed to benchmark the vulnerability of machine learning systems to adversarial examples. It provides reference implementations of attacks such as the Fast Gradient Sign Method (FGSM), Projected Gradient Descent (PGD), and the Carlini-Wagner attack. These implementations are structured to allow researchers and practitioners to construct adversarial examples, evaluate defenses, and measure model robustness.
The library is organized into three primary directories: cleverhans/, tutorials/, and defenses/. The cleverhans/ directory contains attack implementations, each framework (JAX, PyTorch, and TensorFlow 2) having its own subdirectory. The tutorials/ directory includes scripts demonstrating how to use CleverHans for tasks like training MNIST and CIFAR10 models and generating adversarial examples with FGSM and PGD. The defenses/ directory holds implementations of defensive strategies against adversarial attacks.
CleverHans relies on JAX, PyTorch, or TensorFlow 2 for accelerating computations. Installation requires one of these frameworks as a prerequisite. Users can install CleverHans via pip or clone the repository for development. The library supports Python 3.6 and is tested on Ubuntu 18.04 LTS with specific versions of JAX (0.2), PyTorch (1.7), and TensorFlow 2.4.
The library emphasizes modularity, particularly in version 3.1.0 and later, where attacks are stored in separate files to improve maintainability. This structure facilitates contributions and ensures compatibility across frameworks. Users are encouraged to report benchmarks using versioned releases, specifying the attack method, configuration variables, and CleverHans version to ensure reproducibility.
Use Cases
CleverHans is primarily used for testing and red teaming machine learning models. Researchers and practitioners employ it to assess how vulnerable models are to adversarial perturbations, which are carefully crafted inputs designed to fool models into making incorrect predictions. By generating adversarial examples, users can identify weaknesses in model robustness and evaluate the effectiveness of defensive mechanisms.
The library supports two key use cases: constructing adversarial examples and benchmarking defenses. For constructing attacks, CleverHans implements standard methods like FGSM, PGD, and Carlini-Wagner, allowing users to generate adversarial examples for various datasets, including MNIST and CIFAR10. Tutorials in the tutorials/ directory guide users through these processes, covering model training and adversarial example generation.
In benchmarking defenses, CleverHans provides implementations of defensive strategies within the defenses/ directory. Researchers can test how well these defenses mitigate adversarial attacks, comparing performance across different models and attack scenarios. The library’s modular design enables users to experiment with new attacks or defenses, contributing to ongoing advancements in adversarial machine learning research.
The library’s versioned releases and detailed documentation allow researchers to cite specific implementations, ensuring that results can be validated and built upon by others. For example, a researcher might report benchmarking a model’s robustness using CleverHans v4.0.0 with the FastGradientMethod and a max-norm epsilon of 0.3, providing transparency in their methodology.
Key Features & Capabilities
CleverHans supports three major deep learning frameworks: JAX, PyTorch, and TensorFlow 2. Version 4.0.0 marked the discontinuation of TensorFlow 1 support, consolidating efforts on TF2, PyTorch, and JAX. Users requiring TF1 implementations can still access them via the cleverhans_v3.1.0/ directory.
Key attacks include FGSM, PGD, and Carlini-Wagner, which are widely recognized in adversarial machine learning research. For instance, the MNIST tutorial covers adversarial example generation using FGSM and PGD in JAX and TensorFlow 2.
CleverHans encourages community contributions, particularly through coordinated efforts on the discussion board. Contributors are expected to follow the Black coding style and avoid adding git submodules. Bug fixes and new features are managed via pull requests, with the library’s maintainers prioritizing implementations in PyTorch while welcoming contributions for all supported frameworks. The library’s development roadmap includes continuous updates to attacks and defenses, ensuring it remains relevant in a rapidly evolving field.
The examples/ directory, though less maintained than the core library, contains scripts showcasing additional use cases, such as participating in adversarial example contests. While this directory is currently empty due to the discontinuation of TF1 support, users are invited to submit their own examples via pull requests. The tutorials, in contrast, are rigorously tested and maintained to ensure they remain functional, though they are not considered part of the stable API and may change without notice.
CleverHans also provides guidelines for reporting benchmarks, emphasizing the use of versioned releases to ensure reproducibility. Researchers are advised to specify the attack method, configuration variables, and CleverHans version in their reports. For example, a benchmark report might state: 'We benchmarked the robustness of our method to adversarial attack using v4.0.0 of CleverHans.
This metaphor highlights the risk of machine learning models achieving high accuracy on training data while failing to generalize to adversarial or out-of-distribution inputs. CleverHans serves as a tool to expose such vulnerabilities, reinforcing the importance of robust model evaluation.