nickharris808/pqc-guard-action
GitHub: nickharris808/pqc-guard-action
一个 GitHub Action，在后量子密码迁移过程中当重组窗口不安全、基准覆盖率不足或发生测试回归时令 CI 构建失败。
Stars: 0 | Forks: 0
# pqc-guard-action
[](LICENSE)
[](tests/)
[](action.yml)
**在 CI 中捕获不安全的后量子迁移，而不是在现场。**
只需在工作流中添加三行代码。当不存在安全的重组上限时，当基准测试覆盖率低于您的阈值时，或者当您导致以前通过的测试用例发生回归时，构建将会失败。
## 为什么存在这个项目
后量子凭证大小为 7,533 字节或更多。这迫使数据分片，从而迫使您的接收方在能够对其进行身份验证之前，必须持有受攻击者影响的状态，这进而要求设定一个容量上限 —— 而该上限既有*下限*也有*上限*。您完全有可能选择了一个并发限制，而导致**根本不存在安全的上限**。
这是一个设计缺陷，它在代码审查中是不可见的，而且它是一个算术问题。因此，它应该属于 CI 的范畴。
## 快速开始
```
- uses: nickharris808/pqc-guard-action@v1
with:
kem: ML-KEM-768
sig: ML-DSA-65
budget: 65536
concurrency: 4
```
就是这样。如果窗口为空，作业将会失败。
## 输出示例
当它失败时，您会在 PR 上看到一个标注：
```
::error::Reassembly window is EMPTY for ML-KEM-768+SLH-DSA-SHA2-128f credential:
floor 19,392 B > ceiling 16,384 B. No capacity cap is both feasible and safe.
```
以及一份告诉您如何修复它的作业摘要：
**`max safe concurrency` 是可操作的数值** —— 这个防护不仅会拒绝，还会告诉您能够通过的值。
## 两项检查
```
- uses: nickharris808/pqc-guard-action@v1
with:
check: both
kem: ML-KEM-768
sig: ML-DSA-65
budget: 65536
concurrency: 4
submission: results/pqc-mfb.json
min-coverage: "80"
max-zero-families: "5"
```
## 输入
| 输入 | 默认值 | 含义 |
|---|---|---|
| `check` | `window` | `window`、`benchmark` 或 `both` |
| `kem` / `sig` | — | 算法名称；自动为您解析凭证大小 |
| `largest-object` | `0` | 显式字节数，替代 `kem`+`sig` |
| `budget` | `65536` | 全局重组内存预算，字节 |
| `concurrency` | `4` | 最坏情况下的并发重组上下文 |
| `submission` | — | PQC-MFB 提交的 JSON (`{case_id: bool}`) |
| `min-coverage` | `0` | 通过所需的最低覆盖率百分比 |
| `max-zero-families` | 无限制 | 零覆盖率族的上限 |
| `python-version` | `3.12` | 运行检查使用的 Python 版本 |
## 输出
`window-empty` · `ceiling` · `max-safe-concurrency` · `coverage-pct` · `regressions`
```
- id: guard
uses: nickharris808/pqc-guard-action@v1
continue-on-error: true
with: { kem: ML-KEM-768, sig: ML-DSA-65, budget: 65536, concurrency: 4 }
- run: echo "cap should be ${{ steps.guard.outputs.ceiling }} bytes"
```
## 什么情况会被判定为失败
| 条件 | 结果 |
|---|---|
| 重组窗口为空 | **失败** |
| 覆盖率低于 `min-coverage` | **失败** |
| **任何回归** | **失败 —— 无论覆盖率如何** |
| 零覆盖率族过多 | **失败** |
一个提交可以获得 **100% 的覆盖率但依然失败**，前提是它破坏了未修复的基线已经能够处理的用例。有一个测试专门断言这一点。
## 在本地运行
该 Action 只是一个可读脚本的轻量级封装 —— 没有编译后的打包文件，也没有 `node_modules`：
```
pip install pqc-sizes pqc-mfb
python guard.py window --kem ML-KEM-768 --sig ML-DSA-65 --budget 65536 --concurrency 4
python guard.py benchmark results.json --min-coverage 80
```
退出代码：**0** 通过 · **1** 检查失败 · **2** 用法错误。
## 测试
```
pip install pytest pyyaml pqc-sizes pqc-mfb && pytest # 17 passed
```
这些测试将 GitHub Actions 环境连接到临时文件，并以子进程方式驱动 `guard.py`，然后对退出代码、`GITHUB_OUTPUT` 和作业摘要进行断言 —— 因为如果一个 Action 报告了问题但退出代码为 `0`，那么它不会导致任何人的构建失败。
## 适用范围
仅涉及算术和评分。它不会检查您的实现、读取您的流量或以密码学方式验证任何内容。构建通过仅意味着您的*配置*允许一个安全的上限，并且您的提交满足了您的阈值 —— 并不代表您的代码强制执行了它。
## 相关项目
[`pqc-sizes`](https://github.com/nickharris808/pqc-sizes) · [`pqc-mfb`](https://github.com/nickharris808/pqc-mfb) ·
[`pqc-dos-embedded`](https://github.com/nickharris808/pqc-dos-embedded) · [`farkas-check`](https://github.com/nickharris808/farkas-check)
强制执行该上限，并关闭其他 38 个失败族，是闭源核心所做的工作。相关主题已包含在已提交的临时专利申请中。
如需商业使用，请开启一个 [GitHub Discussion](https://github.com/nickharris808) 或 issue。
## PQC 迁移工具包
为将认证密钥交换迁移到后量子时代的团队提供的九款免费工具。它们**负责查找和测量**；不负责修复。
| 工具 | 功能 | 位置 |
|---|---|---|
| [pqc-sizes](https://github.com/nickharris808/pqc-sizes) | 大小、分片数和双向重组窗口 | PyPI |
| [pqc-sizes-js](https://github.com/nickharris808/pqc-sizes-js) | 适用于 Node 和浏览器的相同算术逻辑 | npm |
| **pqc-guard-action** ← 您在这里 | 当窗口为空时使构建失败 | GitHub Action |
| [pqc-dos-embedded](https://github.com/nickharris808/pqc-dos-embedded) | 169 行 C 代码：在真实 64 KB 设备上的失败情况 | 源码 |
| [farkas-check](https://github.com/nickharris808/farkas-check) | 在设备上重新验证边界，无需 SMT 求解器 | 源码 |
| [pqc-migration-mcp](https://github.com/nickharris808/pqc-migration-mcp) | 面向 AI 智能体的六款 MCP 工具 | PyPI |
| [pqc-mfb](https://github.com/nickharris808/pqc-mfb) | 322 个用例 · 39 个失败族 · 评分器 | PyPI |
| [pqc-mfb (data)](https://huggingface.co/datasets/nickh007/pqc-mfb) | 作为数据集的基准测试 | HF |
| [pqc-formal-corpus](https://huggingface.co/datasets/nickh007/pqc-formal-corpus) | 122 个命名的形式化结果，6 个证明器 | HF |
| [pqc-explorer](https://huggingface.co/spaces/nickh007/pqc-explorer) | 在您的浏览器中尝试，无需安装 | HF Space |
**从这里开始：**[`pqc-sizes`](https://github.com/nickharris808/pqc-sizes) 能在五秒钟内告诉您您的凭证是否会被分片，以及是否存在安全的上限。[`pqc-explorer`](https://huggingface.co/spaces/nickh007/pqc-explorer) 可以在浏览器中执行相同的操作。
### 闭源核心
关闭这 39 个失败族 —— 降级绑定、重传安全安装、分片记录、漫游前向安全性、多链路密钥隔离、准入控制、组密钥绑定 —— 是一个独立的专有代码库。相关主题已包含在已提交的临时专利申请中。
这种划分是经过测量的，而非主观断言：在复制噪声控制下，32 个修复机制中只有 **4 个**是外部可区分的，因此发布这些检测器并不会泄露修复方法。
如需商业授权，请开启一个 [GitHub Discussion](https://github.com/nickharris808/pqc-sizes/discussions) 或在这些代码库中任何一个提交 issue。
## 许可证
Apache-2.0。请参阅 [LICENSE](LICENSE) 和 [CONTRIBUTING.md](CONTRIBUTING.md)。
标签：GitHub Action, 后量子密码学, 安全规则引擎, 逆向工具