AdverTorch: BorealisAI's Practical Toolbox for Adversarial Attacks and Defences

A walkthrough of AdverTorch — a PyTorch toolbox from BorealisAI that gives researchers and tinkerers a ready-made kit of adversarial attacks, defences, and robust training methods.

#adversarial-perturbation#pytorch#open-source#toolbox#ai-security

Why AdverTorch Matters

If you have read any of the earlier articles in this series, you have seen how adversarial perturbations work — tiny, invisible changes to images that can completely fool an AI model. But there is a big gap between understanding the idea and actually running an attack yourself.

That is where AdverTorch comes in.

Created by the team at BorealisAI (a Canadian AI research lab based in Montreal), AdverTorch is an open-source Python toolbox designed to make adversarial robustness research practical and accessible. It has over 1,400 stars on GitHub and is used by more than 200 other projects — making it one of the most popular libraries in the adversarial ML space.

What makes it important? Before AdverTorch, researchers studying adversarial attacks had to re-implement every attack from scratch, reading the original paper and writing their own code. AdverTorch changed that by bundling all the major attack algorithms into one library that you can install with a single command.

What Is AdverTorch?

AdverTorch (short for “Adversarial” + “PyTorch”) is a toolbox — a collection of ready-made code modules — for adversarial robustness research. It is built on top of PyTorch, one of the most popular deep learning frameworks in the world.

The toolbox has three main parts:

Component What It Does
Attacks Algorithms that generate adversarial perturbations to fool AI models
Defences Methods that make AI models harder to fool
Adversarial Training Scripts that train models to be robust against attacks

The authors published a paper about it on arXiv in 2019 with the fitting title “AdverTorch v0.1: An Adversarial Robustness Toolbox based on PyTorch” 1.

What Attacks Does It Include?

The real value of AdverTorch is that it gives you access to many of the most famous adversarial attack algorithms, all with a consistent interface. Here are some of the key ones:

1. PGD Attack (Projected Gradient Descent)

This is the most widely used adversarial attack in modern research. It works by taking small, repeated steps in the direction that confuses the model the most. At each step, it clips the perturbation to stay within a certain “budget” (the epsilon value that limits how visible the change is).

from advertorch.attacks import LinfPGDAttack

adversary = LinfPGDAttack(
    model,                         # the AI model to attack
    loss_fn=nn.CrossEntropyLoss(reduction="sum"),
    eps=0.3,                       # maximum perturbation size
    nb_iter=40,                    # number of attack steps
    eps_iter=0.01,                 # step size per iteration
    rand_init=True,                # random starting point
    clip_min=0.0, clip_max=1.0,    # keep pixel values in range
    targeted=False                 # untargeted: just break it
)

# Generate an adversarial example
adv_image = adversary.perturb(original_image, true_label)

2. DeepFool Attack

DeepFool is a more efficient attack that tries to find the smallest possible perturbation that causes a misclassification. It works by finding the nearest “decision boundary” — the invisible line the model draws between one class and another — and pushing the image just across it.

3. JSMA (Jacobian Saliency Map Attack)

This attack is more surgical. It calculates which pixels have the most influence on the model’s output, then changes only those specific pixels one by one. It tends to produce perturbations that look less like random noise and more like a targeted modification.

4. Fast Feature Attack (FFA)

Instead of targeting the final classification output, this attack targets the internal features of the model — the patterns the model learns in its middle layers. It is useful for research into how different layers of a neural network respond to perturbations.

Defences and Robust Training

Attacks are only half the story. AdverTorch also includes tools for defending against adversarial examples.

The most important technique is adversarial training — the process of training a model on both normal images and adversarial examples at the same time. This is like giving the model a vaccine: it learns to ignore the small perturbations that would normally fool it.

The toolbox includes a complete training script for MNIST (the classic handwritten digit dataset) that shows you exactly how to:

  1. Load a normal dataset
  2. Generate adversarial examples during training
  3. Update the model to resist those examples
  4. Evaluate how well it defends against new attacks
# From advertorch_examples/tutorial_train_mnist.py
# Simplified structure of adversarial training:

