DeepRobust: A PyTorch Library for Adversarial Attacks and Defenses

deeprobust.image.attack.base_attack

In order to make further development flexible and extendable, we organize functions shared by different methods in one module as the attack base class. The main body of the algorithm is override in each subclass. Following are detailed instructions for the functions contained in this class:

• •

  __init__(self, model, device = ’cuda’)

  Initialization is completed in this function.
  Parameters:

  • –

    model: the victim model.

  • –

    device: whether the program is run on GPU or CPU.

• •

  check_type_device(self, image, label, **kwargs)

  The main purpose for this function is to convert the input into a unified data type so that they can be correctly used in the algorithm procedure.
  Parameters:

  • –

    image: clean input.

  • –

    label: ground truth label corresponding to the clean input.

  • –

    **kwargs: optional input dependent on each derived class.

• •

  parse_params(self, **kwargs)

  This function provides the interface for these user defined parameters.
  Parameters:

  • –

    **kwargs: optional input dependent on each derived class.

• •

  generate(self, image, label, **kwargs)

  Call generate() to launch the attack algorithms.
  Parameters:

  • –

    **kwargs: optional input. Parameters for the attack algorithms.

deeprobust.image.attack.lbfgs  L-BFGS attack[2] is the key work that has arisen people’s attention on the neural network’s vulnerability to small perturbation. This work tries to find a minimal distorted adversarial example by solving a intuitive box-constraint optimization problem:

where $x^{\prime}$ is the adversarial example and $x$ is the clean example. We aim to find an adversarial example which could be classified as certain class and is close to the clean image. From the implementation perspective, addressing this optimization problem with two constraints is hard. Thus, this work turns to solve an alternative problem by doing binary search on a parameter $c$ to balance the trade off between perturb constraint and attack success for target class, and then use the LBFGS algorithm to get an approximate solution:

where $L(\theta,x^{\prime},t)$ denotes the loss value of $x^{\prime}$ for the target class t.

deeprobust.image.attack.fgsm  Fast Gradient Sign Method(FGSM)[6] is an one-step optimization problem. The intuition is to move the input sample along the gradient direction to achieve highest loss value corresponding to the ground truth label. Thus the perturbed samples could fool the network with high confidence. To guarantee that the adversarial example lies in a small nearby area of starting the point $x$, the gradient descent step is followed by a clip operation. Thus, the formulation of the process is described as follows:

Here, Clip denotes a function to project its argument to the surface of $x$’s $\epsilon$-neighbor ball.

deeprobust.image.attack.pgd  Projected Gradient Descent(PGD)[7] is an iterative version of the FGSM attack. The formulation of generating $x^{\prime}$ is:

It chooses the origin image as a starting point. PGD attack could create strong adversarial examples and is often used as a baseline attack for defense methods.

deeprobust.image.attack.deepfool  Deepfool attack aims to find a shortest path to let the data point $x$ go across the decision boundary. It starts from an binary classifier. Denote the hyperplane as $F=\{x:w^{T}+b=0\}$. The minimum perturbation is the distance from the data point $x_{0}$ to the hyperplane that can be:

This calculation can be extended to general classifiers and also extend this problem to $l_{p}$ norm constraint perturbation. Compare to other methods like FGSM and PGD, Deepfool attack produces less perturbation to attack successfully.

deeprobust.image.attack.cw  Carlini and Wagner’s attack  [8] aims to solve the same problem as defined in L-BFGS attack, namely trying to find the minimally-distorted perturbation.

It addresses the problem by instead solving:

where $f$ is defined as $f(x^{\prime},t)=(\max_{i\neq t}{Z(x^{\prime})_{i}}-Z(x^{\prime})_{t})^{+}$. Here, $Z()$ is the logits function. Minimizing $f(x^{\prime},t)$ encourages the algorithm to find an $x^{\prime}$ that has the larger score for class $t$ than any other label, so that the classifier will predict $x^{\prime}$ as the class $t$. Next, by applying a line search on the constant $c$, it can find the $x^{\prime}$ that has the least distance to $x$.

deeprobust.image.attack.universal  Previous methods only consider one specific targeted victim sample $x$. However, the work  [12] devises an algorithm that successfully misleads a classifier’s decision on almost all test images. It tries to find a perturbation $\delta$ satisfying:

