ObliviousAI/dp-recorder

# dp-recorder **dp-recorder** 是一个用于对差分隐私（DP）库进行**灰盒审计**的 Python 库。它实现了 **Re:cord-play** 框架，旨在检测 DP 算法中的实现错误、敏感度计算错误以及依赖于数据的控制流泄漏。 与传统的黑盒审计不同，`dp-recorder` 会检查算法的内部状态。它可以在单次执行对中确定性地标记隐私违规，或者对特定组件执行有针对性的统计审计。 ## 🚀 主要功能 * **灰盒检查**：对代码进行插桩，以检查隐私机制（例如 Laplace、Gaussian）的内部输入，而不仅仅是最终输出。 * **Re:cord-play（确定性测试）**：捕获数据集 $D$ 上的执行轨迹，并在邻居数据集 $D'$ 上重放它们。它“冻结”机制输出，以验证所有周围的控制流保持**不变**（与数据无关）。 * **敏感度验证**：自动验证隐私原语输入之间的距离不超过声明的敏感度（$\Delta_{actual} \leq \Delta_{declared}$）。 * **Re:cord-play-sample（统计审计）**：对于不受信任或自定义的原语，该工具隔离组件并运行有针对性的分布审计（估计 PLD），而无需重新运行繁重的预处理逻辑。 * **混合组合**：无缝混合受信任的原语（分析 PLD）和不受信任的组件（经验 PLD），以获得端到端的隐私保证。 * **CI/CD 就绪**：设计为在标准开发流程中作为快速单元测试运行。 ## 📦 安装 此项目使用 [Poetry](https://python-poetry.org/) 进行管理。 ``` git clone https://github.com/oblivious-repos/dp-recorder.git cd dp-recorder poetry install ``` ### 🧠 工作原理 该框架基于这样一个见解：DP 算法将**依赖于数据**的调用（隐私机制）与**独立于数据**的逻辑（预处理、控制流）交织在一起。 1. **阶段 1 (Record/记录)**：在数据集 $D$ 上运行算法。记录 DP 原语的所有输入/输出，并记录 PRNG 状态。 2. **阶段 2 (Replay/重放)**：在邻居数据集 $D'$ 上运行算法。 * **冻结输出**：强制 DP 原语返回与阶段 1 *完全相同的输出*。 * **检查不变性**：由于机制输出是相同的，程序状态不应出现分歧。如果出现分歧，说明**私有数据已泄漏**到控制流中。 * **检查敏感度**：测量输入 $q(D)$ 和 $q(D')$ 之间的经验距离。如果它超过了开发者声明的敏感度，则标记为错误。 ### 🛠 用法 **1. 插桩你的原语** 使用 `@audit_spec` 标记添加噪声的函数。如果你想验证特定变量（如超参数或数据形状）不依赖于私有数据，请使用 `ensure_equality`。 ``` from dp_recorder.auditing.audit_primitives import audit_spec, ensure_equality from dp_recorder.auditing.metrics import l1_distance # 一个可信原语（我们验证输入，但信任噪声生成） @audit_spec( kind="laplace_mechanism", input_arg="data", sensitivity_arg="sensitivity", metric_fn=l1_distance ) def laplace_mechanism(data, sensitivity, epsilon): # Standard implementation... return data + np.random.laplace(0, sensitivity / epsilon, size=data.shape) # 您的复杂 DP 算法 def dp_algorithm(private_data, epsilon): # 1. Pre-processing # We must ensure params derived here don't leak privacy clipping_bound = 10.0 # 2. Invariance Check # Explicitly assert that this variable must be identical across neighbors ensure_equality(clipping_bound, name="clipping_bound") # 3. Mechanism Call clipped_data = np.clip(private_data, 0, clipping_bound) return laplace_mechanism(data=clipped_data, sensitivity=clipping_bound, epsilon=epsilon) ``` ### 2. 运行审计器 `Auditor` 管理“Record”和“Replay”阶段。 ``` from dp_recorder.auditing.audit_primitives import Auditor from dp_recorder.auditing.dataset_util import generate_neighbors import numpy as np # 1. 设置数据 data = np.array([1.0, 2.0, 3.0, 100.0]) # Contains an outlier neighbor_data = generate_neighbors(data, strategy="replace_one", rng=42) auditor = Auditor() # 2. 阶段 1：记录（原始数据） auditor.set_record() with auditor: # Run the algo. Traces are saved internally. result_d = dp_algorithm(data, epsilon=1.0) # 3. 阶段 2：重放（邻近数据） auditor.set_replay() with auditor: # Outputs of mechanisms are frozen to match Phase 1. # If control flow diverges here, Auditor raises an InvarianceError. result_dp = dp_algorithm(neighbor_data, epsilon=1.0) # 4. 确定性验证 # 检查经验输入敏感度 <= 声明的敏感度。 # 这可以捕获诸如“忘记裁剪”或“敏感度公式错误”等错误。 try: auditor.validate_records() print("✅ Deterministic checks passed.") except Exception as e: print(f"❌ Privacy Violation Detected: {e}") # 5. （可选）分布审计 # 如果您有未知 accounting 的自定义原语， # 请对这些特定组件运行统计测试。 auditor.run_distributional_audit(n_samples=10000) auditor.compute_overall_pld() ``` ### 项目结构 * `src/dp_recorder/` * `auditing/audit_primitives.py`：核心 `Auditor` 类和插桩钩子。 * `auditing/metrics.py`：用于敏感度检查的距离度量（$L_1, L_2, L_\infty$）。 * `auditing/dataset_util.py`：生成邻居数据集的策略（Add/Remove、Replace-one）。 * `auditing/pld_*`：与 `dp-accounting` 集成以实现混合组合。 * `tests/`：集成测试，复现了在 Opacus、SmartNoise 和 Diffprivlib 等库中发现的真实错误。 ### 开发 要运行快速、确定性的测试套件： ``` poetry run pytest ``` 要运行较慢的统计测试套件： ``` RUN_DISTRIBUTIONAL_AUDIT=true poetry run pytest ``` ### 引用 如果您在研究或工作流程中使用 dp-recorder (Re:cord-play)，请引用以下论文： ``` @inproceedings{recordplay2025, title={Privacy in Theory, Bugs in Practice: A Grey-Box Auditing Framework of Differential Privacy Libraries}, author={Tudor Cebere, David Erb, Damien Desfontaines, Aurélien Bellet and Jack Fitzimons}, booktitle={TODO}, year={2025}, } ```

标签：Atomic Red Team, Poetry, 单元测试, 差分隐私, 拉普拉斯机制, 敏感性分析, 数据泄露检测, 数据独立性, 灰盒测试, 算法审计, 统计审计, 网络安全, 逆向工具, 隐私保护, 隐私保证, 隐私审计, 隐私机制, 隐私预算, 高斯机制