for epoch in range(num_epochs):
    for batch_idx, (data, target) in enumerate(train_loader):
        data, target = data.to(device), target.to(device)
        
        # First: train on clean data
        optimizer.zero_grad()
        output = model(data)
        loss = nn.CrossEntropyLoss()(output, target)
        loss.backward()
        optimizer.step()
        
        # Second: generate adversarial examples
        adv_data = adversary.perturb(data, target)
        
        # Third: train on adversarial data
        optimizer.zero_grad()
        output = model(adv_data)
        loss = nn.CrossEntropyLoss()(output, target)
        loss.backward()
        optimizer.step()

How a Lay Person Can Use It

Here is the good news: you do not need to be a professional AI researcher to use AdverTorch. If you know basic Python and have PyTorch installed, you can start generating adversarial examples in about ten minutes.

Step 1: Install

pip install advertorch

That is it. One line.

Step 2: Grab a Pre-Trained Model

import torch
import torchvision.models as models

# Load a standard image classifier that comes with PyTorch
model = models.resnet18(pretrained=True)
model.eval()

Step 3: Attack It

from advertorch.attacks import LinfPGDAttack
import torch.nn as nn

adversary = LinfPGDAttack(
    model, loss_fn=nn.CrossEntropyLoss(reduction="sum"),
    eps=0.05, nb_iter=10, eps_iter=0.01,
    rand_init=True, clip_min=0.0, clip_max=1.0,
)

# Load an image as a PyTorch tensor
# ... (your image loading code here)

adv_image = adversary.perturb(original_image, true_label)

# Save the adversarial image
torchvision.utils.save_image(adv_image, "adversarial_output.png")

That is a complete adversarial attack in fewer than 15 lines of code.

Step 4: Experiment

The real learning happens when you start tweaking the parameters:

  • Increase eps (the perturbation budget) — the image gets noisier and the model fails more often
  • Decrease eps — the image stays cleaner, and you can see how little noise is needed to fool the model
  • Try targeted=True — instead of just breaking the model, try to make it classify your image as a specific wrong label
# Want the model to think your dog photo is a toaster?
targeted = True
target_label = torch.tensor([859])  # the class index for "toaster" in ImageNet
adv_image = adversary.perturb(original_image, target_label)

AdverTorch has earned its 1,400+ stars for a few clear reasons:

1. Ease of use. The API is clean and consistent. Every attack follows the same pattern: create an adversary, call .perturb(), get an adversarial image.

2. Broad coverage. It includes most of the major attack algorithms from the research literature. You do not need to hunt down ten different code repositories to compare attacks.

3. Built on PyTorch. PyTorch is the most popular deep learning framework in academic research. By building on top of it, AdverTorch works naturally with the tools researchers already use.

4. Good documentation. The library has full documentation at advertorch.readthedocs.io, plus Jupyter notebook tutorials that walk you through real examples.

5. Open source and freely licensed. It is released under the LGPL license, meaning you can use it, modify it, and include it in your own projects.

The Honest Picture

AdverTorch has not been updated in about four years (the last commit was May 2022). In the fast-moving world of ML research, that means some newer attack algorithms are not included, and some parts may need small patches to work with modern versions of PyTorch.

However, the core attacks — PGD, DeepFool, FGSM, and JSMA — are “classic” algorithms that are still used in papers every day. They are well-tested and stable. For someone learning the basics, or running standard robustness evaluations, AdverTorch is still an excellent choice.

If you need bleeding-edge attacks from the last year of research, you might look elsewhere. But if you want a solid, well-documented foundation that covers all the important ground, AdverTorch delivers.

Summary

Aspect Detail
What it is A PyTorch toolbox for adversarial attacks, defences, and robust training
Created by BorealisAI (Montreal, Canada)
GitHub stars 1,400+
Used by 200+ other projects
Key attacks PGD, DeepFool, JSMA, FGSM, Fast Feature Attack
License LGPL-3.0
Last update 2022 (stable, not abandoned)
Install pip install advertorch
Paper arXiv:1902.07623

AdverTorch is a great starting point for anyone who wants to move from reading about adversarial perturbations to actually generating them. It lowers the barrier to entry, gives you a consistent interface to compare attacks side by side, and includes everything you need to start experimenting — as long as you know a little Python and have PyTorch ready to go.

Footnotes

  1. Ding, G. W., Wang, L., & Jin, X. (2019). AdverTorch v0.1: An Adversarial Robustness Toolbox based on PyTorch. arXiv:1902.07623. https://arxiv.org/abs/1902.07623 ↩