Progmune

AI 生成代码的信任决策引擎

English Version · 中文版

在 AI 生成的代码进入生产前验证它。 Progmune 检查协议生命周期（TLS 握手、认证流程、支付完整性、资源管理——注解驱动）、框架路由认证（生产）、真实修复验证过的污点检测（路径穿越、SSRF）——外加一条排序后的防护告警证据流供人工审查。每项能力声明都按证据分级：能力审计。

Progmune 不信任模型说的话，它验证程序实际做的事。

一条命令

npm run sdk src/server.ts --explain

输出：APPROVED / NEEDS_REVIEW / BLOCKED——附信任评分、证据与修复建议。

两条路径：生成时拦截 vs 事后检查

Progmune 用两种互补机制覆盖两类代码来源：

| | 生成路径（Agent 时刻拦截） | 验证路径（事后检查） | |---|---|---| | 覆盖 | 通过 Progmune 生成的代码（progmune_generate / progmune_execute） | 任何来源的代码——Copilot、Cursor、人工（progmune_trust_check / SDK / CI） | | 机制 | 生成循环内 8 道验证关卡：JSON 解析 → schema → SVL-1 符号 → SVL-2 类型 → SVL-3 数据流 → SVL-4 协议状态机 → BFS 确定性修复 → 语义合约。违规代码从不写入磁盘——在发射前被纠正或重试 | 信任引擎：四维加权评分（策略 35% / 协议 30% / 覆盖 20% / 治理 15%）→ 决策 + 证据链 | | 错误处理时机 | 创建时刻——错误从未存在 | 事后——文件已存在 | | 成本曲线 | 零——违规没有落地 | 发现越晚越贵 |

核心产品论：在生成时刻验证，而非事后补救。 LLM 的输出只是提议，状态机才是裁判——LLM 可以被劝服，状态机不会。

Progmune 检测什么

AI 代码生成器产出语法合法的代码，却常常违反协议生命周期——正确的操作顺序，如 open→read→close 或 auth→validate→respond。这些违规对传统静态分析不可见。

| 类别 | 检测到的违规示例 | |------|----------------| | 协议生命周期（注解驱动） | TLS 握手、认证流程、支付完整性、资源管理——你声明协议原语（每协议 ~2-3 个注解），状态机验证执行顺序。已验证：C 真实模块金标 5/5、应用级 P=91.7%/R=100%。未注解代码的自动检测为研究级——17 条真实安全修复命中 0（实测，见 修复回归语料） | | 框架路由认证（TS/Python，生产） | 写操作路由缺认证守卫/校验——NestJS/Express/tRPC/FastAPI/Django/Flask/Fastify/Next.js/Koa/Hapi/Gin/Fiber/Spring：真实语料验证 + 摘保护反证；docmost + immich 真实项目盲测（修复轮后） | | 污点标记检测（真实修复验证） | 路径穿越（TS+Python）与 SSRF（TS+Python）：提取器污点流 → sink，以真实安全修复的真值位置验证（fr-007、fr-016、fr-010、fr-011）+ held-out 命中：immich 上 SSRF = GHSA-hq46。见 能力审计 | | 输入校验 / 数据完整性防护 | 持久化前缺输入校验、缺外键检查——证据流（已排序）而非判定：真实世界加权精确率 ≈6%，排序头部 ≈46% | | 注入类（Python，源码级） | 用 f-string/%/.format/拼接构造 SQL、动态 subprocess 参数导致命令注入、用户可控 URL 抓取导致 SSRF、模板字符串 sink 导致 SSTI、外部实体解析器配置导致 XXE、对用户输入 eval/exec | | Web 类（Python，源码级） | {{ var\|safe }}/autoescape off 模板导致 XSS、用户可控文件路径导致路径穿越、@csrf_exempt 或 GET 状态变更导致 CSRF、客户端 cookie 授权、硬编码 JWT 密钥（含跨模块常量） |

源码级检测采用提取器标记架构：IR 提取器执行污点追踪、import 解析、跨文件分析（模板、模块常量），发射合成标记供规则消费——零管道改动、完全可审计。

快速开始

npm install progmune-runtime

# 验证一个文件——获得信任决策
npm run sdk src/server.ts

# 完整解释（证据 + 修复建议）
npm run sdk src/server.ts --explain

# 信任检查（CI 友好 JSON 输出）
npm run trust -- --project . --json

