MakerChecker

<div align="center"> # MakerChecker ### 面向 AI 代理的开源安全层 默认拒绝执行、人工审批和加密签名审计日志 — 确保您的 AI 代理仅运行被授权的任务，并且**无法自主批准其自身的工作**。 [](https://github.com/sammysltd/makerchecker/actions/workflows/ci.yml) [](https://github.com/sammysltd/makerchecker/releases/latest) [](LICENSING.md) [](https://github.com/sammysltd/makerchecker) **[官网](https://makerchecker.ai) · [在线演示](https://makerchecker.ai/demo/) · [`mc scan`](packages/scan) · [文档](docs/)** </div> 您的 AI 代理可以在现有的框架中（LangChain、Claude SDK、CrewAI）继续运行。MakerChecker 作为一个检查点位于每个工具调用的前面，作为一个签名账本位于后面：AI 代理仅能通过**角色**进行操作，仅能运行被**授权**的技能，不能超过其限制，并且不能批准自己的工作。 --- ## 快速入门 ### 1 — 扫描您的代码 发现您的 AI 代理已经可以独立执行的操作，并按风险分类。无需安装，数据不会离开您的机器： ```bash npx @makerchecker/scan . ``` 它会标记每种可能造成后果的操作 — 删除数据、转移资金、运行 shell 命令、泄露机密 — 并将每种操作与类似的真实事件进行比对，如果需要，还可以为您编写管理代码 `--fix`。 → [`packages/scan`](packages/scan/README.md) ### 2 — 确保其行为 导入控制并封装任何工具。AI 代理现在只能运行其角色被授权的操作 — 未被授权的调用在执行前会被拒绝： ```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") // AI 代理未被授权 — 默认拒绝 .defineAgent("trader", "agent"); // 封装您的工具一次。现在 AI 代理在结构上无法触发它。 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" } ``` 高风险技能被分配到一个**独立**的角色，因此 AI 代理永远无法批准自己的工作 — 每个决定，无论是否被允许，都会被记录到一个签名审计日志中。 → [`packages/embedded`](packages/embedded/README.md) ### 3 — 与审计人员合作？ 步骤 2 已经写入签名日志。当审计人员需要一个持久的、可查询的、防篡改的记录 — 以及人工审批收件箱和审查控制台 — 时，运行自托管服务器： ```bash docker compose up ``` 每个决定都是使用 Ed25519 签名并进行哈希链式存储的：更改任何行，验证就会失败。导出一个包，任何人都可以离线验证 — 无需数据库，也无需信任生成该包的过程。 → [下面的完整服务器设置](#-自托管服务器可选) > **这三个独立的包** — [`mc scan`](packages/scan)、[`@makerchecker/embedded`](packages/embedded) 和 [服务器](packages/server) — 强制执行相同的控制并写入相同的签名审计格式。您可以单独采用其中任何一个。 --- ## 受控用例 AI 代理在人为门槛下执行重要工作的可运行示例： - **药物警戒案例处理** — AI 代理对不良事件报告进行分类，但医疗审查员在加速的 15 天监管报告发送前进行签名。 [examples/pv-icsr-processing](examples/pv-icsr-processing/README.md) - **医疗器械（MDR）投诉分类** — 监管官员在生成草稿报告之前在门槛下决定报告性。 [examples/mdr-reportability-triage](examples/mdr-reportability-triage/README.md) - **肿瘤患者访问** — AI 代理处理受益匹配，但被阻止在没有专家签名的情况下提交共付注册。 [examples/oncology-patient-access](examples/oncology-patient-access/README.md) - **每日现金核对** — 财务 AI 代理核对交易，但在异常门槛下被锁定，直到现金官员签 off。 [examples/daily-cash-reconciliation](examples/daily-cash-reconciliation/README.md) --- ## 与您的框架集成 为现有的工具提供即插即用的连接器： - **LangChain** → [`packages/connector-langchain`](packages/connector-langchain/README.md) - **Claude Agent SDK** → [`packages/connector-claude-agent`](packages/connector-claude-agent/README.md) - **TypeScript / Python SDKs** → [`packages/sdk`](packages/sdk/README.md) · [`packages/sdk-python`](packages/sdk-python/README.md) · 当您运行服务器时，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", // 评估角色授权的 AI 代理 "txn-match@1", // skillRef: 名称@版本 (input) => matchTxns(input), ); await match({ statement, ledger }); // 如果被拒绝，则抛出 GovernanceDeniedError await client.proxy.closeSession(session.id); ``` --- ## 自托管服务器（可选） 当您需要跨多个 AI 代理进行集中控制、人工审批收件箱和审查控制台时，运行完整的网关。`docker compose up` 启动 Postgres、localhost:3000 上的服务器和一个已播种的演示，打印两个 API 密钥 — 一个 **管理员密钥** （您的 AI 代理验证运行）和一个 **官员密钥** （人类审查员批准受控操作）。 已播种的药物警戒流程在医疗审查门槛下停止，请求者被拒绝为其自己的审批者： ```bash export H='authorization: Bearer mk_...' # 管理员密钥 export OFFICER='authorization: Bearer mk_...' # 官员密钥 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/<id>/decision -H "$H" -H 'content-type: application/json' \ -d '{"decision":"approved","reason":"self-approval attempt"}' # 单独的官员签名；现在操作继续进行 curl -X POST localhost:3000/api/approvals/<id>/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](docs/quickstart.md)。 --- ## 可验证的审计日志 每个决定和工具调用都提交到一个哈希链式日志中 — 每个事件都是一个 SHA-256 哈希值，基于 RFC 8785 规范的 JSON，通过 `prev_hash` 从创世区块开始，并使用 Ed25519 签名。更改任何行，验证就会失败。任何人都可以离线验证导出的包 — 无需数据库，也无需信任生成该包的过程： ```bash npx @makerchecker/proof-verifier verify bundle.json ``` 规范：[docs/audit-spec.md](docs/audit-spec.md)。 --- ## 包 | 包 | 许可证 | 描述 | |---|---|---| | [`packages/scan`](packages/scan) | Apache-2.0 | `mc scan` — 发现并分类您的 AI 代理可以执行的操作。 | | [`packages/embedded`](packages/embedded) | Apache-2.0 | 可导入的强制执行原语 — 代码中的治理。 | | [`packages/proof-verifier`](packages/proof-verifier) | Apache-2.0 | 独立验证签名审计包的离线工具。 | | [`packages/sdk`](packages/sdk) | Apache-2.0 | TypeScript 客户端 + 服务器的 `governedTool`。 | | [`packages/sdk-python`](packages/sdk-python) | Apache-2.0 | Python 客户端 + `governed_tool`。 | | [`packages/connector-langchain`](packages/connector-langchain) | Apache-2.0 | 控制 LangChain 工具。 | | [`packages/connector-claude-agent`](packages/connector-claude-agent) | Apache-2.0 | 控制 Claude Agent SDK 工具。 | | [`packages/server`](packages/server) | AGPL-3.0 | 自托管 Fastify + Postgres 网关、流程引擎、审计写入器。 | | [`packages/web`](packages/web) | AGPL-3.0 | React 控制台：审批收件箱、运行日志、注册表。 | | [`packages/shared`](packages/shared) | AGPL-3.0 | 领域类型、规范 JSON、加密实用程序。 | --- ## 许可证和贡献 - **服务器、Web、共享：** [AGPL-3.0](LICENSE)。 - **`mc scan`、`embedded`、SDK、连接器、示例：** [Apache-2.0](LICENSING.md) — 可以在封闭源代码的 AI 代理中自由嵌入。 - 商业（非 copyleft）许可：hello@makerchecker.ai。 贡献：[CONTRIBUTING.md](CONTRIBUTING.md) · 安全：[SECURITY.md](SECURITY.md) · 行为准则：[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)