---

文档 | 论文 | 示例

[AAAI 2021] DeepRobust 是一个基于 PyTorch 的对抗库，用于图像和图上的攻击与防御方法。

• 如果您是 DeepRobust 的新手，我们强烈建议您阅读 文档页面 或本 README 中的以下内容，以了解如何使用它。
• 如果您对该库有任何疑问或建议，请随时在此处创建问题 这里。我们会尽快回复 :)

包含的算法列表可在 [图像包] 和 [图包] 中找到。

环境与安装

使用方法

• 图像攻击与防御

• 图攻击与防御

致谢

有关攻击和防御的更多详细信息，您可以阅读以下论文。

• 图上的对抗攻击与防御：综述、工具及实证研究
• 图像、图和文本中的对抗攻击与防御：综述

如果我们的工作对您的研究有所帮助，请引用： DeepRobust：用于对抗攻击与防御的 PyTorch 库

@article{li2020deeprobust,
  title={Deeprobust: A pytorch library for adversarial attacks and defenses},
  author={Li, Yaxin and Jin, Wei and Xu, Han and Tang, Jiliang},
  journal={arXiv preprint arXiv:2005.06149},
  year={2020}
}

更改记录

• [11/2023] 尝试 git clone https://github.com/DSE-MSU/DeepRobust.git; cd DeepRobust; python setup_empty.py install 直接安装 DeepRobust，无需先安装依赖包。
• [11/2023] DeepRobust 0.2.9 发布。请尝试 pip install deeprobust==0.2.9。我们已修复了在新版本 PyTorch 上 metattack 的 OOM 问题。
• [06/2023] 我们在图模型包中新增了一种后门攻击方法 UGBA, WWW'23。现在可以使用 UGBA 对大规模图数据集（如 ogb-arxiv）进行隐蔽的后门攻击（详见 test_ugba.py）！
• [02/2023] DeepRobust 0.2.8 发布。请尝试 pip install deeprobust==0.2.8！我们在图模型包中新增了一种可扩展攻击方法 PRBCD, NeurIPS'21。现在可以使用 PRBCD 攻击大规模图数据集，例如 ogb-arxiv（详见 test_prbcd.py）！
• [02/2023] 在图模型包中添加了一种鲁棒模型 AirGNN, NeurIPS'21。请尝试 python examples/graph/test_airgnn.py！详细信息请参见 test_airgnn.py。
• [11/2022] DeepRobust 0.2.6 发布。请尝试 pip install deeprobust==0.2.6！后续还将有更多更新，敬请关注！
• [11/2021] 发布了一个包含图像领域流行黑盒攻击方法的子包。可在以下链接找到：链接。
• [11/2021] DeepRobust 0.2.4 发布。请尝试 pip install deeprobust==0.2.4！
• [10/2021] 添加了可扩展攻击方法和 MedianGCN。感谢 Jintang 的贡献！
• [06/2021] [图像包] 新增预处理方法：APE-GAN。
• [05/2021] DeepRobust 在 AAAI 2021 上发表。详情请见 这里！
• [05/2021] DeepRobust 0.2.2 发布。请尝试 pip install deeprobust==0.2.2！
• [04/2021] [图像包] 增加对 ImageNet 数据集的支持。详细信息请参见 test_ImageNet.py。
• [04/2021] [图模型包] 增加对 OGB 数据集的支持。更多细节请参见 教程页面。
• [03/2021] [图模型包] 新增节点嵌入攻击和受害者模型！详情请参见 教程页面。
• [02/2021] [图模型包] DeepRobust 现在提供工具，可以在 Pytorch Geometric 和 DeepRobust 之间转换数据集格式。更多细节请参见 教程页面！ 同时，DeepRobust 现在也支持基于 PyG 的 GAT、Chebnet 和 SGC；详情请参见 test_gat.py、test_chebnet.py 和 test_sgc.py。
• [12/2020] DeepRobust 现在可以通过 pip 安装！请尝试 pip install deeprobust！
• [12/2020] [图模型包] 新增四个 数据集 和一种防御算法。更多详情请参见 这里。后续还将继续增加数据集和算法，敬请期待 :)
• [07/2020] 新增 文档 页面！
• [06/2020] 为图像和图模型包都添加了 docstring。

