ngrok-engine

ngrok エンジン：エンドポイントとトラフィックポリシー

ほとんどすべての ngrok タスクでは、次の 2 つを決めます。

1. どの種類のエンドポイントか？ エージェント、クラウド、内部のどれか。また、どのプロトコルを使うか。
2. トラフィックをどう処理するか？ エッジで実行するトラフィックポリシーです。

このスキルでは、ジョブスキルに必要なレベルで両方の判断を扱い、詳細は references/ に記載しています。結果をどこに適用するかは別の問題です。ngrok-surfaces を参照してください。

これらの判断は、ユーザーの意図に基づいて行ってください。ユーザーにエンドポイントの種類を選ばせてはいけません。分類を把握している必要はありません。

1. エンドポイントの種類

• エージェントエンドポイント - 実行中のエージェントまたは SDK プロセスによって作成され、そのプロセスの実行中のみ存在します。一時的な用途、ローカル環境、デモ、テストに適しています。
• クラウドエンドポイント - API、ダッシュボード、または IaC を介して作成され、エージェントには依存しません。常時稼働し、安定した URL を持ちます。本番環境の入り口や、サードパーティが独自のスケジュールで接続するものに適しています。
• 内部エンドポイント - パブリック URL はありません。forward-internal アクションを介してのみ到達できます。受信側をパブリックインターネットから隔離する方法です。

多くのジョブで使われる構成は、次のとおりです。

クラウドエンドポイント（パブリックで、ポリシーを実行） -> forward-internal -> 内部エンドポイント -> ローカルサービス

プロトコルは種類とは別の要素です。デフォルトは HTTP です。TCP（SSH、RDP、データベース）の場合は、いくつかの点が変わります。パブリック TCP エンドポイントには予約済みのアドレスが必要で、内部 TCP URL には明示的なポートが必要です。また、ポリシーフェーズは on_tcp_connect となり、Kubernetes オペレーターは TCP をまったくサポートしていません。

詳細な判断ロジック、バインディング、TCP のルールについては、references/endpoints.md を参照してください。

2. トラフィックポリシー

フェーズごとにルールがまとめられています。各ルールには、省略可能な CEL expressions と、actions のリストがあります。

on_http_request:
  - expressions:
      - "req.url.path.startsWith('/admin')"
    actions:
      - type: deny

• フェーズ： on_http_request、on_http_response、on_tcp_connect、on_event_stream_message。
• ルールは順番に実行され、終了アクションを実行するとチェーンが終了します。すべての Cloud Endpoint ポリシーには、終了アクションが必要です。エージェントエンドポイントには必要ありません。
• **ポリシーの本文は、どのサーフェスでも同一です。**異なるのはアタッチ方法のみです。

文法、CEL 変数、Secrets と Vaults、最もよく使われる 7 つのアクション、アクションの連結方法については、references/traffic-policy.md を参照してください。

アクションの種類

利用可能なアクションを把握できるように、全 26 種類を示します。追加の情報を取得する必要はありません。

• 接続の変更：deny、forward-internal、http-request、log、restrict-ips、set-vars、terminate-tls
• リクエストの変更：add-headers、circuit-breaker、log、owasp-crs-request、rate-limit、redirect、remove-headers、request-body-find-replace、set-vars、url-rewrite
• レスポンスの変更：add-headers、compress-response、custom-response、log、owasp-crs-response、remove-headers、response-body-find-replace、set-vars、sse-find-replace
• セキュリティ：basic-auth、jwt-validation、oauth、openid-connect、owasp-crs-request、owasp-crs-response、restrict-ips、terminate-tls、verify-webhook
• トラフィック制御：circuit-breaker、close-connection、deny、forward-internal、http-request、owasp-crs-request、owasp-crs-response、rate-limit

**アクションの設定を推測してはいけません。**次の 2 段階で確認してください。

1. references/action-catalog.md - インデックスです。アクションごとに 1 行で、フェーズ、チェーンを終了するかどうか、機能を示します。
2. references/actions/<action>.md - アクションの設定フィールド、結果変数、例を記載しています。

必要なアクションのファイルだけを読んでください。ディレクトリ全体では約 12k トークンを使いますが、アクション 1 つなら数百トークンです。

エージェント向けの注意事項

• references/traffic-policy.md に明記されている7つのアクションは、既存のジョブスキルがたまたま使っているものです。重要なのはそれだけではありません。ほかの機能が必要な場合は、いつでもカタログを参照してください。
• 多くのアクションはそれ自体で制御を行います（rate-limit は独自の429を返し、verify-webhook はフェイルクローズします）。重複する deny を追加する前に、そのアクションの項目を確認してください。
• 後からユーザーが別のサーフェスを追加してもポリシーが維持されるよう、ポリシーは独立した policy.yaml に保存してください。
• ngrok MCP サーバーが接続されている場合は、作成または編集したポリシーを提示または適用する前に、必ず gw_validate_traffic_policy で検証してください。保存時と同じチェック（プランの利用資格を含む）が実行され、各問題の行と列が報告されます。ポリシーがクラウド、TCP、または内部エンドポイント向けの場合は、endpoint_type、scheme、binding を渡してください。