是一个用于对抗鲁棒性研究的 Python 工具箱。其主要功能基于 PyTorch 实现。具体来说，AdverTorch 包含生成对抗扰动和防御对抗样本的模块，以及用于对抗训练的脚本。

最新版本 (v0.2)

安装

安装 AdverTorch 本身

我们是在 Python 3.6 和 PyTorch 1.0.0 及 0.4.1 的环境下开发 AdverTorch 的。要安装 AdverTorch，只需运行：

pip install advertorch

或者克隆仓库并运行：

python setup.py install

若希望以“可编辑”模式安装该包：

pip install -e .

搭建测试环境

部分攻击会与 Foolbox 或 CleverHans 中的实现进行对比测试，以确保正确性。目前，这些测试是在以下相关库的版本下进行的：

conda install -c anaconda tensorflow-gpu==1.11.0
pip install git+https://github.com/tensorflow/cleverhans.git@336b9f4ed95dccc7f0d12d338c2038c53786ab70
pip install Keras==2.2.2
pip install foolbox==1.3.2

示例

# 准备好你的 PyTorch 模型，命名为 "model"
# 准备一批数据和标签，分别命名为 "cln_data" 和 "true_label"
# ...

from advertorch.attacks import LinfPGDAttack

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

adv_untargeted = adversary.perturb(cln_data, true_label)

target = torch.ones_like(true_label) * 3
adversary.targeted = True
adv_targeted = adversary.perturb(cln_data, target)

更多可运行的示例，请参阅 advertorch_examples/tutorial_attack_defense_bpda_mnist.ipynb，了解如何进行攻击与防御；另请参阅 advertorch_examples/tutorial_train_mnist.py，学习如何在 MNIST 数据集上进行对抗训练以构建鲁棒模型。

文档

文档网页位于 readthedocs：https://advertorch.readthedocs.io。

即将推出的功能

AdverTorch 仍在积极开发中。未来我们将添加以下功能或内容：

• 更多示例
• 对其他机器学习框架的支持，例如 TensorFlow
• 更多攻击、防御及其他相关功能
• 对其他 Python 版本和未来 PyTorch 版本的支持
• 贡献指南
• ……

已知问题

FastFeatureAttack 和 JacobianSaliencyMapAttack 在当前使用的 CleverHans 版本下无法通过测试。（它们曾在旧版本的 CleverHans 中通过测试。）此问题正在调查中。在 test_attacks_on_cleverhans.py 文件中，这两个攻击已被标记为在 pytest 测试中“跳过”。

许可证

本项目采用 LGPL 许可证。详细条款可在 LICENSE 和 LICENSE.GPL 文件中找到。

引用

如果您在研究中使用了 AdverTorch，我们诚挚地请求您引用以下技术报告：

@article{ding2019advertorch,
  title={{AdverTorch} v0.1: An Adversarial Robustness Toolbox based on PyTorch},
  author={Ding, Gavin Weiguang and Wang, Luyu and Jin, Xiaomeng},
  journal={arXiv preprint arXiv:1902.07623},
  year={2019}
}

贡献者

• Gavin Weiguang Ding
• 王璐宇
• 金晓萌
• 洛朗·梅尼耶
• 亚历山大·阿拉乌若
• 杰罗姆·罗尼
• 本·费因斯坦
• 弗朗切斯科·克罗切
• 桃太郎·桐谷

AdverTorch 快速上手指南

AdverTorch 是一个基于 PyTorch 的 Python 工具箱，专为对抗鲁棒性研究设计。它提供了生成对抗扰动、防御对抗样本以及进行对抗训练的核心模块。

环境准备

• 操作系统：Linux / macOS / Windows
• Python 版本：推荐 Python 3.6+
• 核心依赖：PyTorch 1.0.0 或 0.4.1+
• 可选依赖（用于测试验证）： 若需与 Foolbox 或 CleverHans 的实现进行对比测试，需安装以下特定版本：

  conda install -c anaconda tensorflow-gpu==1.11.0
  pip install git+https://github.com/tensorflow/cleverhans.git@336b9f4ed95dccc7f0d12d338c2038c53786ab70
  pip install Keras==2.2.2
  pip install foolbox==1.3.2
  

  提示：国内用户可使用清华或阿里镜像源加速 pip 和 conda 安装（例如在 pip 命令后添加 -i https://pypi.tuna.tsinghua.edu.cn/simple）。

安装步骤

你可以通过 PyPI 直接安装，或从源码安装。

方式一：使用 pip 安装（推荐）

pip install advertorch

(国内加速)

pip install advertorch -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装

git clone https://github.com/borealisai/advertorch.git
cd advertorch
python setup.py install

方式三：开发者模式安装

如果你需要修改源码，建议使用可编辑模式安装：

pip install -e .

基本使用

以下示例展示了如何使用 LinfPGDAttack 对 PyTorch 模型生成非定向和定向的对抗样本。

假设你已经准备好了模型 (model)、输入数据 (cln_data) 和真实标签 (true_label)。

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

# 初始化攻击器
adversary = LinfPGDAttack(
    model, 
    loss_fn=nn.CrossEntropyLoss(reduction="sum"), 
    eps=0.3,
    nb_iter=40, 
    eps_iter=0.01, 
    rand_init=True, 
    clip_min=0.0, 
    clip_max=1.0,
    targeted=False
)

# 1. 生成非定向对抗样本 (Untargeted Attack)
adv_untargeted = adversary.perturb(cln_data, true_label)

# 2. 生成定向对抗样本 (Targeted Attack)
# 设定目标类别为 3
target = torch.ones_like(true_label) * 3
adversary.targeted = True
adv_targeted = adversary.perturb(cln_data, target)

更多完整可运行的示例（如 MNIST 上的攻防演练和对抗训练），请参考官方仓库中的 advertorch_examples 目录。