基本环境

• python >= 3.6（python 3.5 也应该可以）
• pytorch >= 1.2.0

更多信息请参阅 setup.py 或 requirements.txt。

安装

通过 pip 安装

pip install deeprobust 

从源码安装

git clone https://github.com/DSE-MSU/DeepRobust.git
cd DeepRobust
python setup.py install

如果发现依赖项难以安装，请尝试以下命令： python setup_empty.py install（仅安装 DeepRobust，不安装其他包）

测试示例

python examples/image/test_PGD.py
python examples/image/test_pgdtraining.py
python examples/graph/test_gcn_jaccard.py --dataset cora
python examples/graph/test_mettack.py --dataset cora --ptb_rate 0.05

使用

图像攻击与防御

1. 训练模型

   示例：在 GPU 上对 MNIST 数据集上的简单 CNN 模型进行 20 个 epoch 的训练。

   import deeprobust.image.netmodels.train_model as trainmodel
   trainmodel.train('CNN', 'MNIST', 'cuda', 20)
   

   训练好的模型将保存在 deeprobust/trained_models/ 目录下。

2. 实例化攻击方法和防御方法。

   示例：使用 PGD 攻击生成对抗样本。

   from deeprobust.image.attack.pgd import PGD
   from deeprobust.image.config import attack_params
   from deeprobust.image.utils import download_model
   import torch
   import deeprobust.image.netmodels.resnet as resnet
   from torchvision import transforms,datasets
   
   URL = "https://github.com/I-am-Bot/deeprobust_model/raw/master/CIFAR10_ResNet18_epoch_20.pt"
   download_model(URL, "$MODEL_PATH$")
   
   model = resnet.ResNet18().to('cuda')
   model.load_state_dict(torch.load("$MODEL_PATH$"))
   model.eval()
   
   transform_val = transforms.Compose([transforms.ToTensor()])
   test_loader  = torch.utils.data.DataLoader(
                   datasets.CIFAR10('deeprobust/image/data', train = False, download=True,
                   transform = transform_val),
                   batch_size = 10, shuffle=True)
   
   x, y = next(iter(test_loader))
   x = x.to('cuda').float()
   
   adversary = PGD(model, 'cuda')
   Adv_img = adversary.generate(x, y, **attack_params['PGD_CIFAR10'])
   

   示例：训练防御模型。

   from deeprobust.image.defense.pgdtraining import PGDtraining
   from deeprobust.image.config import defense_params
   from deeprobust.image.netmodels.CNN import Net
   import torch
   from torchvision import datasets, transforms 
   
   model = Net()
   train_loader = torch.utils.data.DataLoader(
                   datasets.MNIST('deeprobust/image/defense/data', train=True, download=True,
                                   transform=transforms.Compose([transforms.ToTensor()])),
                                   batch_size=100,shuffle=True)
   
   test_loader = torch.utils.data.DataLoader(
                 datasets.MNIST('deeprobust/image/defense/data', train=False,
                               transform=transforms.Compose([transforms.ToTensor()])),
                               batch_size=1000,shuffle=True)
   
   defense = PGDtraining(model, 'cuda')
   defense.generate(train_loader, test_loader, **defense_params["PGDtraining_MNIST"])
   

   更多示例代码可在 deeprobust/examples 中找到。

3. 使用我们的评估程序测试攻击算法对防御的效果。

   示例：

   cd DeepRobust
   python examples/image/test_train.py
   python deeprobust/image/evaluation_attack.py
   

图神经网络攻击与防御

对图神经网络的攻击