# 运行基准套件
npm run precision:all

信任决策

Progmune 的输出是有证据支撑的决策，不是原始发现列表：

| 输出 | 含义 | |------|------| | 信任评分（0–100） | 四维度的量化信任水平 | | 决策 | APPROVED / NEEDS_REVIEW / BLOCKED | | 置信度 | HIGH / MEDIUM / LOW / UNCERTAIN | | 证据 | 每条违规追溯到代码位置 + RFC 引用 + 修复建议 |

严重违规 → 无论评分多少一律硬 BLOCK。 企业关心的是"能不能上线"，不是"我的评分是 58 还是 61"。

→ 信任决策模型

覆盖范围

Progmune 对能验证什么、不能验证什么保持诚实。

| 语言 | 状态 | 证据 | |------|------|------| | TypeScript / JavaScript | ✅ 生产 | 合成盲测基准：召回 98.5% / 精确率 100%（795 条 gold finding，100 个生成项目）。真实项目数字单列并如实发布——见 能力审计（三要件）：告警流加权精确率 ≈6%（排序后头部 ≈46%）、84 条真实公告位置召回 47%（下界）、主路径真实公告命中 1 次 | | Python | ✅ 生产 | 合成盲测基准：召回 100% / 精确率 100%（729 条 gold finding，90 个生成项目）；真实应用验证：PyGoat（OWASP 故意脆弱 Django 应用）67 TP / 0 FP，标记精确率 100%；三个良构应用（django/fastapi realworld、django-unicorn）0 误报真阳性 | | C | ✅ 注解驱动（Beta） | IR 提取接入注册表 + SSG 状态机；每协议标注 ~2-3 个原语即获得可信验证（真实模块金标 5/5：redis ACL / libssh 客户端 / libssh 服务端 / libssh 回调分发 / uftpd 传送授权——全部 0 误报 + 违规精确定位；应用级金标 v2：P=91.7% / R=100% / F1=95.7%）。未注解自动检测不在范围（真实语料 0 TP——定位决议见 C 语言状态文档）；TLS 级覆盖仍无。见 C 语言状态。 | | Go | ✅ 注解驱动（Beta） | IR 提取接入注册表 + SSG 状态机；合成金标 v1：P=100% / R=100%（3 干净 × 3 植入违规）；零外部工具链（纯 TS 词法提取，npm 安装态可用） | | Java | ❌ 无 | 规划中 |

多语言 IR（注册表式）。 TypeScript（ts-morph）与 Python（AST）提取器是同一注册表（src/extract-project-ir.ts）中的注册项；extractProjectIR 把检测到的所有语言合并为一份函数 IR，由 agent loop、execute() 与 MCP server 共享——agent 可在两种语言上编排函数协议链。新增语言（Go、Java……）= 注册一条提取器，调用方零改动。

框架适配器：12 专用检测器（4 结构级 + 8 启发式）。 Express ✅、tRPC ✅、FastAPI ✅、Django ✅（结构级路由认证分析——逐条检查写操作入口的认证）、Flask ✅（路由/before_request 认证守卫分析）、Fastify ✅（路由 preHandler/钩子认证分析）与 Next.js ✅（App Router 路由处理器认证分析）、NestJS ✅（装饰器路由解析 + 全局 APP_GUARD 守卫识别 + @Public 豁免）、Koa ✅、Hapi ✅（路由配置认证策略分析）、Gin ✅ 与 Fiber ✅（Go 路由/认证中间件分析）有专用检测器；Next.js 另有版本感知治理。结构级 = AST 解析（NestJS/FastAPI/Django/Flask——合成金标 P=R=100%）；启发式 = 代码串模式（Express/tRPC/Fastify/Next.js/Koa/Hapi/Gin/Fiber——单测覆盖，真实项目 FP 数据待补）。Spring Boot 待适配——框架适配是 #1 产品缺口。

Progmune 不覆盖什么（诚实边界）