1. 1.

   $||\delta||_{p}\leq\epsilon$.
   

2. 2.

   $\underset{x\sim D(x)}{{P}}(f(x+\delta)\neq f(x))\geq 1-\sigma$.

Formulation 1 is constraint of the norm of perturbation size and formulation 2 set a threshold for the probability of misclassification. Actually it aims to find a invisible perturbation $\delta$ such that the classifier gives wrong decisions on most of the samples.

deeprobust.image.attack.onepixel  One pixel attack  [14] constraints the perturbation by the $l_{0}$ norm instead of $l_{2}$ norm or $l_{\infty}$ norm. That is to say, finding the minimum number of pixels to perturb. Differential evolutionary algorithm(DE) is applied to solve this optimization problem.

deeprobust.image.attack.bpda  Backward Pass Differentiable Approximation(BPDA) [11] is a technique to attack defenses where gradients are not readily available. BPDA solves this problem by finding an approximation function for the non-differential layer and calculating the gradient through the approximation function.

deeprobust.image.attack.nattack  Nattack  [13] is a black box attack trying to find a probability density distribution of where adversarial samples lying over a small region centered around the input. One sample that are drawn from this distribution is likely to be an adversarial example.

It uses an intuitive way to find this density distribution. First, it initializes the distribution with random parameters. Then, it samples from this distribution several times as the neural network input and calculates the average loss value of those samples. Thus, the average loss is a function of the distribution parameters. Finally, It performs gradient decent on the average loss and updates the distribution parameters. It will iterates this process until successful attack.

deeprobust.image.defense.base_defense

This module is the base class of all the adversarial training algorithms. It provides basic components for defense methods. Following functions are contained in this class:

• •

  __init__(self, model, device)

  Parameter initialization is completed in this function.
  Parameters:

  • –

    model: the attack victim model.

  • –

    device: whether the program is run on GPU or CPU.

• •

  parse_params(self, **kwargs)

  This function provides the interface for user defined parameters.
  Parameters:

  • –

    **kwargs: optional input dependent on each derived class.

• •

  generate(self, train_loader, test_loader, **kwargs)

  Call generate() to launch the defense.
  Parameters:

  • –

    **kwargs: optional input dependent on each derived class.

• •

  loss(self, output, target)

  Calculate the training loss. This function will be overridden by each defense class according to the algorithms requirements.
  Parameters:

  • –

    output: model output.

  • –

    target: ground truth label.

• •

  adv_data(self, model, data, target, **kwargs)

  Generate adversarial training samples for robust training. This function will be overridden by each defense class according to algorithms requirements.
  Parameters:

  • –

    model: The victim model used to generate the adversarial example.

  • –

    data: clean data.

  • –

    target: target label

  • –

    **kwargs: optional parameters.

• •

  train(self, train_loader, optimizer, epoch)

  Call train to train the adversarial model.
  Parameters:

  • –

    train_loader: the dataloader used to train robust model.

  • –

    optimizer: the optimizer for the training process.

  • –

    epoch: maximum epoch for the training process.

  • –

    **kwargs: optional input dependent on each derived class.

• •

  test(self, test_loader)

  Call test() function to test adversarial model.
  Parameters:

  • –

    test_loader: the dataloader used to test model.

deeprobust.image.defense.fgsmtraining  FGSM adversarial training  [6] aims to improve model accuracy by training with adversarial examples. It generates adversarial examples in each iteration and updates model parameters via these adversarial examples.

deeprobust.image.defense.fast  Fast  [15] is an improved version of FGSM adversarial training. This work finds out that by simply adding a random initialization into the adversarial training samples’ generating process, the model robustness would improve significantly

deeprobust.image.defense.pgdtraining  PGD adversarial training uses adversarial examples generated by PGD instead of FGSM to train the model and achieve overall high performance.

deeprobust.image.defense.YOPO  You-only-Propagate-Once(YOPO) [16] is an accelerated version of the PGD adversarial training. When it generates the PGD adversarial examples for a $N$ layer network, it approximates the derivative of first $N-1$ layer as a constant, therefore there is no need to calculate the whole back propagation process in every iteration. Thus, the training time would be remarkably reduced.