1. 加载数据集

   import torch
   import numpy as np
   from deeprobust.graph.data import Dataset
   from deeprobust.graph.defense import GCN
   from deeprobust.graph.global_attack import Metattack
   
   data = Dataset(root='/tmp/', name='cora', setting='nettack')
   adj, features, labels = data.adj, data.features, data.labels
   idx_train, idx_val, idx_test = data.idx_train, data.idx_val, data.idx_test
   idx_unlabeled = np.union1d(idx_val, idx_test)
   

2. 设置代理模型

   device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
   surrogate = GCN(nfeat=features.shape[1], nclass=labels.max().item()+1, nhid=16,
                   with_relu=False, device=device)
   surrogate = surrogate.to(device)
   surrogate.fit(features, adj, labels, idx_train)
   

3. 设置攻击模型并生成扰动

   model = Metattack(model=surrogate, nnodes=adj.shape[0], feature_shape=features.shape, device=device)
   model = model.to(device)
   perturbations = int(0.05 * (adj.sum() // 2))
   model.attack(features, adj, labels, idx_train, idx_unlabeled, perturbations, ll_constraint=False)
   modified_adj = model.modified_adj
   

有关更多详细信息，请参阅 mettack.py 或运行 python examples/graph/test_mettack.py --dataset cora --ptb_rate 0.05

防御图攻击

1. 加载数据集

   import torch
   from deeprobust.graph.data import Dataset, PtbDataset
   from deeprobust.graph.defense import GCN, GCNJaccard
   import numpy as np
   np.random.seed(15)
   
   # 加载干净图
   data = Dataset(root='/tmp/', name='cora', setting='nettack')
   adj, features, labels = data.adj, data.features, data.labels
   idx_train, idx_val, idx_test = data.idx_train, data.idx_val, data.idx_test
   
   # 加载被 mettack 攻击过的图
   perturbed_data = PtbDataset(root='/tmp/', name='cora')
   perturbed_adj = perturbed_data.adj
   

2. 测试

   # 设置防御模型并测试性能
   device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
   model = GCNJaccard(nfeat=features.shape[1], nclass=labels.max()+1, nhid=16, device=device)
   model = model.to(device)
   model.fit(features, perturbed_adj, labels, idx_train)
   model.eval()
   output = model.test(idx_test)
   
   # 在 GCN 上进行测试
   model = GCN(nfeat=features.shape[1], nclass=labels.max()+1, nhid=16, device=device)
   model = model.to(device)
   model.fit(features, perturbed_adj, labels, idx_train)
   model.eval()
   output = model.test(idx_test)
   

有关更多详细信息，请参阅 test_gcn_jaccard.py 或运行 python examples/graph/test_gcn_jaccard.py --dataset cora

样本结果

由 FGSM 生成的对抗样本：

左：原始图像，分类为 6；右：对抗样本，分类为 4。

一些训练好的模型可以在这里找到：https://drive.google.com/open?id=1uGLiuCyd8zCAQ8tPz9DDUQH6zm-C4tEL

致谢

部分算法参考了论文作者的实现。相关引用可在每个文件的顶部找到。

网络结构的实现参考了 weiaicunzai 的 GitHub 仓库。原始代码请见： pytorch-cifar100

感谢他们的杰出工作！

DeepRobust 快速上手指南

DeepRobust 是一个基于 PyTorch 的对抗样本库，专注于图像和图数据（Graph）领域的攻击与防御算法。本指南将帮助你快速配置环境并运行基础示例。

1. 环境准备

在开始之前，请确保你的系统满足以下基本要求：

• 操作系统: Linux, macOS 或 Windows
• Python: >= 3.6 (推荐 3.8+)
• PyTorch: >= 1.2.0
• GPU: 可选（推荐用于加速训练和攻击生成）

前置依赖安装建议： 建议先安装 PyTorch。国内用户可使用清华源加速安装：

pip install torch torchvision torchaudio --index-url https://pypi.tuna.tsinghua.edu.cn/simple

其他依赖库（如 numpy, scipy, networkx 等）将在安装 DeepRobust 时自动处理，或参考项目根目录下的 requirements.txt。

2. 安装步骤

你可以选择通过 pip 直接安装，或从源码安装。

方式一：通过 pip 安装（推荐）

这是最快捷的方式，适合大多数用户。国内用户建议指定清华源。

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

注：最新稳定版为 0.2.9，如需指定版本可添加 ==0.2.9。

方式二：从源码安装

如果你需要最新的功能或修改源码，请使用此方式。

git clone https://github.com/DSE-MSU/DeepRobust.git
cd DeepRobust

# 标准安装（会自动安装依赖）
python setup.py install

# 如果依赖安装困难，可选择仅安装 deeprobust 核心包
# python setup_empty.py install

3. 基本使用

DeepRobust 主要分为 图像 (Image) 和 图数据 (Graph) 两大模块。以下是两个最简化的使用示例。

场景一：图像对抗攻击 (PGD Attack)

以下示例演示如何加载预训练模型，并使用 PGD 算法生成对抗样本。

from deeprobust.image.attack.pgd import PGD
from deeprobust.image.config import attack_params
import torch
import deeprobust.image.netmodels.resnet as resnet
from torchvision import transforms, datasets

# 1. 加载模型 (此处以 CIFAR10 ResNet18 为例)
# 假设已下载模型权重到本地 "$MODEL_PATH$"
model = resnet.ResNet18().to('cuda')
model.load_state_dict(torch.load("$MODEL_PATH$"))
model.eval()

# 2. 准备数据
transform_val = transforms.Compose([transforms.ToTensor()])
test_loader = torch.utils.data.DataLoader(
    datasets.CIFAR10('deeprobust/image/data', train=False, download=True, transform=transform_val),
    batch_size=10, shuffle=True
)

x, y = next(iter(test_loader))
x = x.to('cuda').float()

# 3. 初始化攻击器并生成对抗样本
adversary = PGD(model, 'cuda')
# 使用预设的 CIFAR10 攻击参数
Adv_img = adversary.generate(x, y, **attack_params['PGD_CIFAR10'])

print("对抗样本生成完成，形状:", Adv_img.shape)

场景二：图神经网络攻击 (Metattack)

以下示例演示如何在 Cora 数据集上对 GCN 模型进行元攻击（Meta Attack）。

import torch
import numpy as np
from deeprobust.graph.data import Dataset
from deeprobust.graph.defense import GCN
from deeprobust.graph.global_attack import Metattack

# 1. 加载数据集
data = Dataset(root='/tmp/', name='cora', setting='nettack')
adj, features, labels = data.adj, data.features, data.labels
idx_train, idx_val, idx_test = data.idx_train, data.idx_val, data.idx_test
idx_unlabeled = np.union1d(idx_val, idx_test)

# 2. 设置代理模型 (Surrogate Model)
device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
surrogate = GCN(nfeat=features.shape[1], nclass=labels.max().item()+1, nhid=16, dropout=0.5, device=device).to(device)

# 3. 初始化攻击器
attacker = Metattack(model=surrogate, nnodes=adj.shape[0], nfeats=features.shape[1], 
                     device=device, lambda_=0.01, nclass=labels.max().item()+1)

# 4. 执行攻击
# 注意：实际使用时需先训练 surrogate 模型，此处仅为流程展示
# attacker.attack(features, adj, labels, idx_train, idx_unlabeled, perturbations=20)
print("图攻击模块初始化完成，可调用 attack 方法执行攻击。")

运行官方测试示例

安装完成后，你可以直接运行仓库自带的测试脚本来验证环境是否正常：

# 测试图像 PGD 攻击
python examples/image/test_PGD.py

# 测试图数据 Metattack (需指定数据集)
python examples/graph/test_mettack.py --dataset cora --ptb_rate 0.05

更多详细用法、参数配置及新算法（如 UGBA, PRBCD 等）请参考官方 文档 或 examples 目录下的代码。