malwarebo/hatch

AI工具服务器的基于能力的隔离。 `hatch` 在Linux和macOS上沙箱化MCP（模型上下文协议）服务器， 通过签名清单中声明的策略强制执行每个服务器的网络、文件系统和协议级策略。 它以用户级后台守护进程形式运行（在Linux上由systemd管理、在macOS上由`launchd`管理）；每个服务器的`hatch-shim`进程将每个MCP主机（Claude Desktop、Cursor、Claude Code、Zed、Continue、Windsurf）连接到守护进程生成和管控的沙箱服务器。 威胁模型详见 [`docs/src/concepts/threat-model.md`](docs/src/concepts/threat-model.md)。 ## 架构 ``` %%{init: {"flowchart": {"defaultRenderer": "elk"}}}%% flowchart LR Host[MCP host] subgraph trusted [trusted] direction TB Shim[hatch-shim] Daemon[hatch-daemon] Enforce["Per-process enforcement
Linux: hatch-linux-helper
Landlock + seccomp
macOS: sandbox-exec"] Proxy["SNI proxy
+ DNS allowlist"] end subgraph sandbox [sandbox] Srv[MCP server, untrusted] end Net[Allowlisted hosts only] Host -->|stdio| Shim Shim -->|policy query| Daemon Daemon -->|decision| Shim Daemon -->|spawn| Enforce Enforce -->|exec| Srv Srv -->|stdio| Shim Srv -->|HTTPS| Proxy Srv -->|DNS| Proxy Proxy -->|verified SNI| Net ``` Linux沙箱强制执行机制：用户/挂载/进程/网络命名空间、cgroups v2、在每个服务器网络命名空间内的iptables重定向，以及一个预执行辅助程序（`hatch-linux-helper`），它在移交清单程序前应用Landlock和seccomp。macOS沙箱强制执行机制：`sandbox-exec`配置文件、每个沙箱UID的PF锚点和UID池。 主机发出的每个工具调用都经过shim，它会查询守护进程的编译策略（拒绝列表、glob模式、参数上的CEL规则、响应重编辑过滤器）。沙箱服务器发出的每个网络连接都被强制通过SNI代理和DNS解析器，两者都只允许服务器签名清单中声明的目的地。所有操作都被审计为带有哈希链的JSONL日志。 ## 安装 标记 `vX.Y.Z` 会触发 `.github/workflows/release.yml`，该工作流构建以下构件并附加到 [GitHub 发布页](https://github.com/malwarebo/hatch/releases)： - **Debian / Ubuntu** curl -LO https://github.com/malwarebo/hatch/releases/latest/download/hatch_0.1.0-1_amd64.deb sudo apt install ./hatch_0.1.0-1_amd64.deb - **Fedora / RHEL** sudo dnf install https://github.com/malwarebo/hatch/releases/latest/download/hatch-0.1.0-1.x86_64.rpm - **macOS `.pkg`** 从[最新发布](https://github.com/malwarebo/hatch/releases/latest)下载 并双击安装。当工作流提供Apple开发者凭据时， pkg将被签名和公证，并在以下位置安装launchd代理： `/Library/LaunchAgents/sh.hatch.daemon.plist` 本地构建包： ``` cargo install cargo-deb cargo-generate-rpm cargo build --release cargo deb -p hatch-cli --no-build --no-strip # -> target/debian/hatch_*.deb (cd crates/hatch-cli && cargo generate-rpm) # -> target/generate-rpm/hatch-*.rpm ``` `cargo generate-rpm` 无法通过 `-p` 解析嵌套的工作区成员，因此 请从 `crates/hatch-cli/` 目录内运行。 对于签名的 `.pkg`，请在设置环境变量 `APPLE_DEVELOPER_ID_APPLICATION`、`APPLE_DEVELOPER_ID_INSTALLER` 和 `APPLE_NOTARY_PROFILE` 后运行 `scripts/notarize-macos.sh `。 Linux systemd用户单元位于 [`packaging/systemd/hatch-daemon.service`](packaging/systemd/hatch-daemon.service)； 安装后： ``` systemctl --user daemon-reload systemctl --user enable --now hatch-daemon ``` ## 构建 ``` cargo build --workspace cargo test --workspace ``` 要求：Rust稳定版（1.83+）。 - Linux：需要支持用户命名空间、cgroups v2、seccomp和Landlock的内核（5.13+）。 - macOS：需要macOS 13或更新版本。 ## 运行 无需外部依赖即可对完整流水线进行冒烟测试。`minimal.toml` 在守护进程下运行 `/bin/cat`，演练标准IO路由、审计日志记录和端到端IPC协议： ``` cargo run -p hatch-daemon -- --foreground --state-dir ./.hatch & cargo run -p hatch-cli -- --state-dir ./.hatch status cargo run -p hatch-cli -- manifest validate examples/manifests/minimal.toml cargo run -p hatch-cli -- --state-dir ./.hatch install --file examples/manifests/minimal.toml --allow-unsigned cargo run -p hatch-cli -- --state-dir ./.hatch run minimal --seconds 2 cargo run -p hatch-cli -- --state-dir ./.hatch audit cargo run -p hatch-cli -- --state-dir ./.hatch daemon stop ``` 对于实际的MCP服务器，请安装 `examples/manifests/filesystem.toml`。它将官方 `@modelcontextprotocol/server-filesystem` 的作用域限制在 `$PROJECT_ROOT`。需要Node： ``` cargo run -p hatch-cli -- --state-dir ./.hatch \ install --file examples/manifests/filesystem.toml --allow-unsigned cargo run -p hatch-cli -- --state-dir ./.hatch run filesystem --seconds 5 ``` 值得了解的守护进程标志： - `--enable-proxy` — 启动SNI代理和DNS允许列表解析器。 - `--real-sandbox` — 使用Linux或macOS后端，而不是直通存根。 - `--metrics-addr 127.0.0.1:9876` — 暴露Prometheus指标。 ## 命令行接口 ``` hatch status daemon health hatch list [--running] installed manifests / running servers hatch ps running servers hatch run NAME spawn an installed manifest hatch stop TARGET stop a running server hatch inspect TARGET show a running server's compiled policy hatch install --file PATH install a local manifest hatch uninstall NAME hatch approve ID [--remember once|session|manifest-version] hatch deny ID hatch audit [--tui] tail / interactive audit viewer hatch observe -- CMD ... run with syscall tracing, emit candidate manifest hatch manifest validate PATH hatch manifest explain PATH hatch manifest show NAME hatch manifest diff NAME PATH hatch manifest edit NAME open in $EDITOR, validate, reinstall hatch config status [--workspace] hatch config sync [--host H] [--force] [--workspace | --workspace-path DIR] hatch config unsync [--host H] [--workspace | --workspace-path DIR] hatch registry install-bundle PATH hatch registry list hatch registry verify NAME hatch debug audit-verify [--path FILE | --all] verify the audit hash chain hatch debug profile NAME render the compiled platform profile hatch daemon status | stop hatch doctor hatch version ``` `--format json` 切换结构化输出。退出代码：0表示成功，11表示未找到，12表示清单无效，13表示签名失败，14表示批准超时，15表示生成失败。 ## 清单 ``` schema_version = "1.0" name = "github" version = "1.2.0" description = "Official GitHub MCP server" [command] program = "npx" args = ["-y", "@modelcontextprotocol/server-github"] [network] allow_https = ["api.github.com", "*.githubusercontent.com"] allow_dns = ["api.github.com", "*.githubusercontent.com"] [filesystem] read = [] write = [] tmpfs = ["/tmp"] [env] passthrough = ["GITHUB_TOKEN"] [exec] allow_subprocess = false [resources] memory_mb = 512 cpu_percent = 50 pids_max = 50 nofile = 256 tool_call_timeout_seconds = 60 [tool_policy] require_approval = ["delete_*", "admin_*"] [[tool_policy.rules]] tool = "create_or_update_file" when = "args.branch in ['main', 'master', 'production']" action = "require_approval" [platform.linux] seccomp_preset = "strict" landlock = true [platform.macos] endpoint_security = false ``` 完整模式参考：[`docs/src/reference/manifest-schema.md`](docs/src/reference/manifest-schema.md) 和 [`manifests/schema/manifest.schema.json`](manifests/schema/manifest.schema.json)。 ## 待办事项 需要外部操作的项目： - Apple开发者注册、签名证书和公证工具密钥链配置。`scripts/notarize-macos.sh` 和 `scripts/release.sh` 中的脚本会从环境变量或GitHub Action机密中读取 `APPLE_DEVELOPER_ID_APPLICATION`、`APPLE_DEVELOPER_ID_INSTALLER` 和 `APPLE_NOTARY_PROFILE`。 - 端点安全权限申请。macOS后端已准备好针对授权版本的功能标志架构。 - `manifests.hatch.sh` 静态注册表浏览器。注册表端的TOML和模式位于 `manifests/`；静态站点是位于此仓库之外的独立Astro项目。 - 在真实Linux主机上使用用户命名空间、cgroups v2、Landlock 5.13+和seccomp-bpf对Linux后端进行实时演练。工作空间在CI中可干净地交叉编译目标 `x86_64-unknown-linux-gnu` / `aarch64-unknown-linux-gnu`，但 `hatch-sandbox-linux` 中的命名空间 + cgroup + iptables 连接以及 `hatch-linux-helper` 应用的Landlock + seccomp过滤器只能在真实主机上端到端运行。 - 发布构件签名。发布工作流当前在二进制文件旁边生成一个 `SHA256SUMS` 文件，但构件本身未签名。minisign或Sigstore（`cosign`）签名属于 `v0.2` 的范畴，同时会在仓库中签入 `hatch.pub` 密钥。 - 单行安装程序。一个 `curl | sh` 安装程序，能够自动检测平台和架构，下载正确的构件，验证其签名，并启用守护进程（Linux上的systemd用户单元，macOS上的`launchd`代理），属于 `v0.2` 的范畴。

标签：AI工具服务器, cgroups, DNS安全, iptables, Landlock, launchd, Lerna, macOS安全, MCP协议, sandbox-exec, seccomp, SNI代理, systemd, 可视化界面, 基于能力的安全, 威胁模型, 子域名枚举, 守护进程, 安全策略, 安全隔离, 工具服务器管理, 提示词设计, 操作系统沙箱, 沙箱技术, 策略执行, 签名清单, 系统安全, 网络命名空间, 进程隔离, 通知系统