progmune-runtime 3.3.5 → 3.3.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -0
- package/README.zh-CN.md +228 -0
- package/dist/protocol-detector.js +3 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -7,6 +7,8 @@
|
|
|
7
7
|
[]()
|
|
8
8
|
[]()
|
|
9
9
|
|
|
10
|
+
> [中文版](README.zh-CN.md) · English Version
|
|
11
|
+
|
|
10
12
|
**Verify AI-generated code before it reaches production.** Progmune checks whether your AI-generated code follows correct protocol lifecycles — TLS handshakes, auth flows, payment integrity, resource management — violations that SAST and SCA tools cannot see because they span sequences of function calls, not single statements.
|
|
11
13
|
|
|
12
14
|
Progmune doesn't trust what the model says. It verifies what the program actually does.
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
# Progmune
|
|
2
|
+
|
|
3
|
+
## AI 生成代码的信任决策引擎
|
|
4
|
+
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
6
|
+
[](https://modelcontextprotocol.io)
|
|
7
|
+
[]()
|
|
8
|
+
[]()
|
|
9
|
+
|
|
10
|
+
> [English Version](README.md) · 中文版
|
|
11
|
+
|
|
12
|
+
**在 AI 生成的代码进入生产前验证它。** Progmune 检查你的 AI 生成代码是否遵循正确的协议生命周期——TLS 握手、认证流程、支付完整性、资源管理——这些违规横跨**函数调用序列**而非单条语句，SAST 和 SCA 工具都看不见。
|
|
13
|
+
|
|
14
|
+
Progmune 不信任模型说的话，它验证程序实际做的事。
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 一条命令
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
npm run sdk src/server.ts --explain
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
输出：`APPROVED` / `NEEDS_REVIEW` / `BLOCKED`——附信任评分、证据与修复建议。
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## 两条路径：生成时拦截 vs 事后检查
|
|
29
|
+
|
|
30
|
+
Progmune 用两种互补机制覆盖两类代码来源：
|
|
31
|
+
|
|
32
|
+
| | **生成路径**（Agent 时刻拦截） | **验证路径**（事后检查） |
|
|
33
|
+
|---|---|---|
|
|
34
|
+
| **覆盖** | 通过 Progmune 生成的代码（`progmune_generate` / `progmune_execute`） | 任何来源的代码——Copilot、Cursor、人工（`progmune_trust_check` / SDK / CI） |
|
|
35
|
+
| **机制** | 生成循环内 8 道验证关卡：JSON 解析 → schema → SVL-1 符号 → SVL-2 类型 → SVL-3 数据流 → SVL-4 协议状态机 → BFS 确定性修复 → 语义合约。违规代码**从不写入磁盘**——在发射前被纠正或重试 | 信任引擎：四维加权评分（策略 35% / 协议 30% / 覆盖 20% / 治理 15%）→ 决策 + 证据链 |
|
|
36
|
+
| **错误处理时机** | 创建时刻——错误从未存在 | 事后——文件已存在 |
|
|
37
|
+
| **成本曲线** | 零——违规没有落地 | 发现越晚越贵 |
|
|
38
|
+
|
|
39
|
+
核心产品论：**在生成时刻验证，而非事后补救。** LLM 的输出只是提议，状态机才是裁判——LLM 可以被劝服，状态机不会。
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Progmune 检测什么
|
|
44
|
+
|
|
45
|
+
AI 代码生成器产出语法合法的代码，却常常违反**协议生命周期**——正确的操作顺序，如 open→read→close 或 auth→validate→respond。这些违规对传统静态分析不可见。
|
|
46
|
+
|
|
47
|
+
| 类别 | 检测到的违规示例 |
|
|
48
|
+
|------|----------------|
|
|
49
|
+
| **TLS / SSL** | 握手未校验证书、缺少主机名校验 |
|
|
50
|
+
| **认证** | 令牌无过期时间、会话无超时、缺少限流 |
|
|
51
|
+
| **支付** | 订单未验证、退款未授权、Webhook 无签名校验 |
|
|
52
|
+
| **资源** | 文件打开未关闭、连接未清理、malloc 未 free |
|
|
53
|
+
| **数据完整性** | 变更无审计轨迹、缺少输入校验 |
|
|
54
|
+
| **注入类（Python，源码级）** | 用 f-string/`%`/`.format`/拼接构造 SQL、动态 subprocess 参数导致命令注入、用户可控 URL 抓取导致 SSRF、模板字符串 sink 导致 SSTI、外部实体解析器配置导致 XXE、对用户输入 eval/exec |
|
|
55
|
+
| **Web 类（Python，源码级）** | `{{ var\|safe }}`/autoescape off 模板导致 XSS、用户可控文件路径导致路径穿越、`@csrf_exempt` 或 GET 状态变更导致 CSRF、客户端 cookie 授权、硬编码 JWT 密钥（含跨模块常量） |
|
|
56
|
+
|
|
57
|
+
源码级检测采用**提取器标记架构**：IR 提取器执行污点追踪、import 解析、跨文件分析（模板、模块常量），发射合成标记供规则消费——零管道改动、完全可审计。
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## 快速开始
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
npm install progmune-runtime
|
|
65
|
+
|
|
66
|
+
# 验证一个文件——获得信任决策
|
|
67
|
+
npm run sdk src/server.ts
|
|
68
|
+
|
|
69
|
+
# 完整解释（证据 + 修复建议）
|
|
70
|
+
npm run sdk src/server.ts --explain
|
|
71
|
+
|
|
72
|
+
# 信任检查（CI 友好 JSON 输出）
|
|
73
|
+
npm run trust -- --project . --json
|
|
74
|
+
|
|
75
|
+
# 运行基准套件
|
|
76
|
+
npm run precision:all
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## 信任决策
|
|
82
|
+
|
|
83
|
+
Progmune 的输出是**有证据支撑的决策**，不是原始发现列表：
|
|
84
|
+
|
|
85
|
+
| 输出 | 含义 |
|
|
86
|
+
|------|------|
|
|
87
|
+
| **信任评分**（0–100） | 四维度的量化信任水平 |
|
|
88
|
+
| **决策** | `APPROVED` / `NEEDS_REVIEW` / `BLOCKED` |
|
|
89
|
+
| **置信度** | `HIGH` / `MEDIUM` / `LOW` / `UNCERTAIN` |
|
|
90
|
+
| **证据** | 每条违规追溯到代码位置 + RFC 引用 + 修复建议 |
|
|
91
|
+
|
|
92
|
+
**严重违规 → 无论评分多少一律硬 BLOCK。** 企业关心的是"能不能上线"，不是"我的评分是 58 还是 61"。
|
|
93
|
+
|
|
94
|
+
→ [信任决策模型](docs/ai-trust-decision-model-v1.md)
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## 覆盖范围
|
|
99
|
+
|
|
100
|
+
Progmune 对能验证什么、不能验证什么保持诚实。
|
|
101
|
+
|
|
102
|
+
| 语言 | 状态 | 证据 |
|
|
103
|
+
|------|------|------|
|
|
104
|
+
| **TypeScript / JavaScript** | ✅ 生产 | 盲测基准：**召回 98.5% / 精确率 100%**（795 条 gold finding，100 个项目） |
|
|
105
|
+
| **Python** | ✅ 生产 | 盲测基准：**召回 100% / 精确率 100%**（729 条 gold finding，90 个项目）；真实应用验证：PyGoat（OWASP 故意脆弱 Django 应用）**67 TP / 0 FP，标记精确率 100%**；三个良构应用（django/fastapi realworld、django-unicorn）0 误报真阳性 |
|
|
106
|
+
| **C** | ⚠️ 仅研究 | 黄金基准 F1=16.5%。L3 跨函数实验已终止；L4 无计划。见 [C 语言状态](docs/c-language-status.md)。 |
|
|
107
|
+
| **Go, Java** | ❌ 无 | 规划中 |
|
|
108
|
+
|
|
109
|
+
**框架适配器：2/13。** Express ✅ 与 tRPC ✅ 有专用检测器；Next.js 有版本感知治理；NestJS 部分支持。Django、FastAPI 及另外 8 个待适配——框架适配是 #1 产品缺口。
|
|
110
|
+
|
|
111
|
+
### Progmune 不覆盖什么（诚实边界）
|
|
112
|
+
|
|
113
|
+
- **TS 侧的污点注入类缺陷**——源码级 SQLi/XSS/SSRF 检测已在 Python 上线；TypeScript 提取器基于名称/调用，TS 注入类暂未覆盖（如实记录，不隐藏）。
|
|
114
|
+
- **SCA / 依赖漏洞**——幻觉包名、供应链问题。已有独立工具。
|
|
115
|
+
- **运行时行为**——Progmune 仅做静态分析；无 DAST/沙箱执行。
|
|
116
|
+
- **框架内部件**——知名框架的分发/缓存机制（如 django-unicorn 内部件）可能产生少量边界误报；各语料基准 gold 文件中已逐条记录。
|
|
117
|
+
- **已知失败边界一律记录**而非隐藏：如果 Progmune 无法验证某语言（如 Go），置信度会降低而不是假装 100%。
|
|
118
|
+
|
|
119
|
+
→ [完整覆盖矩阵](docs/coverage-matrix.md)
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## 基准
|
|
124
|
+
|
|
125
|
+
公开、可复现的精确率数据。所有数字均对 gold 标注基准测量。
|
|
126
|
+
|
|
127
|
+
### TypeScript（盲测基准 v6——100 个项目）
|
|
128
|
+
|
|
129
|
+
| 指标 | 值 |
|
|
130
|
+
|------|-----|
|
|
131
|
+
| 精确率 | **100%**（0 条事实性误报） |
|
|
132
|
+
| 召回率 | **98.5%**（有效口径 100%——12 条未检出按方法论排除） |
|
|
133
|
+
| Gold findings | 795 条，覆盖 100 个项目（90 风格变体 + 10 模型变体） |
|
|
134
|
+
|
|
135
|
+
### Python（盲测基准 v1——90 个项目）
|
|
136
|
+
|
|
137
|
+
| 指标 | 值 |
|
|
138
|
+
|------|-----|
|
|
139
|
+
| 精确率 | **100%** |
|
|
140
|
+
| 召回率 | **100%** |
|
|
141
|
+
| Gold findings | 729 条，覆盖 90 个风格变体项目 |
|
|
142
|
+
|
|
143
|
+
### 真实应用验证（PyGoat，OWASP 故意脆弱 Django 应用）
|
|
144
|
+
|
|
145
|
+
| 指标 | 值 |
|
|
146
|
+
|------|-----|
|
|
147
|
+
| 标记精确率 | **100%**（67 真阳性 / 0 误报，逐条人工核实） |
|
|
148
|
+
| 覆盖类别 | 14 个漏洞类别，含 SQLi、SSRF、路径穿越、XSS、SSTI、XXE、命令注入、反序列化、CSRF（双形态）、cookie 授权、硬编码密钥 |
|
|
149
|
+
| 良构应用 | django-realworld、fastapi-realworld、django-unicorn——0 误报真阳性 |
|
|
150
|
+
|
|
151
|
+
→ [真实验证报告](blind-benchmark/REALWORLD_APP_V1.md) · [基准基线](blind-benchmark/BASELINE_v6.md)
|
|
152
|
+
|
|
153
|
+
### C（黄金基准——研究状态）
|
|
154
|
+
|
|
155
|
+
C 分析**仅研究**：黄金基准 F1=16.5%，覆盖 4 个仓库（curl、libssh、nginx、openssl）。瓶颈是规则覆盖而非上下文。L3（跨函数）已带数据终止；L4（指针/CFG）是多年研究问题，无计划。详见 [C 语言状态](docs/c-language-status.md)。
|
|
156
|
+
|
|
157
|
+
### P0-P3 规则注入（2026-08）
|
|
158
|
+
|
|
159
|
+
- 10 个 TS 项目 **+19 条新检测**，6 个 C 仓库 + PostgreSQL **0 误报**
|
|
160
|
+
- 打破引导死锁：全部 21 个协议命名空间已有规则词汇
|
|
161
|
+
- `excludePatterns` + `languages` 架构管理误报
|
|
162
|
+
|
|
163
|
+
→ [双峰报告](docs/two-hump-report.md) · [P0-P3 终报](docs/p0-p3-final-report.md)
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## 架构
|
|
168
|
+
|
|
169
|
+
```
|
|
170
|
+
SDK (src/sdk.ts) verify() → APPROVED / NEEDS_REVIEW / BLOCKED
|
|
171
|
+
└─ 信任引擎 四维评分 → 决策
|
|
172
|
+
├─ 策略引擎 企业策略执行（ALLOW/WARN/BLOCK）
|
|
173
|
+
├─ SSG 校验器 协议状态机验证
|
|
174
|
+
├─ 协议检测器 基于正则的协议步骤检测（22 个检测器）
|
|
175
|
+
├─ IR 提取器 TypeScript（ts-morph）+ Python（ast 模块）→ 函数 IR；
|
|
176
|
+
│ 源码级标记：污点追踪、import 解析、限定调用链、跨文件模板分析
|
|
177
|
+
├─ 修复执行器 detect → plan → fix → validate → commit/rollback
|
|
178
|
+
└─ 知识库 31 个域、140 条规则、证据链
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### 接口
|
|
182
|
+
|
|
183
|
+
| 接口 | 用途 |
|
|
184
|
+
|------|------|
|
|
185
|
+
| **SDK**（`verify()`） | 开发者一次性调用 API |
|
|
186
|
+
| **CLI**（`npm run trust`） | 命令行信任检查 |
|
|
187
|
+
| **MCP 服务器** | Claude Code 集成（`progmune_check`、`progmune_trust_check`） |
|
|
188
|
+
| **GitHub Action** | CI/CD 门禁——在 PR 拦截未验证的 AI 代码 |
|
|
189
|
+
| **Trust API** | `POST /trust/check`——机器间接口 |
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
193
|
+
## 科学基础
|
|
194
|
+
|
|
195
|
+
Progmune 建立在"**LLM 输出是统计表演而非推理**"这一前提上——该观点源自 Subbarao Kambhampati 等人的立场论文 ["Stop Anthropomorphizing Intermediate Tokens as Reasoning/Thinking Traces!"](https://arxiv.org/abs/2505.22285)（arXiv:2505.22285，2025），并在其 ICML 2026 演讲 "On the Role of Verifiers and Thinking Traces in Reasoning Models" 中展开。Progmune 不信任模型对代码的说法，而是用协议状态机、IR 提取与证据链验证程序实际行为。
|
|
196
|
+
|
|
197
|
+
覆盖缺口分析借用"双峰问题"术语作为**跨域类比**，源自 Sergei Gukov 在数学物理领域的工作（群论中的 Andrews-Curtis 猜想，2026）——它描述的是双峰覆盖分布，而非合作关系。详见 [双峰报告](docs/two-hump-report.md)。
|
|
198
|
+
|
|
199
|
+
→ [投资人白皮书](docs/Progmune_投资人白皮书_v2.0.html) · [信任决策模型](docs/ai-trust-decision-model-v1.md)
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
## 贡献
|
|
204
|
+
|
|
205
|
+
架构与代码规范见 [CLAUDE.md](CLAUDE.md)，开发流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。
|
|
206
|
+
|
|
207
|
+
高价值贡献方向：
|
|
208
|
+
- **框架适配器**（Express、Next.js、FastAPI）——#1 产品缺口
|
|
209
|
+
- **Python 验证规则**——向 TypeScript 之外扩展
|
|
210
|
+
- 现有检测器与防护规则的**缺陷修复**
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## 状态
|
|
215
|
+
|
|
216
|
+
- **运行时管线：** 检测 → 解释 → 修复 → 验证（L1–L4）
|
|
217
|
+
- **信任引擎：** 四维评分 + 二元可解释性门
|
|
218
|
+
- **MCP 工具：** 19 个——`progmune_trust_check`、`progmune_score`、`progmune_policy_check`、`progmune_certify` 等
|
|
219
|
+
- **框架适配器：** Express ✅、tRPC ✅、NestJS 部分（2/13）
|
|
220
|
+
- **知识库：** 31 个域、148 条协议规则、22 个检测器、26 条防护规则、PLSB 13/13 类别——另加 15 条源码级检测规则（Python）
|
|
221
|
+
- **语料：** 6+ 仓库 2,500+ 轨迹；盲测基准 100（TS）+ 90（Python）个项目；4 个应用仓库真实验证
|
|
222
|
+
- **当前重点：** 企业 PoC 验证 + 剩余框架内部边界误报
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## License
|
|
227
|
+
|
|
228
|
+
MIT — [LICENSE](LICENSE)
|
|
@@ -363,6 +363,8 @@ const SAFEGUARD_RULES = [
|
|
|
363
363
|
/listpack/, // Redis internal data structure
|
|
364
364
|
/readSync|readQuery/, // internal I/O
|
|
365
365
|
/findBig|findKey|findPk/, // internal search (not API)
|
|
366
|
+
/get_cache\w*/, // cache machinery (get_cache_alias — not data access)
|
|
367
|
+
/get_context_data/, // Django CBV context assembly — framework verb
|
|
366
368
|
],
|
|
367
369
|
},
|
|
368
370
|
// Mutations without any authentication. The Unauthenticated Access rule above
|
|
@@ -388,6 +390,7 @@ const SAFEGUARD_RULES = [
|
|
|
388
390
|
/set_ssl_/, // SSL config setter
|
|
389
391
|
/set_config/, // configuration setter
|
|
390
392
|
/set_option/, // option setter
|
|
393
|
+
/\bsetup\b/, // framework/component setup — configuration, not data mutation
|
|
391
394
|
],
|
|
392
395
|
},
|
|
393
396
|
// ── Data Integrity (Foreign Key Validation) ──
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "progmune-runtime",
|
|
3
|
-
"version": "3.3.
|
|
3
|
+
"version": "3.3.7",
|
|
4
4
|
"description": "Progmune — AI Trust Decision Engine. Verify AI-generated code before it reaches production. Outputs APPROVED / NEEDS_REVIEW / BLOCKED with evidence.",
|
|
5
5
|
"files": [
|
|
6
6
|
"dist/",
|