provision-sandbox-access について
provision-sandbox-accessは、サンドボックス、コンテナ、顧客設備ごとに隔離されたngrokの入口を用意するスキルです。リソース作成、権限を絞った認証情報、エンドポイント設定、削除を扱い、信頼できないワークロードを公開する制御プレーンを対象とします。
主な機能
- 01ワークロードごとにngrokリソースを作成
- 02UUIDでリソースと内部ホスト名を連携
- 03ACLで範囲を限定したエージェント認証情報を発行
- 04Traffic 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 キー(エージェントの 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)
公開側は、ワークロードの起動前にコントロールプレーンによってプロビジョニングされます。内部側は、起動時にワークロード内からエージェントによって作成されます。両者は合意済みの内部ホスト名を使って合流するため、そのホスト名は新たに考案するのではなく、導出する必要があります。
1. 安定した識別子を導出する
環境を所有するオブジェクト(サンドボックスレコード、テナント、セッションなど)に、自分のオブジェクトモデルですでに使っている UUID を選びます。作成するすべての ngrok リソースは、その UUID をもとに名前を付け、タグを付けます。
ngrok のために新しい識別子を発行してはいけません。重要なのは、後で ngrok の状態を自分の状態と照合できることです。そのためには共有キーが必要です。
内部ホスト名も UUID から導出します:tcp://sandbox-<uuid>.internal:22。合流する両側で同じ UUID から同じ文字列を計算するため、相手を探す必要はありません。
2. ID とアドレスを作成する
ワークロードの起動前に、コントロールプレーンで次を実行します。
- サービスユーザー(
POST /service_users)— 従業員アカウントに紐付けられないよう、認証情報を所有します。このリソースで指定できるのはnameのみで、メタデータは指定できません。識別子は名前に含めてください。 - 公開アドレス。プロトコルによって異なります。
- 生の TCP(SSH、RDP、データベース)->
POST /reserved_addrs。ngrok がhost:portを割り当て、addrとして返します。作成時に固定されるregionを指定します(ワークロードのユーザーが別の場所にいる場合を除き、usを指定してください)。 - HTTP/TLS ->
POST /reserved_domains。ホスト名を指定すると、addrではなくdomainとして返されます。regionは不要です。このフィールドは ドメインでは非推奨です。カスタムドメインの場合、名前解決される前に DNS でcname_targetも設定する必要があります。ngrok 所有のサブドメインでは DNS の設定が不要なため、 ワークロードごとのプロビジョニングでは通常こちらを使います。
- 生の TCP(SSH、RDP、データベース)->
ダッシュボードで人が識別できる内容を description に、UUID を含む JSON 文字列を metadata に設定してください。両方が必要な理由と正確なリクエストボディについては、ngrok-surfaces を参照してください。
3. 1つの操作だけを実行できる認証情報を発行する
これはセキュリティ上、最も重要な手順です。
{
"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"]、および手順 2 の url: "tcp://{addr}" とともに実行します。そのトラフィックポリシーは、ワークロードが後で作成する内部エンドポイントに転送します。
on_tcp_connect:
- actions:
- type: forward-internal
config:
url: tcp://sandbox-<uuid>.internal:22
HTTP ワークロードの場合は on_http_request と https:// の内部 URL を使用します。ポリシーはシリアライズされた文字列として API に渡します。詳しくは ngrok-surfaces を参照してください。
このエンドポイントはすぐに作成され、安定して存在します。ワークロード内のエージェントが起動して内部エンドポイントをバインドするまでは、接続を拒否します。これは正しい動作です。アドレスはプロビジョニング時に割り当てられ、起動時に到達可能になります。
ポリシーはワークロード内ではなくエッジ側にあるため、サンドボックスから削除できない制御を追加する場所でもあります。TCP エンドポイントでは、on_tcp_connect に restrict-ips または deny を追加できます。HTTP エンドポイントでは、これらのアクションに加えて oauth と rate-limit も使用できます。詳しくは secure-endpoint を参照してください。
5. ワークロード内のエージェントを設定する
ワークロードには、環境変数内の authtoken、ngrok エージェントのバイナリ、内部エンドポイントを指定する設定ファイルが必要です。
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 を参照してください。
次の 3 つの文字列は、完全に一致している必要があります。エージェントの設定内の内部 URL、クラウドエンドポイントのポリシー内の forward-internal の転送先、ACL 内の bind: ルールです。一致しない場合、「エンドポイントは起動しているが、何も到達しない」という状態になったり、エージェントが起動できなくなったりします。1 つの関数で、同じ UUID から 3 つすべてを生成してください。
削除する
環境を破棄するときは、逆の順序で削除します。エンドポイント、認証情報、予約済み TCP アドレスまたは HTTP ドメイン、サービスユーザーの順です。作成時に各 id をレコードに保存してください。
そのうえで、必ず調整処理も実行してください。プロビジョニングは複数の呼び出しからなるため、途中で失敗します。ngrok のリソースを一覧表示し、metadata を解析して、親が存在しないリソースを削除するジョブは、大規模運用では必須です。削除の呼び出しについては ngrok-surfaces を参照してください。
シナリオ
一時的な開発用サンドボックス。 上記のケースです。サンドボックスごとに予約済み TCP アドレスを 1 つ使って SSH 接続し、サンドボックスとともに削除します。全手順については references/sandbox-ssh.md を参照してください。
顧客構内のデバイスまたはネットワーク。 同じリソース一式を、より長期間使用します。顧客ごとにサービスユーザーと ACL でスコープを限定したトークンを 1 つずつ作成し、ある顧客での侵害が別の顧客に影響しないようにします。多くの場合、1 つのエージェントの背後に複数の内部エンドポイント(SSH、RDP、データベースなど)を配置し、それぞれに専用のクラウドエンドポイントを用意します。
開発者ごとのプレビュー環境。 ワイルドカードの予約済みドメインと 1 つのクラウドエンドポイントで全員に対応し、ホスト名に基づいて <alias>.internal にルーティングできます。開発者ごとに bind:<alias>.internal にスコープを限定したトークンを発行します。アクセス制御については secure-endpoint を参照してください。
エージェント向けの注意事項
- 呼び出し元の UUID をキーとして、この処理を冪等かつ安全に再試行できるようにしてください。部分的なプロビジョニングは通常の失敗モードです。
- 複数のテナントで 1 つの authtoken を再利用することや、ユーザーコードを実行するワークロードにスコープなしのトークンを使うことは、決して提案しないでください。ユーザーがその方法を提案した場合は、それによって生じるリスクを明確に伝えてください。
- authtoken をコンテナーイメージ、イメージに組み込まれた設定ファイル、ログに入れないでください。プロバイダーのシークレットストアから環境変数として渡してください。
- 最初の実装ではエージェントのバイナリを優先してください。SDK(
ngrok-surfaces)を使って既存のプロセスに ngrok を組み込むと、変動要素を減らせるため、最終的には適切な方法になることもありますが、エンドポイント URL が誤っている場合のデバッグはより困難です。 - ユーザーが Kubernetes を使用している場合は、API を直接呼び出すよりもオペレーターが適していることがあります。
ngrok-surfacesを参照してください。