• TS 侧的污点注入类缺陷——源码级 SQLi/XSS/SSRF 检测已在 Python 上线；TypeScript 提取器基于名称/调用，TS 注入类暂未覆盖（如实记录，不隐藏）。
• SCA / 依赖漏洞——幻觉包名、供应链问题。已有独立工具。
• 运行时行为——Progmune 仅做静态分析；无 DAST/沙箱执行。
• 框架内部件——知名框架的分发/缓存机制（如 django-unicorn 内部件）可能产生少量边界误报；各语料基准 gold 文件中已逐条记录。
• 已知失败边界一律记录而非隐藏：如果 Progmune 无法验证某语言（如 Go），置信度会降低而不是假装 100%。
• 刻意规避不在防护目标内——注解驱动模型拦截的是 AI 的「意外」协议错误（漏写前置步骤、顺序颠倒）；对故意改名/混淆的对抗性规避不设防（任何静态工具同理）。
• BLOCK 的强制力由集成方承担——Progmune 输出判定与证据，不运行时拦截。OS 级强制执行点：trust --ci 退出码（CI 门禁）、policy CLI 退出码、以及 opt-in 的写后回滚门（项目配置 .progmune-policy.json 后，execute 写盘随即验证，BLOCK 时文件不残留。注意这是补偿控制而非写前拦截：写盘与回滚之间若进程被中断，违规内容可能短暂/持续残留——已知边界）。

分资产分级接入（TIERED_POLICY）：不要给所有代码同一套门禁——按「出错代价 × AI 参与度」选档，一条命令落地：

npx progmune-init-policy --tier 1   # 强制：鉴权/支付/资源生命周期——写盘策略门激活
npx progmune-init-policy --tier 2   # 标准：业务逻辑——violations 阻断，其余 WARN
npx progmune-init-policy --tier 3   # 观察：工具/demo——只报告不拦截

→ 完整覆盖矩阵

基准

公开、可复现的精确率数据。所有数字均对 gold 标注基准测量。

⚠ 口径：以下数字是合成基准（模板生成项目 + 人工金标）——它证明"规则在这些形态上工作"，不证明"在真实项目上同样准确"。真实项目数字单列在 能力审计（三要件）：真实告警流加权精确率 ≈6%（排序后头部 ≈46%）、84 条真实公告位置召回 47%（下界）、主路径真实公告命中 1 次（SSRF = GHSA-hq46）。合成 P100% 与真实项目大量误报可以同时为真——两者测的是不同的事。

TypeScript（盲测基准 v6——100 个项目）

| 指标 | 值 | |------|-----| | 精确率 | 100%（0 条事实性误报） | | 召回率 | 98.5%（有效口径 100%——12 条未检出按方法论排除） | | Gold findings | 795 条，覆盖 100 个项目（90 风格变体 + 10 模型变体） |

Python（盲测基准 v1——90 个项目）

| 指标 | 值 | |------|-----| | 精确率 | 100% | | 召回率 | 100% | | Gold findings | 729 条，覆盖 90 个风格变体项目 |

真实应用验证（PyGoat，OWASP 故意脆弱 Django 应用）

| 指标 | 值 | |------|-----| | 标记精确率 | 100%（67 真阳性 / 0 误报，逐条人工核实） | | 覆盖类别 | 14 个漏洞类别，Python 口径（Django lab 应用）——SQLi、SSRF、路径穿越、XSS、SSTI、XXE、命令注入、反序列化、CSRF（双形态）、cookie 授权、硬编码密钥。⚠ 这些类别在 TypeScript 上并未全部接线：48 条规则中 15 条 python-only，在 TS 项目上永不触发（含 XSS/CSRF/XXE/硬编码密钥）——实测数据见 PATH_GUARD_EVIDENCE_DESIGN §49.18 | | 良构应用 | django-realworld、fastapi-realworld、django-unicorn——0 误报真阳性 |

→ 真实验证报告 · 基准基线

C（IR 提取 + 注解驱动协议验证——Beta）

3.7.4 起 C 拥有多语言注册表中的 IR 提取器：C 项目进入 IR-first 序列验证 + SSG 状态机。应用级协议生命周期（认证/数据库/文件/支付）在 C 上可验证——应用级金标 v2：11/11 违规全检出（召回 100%）、1 误报、F1=95.7%。注解驱动是 C 的生产形态（3.7.6 起 Beta）：真实模块金标 5/5（redis ACL、libssh 客户端/服务端/回调分发、uftpd 传送授权）+ 1 个独立采纳案例（uftpd）——全部 0 误报 + 违规精确定位，标注成本稳定在每协议 ~2-3 条。未注解自动检测不在范围（真实语料 0 TP）。提取覆盖大型真实仓库（openssl 15.5k / redis 5.7k / curl 4.2k 函数，秒级，黄金函数恢复率 97–100%）。两条边界不变：旧正则口径黄金基准 F1=16.5% 测的是 TLS 级误用（SSG 无 TLS 状态机，该口径不变）；L3/L4 结论维持（函数指针分发静态不可见；无指针/CFG 分析计划）。详见 C 语言状态。

