mcpField
P
provision-sandbox-access

provision-sandbox-access

github.com/ngrok云与 DevOps18141 次安装4 天前更新
代码仓库

关于 provision-sandbox-access

provision-sandbox-access 是为沙箱、容器或客户设备逐个配置隔离 ngrok 入口的技能,涵盖资源创建、受限凭证、端点配置和清理。适用于需要由控制平面管理不可信工作负载访问的平台。

主要功能

  1. 01按工作负载创建独立 ngrok 资源
  2. 02用 UUID 关联资源和内部主机名
  3. 03创建 ACL 受限的 Agent 凭证
  4. 04通过 Traffic Policy 转发至内部端点
  5. 05销毁资源并协调清理残留

适用场景

  1. 01为临时开发沙箱配置 SSH 入口
  2. 02隔离不同客户现场设备的访问
  3. 03为开发者预览环境配置独立入口

MCP 相关

ngrok MCP 服务可用于检查控制平面创建的资源,例如列出端点;资源创建流程本身由控制平面调用 ngrok API 完成。

安装

复制下面的命令,在终端中运行。

$npx skills add https://github.com/ngrok/skills --skill provision-sandbox-access

安装后在 Claude Code 中输入/provision-sandbox-access确认已加载。

附带文件references/sandbox-ssh.md

详细介绍

按沙箱配置隔离访问

任务:控制平面创建一个环境——沙箱、容器或客户设备——每个环境都需要一个可访问且相互隔离的入口点。不是通过路由共用一个端点,而是为每个工作负载创建一组独立的 ngrok 资源,并随其创建和销毁。

这在生命周期和信任模型上都不同于 expose-localhost。在那里,开发者公开的是自己的机器,也信任自己。而这里,平台以机器速度公开_他人的_工作负载,必须假设其中的代码具有恶意。

开始之前

你需要在控制平面中准备一个 ngrok API 密钥(不是 Agent authtoken)。请参阅 ngrok-setup。ngrok MCP 服务无法替代它,因为控制平面是无需你参与即可运行的代码。如果已连接 MCP 服务,可用它检查控制平面创建了什么,例如 gw_list_endpoints。配置调用的文档见 ngrok-surfaces(ngrok-surfaces/references/api.md 和 ngrok-surfaces/references/api-resources.md);本技能介绍操作方案,这些文档介绍具体机制。

架构

public client
  -> cloud endpoint        (stable public URL/address, always on, runs the policy)
  -> forward-internal      (Traffic Policy)
  -> internal endpoint     (no public address; only reachable via forward-internal)
  -> ngrok agent inside the workload
  -> the local service (sshd, HTTP server, database)

工作负载启动前,由你的控制平面配置公网侧。工作负载启动时,由 Agent 在其内部创建内网侧。双方通过约定的内部主机名会合,因此该主机名必须通过推导得出,而不能凭空编造。

1. 推导稳定标识符

选择你自己的对象模型中已用于标识环境所属对象的 UUID,例如沙箱记录、租户或会话。你创建的每个 ngrok 资源都会根据它来命名和打标签。

不要为了 ngrok 另行生成标识符。这样做的目的,是让 ngrok 的状态日后可以与你自己的状态进行协调,而这需要双方使用同一个键。

内部主机名也由它推导而来:tcp://sandbox-<uuid>.internal:22。会合双方根据同一个 UUID 计算出相同的字符串,因此不必相互发现。

2. 创建身份和地址

在工作负载启动前,于控制平面中执行:

  • 服务用户(POST /service_users)——用于拥有凭据,避免将凭据关联到员工账户。请注意,此资源只接受 name,不接受元数据;应将标识符放入名称中。
  • 公网地址,根据协议而有所不同:
    • 原始 TCP(SSH、RDP、数据库)-> POST /reserved_addrs。ngrok 会分配 host:port,并将其作为 addr 返回。需要指定 region(除非 工作负载的用户位于其他地区,否则使用 us),且创建后不可更改。
    • HTTP/TLS -> POST /reserved_domains。由你选择主机名,返回字段为 domain,而不是 addr。没有 region 字段——该字段对于 域名已弃用。自定义域名还需要先在 DNS 中设置 cname_target,才能 解析;ngrok 所有的子域名则不需要 DNS 步骤,通常这正是按工作负载 配置资源时所需的方式。

将人类可在控制面板中识别的信息填入 description,并将包含 UUID 的 JSON 字符串填入 metadata。关于为何两者都需要,以及准确的请求体,请参阅 ngrok-surfaces。

3. 创建仅能执行一项操作的凭据

这是安全配置中的关键步骤。

{
  "description": "Agent authtoken for sandbox <uuid>",
  "metadata": "{\"sandbox_id\":\"<uuid>\"}",
  "acl": ["bind:tcp://sandbox-<uuid>.internal:22"],
  "owner_id": "<service user id>"
}

