zekangl317-cyber/cps-authz-bench
GitHub: zekangl317-cyber/cps-authz-bench
一套用于信息物理系统授权分析器的确定性基准测试框架，通过种子化图生成、命名变异注入和 oracle 差异比对来评估分析器的正确性。
Stars: 0 | Forks: 0
# cps-authz-bench
[English](README.md) | [简体中文](README.zh-CN.md)
`cps-authz-bench` 是一个确定性的 Python 3.11+ 基准测试和测试工具包，用于信息物理系统授权分析器。它生成带有参考真值的带种子服务/效果图，注入命名的授权缺陷，通过有界 subprocess 适配器运行任意命令行分析器，比较检查结果，存储失败用例，并简化结构化的反例。
其运行时仅使用 Python 标准库。它不需要 GPU、云服务、Docker、WSL、付费 API、硬件目标、网络连接或同级代码库。
## 建模内容
图包含版本化的服务、由服务拥有的物理或逻辑效应、已批准的授权、当前的授权以及请求。当请求的调用者拥有该效应的当前授权、该效应存在、且请求的服务版本与当前服务记录匹配时，该请求即被授权。参考 oracle 报告结构或授权违规；它不是用于任意设备动态的模型检查器，也不能证明现实世界的安全性。
命名的变异包括：
| CLI 名称 | Oracle 规则 | 变异 |
|---|---|---|
| `privilege_expansion` | `PRIVILEGE_EXPANSION` | 添加一个当前授权中没有的已批准授权 |
| `confused_deputy` | `CONFUSED_DEPUTY` | 添加一个调用者缺少所请求效应授权的请求 |
| `stale_version` | `STALE_VERSION` | 选择一个不同的在范围内的目标服务版本 |
| `orphan_effect` | `ORPHAN_EFFECT` | 添加一个引用不存在效应的请求 |
| `parser_corruption` | `PARSER_CORRUPTION` | 确定性地截断序列化的 JSON |
每个变异用例将分析器输入存储为 base64，并分离 oracle 的发现结果，因此预期结果不会发送给外部分析器。
创建请求 ID 的变异会检查现有的请求命名空间，并且 `orphan_effect` 还会针对现有的效应命名空间检查其合成的缺失效应 ID。如果首选的确定性 ID 已被占用，生成过程将使用确定性的数字后缀。`apply_mutation` 仅在重新计算的 oracle 恰好包含一个与表中承诺的规则匹配的发现结果时返回；`mutate` 会在写入前立即再次检查该后置条件。
`cps-authz-graph/v1` 读取器是封闭且有界的。它要求精确的 v1 顶层和记录字段、强类型的整数和字符串、唯一的安全标识符、唯一的授权以及有效的服务/效应引用。唯一有意设置的悬空引用是请求的效应，这也是表示 `ORPHAN_EFFECT` 的方式。格式错误的 JSON 和模式无效的 v1 文档会精确产生一个 `PARSER_CORRUPTION` 发现结果。每个解码后的 JSON 字符串值和对象键必须可编码为 UTF-8；转义的单独代理项将被拒绝。
已解码的映射在检查形状或字段之前会接受相同的递归检查，而不会将键或值字符串化。
生成器、变异、用例和结果的种子共享同一个非布尔值的 64 位有符号整数域。序列化输入的上限为 32 MiB；集合的上限为 4,096 个服务、16,384 个效应、每个授权集 65,536 个授权以及 65,536 个请求。
`mutate` 在进行任何特定于变异的字段访问之前，会将原始输入字节通过同样严格、封闭且有界的图读取器进行发送。`apply_mutation` API 会为直接映射调用者重复图验证过程。格式错误的图、或未满足的变异前置条件或后置条件，将通过 CLI 稳定的 `cps-authz-bench: input error:` 诊断信息报告，并以退出码 `64` 结束；不会写入新的输出文件。特别是，当请求的变异无法使用例精确保留其承诺的发现结果时，已经带有另一个 oracle 发现结果的结构有效的输入将被拒绝。
`stale_version` 会对选定的请求版本进行递增，除非它已经是最大的 32 位有符号版本，在这种情况下它会对其进行递减。因此，两个模式边界都保持在范围内，并产生精确的 `STALE_VERSION` 真值。
## Windows 快速开始（无需安装）
在 PowerShell 中从代码库根目录运行：
```
$env:PYTHONPATH = "src"
python -m cps_authz_bench generate `
--seed 42 --services 6 --effects 10 --requests 16 `
--output graph.json
python -m cps_authz_bench mutate `
--input graph.json --mutation confused_deputy --seed 7 `
--output case.json
python -m cps_authz_bench oracle --case case.json
python -m cps_authz_bench run `
--case case.json --tool-name reference-oracle `
--timeout 2 --max-output-bytes 65536 --result result.jsonl `
-- python examples/tools/reference_analyzer.py
```
参考分析器仅是围绕此包的 oracle 的一个冒烟测试适配器。将 `--` 之后的命令替换为遵循下述 stdin/stdout 契约的任何外部分析器。可选的 可编辑安装：
```
python -m pip install --no-build-isolation -e .
cps-authz-bench --help
```
## 外部分析器契约
适配器使用 `shell=False` 直接执行参数列表。它将用例的 payload 字节写入 stdin。成功的分析器以退出码 `0` 结束，并在 stdout 上精确输出一个 UTF-8 JSON 对象：
```
{
"findings": [
{"rule_id": "CONFUSED_DEPUTY", "subject": "request-confused-016"}
]
}
```
分析器文档是封闭的：`findings` 是其唯一的顶层字段。每个发现结果都需要有界的 `rule_id` 和 `subject` 字符串，并且仅可额外包含一个有界的 `message`、纯标量 `details` 和有限的 `[0, 1]` `confidence`。重复的 JSON 成员、非标准数字、字符串值或对象键中转义的单独代理项、未知字段，以及超过 65,536 个发现结果均被视为格式错误的输出。Subject、message、detail-key 和字符串 detail 值在字面量和转义的 JSON 中均拒绝所有的 C0 和 C1 控制字符（`U+0000`--`U+001F` 和 `U+007F`--`U+009F`）。Unicode 格式字符（通用类别 `Cf`）被接受并保留，不进行规范化。
发现结果将作为一组 `(rule_id, subject)` 标识进行比较。
超时、非零退出码、格式错误的 JSON 以及 stdout/stderr 组合溢出均具有不同的状态。`timeout_seconds` 必须是 `(0, 300]` 范围内的有限实数；`max_output_bytes` 必须是 `[1, 16,777,216]` 范围内的整数。
进程的 stdout 和 stderr 存储在显式的 `{encoding, data}` 捕获中。有效的 UTF-8 保留为文本；格式错误的 UTF-8 转换为规范的 base64，因此每个有界的原始字节流都有一个单射的、逐字节可恢复的表示形式。
进程内的 `invalid-utf8-base64:` 显示仅供诊断使用，绝不是序列化的证据边界。
超时和溢出清理目标是通过 Windows 的关闭时终止 Job Object 或 POSIX 进程组来定位分析器的普通后代树，包括启动器退出而子进程仍保留其管道的情况。Windows 会挂起启动分析器，在第一条指令运行之前配置并分配 Job，并且仅在成功包含后恢复执行。包含设置失败属于故障关闭 (`fail-closed`) 的 `launch_error`。该适配器是一个资源保护者，**而不是操作系统沙箱**；如果操作系统允许，独立分离或脱离的进程可能会逃脱，因此请不要在敏感主机上运行不受信任的可执行文件。
`run` 在完全匹配时退出码为 `0`，在分析器/oracle 不匹配时为 `1`，在工具执行失败时为 `2`，在无效的基准测试输入时为 `64`。
## 失败语料库与简化
使用有意设置不完整的示例分析器捕获不匹配项：
```
python -m cps_authz_bench run `
--case case.json --tool-name always-empty `
--corpus failure-corpus --result result.jsonl `
-- python examples/tools/always_empty.py
python -m cps_authz_bench corpus-list --corpus failure-corpus
```
语料库将确定性的 `.case.json` 信封和 `.result.json` 相邻存储。完全成功的运行会被拒绝进入失败语料库。
对于结构化（非 parser-corruption）用例，简化目标 oracle 发现结果：
```
python -m cps_authz_bench reduce `
--case case.json --rule-id CONFUSED_DEPUTY --output reduced.json
```
该库还导出了通用的 `ddmin(items, predicate)` 和 `reduce_graph(graph, predicate)` 函数。两者在简化前都会验证断言，保持项目顺序，避免修改调用者数据，并返回保留断言的结果。Delta 调试为测试的删除策略找到的是 1-最小化结果，而不是全局最小的图。
## 差异比较
给定带有 `findings` 数组的分析器输出 JSON 文件：
```
python -m cps_authz_bench diff `
--tool analyzer-a=output-a.json `
--tool analyzer-b=output-b.json
```
API 函数 `compare_findings` 和 `differential_compare` 会展示 oracle 的精确率/召回率以及跨工具的成对分歧。重复的发现标识在评分前会被去重。
## JSONL 结果模式
每个 `run` 记录都使用 `schema_version: "cps-authz-result/v2"`，并包含用例标识、工具名称、规范化的执行结果、独立的 oracle 和工具发现结果，以及比较指标。不包含时间戳或测量的持续时间，因此测试框架不会添加非确定性字段。机器可读的模式是 [`docs/cps-authz-result.schema.json`](docs/cps-authz-result.schema.json)。
验证过程不信任存储的分数或存储的发现摘要：它会封闭每个嵌套形状，检查执行状态的一致性，从存储的分析器 stdout 重新解析发现结果，并重新计算完整的比较结果。相反，`malformed_output` 记录必须包含未能通过严格分析器解析器的 stdout。失败语料库的添加/加载操作还会将用例 ID、变异、种子、oracle 发现结果和重新计算的比较结果绑定到配对的用例信封上。JSONL 解析仅将 LF (`U+000A`) 视为记录分隔符。接受 CRLF，因为 CR 是 JSON 空白符；单纯的 CR 不会拆分记录。字面量的行分隔符和段落分隔符（`U+2028` 和 `U+2029`）保留为 JSON 字符串数据，并通过 `render_jsonl` 和 `parse_jsonl` 进行往返转换。
## Python API
```
from cps_authz_bench import (
apply_mutation,
build_result,
compare_findings,
generate_graph,
run_tool,
)
graph = generate_graph(seed=42, service_count=6, effect_count=10, request_count=16)
case = apply_mutation(graph, "stale_version", seed=7)
execution = run_tool(["python", "my_analyzer.py"], case.payload)
result = build_result(case, "my-analyzer", execution)
```
有关模型、oracle、信任边界和确定性设计，请参阅 [`docs/architecture.md`](docs/architecture.md)。签入的 [`examples/fixtures/base-graph.json`](examples/fixtures/base-graph.json) 是一个小巧易读的固定数据；生成的用例对于给定的种子和大小是确定性的。
## 测试
```
$env:PYTHONDONTWRITEBYTECODE = "1"
$env:PYTHONPATH = "src"
python -B -m unittest discover -s tests -v
```
测试涵盖了种子可重现性、oracle 正确性、每种变异、源图不可变性、工具超时、格式错误和超大输出、后代清理、原子 Windows 直接子进程包含、转义和字面量 C1 拒绝、对抗性 v1 模式输入、针对每种变异的 CLI 对缺失和错误类型图字段的拒绝、变异 ID 冲突和精确后置条件强制执行、仅 LF 的 JSONL 帧定界和字面量 U+2028/U+2029 往返、差异评分、语料库往返、CLI 工件以及保留断言的简化。
## 项目状态
版本 0.1.0 是一个参考基准测试格式和测试框架。其 oracle 定义了该基准测试的合成真值；它不能确立此模型之外的授权设计的正确性，也未经工业控制或功能安全标准认证。
标签：Python, 信息物理系统, 变异测试, 授权分析, 无后门, 逆向工具