Correctover/ccs-sdk

**AI Agent 运行时保障 — 拦截 RCE、SSRF、凭证劫持，延迟 < 10μs。**      [](https://pypi.org/project/correctover/) [](https://www.npmjs.com/package/correctover) [](https://doi.org/10.5281/zenodo.21603250) [](https://github.com/punkpeye/awesome-mcp-servers) Correctover 是 **CCS (Correctover Conformance Standard)** 的开源实现——面向 AI Agent 工具调用的运行时安全标准，支持 Python / TypeScript / Go 三种语言。 当 CrewAI、AutoGen、LangGraph 等主流框架使用观察者模式钩子做安全治理时，它们在架构上存在致命缺陷：治理层抛异常 → 框架默认放行 → 工具直接执行。**这不是 bug，是 CWE-636 级别的架构漏洞（CVSS 9.1）。** CCS 用函数装饰器替代钩子。装饰器掌控执行路径——治理失败 = 工具被阻断，永不放行。 ``` 观察者钩子: governance_crash → exception caught → hook_blocked=False → tool EXECUTES ❌ CCS 装饰器: governance_crash → exception caught → tool NEVER CALLED ✅ ``` ## 产品架构 ``` ┌──────────────────────────────────────────────────────────────────┐ │ CCS 标准 (Community) │ │ MCP Agent 运行时安全中立协议 │ ├──────────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │ 认证引擎 │ │ SSRF 防护 │ │ 凭证保护 │ │ 审计链路 │ │ │ │ CKG v2 │ │ DNS Pin │ │ EnvGuard │ │ SHA-256 │ │ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │ │ │ Correctover SDK (Open Source · MIT) │ │ Python · TypeScript · Go — ~5μs P50 overhead │ ├──────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────┐ ┌─────────────────────────────┐ │ │ │ MCP 安全审计服务 │ │ CCS 情报订阅 (月度报告) │ │ │ │ 零风险：未检出免费 │ │ 漏洞预警 + 修复指南 │ │ │ └─────────────────────┘ └─────────────────────────────┘ │ │ │ │ Enterprise Services │ │ 主导标准 + 底层 SDK + 合规审计 │ └──────────────────────────────────────────────────────────────────┘ ``` ## 快速开始 **安装（一行）：** ``` pip install correctover # Python npm install correctover # TypeScript go get github.com/Correctover/ccs-sdk/go # Go ``` **3 行代码，给工具加上安全治理：** ``` from ccs import govern @govern(policy="default") def my_tool(args: dict) -> str: return "result" # 治理评估在函数执行前发生 # 拒绝 → PermissionError，函数永远不会执行 ``` ## 它做了什么 - **Fail-Closed 治理引擎。** 框架钩子是 fail-open 的（异常=放行），CCS 装饰器是 fail-closed 的（异常=阻断）。这是一个架构级的差异，不是配置问题。 - **6 种内置 Guardrail Provider。** CKG 认证（6 种谓词）、EnvProtection（阻断 .env 读写，CVE-2026-12957）、ToolList 白名单/黑名单、Composite 策略组合、MCP 配置预检扫描（CVE-2026-42271/12957/25536）。 - **框架无关的适配器。** 已验证：CrewAI ≥0.1.0、AutoGen ≥0.7.0、LangGraph ≥0.2.0。一行 `adapter.install()` 拦截所有工具调用。 - **加密审计链路。** 每个决策都是 SHA-256 内容寻址的，可独立验证、不可篡改。启用审计对性能无可观测影响。 - **MCP 安全扫描器。** 预检扫描 MCP 配置文件，发现 SSRF、凭证泄露、路径遍历等已知漏洞模式。 ## 完整示例：组合安全策略 ``` from ccs import ( CKGGuardrailProvider, EnvProtectionProvider, CompositeGuardrailProvider, AuditTrail, make_guardrail_hook, ToolCallContext, ) # 组合策略：CKG 认证 AND .env 保护 ckg = CKGGuardrailProvider("ckg") env = EnvProtectionProvider("env-prot") composite = CompositeGuardrailProvider("security", mode="AND", providers=[ckg, env]) # 加密审计 audit = AuditTrail() # 一行集成 secured_tool = make_guardrail_hook(my_tool, composite, audit) # 执行时自带完整授权 + 审计 ctx = ToolCallContext( tool_name="my_tool", arguments={"file": "data.txt"}, agent_id="agent-1", metadata={} ) result = secured_tool(ctx) # 验证决策完整性 receipt = audit.last_receipt() assert receipt.verify() # SHA-256 密码学验证 ``` ## 内置 Guardrail Provider | Provider | 功能 | 参考 CVE | |----------|------|---------| | `CKGGuardrailProvider` | 6 种内置谓词的认证授权 | — | | `EnvProtectionProvider` | 运行时阻断 .env 文件读写 | CVE-2026-12957 | | `ToolListGuardrailProvider` | 工具白名单/黑名单授权 | — | | `CompositeGuardrailProvider` | AND/OR 多策略组合 | — | | `MCPSecurityValidator` | MCP 配置安全预检扫描 | CVE-2026-42271/12957/25536 | ## Fail-Closed 保证 | | Observer Hooks (AGT) | CCS Decorators | |---|---|---| | 集成方式 | 框架捕获钩子异常 | 装饰器掌控执行路径 | | 治理崩溃时 | `hook_blocked` 保持 `False` → 工具执行 | 异常传播 → 工具永不调用 | | 失败模式 | **FAIL-OPEN** ❌ | **FAIL-CLOSED** ✅ | | CWE | CWE-636 (Not Failing Securely) | 结构性免疫 | ## 框架适配器 ``` # CrewAI from ccs.adapters import crewai_adapter crewai_adapter.install() # 全局 patch BaseTool.run # AutoGen (async) from ccs.adapters import autogen_adapter autogen_adapter.install() # patch FunctionTool.run # LangGraph / LangChain from ccs.adapters import langgraph_adapter langgraph_adapter.install() # patch LCBaseTool.run ``` | 框架 | 版本要求 | 拦截点 | 模式 | |------|---------|--------|------| | CrewAI | ≥ 0.1.0 | `BaseTool.run()` | sync | | AutoGen | ≥ 0.7.0 | `FunctionTool.run()` | async | | LangGraph | ≥ 0.2.0 | `LCBaseTool.run()` | sync | ## 真实性能数据 基于 50,000 次完整调用路径实测（三轮测试取中位值）： | 指标 | 数值 | 说明 | |------|------|------| | **P50 延迟** | ≈ 7.5μs | 单次工具调用的额外开销 | | **P99 延迟** | ≈ 21μs | 尾部延迟 | | **audit_log 影响** | 无 | 启用审计对 P50 无可观测影响 | 对外口径：**P50 < 10μs / P99 < 25μs** ## 仓库结构 ``` ccs-sdk/ ├── ccs/ # Python SDK │ ├── core.py # 治理运行时 + 装饰器 │ ├── guardrail.py # GuardrailProvider 模块 (v4.1.0) │ ├── adapters.py # CrewAI/AutoGen/LangGraph 适配器 │ └── mcp_server/ # MCP 服务端 (stdio transport) ├── ts/ # TypeScript SDK (npm: correctover) │ └── src/ # core.ts + guardrail.ts + mcp_v2/ ├── go/ # Go SDK │ └── ccs/ # core.go + guardrail.go ├── docs/ # 文档 ├── strict_9test.py # Python 9-test 验证套件 └── pyproject.toml ``` ## 生态项目 | 项目 | 说明 | 状态 | |------|------|------| | [**ccs-sdk**](https://github.com/Correctover/ccs-sdk) | 本仓库 — CCS 标准 Python/TS/Go SDK | ✅ v4.1.0 | | [**correctover.github.io**](https://correctover.com) | 官网 + 服务页 + 博客 | ✅ Live | | [**correctover-scanner**](https://github.com/Correctover/correctover-scanner) | 5 秒 AI Agent 安全审计扫描器 | ✅ Active | | [**mcp-server**](https://github.com/Correctover/mcp-server) | MCP Server — 6 维输出验证 + 自愈 Failover | ✅ Active | | [**standards**](https://github.com/Correctover/standards) | CCS 标准正式文档 + DOI 归档 | ✅ 16 DOI | ## CCS 标准 CCS (Correctover Conformance Standard) 是面向 MCP Agent 运行时安全的中立社区标准。 **核心原则：** - **Fail-Closed** — 治理失败 = 阻断，永不放行 - **内容寻址** — 每个决策可独立验证，不可篡改 - **框架无关** — 装饰器模式，不依赖特定框架的钩子机制 - **零信任** — 默认拒绝，显式授权 标准文档：[10.5281/zenodo.21603250](https://doi.org/10.5281/zenodo.21603250) ## 成熟度 Correctover v4.1.0 是经过三轮 50K 实测验证的生产就绪版本： - 所有性能数据均为实测，标注了复现方法 - 所有漏洞发现均经过真实复现验证 - CCS 标准已通过 Zenodo DOI 正式归档（16 DOI 已确权） - PyPI + npm + Go 三语言 SDK 同步发布 ## License MIT ## 联系方式 **Guigui Wang | Correctover — MCP 可靠性基础设施** - 🌐 [correctover.com](https://correctover.com) - 📧 wangguigui@correctover.com - 🐙 [GitHub](https://github.com/Correctover)

Correctover — AI 可靠性™
_{Agent 运行时安全 · CCS 标准 · MCP 审计}

标签：CISA项目, Python, RASP, TypeScript, 安全插件, 工具调用拦截, 无后门, 日志审计, 逆向工具