P0-P3 规则注入（2026-08）

• 注入 +31 条规则 / +86 条轨迹 / +13 个检测器 / +11 条防护；10 个 TS 项目 +19 条新检测，6 个 C 仓库 + PostgreSQL 0 误报
• 打破引导死锁：全部 21 个协议命名空间获得规则词汇（今天：27 个命名空间、148 条规则）
• excludePatterns + languages 架构管理误报

→ P0-P3 终报

架构

SDK (src/sdk.ts)           verify() → APPROVED / NEEDS_REVIEW / BLOCKED
  └─ 信任引擎                四维评分 → 决策
       ├─ 策略引擎           企业策略执行（ALLOW/WARN/BLOCK）
       ├─ SSG 校验器         协议状态机验证
       ├─ 调用序列           P4.6 跨函数：入口展开（深度 ≤4）+
       │                     helper 片段抑制
       ├─ 协议检测器         无 IR 语言（C）的正则回退，22 个检测器
       ├─ IR 提取            注册表式：TS（ts-morph）+ Python（ast 模块）
       │                     合并为每项目一份函数 IR；
       │                     源码级标记：污点追踪、import 解析、限定调用链、跨文件模板分析
       ├─ 修复执行器         detect → plan → fix → validate → commit/rollback
       └─ 知识库             31 个域、148 条规则、证据链

接口

| 接口 | 用途 | |------|------| | SDK（verify()） | 开发者一次性调用 API | | CLI（npm run trust） | 命令行信任检查 | | MCP 服务器 | Claude Code 集成（progmune_check、progmune_trust_check） | | GitHub Action | CI/CD 门禁——在 PR 拦截未验证的 AI 代码 | | Trust API | POST /trust/check——机器间接口 |

社区与反馈

你的意见塑造 Progmune。扫码加入用户讨论群（微信 / WhatsApp），或通过 GitHub Issue 提交缺陷报告、功能需求与建议。

双渠道自动回复已上线：微信公众号与 WhatsApp Business 均已接入关键词自动回复机器人（wechat-bot/ 与 whatsapp-bot/）——关注公众号 / 向官方号码发送「帮助」即可查看全部指令，即时互动。

科学基础

Progmune 建立在"LLM 输出是统计表演而非推理"这一前提上——该观点源自 Subbarao Kambhampati 等人的立场论文 "Stop Anthropomorphizing Intermediate Tokens as Reasoning/Thinking Traces!"（arXiv:2504.09762，2025），并在其 ICML 2026 演讲 "On the Role of Verifiers and Thinking Traces in Reasoning Models" 中展开。Progmune 不信任模型对代码的说法，而是用协议状态机、IR 提取与证据链验证程序实际行为。

→ 投资人白皮书 · 信任决策模型

贡献

架构与代码规范见 CLAUDE.md，开发流程见 CONTRIBUTING.md。

高价值贡献方向：

• 框架适配器（Express、Next.js、FastAPI）——#1 产品缺口
• Python 验证规则——向 TypeScript 之外扩展
• 现有检测器与防护规则的缺陷修复

状态

• 运行时管线： 检测 → 解释 → 修复 → 验证（L1–L4）
• 信任引擎： 四维评分 + 二元可解释性门
• MCP 工具： 19 个——progmune_trust_check、progmune_score、progmune_policy_check、progmune_certify 等
• 框架适配器： 12 专用检测器——4 结构级（NestJS/FastAPI/Django/Flask）+ 8 启发式（Express/tRPC/Fastify/Next.js/Koa/Hapi/Gin/Fiber）
• 知识库： 31 个域、148 条协议规则、22 个检测器、26 条防护规则、PLSB 13/13 类别——另加 15 条源码级检测规则（Python）
• 语料： 6+ 仓库 2,500+ 轨迹；盲测基准 100（TS）+ 90（Python）个项目；4 个应用仓库真实验证
• 当前重点： 企业 PoC 验证 + 剩余框架内部边界误报

License

MIT — LICENSE