makerchecker/MakerChecker 来源: https://github.com/makerchecker/MakerChecker # 🛡️ MakerChecker ### 面向AI代理的开源安全层。默认拒绝执行、人工审批和加密签名审计追踪——确保你的代理仅运行被授权的操作，并且可证明无法自我批准。 CI (https://github.com/sammysltd/makerchecker/actions/workflows/ci.yml) Release (https://github.com/sammysltd/makerchecker/releases/latest) 许可证 Stars (https://github.com/sammysltd/makerchecker) 网站 (https://makerchecker.ai) · 在线演示 (https://makerchecker.ai/demo/) · mc scan · 文档 你的代理可继续在其现有框架（LangChain、Claude SDK、CrewAI）中运行。MakerChecker 位于每一次工具调用的前方作为检查点，并位于其后作为签名账本：代理仅能通过角色行动，仅能运行已授权的技能，不能超出其限制，且不能自我批准工作。 — ## 🚀 快速上手 ### 1 — 扫描你的代码 发现你的代理本身能做什么，并按风险分类。无需安装，信息不会离开你的机器： bash npx @makerchecker/scan . 它会标出所有严重后果的操作——删除数据、转移资金、运行 shell 命令、窃取秘密——将其对应到真实的安全事件名称，并且可以通过 --fix 为你编写治理代码。 → packages/scan ### 2 — 保证其行为 导入控制模块并包装任意工具。代理现在只能运行其角色被授权的操作——不允许的调用会在执行前被拒绝： bash npm i @makerchecker/embedded ts import { createGovernor, GovernanceDeniedError } from "@makerchecker/embedded"; const gov = createGovernor() .defineSkill("place-order@1", { riskTier: "high" }) .defineRole("agent") .defineRole("risk-desk") .grant("risk-desk", "place-order@1") // 代理未获授权 — 默认拒绝 .defineAgent("trader", "agent"); // 包装工具一次。现在代理在结构上无法触发它。 const placeOrder = gov.governedTool("trader", "place-order@1", (order) => broker.submit(order)); try { await placeOrder({ symbol: "BTC", qty: 10 }); } catch (err) { if (err instanceof GovernanceDeniedError) console.log(err.code); // "skill_not_granted" } 高风险技能被分配给不同的角色，因此代理永远不能自我批准操作——每一个决策（允许或拒绝）都会被提交到签名审计日志。 → packages/embedded ### 3 — 需要与审计人员协作？ 步骤2已写入签名日志。当审计人员需要持久、可查询、防篡改的记录——再加上一个人工审批收件箱和审查控制台——可运行自托管服务器： bash docker compose up 每个决策都经过 Ed25519 签名并哈希链式连接：修改任何一行，验证就会失败。导出一个包，任何人都可离线验证——无需数据库，也无需信任产生该包的过程。 → 下方完整服务器设置 > 这三个是独立的包 —— mc scan、@makerchecker/embedded 和 服务器——它们强制执行相同的控制并写入相同的签名审计格式。可单独采用任何一个。 — ## 🔬 受治理的使用案例 在人工审批后运行的代理执行重要任务的示例： - 药物警戒个例安全性报告处理——代理分类不良事件报告，但在加速的15天监管报告发送前需医学审核员签名。 examples/pv-icsr-processing - 医疗器械（MDR）投诉分类——监管官员在草拟报告前在审批门后决定可报告性。 examples/mdr-reportability-triage - 肿瘤患者准入——代理处理福利匹配，但在未经专家签名的情况下不能提交共付额注册。 examples/oncology-patient-access - 每日现金对账——财务代理对账交易，但在异常门处锁定直至现金官员签字。 examples/daily-cash-reconciliation — ## 🔌 集成到你的框架 即插即用的连接器可治理你已有的工具： - LangChain → packages/connector-langchain - Claude Agent SDK → packages/connector-claude-agent - TypeScript / Python SDK → packages/sdk · packages/sdk-python 当你运行服务器时，SDK 的 governedTool 将每次调用通过代理会话路由，以实现集中式授权和记录： ts import { createClient, governedTool, GovernanceDeniedError } from "@makerchecker/sdk"; const client = createClient({ baseUrl: "http://localhost:3000", apiKey: "mk_..." }); const { session } = await client.proxy.openSession({ label: "recon-run" }); const match = governedTool( client, session.id, "recon-preparer", // 评估其角色授权的代理 "txn-match@1", // skillRef: name@版本 (input) => matchTxns(input), ); await match({ statement, ledger }); // 若被拒绝则抛出 GovernanceDeniedError await client.proxy.closeSession(session.id); — ## 🖥️ 自托管服务器（可选） 当你需要跨多个代理进行集中式执行、人工审批收件箱和审查控制台时，运行完整网关。docker compose up 将启动 Postgres、localhost:3000 上的服务器以及一个预填充的演示，并打印两个 API 密钥——管理员密钥（你的代理用于验证运行）和官员密钥（人类审核员用于批准有门控的操作）。 预填充的药物警戒流程会停在一个医学审核门处，请求者被拒绝成为自己的审批者： bash export H='authorization: Bearer mk_...' # admin key export OFFICER='authorization: Bearer mk_...' # officer key curl -X POST localhost:3000/api/flows/pv-icsr-processing/runs -H "$H" -H 'content-type: application/json' -d '{}' curl localhost:3000/api/approvals -H "$H" # 请求者不能批准自己的运行 — 返回403拒绝 curl -X POST localhost:3000/api/approvals//decision -H "$H" -H 'content-type: application/json' \ -d '{"decision":"approved","reason":"self-approval attempt"}' # 独立的官员签名；只有此时操作才继续 curl -X POST localhost:3000/api/approvals//decision -H "$OFFICER" -H 'content-type: application/json' \ -d '{"decision":"approved","reason":"Seriousness confirmed; file 15-day expedited ICSRs."}' curl localhost:3000/api/audit/verify -H "$H" 完整设置、Kubernetes/Helm 以及使用实时模型运行： docs/quickstart.md。 — ## 🔒 可验证的审计追踪 每个决策和工具调用都提交到哈希链式日志——每个事件是经过 RFC 8785 规范化 JSON 的 SHA-256 哈希，通过创世以来的 prev_hash 链接，并使用 Ed25519 签名。修改任何一行，验证就会失效。任何人都可以离线验证导出的包——无需数据库，也无需信任产生该包的过程： bash npx @makerchecker/proof-verifier verify bundle.json 规范：docs/audit-spec.md。 — ## 🗂️ 包 | 包 | 许可证 | 说明 | |—|—|—| | packages/scan | Apache-2.0 | mc scan——发现并分类你的代理能做什么。 | | packages/embedded | Apache-2.0 | 可导入的强制执行原语——在你的代码中实现治理。 | | packages/proof-verifier | Apache-2.0 | 离线独立验证签名的审计包。 | | packages/sdk | Apache-2.0 | TypeScript 客户端 + 用于服务器的 governedTool。 | | packages/sdk-python | Apache-2.0 | Python 客户端 + governed_tool。 | | packages/connector-langchain | Apache-2.0 | 治理 LangChain 工具。 | | packages/connector-claude-agent | Apache-2.0 | 治理 Claude Agent SDK 工具。 | | packages/server | AGPL-3.0 | 自托管 Fastify + Postgres 网关、流程引擎、审计写入器。 | | packages/web | AGPL-3.0 | React 控制台：审批收件箱、运行日志、注册表。 | | packages/shared | AGPL-3.0 | 领域类型、规范化 JSON、加密工具。 | — ## 📄 许可证与贡献 - 服务器、Web、共享: AGPL-3.0。 - mc scan、embedded、SDK、连接器、示例: Apache-2.0——可自由嵌入闭源代理。 - 商业（非 copyleft）许可：[email protected]。 贡献：CONTRIBUTING.md · 安全：SECURITY.md · 行为准则：CODE_OF_CONDUCT.md