AndrewDryga/emisar

# emisar **为 AI 工具批准的基础设施操作，在主机上强制执行。** emisar 是一个控制平面、仅出站运行器和 MCP 桥接器，用于让 AI 工具请求一组有限且预先声明的操作，而无需接收原始的 shell 或 SSH 访问权限。 状态：**公测版。** 这个 monorepo 包含了完整的运行器、Phoenix 控制平面、公共网站和 MCP stdio 桥接器。 托管控制平面是目前支持的产品边界；自托管和气隙部署目前尚未正式可用。 ## 它的功能 - 在每个运行器上加载带版本控制且内容寻址的 **action pack**。 - 通过 TLS websocket **向外**拨号连接到控制平面 —— 没有入站监听器。 - 当运行器播报新的、自定义的或更改的 pack 内容时阻止调度，直到管理员信任该哈希。 - 通过 OAuth 连接远程 MCP 客户端，并通过 `emisar-mcp` stdio 桥接器连接本地客户端。 - 应用基于用户的运行器作用域、风险等级策略、操作覆盖、人工批准以及可撤销的长期授权。 - 对于来自云端的每个 `run_action` 消息： 1. 根据操作声明的 schema 重新验证参数。 2. 重新计算并验证受信任的 pack 哈希。 3. 将云端提供的 opts 限制在操作的 `*_min`/`*_max` 边界内。 4. 通过 `os/exec` 执行，使用 **argv 数组，绝不使用 shell 字符串**。 5. 通过 websocket 流式传输经过行缓冲和脱敏的输出。 6. 将每次尝试的 hash 链 JSONL 事件写入本地安全日志。 - 将运行状态镜像到可搜索的审计日志中，并提供只读的 SIEM 导出。 ## 它刻意避免做的事 - 不是沙盒或进程隔离器。 - 不是任意远程 shell 或通用的 `execute(command)` 工具。 - 不能替代 OS 级别的最小权限、进程隔离或客户变更管理控制。 - 不是 OSI 批准的开源软件。该仓库在 [`LICENSE.md`](LICENSE.md) 下提供源码可见许可。 请参阅 [`docs/security-model.md`](docs/security-model.md)。 ## 安装（生产环境） 从门户创建运行器，以接收具有作用域的 bootstrap 密钥和生成的安装命令。适用于 Linux（systemd）和 macOS（launchd）的底层托管安装程序为： ``` curl -sSL https://raw.githubusercontent.com/andrewdryga/emisar/main/install.sh | sudo bash ``` 这将下载最新标记的发布版本，验证 SHA256，创建专用的服务用户（Linux），安装 `/usr/local/bin/emisar`，在 `/etc/emisar/` 下方放置配置骨架，并安装带有 `Restart=on-failure` 监督和 `StartLimitBurst` 上限的 systemd unit 或 launchd plist。 安装后，如果门户生成的命令没有填充配置文件，请编辑 `/etc/emisar/config.yaml` 和 `/etc/emisar/runner.env`，然后启动服务。有关升级、卸载、气隙安装和完整操作命令，请参阅 [`docs/install.md`](docs/install.md)。 ## 快速开始（开发 / 本地） 命令从仓库根目录运行。运行器是位于 `runner/` 下的独立 Go 模块（请参阅下方的[仓库布局](#repository-layout)）；构建它会将二进制文件放在 `bin/emisar`： ``` # 1. 构建 runner + MCP bridge (cd runner && go build -o ../bin/emisar .) (cd mcp && go build -o ../bin/emisar-mcp .) # 2. 验证捆绑的 example packs ./bin/emisar pack validate ./packs/linux-core ./bin/emisar pack validate ./packs/cassandra ./bin/emisar pack validate ./packs/showcase # 3. 查看 runner 将向 cloud 宣告的内容 ./bin/emisar --config ./runner/examples/config.yaml state | jq # 4. 在本地运行 action 进行调试（绕过 cloud） ./bin/emisar --config ./runner/examples/config.yaml \ action run linux.uptime --reason "smoke test" # 5. 流式传输长时间运行的 action 的输出 ./bin/emisar --config ./runner/examples/config.yaml \ action run linux.journalctl --arg unit=docker --stream # 6. 检查 JSONL 日志 ./bin/emisar --config ./runner/examples/config.yaml events tail --lines 20 ``` 以 daemon 模式运行（等待云命令）： ``` EMISAR_AUTH_KEY=emkey-auth-... \ ./bin/emisar --config ./runner/examples/config.yaml connect ``` ## 文档 | 文档 | 主题 | | --------------------------------------------------- | ---------------------------------------------------- | | [docs/architecture.md](docs/architecture.md) | 包布局，runtime pipeline，启动序列。 | | [docs/install.md](docs/install.md) | 生产环境安装，托管操作，升级。 | | [docs/security-model.md](docs/security-model.md) | 考虑及明确不考虑的威胁。 | | [docs/signed-dispatch.md](docs/signed-dispatch.md) | 仅运行人工签名的操作（客户端证明的调度）。 | | [docs/action-packs.md](docs/action-packs.md) | 如何编写 pack。 | | [docs/cloud-boundary.md](docs/cloud-boundary.md) | 控制平面和运行器各自强制执行的内容。 | | [docs/wire-protocol.md](docs/wire-protocol.md) | JSON 消息类型，连接生命周期，opts。 | ## 仓库布局 采用 monorepo 架构，每个可部署组件对应一个文件夹，采用基于语言命名的布局。每个 Go 文件夹都是其独立的模块；Elixir 控制平面是一个 umbrella 项目。`go.work` 将两个 Go 模块连接在一起，以便于编辑器和 CLI 使用。 ``` portal/ Elixir/Phoenix control plane (umbrella) apps/emisar/ domain contexts: accounts, runs, policies, audit, billing apps/emisar_web/ LiveView dashboard + marketing site + MCP HTTP API runner/ Go module — on-host runner binary main.go, connect.go, … CLI (cobra) internal/cloud wire protocol + outbound websocket client internal/engine action runtime (validate → clamp → execute → redact → journal) internal/packs pack loader + in-memory registry internal/executor exec/script process runner (line-buffered streaming) internal/validation arg schema enforcement internal/expressions tiny argv-substitution template engine internal/redact output redaction internal/audit hash-chained JSONL event log internal/config config loader pkg/actionspec action spec types (YAML schema) pkg/packspec pack manifest types examples/config.yaml example runner config mcp/ Go module — stdio MCP bridge for Claude Code / Cursor / etc. packs/ action pack catalog (YAML) — linux-core, cassandra, docker, + 70 more; consumed by the runner + portal docs/ architecture, security, signed-dispatch, action-packs, cloud-boundary, wire-protocol docker-compose.yml Full local stack: Postgres, portal, seeder, and runners install.sh supervised install (systemd / launchd) — run against tarball ``` ## 许可证 本仓库是**源码可见**的，而非 OSI 批准的开源软件。 提供代码的目的是让用户能够检查它、评估它、运行允许的内部用途、了解其工作原理以及贡献改进。它不可用于克隆产品、运营竞争服务、商业再分发、AI 训练、模型微调、embedding 语料库、净室复制或构建替代产品。 请参阅： - [`LICENSE.md`](./LICENSE.md) - [`AI-USE-POLICY.md`](.github/AI-USE-POLICY.md) - [`CONTRIBUTING.md`](.github/CONTRIBUTING.md) - [`CLA.md`](.github/CLA.md) - [`NOTICE.md`](.github/NOTICE.md) - [`SECURITY.md`](.github/SECURITY.md) 如需商业许可、托管使用、AI 权限或其他权利，请联系 `licensing@emisar.dev`。

标签：AI辅助运维, MCP, Streamlit, 命令执行控制, 日志审计, 测试用例, 访问控制, 运维工具