cullis-security/cullis

GitHub: cullis-security/cullis

一个面向 AI 代理的联邦信任基础设施，提供基于 x509 与 DPoP 的身份认证、端到端加密与策略审计。

Stars: 0 | Forks: 0

Cullis
Zero-trust identity and authorization for AI agent-to-agent communication

## 状态这是一个在公开环境中构建的**研究与学习项目**。当前的目标包括：（1）探索跨组织 AI 代理的身份认证、联合授权和防篡改审计；（2）将现有标准（x509、SPIFFE、DPoP、OAuth 2.0、OPA）组合成适用于代理时代的连贯架构；（3）让安全研究人员和工作负载身份社区审查设计。实际意义如下： - **演示（`./deploy_demo.sh`）** 是唯一由自动化测试覆盖的端到端路径。请使用它来探索架构。 - **Helm 图表** 处于探索阶段 —— 暂无 SLA、升级路径或迁移方案。 - **尚未进行安全审查。** 代码库已经过内部审计轮次，但从未接受过独立的第三方审查。 - **架构和 API 可能变更。** 在 1.0 版本之前，不提供语义化版本保证。如果你想**试用**，演示是合适的入口。如果你想**审查或破坏它**，请参阅 [SECURITY.md](SECURITY.md)。如果你想**为真实工作负载部署** —— 请不要这么做，至少现在不行。当你的 AI 代理与另一家公司的 AI 代理协商时 —— 谁来验证身份？谁来执行策略？谁来审计发生了什么？ Cullis 是一个**联邦信任代理**，为 AI 代理而构建：基于 x509 PKI 的身份、绑定令牌的 DPoP、端到端加密消息、默认拒绝策略，以及加密审计账本。为代理到代理时代量身定制的基础设施。 ## 快速开始启动完整架构（代理 + 2 个 MCP 代理 + 2 个组织中的 2 个代理），路由一条跨组织端到端加密消息，然后拆除一切。端到端大约一分钟。 ### 你需要什么 | 要求 | 原因 | |------|------| | **Docker Engine** 并安装 **Compose v2** 插件 | 演示会运行五个容器（代理、2 个 MCP 代理、PostgreSQL、Redis） | | **主机上的 Python 3.10+** | 编排器、发送器和检查脚本在主机上运行，而非容器内 | | **`httpx`** 与 **`cryptography`** Python 包 | 主机侧依赖（编排器 + 代理 CA 生成） | | 空闲 TCP 端口 **8800**、**9800**、**9801** | 若被占用，脚本会快速报错并提示 | | 约 2 GB 磁盘空间 + 外网连接 | 首次运行会拉取代理与代理镜像 | 支持的主机：Linux 原生、macOS（Docker Desktop / OrbStack / Colima）、Windows（通过 WSL2 + Docker Desktop）。无需 Nix（Nix 仅用于维护者的开发循环）。 ### 运行它 ``` git clone https://github.com/cullis-security/cullis cd cullis python3 -m venv .venv .venv/bin/pip install httpx cryptography ./deploy_demo.sh up ./deploy_demo.sh send ``` 该包装器会自动检测 `.venv/bin/python`，无需手动激活。从零到运行中的联邦信任网络仅需六条命令，首次运行包含完整的 Docker 构建。请参阅 [`scripts/demo/README.md`](scripts/demo/README.md) 获取完整引导（仪表盘、自定义、故障排查）。

Ubuntu Server 24.04（全新安装）—— 额外步骤

Ubuntu Server 默认不提供 `pip` 或 `venv`，也没有 `python` 别名（只有 `python3`）。请在以上命令前运行： ``` sudo apt update && sudo apt install -y python3-pip python3-venv ```