bind: ACL 会将令牌限制为只能创建这一个端点,不能执行其他操作。如果没有 ACL,该令牌就能在你的账户上创建任意端点——而这个令牌即将被放入运行不受信任代码的工作负载中。请假设它一定会泄露。配置 ACL 后,即使令牌泄露,攻击者也只能绑定一个本就属于他们的端点。

token 只会返回一次。请在同一代码路径中直接将其写入沙箱提供商的密钥存储;绝不要记录它,也不要通过你自己的 API 将其传回。

4. 创建云端点

使用 POST /endpoints,设置 type: "cloud"、bindings: ["public"],并将 url: "tcp://{addr}" 设为第 2 步中的地址。其流量策略会将流量转发到工作负载稍后创建的内部端点:

on_tcp_connect:
  - actions:
      - type: forward-internal
        config:
          url: tcp://sandbox-<uuid>.internal:22

对于 HTTP 工作负载,事件为 on_http_request,内部 URL 使用 https://。策略以序列化字符串的形式传递给 API——请参阅 ngrok-surfaces。

此端点会立即创建,并且保持稳定。直到工作负载内的 Agent 启动并绑定内部端点之前,它都会拒绝连接。这是正确的行为:地址在配置资源时分配,在启动时即可访问。

由于策略位于边缘而不在工作负载中,因此也可以在此处添加沙盒无法移除的控制措施。对于 TCP 端点,可以在 on_tcp_connect 中添加 restrict-ips 或 deny。对于 HTTP 端点,除了这些操作,还可以使用 oauth 和 rate-limit。详情请参阅 secure-endpoint。

5. 配置工作负载内的 Agent

工作负载需要:环境变量中的 authtoken、ngrok Agent 二进制文件,以及一个指定内部端点的配置文件。

version: 3
endpoints:
  - name: ssh
    # must match what the cloud endpoint forwards to, and what the ACL allows
    url: tcp://sandbox-<uuid>.internal:22
    upstream:
      url: 22
ngrok start --all --config /path/to/ngrok.yml

authtoken 从环境变量 NGROK_AUTHTOKEN 中读取,而不是从配置文件中读取,因此令牌不会写入映像中的磁盘。关于配置界面的一般说明,请参阅 ngrok-surfaces;完整的沙盒容器操作流程(包括二进制文件下载和嵌入式 SDK 替代方案),请参阅 references/sandbox-ssh.md。

以下三个字符串必须完全一致:Agent 配置中的内部 URL、云端点策略中的 forward-internal 目标,以及 ACL 中的 bind: 规则。不匹配会导致“端点已启动,但没有流量到达”或 Agent 根本无法启动。应在一个函数中根据同一个 UUID 生成这三个字符串。

拆除资源

销毁环境时,按相反顺序删除:端点、凭证、保留的 TCP 地址或 HTTP 域名、服务用户。创建时将每个 id 保存到对应记录中。

之后仍需运行资源协调。配置资源是一个由多个 API 调用组成的序列,可能会在中途失败;在规模化运行时,列出 ngrok 资源、解析 metadata 并删除父资源已不存在的资源,这一步必不可少。删除调用请参阅 ngrok-surfaces。

使用场景

临时开发沙盒。 即上述场景。通过保留的 TCP 地址进行 SSH 连接,每个沙盒使用一个地址,并在沙盒销毁时一并拆除。完整操作流程请参阅 references/sandbox-ssh.md。

客户现场设备或网络。 使用相同的资源集合,但生命周期更长。每个客户站点使用一个服务用户和一个受 ACL 限定的令牌,这样一个客户处发生安全漏洞时,无法影响其他客户。通常,一个 Agent 后面会有多个内部端点(SSH、RDP、数据库),每个端点都有自己的云端点。

按开发者划分的预览环境。 一个通配符保留域名和一个云端点即可服务所有用户,根据主机名路由到 <alias>.internal,并为每位开发者使用一个作用域限定为 bind:<alias>.internal 的令牌。访问控制方面请参阅 secure-endpoint。

给 Agent 的说明

  • 按调用方的 UUID 实现幂等和安全重试。配置资源只完成一部分是常见的失败模式。
  • 切勿建议在多个租户间重复使用同一个 authtoken,也切勿建议在运行用户代码的工作负载中使用未限定作用域的令牌。如果用户提出这种做法,应明确说明其代价。
  • 不要将 authtoken 放入容器映像、烘焙到映像中的配置文件或日志中。应从提供商的密钥存储中通过环境变量传入。
  • 初次实现时优先使用 Agent 二进制文件。通过 SDK 将 ngrok 嵌入现有进程中(ngrok-surfaces)可以减少一个活动部件,也可能是合适的最终方案,但端点 URL 错误时更难调试。
  • 如果用户使用 Kubernetes,operator 可能比直接调用 API 更合适;请参阅 ngrok-surfaces。

评论

支持 Markdown