interpretable-dp/riskcal
GitHub: interpretable-dp/riskcal
该库用于测量和校准差分隐私算法的运行时风险，能够将抽象的隐私参数转化为攻击优势等可操作的安全指标。
Stars: 12 | Forks: 1
## riskcal
[](https://pypi.org/project/riskcal/)
[](https://riskcal.readthedocs.io/latest/)
[](https://github.com/bogdan-kulynych/riskcal/actions/workflows/ci.yml)
[](https://arxiv.org/abs/2407.02191)
[](https://arxiv.org/abs/2507.06969)
⚠️ 这是一个研究原型。在生产环境中使用时请避免使用或务必格外小心。
该库提供了用于计算差分隐私算法的 f-DP 权衡曲线，并根据可操作的隐私风险度量（攻击优势，或攻击 TPR 和 FPR）校准其噪声规模的工具。该库能够在保持相同的目标攻击风险水平的同时降低噪声规模。
### 背景
#### 隐私风险与 f-DP
[差分隐私](https://en.wikipedia.org/wiki/Differential_privacy) (DP) 通过添加受控的随机噪声来保护机器学习模型、数据集和统计数据发布免受信息泄露。传统的 DP 使用难以解释的 epsilon-delta 参数。在实践中，我们需要根据具体的攻击风险（成员推断、重新识别和属性重构）来理解隐私。
**f-差分隐私 (f-DP)** 使用以下指标直接量化这些攻击风险：
- **权衡曲线**：针对最坏情况攻击者的假阳性率 (FPR, `alpha`) 与假阴性率 (FNR, `beta`) 之间的关系。注意，真阳性率 (TPR) 为 `1 - beta`。
- **优势**：`TPR - FPR` = `1 - beta - alpha` 的最大值，在最优阈值处实现。该界限也被称为全变差 (TV) 隐私。
f-DP 权衡曲线和优势直接对应于可操作的攻击指标：
| 度量 | 成员推断 | 单独识别 / 重构 / 属性推断 |
|---------|----------------------|-----------------------------------------------------|
| **权衡曲线 (beta/alpha)** | 给定 FPR 下的最小 FNR | 由基线 `alpha` 处的 TPR 限界的最大成功概率 |
| **优势** | 最大 TPR - FPR | 相对于基线的最大概率增量 |
关于成员推断，请参阅 Kulynych & Gomez et al. (2024)[^1]；关于连接重新识别、属性推断和重构的统一框架，请参阅 Kulynych et al. (2025)[^2]。
#### 方法
该库实现了 Kulynych & Gomez et al., 2024[^1] 中描述的方法。
- 基于隐私损失随机变量计算权衡曲线的直接方法在算法 1 中进行了描述。
- f-DP 与可操作隐私风险之间的映射，以及直接针对风险而非针对给定的 校准噪声的思想，在第 2 节和第 3 节中进行了描述。
#### 参考文献
[^1]: [Attack-Aware Noise Calibration for Differential
Privacy](https://arxiv.org/abs/2407.02191). NeurIPS 2024.
[^2]: [Unifying Re-Identification, Attribute Inference, and Data Reconstruction
Risks in Differential Privacy](https://arxiv.org/abs/2507.06969). NeurIPS 2025.
如果您使用了该库或相关方法，请引用：
```
@article{kulynych2024attack,
title={Attack-Aware Noise Calibration for Differential Privacy},
author={Kulynych, Bogdan and Gomez, Juan Felipe and Kaissis, Georgios and du Pin Calmon, Flavio and Troncoso, Carmela},
journal={Advances in Neural Information Processing Systems},
volume={37},
year={2024}
}
@article{kulynych2025unifying,
title={Unifying Re-Identification, Attribute Inference, and Data Reconstruction Risks in Differential Privacy},
author = {Kulynych, Bogdan and Gomez, Juan Felipe and Kaissis, Georgios and Hayes, Jamie and Balle, Borja and du Pin Calmon, Flavio and Raisaro, Jean Louis},
journal={Advances in Neural Information Processing Systems},
volume={38},
year={2025}
}
```
### 安装
使用 pip 安装：
```
pip install riskcal
```
对于本地开发，请克隆仓库并运行：
```
uv sync --dev
```
### 快速开始
#### 分析与转换
该库支持从不同的隐私表示计算隐私风险指标：
| 源隐私概念 | 权衡 (f-DP) | 优势 (TV) | 贝叶斯风险 |
|-----------------------|------------------|----------------|------------|
| **PLD** (Privacy Loss Distribution) | ✓ | ✓ | ✓ |
| **GDP** (Gaussian DP) | ✓ | ✓ | ✓ |
| **ADP** (Approximate DP) | ✓* | ✓* | – |
| **RDP** (Renyi DP) | ✓ | – | – |
| **zCDP** (Zero-Concentrated DP) | ✓ | ✓ | – |
* 从单个 对 ADP 保证的转换对于大多数机制而言是非常有损的[^1]。为了获得有意义的风险界限，请使用其他可用的表示。
_最小示例。_ 这是一个完整的示例，展示了如何评估简单机制的隐私风险：
```
from riskcal import analysis
from dp_accounting.pld.privacy_loss_distribution import from_gaussian_mechanism
# 创建噪声比例为 1.0 的 Gaussian mechanism
pld = from_gaussian_mechanism(1.0)
# 最坏情况下的攻击优势是多少？
advantage = analysis.get_advantage_from_pld(pld)
print(f"Maximum attack advantage: {advantage:.3f}")
# 在 1% FPR 下的最大攻击 TPR 是多少？
beta = analysis.get_beta_from_pld(pld, alpha=0.01)
tpr_bound = 1 - beta
print(f"Max TPR at 1% FPR: {tpr_bound:.3f}")
```
_计算权衡曲线。_ 权衡曲线显示了针对最坏情况攻击者的假阳性率 (FPR, `alpha`) 和假阴性率 (FNR, `beta`) 之间的关系。对于 DP-SGD：
```
from riskcal.analysis import get_beta_from_pld
from dp_accounting.pld import privacy_loss_distribution as pld_module
import numpy as np
# DP-SGD 参数
noise_multiplier = 0.5
sample_rate = 0.002
num_steps = 10000
# 使用组合为 DP-SGD 创建 PLD
pld = pld_module.from_gaussian_mechanism(
standard_deviation=noise_multiplier,
sampling_prob=sample_rate,
use_connect_dots=True,
).self_compose(num_steps)
# 计算不同 FPR (alpha) 值下的 FNR (beta)
alpha = np.array([0.01, 0.05, 0.1])
beta = get_beta_from_pld(pld, alpha=alpha)
print(f"Trade-off curve: {list(zip(alpha, beta))}")
```
您还可以使用与 Opacus 兼容的 accountant，以便更轻松地与 DP-SGD 训练集成：
```
from riskcal.accountants import CTDAccountant
import numpy as np
# 在训练过程中跟踪隐私
acct = CTDAccountant()
noise_multiplier = 0.5
sample_rate = 0.002
num_steps = 100
for _ in range(num_steps):
acct.step(noise_multiplier=noise_multiplier, sample_rate=sample_rate)
# 获取权衡曲线
alpha = np.array([0.01, 0.05, 0.1])
beta = acct.get_beta(alpha=alpha)
# 获取最大优势
advantage = acct.get_advantage()
print(f"Maximum attack advantage: {advantage:.3f}")
```
该库适用于 `dp_accounting` 库[支持](https://github.com/google/differential-privacy/tree/main/python/dp_accounting)的任何 DP 机制，例如（子采样）高斯机制、离散高斯机制、拉普拉斯机制的任意自适应组合：
```
from riskcal.analysis import get_beta_from_pld, get_advantage_from_pld
from dp_accounting.pld.privacy_loss_distribution import from_gaussian_mechanism, from_laplace_mechanism
# 组合多个 mechanism
pld = from_gaussian_mechanism(1.0).compose(from_laplace_mechanism(0.5))
# 分析组合后的 mechanism
advantage = get_advantage_from_pld(pld)
beta = get_beta_from_pld(pld, alpha=0.1)
print(f"Advantage: {advantage:.3f}, Beta at alpha=0.1: {beta:.3f}")
```
_高斯差分隐私 (GDP)。_ 高斯差分隐私紧密地刻画了许多基于高斯机制或其组合的 DP 机制。对于给定的 GDP 参数 `mu`，获取优势和权衡曲线：
```
from riskcal.analysis import get_advantage_from_gdp, get_beta_from_gdp
import numpy as np
mu = 2.0 # GDP parameter
# 直接从 mu 获取优势
advantage = get_advantage_from_gdp(mu)
# 获取权衡曲线
alpha = np.linspace(0, 1, 100)
beta = get_beta_from_gdp(mu, alpha)
```
这比基于 PLD 的计算更快。另请参阅一个专门用于以 GDP 术语对 DP 机制进行隐私计数的库 [`gdpnum`](https://github.com/Felipe-Gomez/gdp-numeric)。
_零集中差分隐私 和 Renyi DP (RDP)。_ 零集中差分隐私 由单个参数 `rho` 表征。Renyi DP 由特定散度 `order` 下的 `epsilon` 值参数化。
从 zCDP 获取权衡曲线：
```
from riskcal.analysis import get_advantage_from_zcdp, get_beta_from_zcdp
import numpy as np
rho = 0.5 # zCDP parameter
# 直接从 rho 获取优势
advantage = get_advantage_from_zcdp(rho)
print(f"Maximum attack advantage: {advantage:.3f}")
# 获取不同 FPR 值的权衡曲线
alpha = np.linspace(0.01, 0.1, 10)
beta = get_beta_from_zcdp(rho, alpha)
print(f"Trade-off curve: {list(zip(alpha, beta))}")
```
从 RDP 获取权衡曲线：
```
from riskcal.analysis import get_beta_from_rdp
import numpy as np
epsilon = 1.0 # Renyi divergence parameter
order = 2.0 # Renyi divergence order (alpha in Renyi DP literature)
# 获取特定 FPR 下的 FNR
beta = get_beta_from_rdp(epsilon=epsilon, alpha=0.1, order=order)
print(f"Beta (FNR) at alpha=0.1: {beta:.3f}")
```
_计算贝叶斯风险。_ 贝叶斯风险衡量二元先验下攻击的最大准确率。这对于属性推断（假设记录具有两个属性之一）或成员推断（具有成员资格的先验概率）很有用：
```
from riskcal.analysis import get_bayes_risk_from_pld
from dp_accounting.pld.privacy_loss_distribution import from_laplace_mechanism
import numpy as np
pld = from_laplace_mechanism(1.0)
# 计算不同先验概率的攻击准确率
prior = np.array([0.5, 0.8, 0.95])
risk = get_bayes_risk_from_pld(pld, prior=prior)
print(f"Bayes risk at priors {prior}: {risk}")
```
#### 校准
您可以直接校准噪声以限制攻击成功率。
_为 DP-SGD 校准噪声。_ 校准至最大攻击优势：
```
from riskcal.calibration.dpsgd import find_noise_multiplier_for_advantage
sample_rate = 0.002
num_steps = 10000
# 找到将优势限制在 10% 的噪声乘数
noise_multiplier = find_noise_multiplier_for_advantage(
advantage=0.1,
sample_rate=sample_rate,
num_steps=num_steps,
)
print(f"Required noise multiplier: {noise_multiplier:.3f}")
```
校准以限制特定 FPR 下的攻击 TPR：
```
from riskcal.calibration.dpsgd import find_noise_multiplier_for_err_rates
# 将攻击限制在 1% FPR 下最大 5% TPR
noise_multiplier = find_noise_multiplier_for_err_rates(
beta=0.95, # FNR = 1 - TPR = 1 - 0.05
alpha=0.01, # FPR
sample_rate=0.002,
num_steps=10000,
grid_step=1e-2, # Lower resolution for the sake of running the example faster.
)
print(f"Required noise multiplier: {noise_multiplier:.3f}")
```
_校准通用机制。* 对于 DP-SGD 之外的定制机制，请使用通用校准框架。您提供一个评估器函数，用于计算给定参数值的隐私指标：
```
from riskcal.calibration.core import (
calibrate_parameter,
PrivacyEvaluator,
PrivacyMetrics,
CalibrationTarget,
CalibrationConfig,
)
from riskcal.analysis import get_advantage_from_pld, get_beta_from_pld
from dp_accounting.pld.privacy_loss_distribution import from_laplace_mechanism
# 定义 Laplace mechanism 的评估器
def evaluate_laplace(scale: float) -> PrivacyMetrics:
"""Compute privacy metrics for Laplace mechanism with given scale."""
pld = from_laplace_mechanism(sensitivity=1.0, parameter=scale)
advantage = get_advantage_from_pld(pld)
beta = get_beta_from_pld(pld, alpha=0.01) # For FPR=1%
return PrivacyMetrics(advantage=advantage, alpha=0.01, beta=beta)
# 校准到优势目标
target = CalibrationTarget(kind="advantage", advantage=0.1)
config = CalibrationConfig(param_min=0.1, param_max=30.0, increasing=False)
result = calibrate_parameter(
evaluator=evaluate_laplace,
target=target,
config=config,
parameter_name="scale"
)
print(f"Required Laplace scale: {result.parameter_value:.3f}")
print(f"Achieved advantage: {result.achieved_advantage:.3f}")
```
此方法适用于任何可以将隐私指标计算为可调参数（噪声规模、采样率等）函数的机制。
标签：f-Differential Privacy, f-DP, 反取证, 噪声校准, 安全评估, 密钥泄露防护, 差分隐私, 成员推断, 攻击优势, 数据隐私, 机器学习安全, 漏报率, 统计隐私, 网络安全, 误报率, 逆向工具, 隐私保护, 隐私审计, 隐私度量, 隐私攻击, 隐私预算, 隐私风险量化