https://github.com/user-attachments/assets/d838ce65-c0cc-4d12-95de-12cb8a37325e ## 两个组件 Cullis 以两个独立、可独立部署的组件形式发布： | | **Cullis Broker** | **Cullis MCP Proxy** | |---|---|---| | **角色** | 网络控制平面 | 组织数据平面 | | **部署位置** | 网络运营商基础设施 | 每个参与组织的网络 | | **管理内容** | 身份、路由、策略联邦、审计账本 | 代理证书、代理上行链路、工具执行 | | **仪表盘** | 网络管理员（组织加入、审批、审计） | 组织管理员（注册、创建代理、管理工具） | | **默认端口** | 8000（HTTP）/ 8443（HTTPS） | 9100 | ## 架构 ``` flowchart TB subgraph org_a["🏢 Organization A"] direction TB A1["🤖 Buyer Agent"] A2["🤖 Inventory Agent"] VA["🔐 Vault A"] PA["⚡ MCP Proxy A
_{auto PKI · cert issuance · API key auth}"] A1 -->|"① API Key"| PA A2 -->|"① API Key"| PA VA -.->|"agent keys"| PA end subgraph broker["🌐 Cullis Broker — self-hosted"] direction TB AUTH["② Verify x509 chain"] DPOP["③ Validate DPoP"] POL["④ Query policies"] FWD["⑥ Forward E2E"] AUTH --> DPOP --> POL --> FWD end subgraph org_b["🏢 Organization B"] direction TB B1["🤖 Supplier Agent"] T1["🔧 Tool: ERP"] VB["🔐 Vault B"] PB["⚡ MCP Proxy B
_{auto PKI · cert issuance · API key auth}"] PB -->|"⑦ API Key"| B1 PB -->|"⑦ tool call"| T1 VB -.->|"agent keys"| PB end PA ==>|"② x509 + DPoP + E2E"| broker broker ==>|"⑥ E2E encrypted"| PB broker ---|"④ policy query"| PDPA["📋 Org A PDP
_{webhook / OPA}"] broker ---|"④ policy query"| PDPB["📋 Org B PDP
_{webhook / OPA}"] PDPA -->|"⑤ allow ✓"| DUAL{"Both must
allow"} PDPB -->|"⑤ allow ✓"| DUAL classDef broker fill:#4f46e5,stroke:#6366f1,color:#fff,font-weight:bold classDef proxy fill:#0d9488,stroke:#14b8a6,color:#fff,font-weight:bold classDef agent fill:#1e293b,stroke:#334155,color:#e2e8f0 classDef pdp fill:#92400e,stroke:#d97706,color:#fef3c7 classDef vault fill:#1e1b4b,stroke:#4338ca,color:#c7d2fe classDef decision fill:#b45309,stroke:#f59e0b,color:#fff class AUTH,DPOP,POL,FWD broker class PA,PB proxy class A1,A2,B1,T1 agent class PDPA,PDPB pdp class VA,VB vault class DUAL decision ``` 1. **代理 → 代理** — 代理通过本地 API 密钥（`X-API-Key`）进行身份验证 2. **代理 → Broker** — 代理使用 x509 + DPoP 签名并端到端加密，代理从不接触密钥 3. **Broker 验证** — x509 链、DPoP 证明持有、证书指纹固定 4. **策略查询** — Broker 向双方组织的 PDP（Webhook 或 OPA）发起请求 5. **双重授权** — 仅当 **双方** 组织均返回 `allow` 时会话才继续（默认拒绝） 6. **端到端转发** — Broker 转发其无法读取的加密消息（零知识） 7. **代理 → 代理 / 工具** — 接收方代理解密并交付 ## 核心特性 - **3 层 x509 PKI + SPIFFE 工作负载身份** — Broker CA → 组织 CA → 代理证书（包含 `spiffe://信任域/组织/代理` 的 SAN） - **DPoP 令牌绑定（RFC 9449）** — 每个令牌绑定到临时 EC P-256 密钥，服务器使用 nonce 轮换 - **端到端加密** — AES-256-GCM 载荷、RSA-OAEP-SHA256 密钥封装、双层 RSA-PSS 签名 - **联邦双组织策略** — PDP 可为 Webhook 或 OPA，默认拒绝，双方必须允许 - **加密审计账本** — 仅追加、SHA-256 哈希链、篡改检测、支持 NDJSON / CSV 导出 - **自助组织加入** — 邀请令牌、自动生成组织 CA，无需手动 openssl - **OIDC 联邦管理员登录** — 支持 Okta、Azure AD、Google，每个组织可配置独立 IdP - **KMS 后端** — 开发环境使用本地文件系统，生产环境使用 HashiCorp Vault KV v2，支持扩展 - **无需 SaaS，自主托管** ## Python SDK ``` from cullis_sdk.client import CullisClient client = CullisClient("https://broker.example.com") client.login("buyer", "acme", "agent.pem", "agent-key.pem") agents = client.discover(capabilities=["supply"]) session_id = client.open_session("widgets::supplier", "widgets", ["supply"]) client.send(session_id, "acme::buyer", {"order": "100 units"}, "widgets::supplier") ``` TypeScript SDK 位于 [`sdk-ts/`](sdk-ts/)。一个提供 10 个 Cullis 工具的 MCP 服务器（使任何 MCP 兼容 LLM 都能成为 Cullis 代理）位于 `cullis_sdk/mcp_server.py`。 ## 项目结构 ``` app/ Broker FastAPI application (auth, registry, broker, dashboard, kms) mcp_proxy/ Org MCP gateway (egress, ingress, dashboard, agent manager) cullis_sdk/ Python SDK + MCP server sdk-ts/ TypeScript SDK alembic/ Broker database migrations tests/ Unit + integration tests; tests/e2e/ holds the full-stack suite scripts/ Ops scripts (generate-env, pg-backup) + scripts/demo/ live demo deploy/ Helm chart for Kubernetes enterprise-kit/ BYOCA guide, OPA policy bundles, monitoring, PDP template docs/ cullis.io site source + ops runbook .github/ CI workflows + issue / PR templates ``` 运行时：Python 3.11 · FastAPI · PostgreSQL 16 · Redis · HashiCorp Vault · cryptography · PyJWT · OpenTelemetry + Jaeger · OPA · Docker · Helm。 ## 贡献请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取开发环境设置、PR 工作流和代码规范。安全漏洞请参考 [SECURITY.md](SECURITY.md) 获取私有报告指南。 ## 联系方式 | | | |---|---| | 常规问题、合作伙伴关系、演示 | **[hello@cullis.io](mailto:hello@cullis.io)** | | 安全漏洞（私有） | **[security@cullis.io](mailto:security@cullis.io)** · 参考 [SECURITY.md](SECURITY.md) | | 错误报告、功能请求 | [GitHub Issues](https://github.com/cullis-security/cullis/issues) | | 讨论、问题、想法 | [GitHub Discussions](https://github.com/cullis-security/cullis/discussions) | ## 许可证 Cullis 采用分许可模型： - **Broker（`app/`）与 MCP 代理（`mcp_proxy/`）** — [功能性源代码许可 1.1，未来 Apache 2.0 许可（FSL-1.1-Apache-2.0）](LICENSE)。允许所有非竞争使用（内部部署、专业服务、研究、修改、分叉）。每个版本发布后自动变为 [Apache 2.0](LICENSE-APACHE-2.0) 许可，两年后生效。 - **Python SDK（`cullis_sdk/`）** — [Apache License 2.0]()。永久宽松授权。 - **TypeScript SDK（`sdk-ts/`）** — [MIT 许可证](sdk-ts/LICENSE)。永久宽松授权。 - **集成模板（`enterprise-kit/`）** — [Apache License 2.0](enterprise-kit/LICENSE)。永久宽松授权。请参阅 [NOTICE](NOTICE) 获取组件级映射及选择理由。

标签：AI代理, Apache 2.0, CI, Docker, DPoP, Helm, JSONLines, OAuth 2.0, OPA, Python, SPIFFE, x509, 不可篡改审计, 加密审计, 可信基础设施, 安全防御评估, 授权, 搜索引擎查询, 无后门, 早期阶段, 测试用例, 用户代理, 研究项目, 联邦授权, 请求拦截, 跨组织, 逆向工具, 零信任, 靶场