AKIVA-AI/toolkit-policy-test-bench

# Toolkit Policy 测试台 一个用于 LLM 应用的轻量级红队与合规回归测试框架。 它帮助团队持续测试模型/应用输出是否符合以下要求： - **PII 泄露** - 电子邮件/电话/社会安全号码 (SSN)/信用卡 - **密钥泄露** - API 密钥模式、JWT、AWS 密钥等 - **策略约束** - 内容包含/禁用规则、正则表达式规则、最大输出长度 - **JSON 输出结构检查** - 必需键、多余键 - **自定义检测器** - 通过插件注册您自己的 PII/密钥模式 该工具设计为可作为独立实用程序安全地开源。商业/Pro 版本可增加治理、租户感知策略、签名包和审计导出功能。 ## 安装 (开发) ``` pip install -e ".[dev]" pytest -q ``` 如需 Ed25519 签名支持： ``` pip install -e ".[signing]" ``` ## 概念 - **Suite (套件)**: 版本化的测试用例集和检查配置 (`suite.json` + `cases.jsonl`)，可选择打包成 zip。 - **Case (用例)**: `{ "id": "...", "input": ..., "tags": [...] }` (input 通常是聊天消息)。 - **Predictions (预测结果)**: JSONL 格式 `{ "id": "...", "prediction": "..." }`。 - **Report (报告)**: JSON 输出，包含每个用例的发现和汇总指标。 - **Pack (包)**: Suite 的 Zip 归档文件，包含清单 (SHA-256 哈希) 和可选的 Ed25519 签名。 ## 快速开始 创建一个 suite pack zip： ``` toolkit-policy pack create --suite-dir examples/suite --out packs/policy.zip ``` 验证包完整性 (哈希)： ``` toolkit-policy pack verify --suite packs/policy.zip ``` 签署 suite packs (可选)： ``` toolkit-policy keygen --private-key ed25519_priv.pem --public-key ed25519_pub.pem toolkit-policy pack sign --suite packs/policy.zip --private-key ed25519_priv.pem --out packs/policy.sig.json toolkit-policy pack verify-signature --suite packs/policy.zip --signature packs/policy.sig.json --public-key ed25519_pub.pem ``` 运行评估并生成报告： ``` toolkit-policy run --suite packs/policy.zip --predictions examples/preds.jsonl --out report.json ``` 将候选报告与基线报告进行比较 (CI 门禁)： ``` toolkit-policy compare --baseline baseline.json --candidate report.json ``` ## 完整 CLI 参考 ### 全局标志 | Flag | Description | | ---- | ----------- | | `--version` | 打印版本并退出 | | `-v, --verbose` | 启用 DEBUG 级别的日志输出到 stderr | | `--log-format {text,json}` | 日志输出格式 (默认: `text`) | ### `toolkit-policy run` 针对预测结果运行策略套件。 ``` toolkit-policy run --suite --predictions [--out ] [--format {json,table}] ``` | Flag | Required | Description | | ---- | -------- | ----------- | | `--suite` | 是 | Suite 路径 (目录或 `.zip` 包) | | `--predictions` | 是 | 预测结果 JSONL 文件 (`id` + `prediction`) | | `--out` | 否 | 将报告 JSON 写入文件 | | `--format` | 否 | 输出格式: `json` (默认) 或 `table` | ### `toolkit-policy compare` 将候选报告与基线报告进行比较，用于 CI 门禁。 ``` toolkit-policy compare --baseline --candidate [--format {json,table}] [--max-fail-rate-increase-pct N] [--max-pii-hits-increase N] [--max-secret-hits-increase N] ``` | Flag | Required | Description | | ---- | -------- | ----------- | | `--baseline` | 是 | 基线报告 JSON | | `--candidate` | 是 | 候选报告 JSON | | `--format` | 否 | 输出格式: `json` (默认) 或 `table` | | `--max-fail-rate-increase-pct` | 否 | 最大失败率增加百分比 (默认: 0.0) | | `--max-pii-hits-increase` | 否 | 最大 PII 命中增加数 (默认: 0) | | `--max-secret-hits-increase` | 否 | 最大密钥命中增加数 (默认: 0) | ### `toolkit-policy validate-report` 验证策略报告 JSON 是否具有预期的结构。 ``` toolkit-policy validate-report --report ``` ### `toolkit-policy pack create` 从 suite 目录创建一个 suite pack zip。 ``` toolkit-policy pack create --suite-dir --out ``` ### `toolkit-policy pack inspect` 检查 suite (目录或 zip) 并将其元数据打印为 JSON。 ``` toolkit-policy pack inspect --suite ``` ### `toolkit-policy pack verify` 通过检查清单中的 SHA-256 哈希来验证包完整性。 ``` toolkit-policy pack verify --suite ``` ### `toolkit-policy pack sign` 使用 Ed25519 私钥对 pack zip 进行签名 ( detached signature )。 ``` toolkit-policy pack sign --suite --private-key [--out ] ``` ### `toolkit-policy pack verify-signature` 验证 pack 的 detached Ed25519 签名。 ``` toolkit-policy pack verify-signature --suite --signature --public-key ``` ### `toolkit-policy keygen` 生成用于签署 suite packs 的 Ed25519 密钥对。 ``` toolkit-policy keygen --private-key --public-key ``` ## 自定义检测器插件 通过编程方式注册自定义 PII 或密钥检测器： ``` import re from toolkit_policy_test_bench.plugins import registry, DetectorPlugin def detect_mrn(text: str) -> dict[str, int]: return {"medical_record": len(re.findall(r"MRN-\d{8}", text))} registry.register(DetectorPlugin( name="medical_record", kind="pii", detect=detect_mrn, )) ``` 或者从 JSON 文件加载模式： ``` { "detectors": [ {"name": "internal_id", "kind": "pii", "pattern": "INT-\\d{6}"}, {"name": "github_token", "kind": "secret", "pattern": "ghp_[A-Za-z0-9]{36}"} ] } ``` ``` from pathlib import Path from toolkit_policy_test_bench.plugins import registry registry.load_patterns_file(Path("custom_patterns.json")) ``` 当启用 PII 或密钥检测时，自定义检测器会在 `run_suite` 期间自动被调用。 ## CI 退出代码 | Code | Meaning | | ---- | ------- | | `0` | 成功 | | `2` | CLI 错误 (参数错误、文件未找到) | | `3` | 意外错误 | | `4` | 验证失败 (超出比较预算、报告无效) | ## CI 集成示例 ``` - name: Run policy tests run: | toolkit-policy run \ --suite packs/policy.zip \ --predictions preds.jsonl \ --out report.json toolkit-policy compare \ --baseline baseline.json \ --candidate report.json \ --max-fail-rate-increase-pct 0.0 ``` ## 许可证 MIT License - 详见 LICENSE 文件。

标签：API密钥检测, DLL 劫持, Ed25519签名, Homebrew安装, JSON校验, PII检测, Python, 合规性测试, 大语言模型, 安全合规, 安全回归测试, 安全工具包, 安全规则引擎, 密钥泄露, 数据脱敏, 文档结构分析, 无后门, 时序数据库, 策略合规, 网络代理, 网络安全, 输入验证, 输出验证, 逆向工具, 隐私保护