Lynx-Jin/DFLLib

# 🛡️ DFLLib：面向检测的联邦学习库 DFLLib 是一个基于 PyTorch 的研究框架，专注于联邦学习中的**拜占庭模型中毒攻击、鲁棒聚合以及可审计的更新级检测**。它在 [PFLlib](https://github.com/TsingZ0/PFLlib) 的训练基础设施基础上进行了扩展，提供了一个专为可复现安全实验设计的攻击-防御 pipeline。 ## ✨ DFLLib 扩展功能 - 🧪 **感知威胁模型的攻击：** 与 AGR 无关的 Min-Max 和 Min-Sum；基于 oracle 的、针对 Krum 的 Fang 攻击；标签翻转攻击；以及高斯搭便车基线。 - 🧱 **鲁棒聚合与检测：** Krum、Multi-Krum、Bulyan、逐坐标的截断均值/中位数、DnC 随机子空间 SVD 过滤，以及 AFA 风格的余弦评分聚类。 - 🔎 **逐轮可审计性：** 记录计划、上传、接受和阻止的客户端；防御前的 L0/L2/L∞ 和余弦统计；防御评分；OA、SA、ASR 以及仪表盘图表。 - ⚙️ **实验控制：** 独立的攻击和防御预算、固定的恶意客户端采样、防御预热，以及重复的 DnC 随机子空间过滤。 - 🧠 **训练/模型支持：** FedAvg 和单 minibatch 的 FedSGD（配合服务端 SGD/Adam）；支持 FedAvgMLP、CNN、VGG11、AlexNet 以及适用于小图像的 ResNet18。 ## 🗂️ 目录结构 | 路径 | 用途 | |---|---| | `system/main.py` | 实验入口点和 CLI 参数。 | | `system/flcore/security/attack/` | 中毒攻击。 | | `system/flcore/security/defense/` | 鲁棒聚合与过滤。 | | `system/flcore/security/monitor/` | CSV 审计记录和监控仪表盘。 | | `system/flcore/security/README.md` | 安全模块实现笔记和详细用法。 | ## 🧪 攻击 通用参数：`-atk`（默认为 `none`），`-amr` 恶意客户端比例（默认为 `0.0`），以及 `-aseed` 恶意 ID 种子（默认为 `0`）。使用 `-amon` 开启审计；并使用 `-amondir attack_monitor`、`-amonplot 10` 和 `-amoneps 0.0` 进行配置。 | `-atk` | 方法 | 实现 | 方法特定参数 | |---|---|---|---| | `none` | 干净基线 | 保持上传内容不变。 | 无；使用 `-atk none -amr 0`。 | | `label_flip` | MNIST 标签翻转攻击 | 对于名称以 `MNIST` 开头的数据集上的恶意客户端，将训练标签 `7 → 1` 进行更改；测试标签保持干净。 | 无源/目标 CLI 映射。 | | `free_rider` | 高斯上传基线 | 用独立的高斯噪声替换完整的恶意上传。 | 噪声标准差目前固定为 `0.5`。 | | `minmax` | 与 AGR 无关的 Min-Max | 仅使用活跃恶意客户端的干净本地更新作为代理；搜索受限于最大平方 L2 距离的共享更新。每个活跃的恶意客户端提交相同的更新。 | `-adev {unit_vec,sign,std}`（默认为 `std`），`-alinit 10.0`，`-atol 1e-5`，`-amaxsteps 80`。 | | `minsum` | 与 AGR 无关的 Min-Sum | 与 Min-Max 具有相同的信息模型和共谋更新；受限于到恶意代理的平方 L2 距离之和。 | `-adev {unit_vec,sign,std}`（默认为 `std`），`-alinit 10.0`，`-atol 1e-5`，`-amaxsteps 80`。 | | `fang` | Oracle Fang–Krum | 观察当前的良性上传，并搜索被 Krum 选中的符号反转的恶意更新。这是一种已知 AGR 和已知良性更新的攻击。 | `-fmar 0.20`，`-alinit 10.0`，`-atol 1e-5`，`-amaxsteps 80`；结合 `-def krum` 进行解读。 | `-adev`：`unit_vec` 使用单位代理均值方向；`sign` 使用逐坐标的代理均值符号；`std` 使用逐坐标的代理更新标准差。 ## 🧱 防御 所有防御均使用 `-def`（默认为 `none`）和 `-defstart`（默认为 `0`）。仅当 `round >= defstart` 时才会应用防御。`-rmar 0.20` 是 Krum、Multi-Krum、Bulyan、截断均值和中位数所采用的拜占庭比例假设；它与真实的攻击参数 `-amr` 不同。 | `-def` | 方法 | 实现 | 参数与约束条件 | |---|---|---|---| | `none` | 标准聚合 | 基于样本权重的 FedAvg；FedSGD 将服务端优化器应用于平均梯度。 | 无。 | | `krum` | Krum | 选择到其 `n-f-2` 个最近邻居的距离平方和最小的更新。 | `-rmar 0.20`；要求 `n ≥ 2f+3`。 | | `multikrum` | Multi-Krum | 选择若干个 Krum 获胜者并求平均值。 | `-rmar 0.20`；`-mks 0` 选择最大合法数量 `n-2f-3`，或提供一个正整数；要求 `n ≥ 2f+3`。 | | `bulyan` | Bulyan | 先进行 Multi-Krum 候选选择，随后进行以中位数为中心的逐坐标平均。 | `-rmar 0.20`；要求 `n ≥ 4f+3`。 | | `trimmedmean` | 截断均值 | 去除每个坐标上最大和最小的 `f` 个值，然后求平均。 | `-rmar 0.20`；要求 `n > 2f`；坐标级聚合。 | | `median` | 坐标中位数 | 取每个坐标的中位数。 | `-rmar 0.20`；坐标级聚合。 | | `cosine_cluster` | AFA 风格的余弦聚类 | 使用确定性的 1-D 双均值对 `cos(u_i, Σ_j w_j u_j)` 进行聚类，然后保留其中一个集群。这是一个基线方法，并非完全准确的 AFA 实现。 | `-ccselect {high_mean,largest_cluster}`（默认为 `high_mean`）；`high_mean` 保留平均余弦值较高的集群，`largest_cluster` 保留较大的客户端集群，并在平局时使用平均余弦值进行选择；`-cciter 50`；`-cctol 1e-6`。 | | `dnc` | DnC 谱过滤 | 对参数坐标进行采样，对更新进行中心化处理，执行 SVD，并过滤在第一个右奇异向量上具有高平方投影的更新。重复运行会对存活集取交集。 | `-dmar 0.20`，`-df 1.0`，`-di 1`，`-db 10000`，`-dseed 0`。 | ## 🚀 示例 在 `system/` 目录下运行。 ``` # Clean FedSGD 基线 python main.py -algo FedSGD -fopt adam -flr 0.001 -data MNIST_100 -m FedAvgMLP \ -nc 100 -jr 1 -gr 500 -lbs 100 -atk none -amr 0 -amon # AGR-agnostic Min-Max 与 cosine clustering python main.py -algo FedSGD -fopt adam -flr 0.001 -data MNIST_100 -m FedAvgMLP \ -nc 100 -jr 1 -gr 500 -lbs 100 -atk minmax -amr 0.20 -adev sign \ -def cosine_cluster -ccselect high_mean -cciter 50 -cctol 1e-6 -amon # Min-Sum 与 majority-cluster 选择及 defense warm-up python main.py -algo FedSGD -fopt adam -flr 0.001 -data MNIST_100 -m FedAvgMLP \ -nc 100 -jr 1 -gr 500 -lbs 100 -atk minsum -amr 0.20 -adev sign \ -def cosine_cluster -ccselect largest_cluster -defstart 50 -amon # DnC oracle-budget 消融 (dmar = amr) python main.py -algo FedSGD -fopt adam -flr 0.001 -data MNIST_100 -m FedAvgMLP \ -nc 100 -jr 1 -gr 500 -lbs 100 -atk minmax -amr 0.20 -adev sign \ -def dnc -dmar 0.20 -df 1.0 -di 1 -db 10000 -dseed 0 -amon ``` ## 📊 审计输出 | 文件 | 内容 | |---|---| | `round_audit.csv` | 计划/上传/接受/阻止的 ID，良性/恶意计数，防御评分，聚合模式以及余弦聚类选择规则。 | | `client_metrics.csv` | 防御前的 L0/L2/L∞，与加权平均更新的余弦值，防御评分以及每次上传的决定。 | | `group_summary.csv` | 离线的良性/恶意组统计数据。 | | `global_metrics.csv` | 测试准确率/AUC/损失，OA，SA，ASR 以及 ASR 可用性。 | | `monitor_dashboard.png` | 逐轮的检测和任务指标图表。 | 对于诸如 Min-Max 和 Min-Sum 等无目标更新攻击，ASR 并不是一个有意义的安全指标。请报告干净/受攻击的准确率、恶意接受和阻止率、良性误阻止率以及每轮的实际上传数量。如果 `-amr`、`-rmar` 或 `-dmar` 被刻意设定为匹配值，请将该设置报告为 oracle 预算消融实验。 ## 📚 引用说明 DFLLib 基于 [PFLlib](https://github.com/TsingZ0/PFLlib) 的训练框架和部分基础设施构建。在使用本仓库时，请遵守上游的 Apache-2.0 许可证并进行适当的署名。

标签：PyTorch, 凭据扫描, 密钥泄露防护, 异常检测, 投毒攻击, 机器学习安全, 联邦学习, 逆向工具, 鲁棒聚合