Skip to main content
Glama
lz-123123

Cerberus

by lz-123123
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Cerberus：面向 AI Agent 的链上支付防火墙

Cerberus 是面向 AI Agent 支付场景的安全中间件。每笔支付依次经过身份验证、风险控制和执行授权三道闸门；MCP 提供灵活的链下判断，链上 Policy 与 PaymentGateway 提供不可绕过、可审计的安全底线。

项目亮点

  • 三层防火墙：Identity → Risk Control → Execution

  • Agent Registry：查看已注册 Agent，并可暂停 / 激活（作用于 Layer 1）

  • 链上 Policy：白名单和单笔金额上限由智能合约强制执行

  • 用户钱包结算：防火墙通过后调用 PaymentGateway.pay()；payByDelegate 已在合约中预留，不是当前 Demo 默认路径

  • MCP Server：可接入真实 Agent 客户端

  • 可验证审计：保存逐层结果、哈希链和链上支付事件

Related MCP server: fidacy-mcp

架构

Payment Request
      │
      ▼
┌─────────────────────────────────────┐
│ Layer 1：Identity                    │
│ Agent 注册、钱包绑定、Challenge      │
│ @cerberus/mcp-identity               │
├─────────────────────────────────────┤
│ Layer 2：Risk Control                │
│ 黑名单、金额、频率、Prompt Injection │
│ @cerberus/mcp-payment-guard          │
├─────────────────────────────────────┤
│ Layer 3：Execution                   │
│ 预算、链上 Policy、钱包签名 pay()    │
│ @cerberus/mcp-execution              │
└─────────────────────────────────────┘
      │
      ▼
 Approved / Blocked + Audit Log + Events

页面功能

  • Overview：五种场景、三层结果和安全指标

  • Custom Payment：从 Agent Registry 下拉选择 Agent，创建自定义支付

  • Agent Registry：查看 Agent、暂停/激活（Layer 1）；新注册仅写入链下 Store

  • Policy Center：查看预算、风险策略和链上白名单

  • Audit Log：查看支付决定、哈希和逐层 Trace

新增内容

Agent Registry

GET    /api/agents
POST   /api/agents
GET    /api/agents/:agentId
PUT    /api/agents/:agentId
DELETE /api/agents/:agentId

注册示例：

{
  "agentId": "agent-research-002",
  "name": "Research Agent",
  "walletAddress": "0x5555555555555555555555555555555555555555",
  "publicKey": "ed25519:demo-key"
}

当前 Registry 支持动态列表、详情、活动统计、新 Agent 注册（链下 Layer 1）以及 Suspend / Activate。Custom Payment 的 agentId 从 Registry 动态生成下拉框。

Policy Center 提供 Authorize merchant（仅 owner）：调用链上 Policy.setWhitelist。默认商家 0x5555…5555，不会改掉场景 3 使用的 0x3333…。

合约已预留委托支付（setAgentDelegate / payByDelegate），便于后续「用户出钱、Agent 签名」。当前 Demo 默认路径仍是用户钱包调用 PaymentGateway.pay()，避免决赛现场多一次签名、双钱包未接好导致失败。

Agent 注册与钱包流程

当前 Demo 注册

输入 Agent ID / 名称 / 钱包地址
          ↓
POST /api/agents → 内存 Agent Store
          ↓
Agent 出现在 Registry
          ↓
查看、暂停、激活

页面注册只写入内存 Store，用于 Layer 1 演示。链上付款请使用部署时登记的 agent-shopping-001。

委托支付（Mode B）的合约接口见 docs/AGENT_REGISTRY_AND_DELEGATION_GUIDE.md，不是决赛默认演示路径。

API

GET    /api/scenarios
GET    /api/evaluate?scenario=normal-payment
POST   /api/evaluate
GET    /api/audit
GET    /api/policy
PUT    /api/policy
DELETE /api/policy
GET    /api/chain

启动方法：模拟模式

要求 Node.js 18+：

npm install
npm run demo

打开 http://localhost:3000。没有链上环境变量时显示 Simulated。

启动方法：本地链上模式

终端 1：

npm run node

终端 2：

npm run compile
npm run deploy:local

终端 3：

npm run demo

部署会生成 apps/demo/.env.local 和 apps/demo/public/deployed-addresses.json。

MetaMask 网络：

Network name: Localhost 8545
RPC URL: http://127.0.0.1:8545
Chain ID: 31337
Currency symbol: ETH

Hardhat Account #0 私钥：

0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

测试步骤：导入 Account #0 → 切换到 Localhost 8545 → Overview 运行 4 · Successful Payment → Connect Wallet → 确认 approve 和 PaymentGateway.pay() → 可选：Agent Registry 暂停 Agent 展示 Layer 1，或打开 Audit Log 查看逐层结果。

Hardhat 节点重启会清空状态，需要重新部署。

Base Sepolia 测试网

准备专用测试钱包和测试 ETH：

$env:PRIVATE_KEY="0x你的测试钱包私钥"
$env:RPC_URL="https://sepolia.base.org"
npm run deploy:base-sepolia
npm run demo

MetaMask：Base Sepolia、RPC https://sepolia.base.org、Chain ID 84532、Explorer https://sepolia.basescan.org。

项目中的 MockUSDC 是测试代币，不是真实 USDC。不要将测试私钥用于主网或提交到 Git。

MCP Server

npm run mcp:identity
npm run mcp:guard
npm run mcp:execution

工具包括：verify_agent、issue_challenge、screen_payment、validate_on_chain_policy、record_payment、get_policy。

项目结构

cerberus/
├── apps/demo/                  # Next.js 控制台、API、wagmi 钱包连接
├── packages/core/              # 三层防火墙、Store、viem 链上客户端
├── packages/mcp-identity/      # 身份 MCP Server
├── packages/mcp-payment-guard/ # 风控 MCP Server
├── packages/mcp-execution/     # 执行 MCP Server
├── packages/contracts/         # Policy、Gateway、Registry、MockUSDC
└── docs/                       # 项目指南和 Agent Registry 文档

安全边界

  • 本项目用于本地链和测试网 Demo，不是生产资金系统。

  • 生产环境应使用 EIP-712、真实公钥验证、nonce 过期和数据库持久化。

  • Agent 密钥应使用 KMS、HSM、MPC 或 Session Key 管理。

  • Hardhat 私钥是公开测试私钥，只能用于本地链。

许可证

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • fidacy-mcp

    lucaslubi
    A
    license
    A
    quality
    A
    maintenance
    Payment firewall for AI agents: a signed, independently verifiable verdict on every money-moving action. Blocks wrong/lookalike payee, over-cap, and duplicate-invoice (BEC) fraud before money moves — anyone can verify a verdict against the public JWKS. Free, local-first, non-custodial.
    12
    1
    Apache 2.0

  • Guardian MCP

    izmiradami
    A
    license
    Not graded
    quality
    C
    maintenance
    Security layer for AI agents that evaluates transaction intents and returns verdicts (ALLOW/WARN/DENY) using deterministic rules, on-chain checks, and simulation.
    4 npm
    MIT
  • EVIDIQ Aegis by evidiq

    EVIDIQ Aegisofficial

    evidiq
    A
    license
    Not graded
    quality
    B
    maintenance
    Autonomous financial policy engine and budget guard for AI agent fleets. It verifies payment payloads, velocity caps, escrow release terms, and slippage inflation, returning risk verdicts and signed attestations.
    1
    MIT