关于 provision-sandbox-access
provision-sandbox-access 是为沙箱、容器或客户设备逐个配置隔离 ngrok 入口的技能,涵盖资源创建、受限凭证、端点配置和清理。适用于需要由控制平面管理不可信工作负载访问的平台。
主要功能
- 01按工作负载创建独立 ngrok 资源
- 02用 UUID 关联资源和内部主机名
- 03创建 ACL 受限的 Agent 凭证
- 04通过 Traffic Policy 转发至内部端点
- 05销毁资源并协调清理残留
适用场景
- 01为临时开发沙箱配置 SSH 入口
- 02隔离不同客户现场设备的访问
- 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 步骤,通常这正是按工作负载 配置资源时所需的方式。
- 原始 TCP(SSH、RDP、数据库)->
将人类可在控制面板中识别的信息填入 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。