deprobust.image.defense.trades  The work [17] proposes a adversarial training strategy which encourages the clean samples and adversarial examples to be close in feature space. Its training objective is to minimize the loss:

This loss function can be devided into two parts, the first part is the natural loss while the second part set a goal for minimizing the distance between the classifier output for those examples that are close in input space. Similar to the PGD adversarial training strategy, in each step, it first solves the inner maximization problem to find an optimal $x^{\prime}$, and then updates model parameters to minimize the outside loss value.

deeprobust.image.defense.TherEncoding  Thermometer encoding [18] is one way to mask the gradient information of the DNN models, in order to avoid the attacker from finding successful adversarial examples. It uses a preprocessor to discretize an image’s pixel value $x_{i}$ into a $l$-dimensional vector $\tau(x_{i})$. (e.g. when $l=10$, $\tau(0.66)=1111110000$). The vector $\tau(x_{i})$ acts as a “thermometer” to record the pixel $x_{i}$’s value.

deeprobust.image.defense.LIDclassifier Local Intrinsic Dimensionality(LID) detection  [19] tries to train a classifier to distinguish adversarial examples from normal examples based on the LID features. Starting from a sample, it calculates the number of data points in a ball of a certain distance, and LID features measure the growth rate of the number of data points as the distance increases.

deeprobust.graph.defense.adv_training  Since adversarial training is a widely used countermeasure for adversarial attacks in the image data [6], we can also adopt this strategy to defend graph adversarial attacks. The min-max optimization problem indicates that adversarial training involves two processes: (1) generating perturbations that maximize the prediction loss and (2) updating model parameters that minimize the prediction loss. By alternating the above two processes attractively, we can train a robust model against adversarial attacks. Since there are two inputs for graphs, i.e., adjacency matrix and attribute matrix, adversarial training can be done on them separately.

dedprobust.graph.defense.gcn_jaccard  The work [24] proposes a preprocessing method based on two empirical observations of the attack methods: (1) Attackers usually prefer to adding edges over removing edges or modifying features and (2) Attackers tend to connect dissimilar nodes. Based on these findings, they propose a defense method by eliminating the edges whose two end nodes have small Jaccard Similarity [30].

dedprobust.graph.defense.gcn_svd  It is observed that Nettack [22] generates the perturbations which mainly change the small singular values of the graph adjacency matrix [31]. Thus it proposes to preprocess the perturbed adjacency matrix by using truncated SVD to get its low-rank approximation.

deprobust.graph.defense.rgcn  Different from the above preprocessing methods which try to exclude adversarial perturbations, RGCN [32] aims to train a robust GNN model by penalizing model’s weights on adversarial edges or nodes. Based on the assumption that adversarial nodes may have high prediction uncertainty, they propose to model the hidden representation of nodes as Gaussian distribution with mean value and variance where the uncertainty can be reflected in the variance. When aggregating the information from neighbor nodes, it applies an attention mechanism to penalize the nodes with high variance.

In deeprobust.image.netmodels, we provide several deep network architecture. Call train() to train a model.

To launch an attack method, The first step is to import certain attack class from deeprobust.image.attack. Then, we need to initialize a victim model and create a dataloader, which contains the test images to be generated as adversarial examples. Then, we can feed the model and data to the attack method. The output would be adversarial examples.

Defense method can be imported in deeprobust.image.defense. We need to feed a model structure and a dataloader to the defense model. The output would be adversarial trained model and the performance on both clean data and adversarial data.

We provide a simple access to evaluate the performance of attack toward defense.

We show an example of attacking graph neural networks. We will use a linearized GCN as the surrogate model and apply untargeted Metattack to generate perturbed graph on the Cora citation dataset.

First we need to import the packages we are going to use in the head of the code and load Cora dataset.

Then set up the surrogate model to be attacked.

Then we use Metattack to generate perturbations to attack the surrogate model. Here the variable modified_adj is the perturbed graph generated by Metattack.

We show an example of defending graph adversarial attacks. We will use Metattack as the attacking method and GCN-Jaccard as the defense method.

First, we import all the packages we need to use and load the clean graph and pre-attacked graph of Cora dataset.

Then we set up the defense model GCN-Jaccard and test it performance on the perturbed graph.

As a comparison, we can also set up GCN model and test its performance on the perturbed graph.