vtex-io-security-boundaries

セキュリティ境界と公開範囲のレビュー

このスキルを使用する場面

VTEX IO のルート、統合、またはサービス境界が安全かどうかが主な論点である場合に、このスキルを使用します。

• 公開ルートと非公開ルートの公開範囲をレビューする
• サービス境界で外部入力を検証する
• トークン、アカウントコンテキスト、機密性の高いペイロードを扱う
• アカウント、ワークスペース、ユーザー間のデータ漏えいを防ぐ
• 機密データを公開または利用する統合を強化する

以下の用途にはこのスキルを使用しないでください。

• manifest.json のポリシー宣言構文
• サービスのランタイムサイジング
• ロギングと可観測性の戦略
• フロントエンドのブラウザーセキュリティに関する懸念
• エンドポイントの呼び出しに使用する VTEX 認証トークンの決定

判断ルール

• このスキルは、アプリの境界を安全に越えられるデータと入力を判断するために使用します。呼び出しを許可するポリシーやトークンの判断には使用しません。
• すべての公開ルートを明示的な信頼境界として扱います。
• service.json でルートを public: false から public: true に変更することは境界の変更であり、明示的なセキュリティレビューを実施してください。
• パートナーの Webhook や外部から利用される統合エンドポイントなど、VTEX IO の外部から呼び出す必要があるルートには public: true を使用します。これらはインターネットに公開された境界として扱ってください。
• VTEX 内部のフローまたはほかの IO アプリのみを対象とするルートには public: false を使用します。ただし、暗黙的に安全とは見なさないでください。これらのルートにも検証と、範囲を限定した前提が必要です。
• service.json で public: true に設定されたルートは、アカウントのドメインにアクセスできる限り、アプリの外部から到達可能です。セキュリティ対策として、分かりにくいパスや内部向けに見える URL に頼らないでください。
• 外部入力は、ドメインロジックや下流の統合に到達する前に、できるだけ早い段階で検証してください。
• Webhook 型のルートでは、下流のクライアントを呼び出す前に、必須フィールドに加えて共有シークレットや署名ヘッダーなどを用いて、構造と真正性の両方を検証してください。
• リクエストが別の VTEX サービスから来た、または内部向けに見えるルートパスを通ったという理由で、安全だと判断しないでください。
• サービスがスコープ付きデータを読み書きする場合は、アカウント、ワークスペース、ユーザーのコンテキストを明示してください。
• 特定のワークスペースにデータや動作を制限する必要がある場合は、ctx.vtex.workspace を明示的に確認し、ほかのワークスペースからの呼び出しを拒否してください。
• 呼び出し元が必要とする以上のデータを公開しないでください。下流から受け取った生のペイロードをそのまま返さず、意図的にレスポンスを整形してください。
• シークレット、トークン、セキュリティ上重要なヘッダーをログやルートのレスポンスに含めないでください。
• 本番環境のルートやサービスでは console.log や console.error を使用しないでください。アプリケーションのロギングには、構造化オブジェクトを使って ctx.vtex.logger を使用してください。また、アプリがパートナー所有のシステムにログを転送する場合に限り、専用の外部ロギングクライアントを使用してください。
• 内部設定、シークレット、下流から受け取った完全なペイロードを返すデバッグ用または診断用ルートを公開しないでください。そのようなルートがどうしても必要な場合は、非公開にし、機密性のない最小限の情報に限定してください。
• 境界を越えてよいものを判断するにはこのスキルを使用し、境界の認可と保護方法を判断するには vtex-io-auth-and-policies を使用してください。

関連スキル

• vtex-io-auth-and-policies - ルートまたはリソースへのアクセスをどのように認可するかが主な判断事項である場合に使用します
• vtex-io-auth-tokens-and-context - VTEX エンドポイントの呼び出しにどのランタイム ID を使用するかが主な判断事項である場合に使用します

厳守事項

制約：パブリックルートでは、信頼できない入力を境界で検証する必要があります

厳重に管理された内部境界の外部に公開されるルートでは、ドメインロジックや下流のクライアントを呼び出す前に、受信データを必ず検証する必要があります。

重要な理由

パブリックな境界で入力を検証しないと、不正利用や不正な書き込み、下流での予期しない障害につながりやすくなります。

検出方法

パブリックルートが、リクエストボディのフィールド、パラメーター、ヘッダーを検証せずにビジネスロジックやクライアント呼び出しへ直接渡している場合は、作業を中断して、まず検証を追加します。

正しい例

export async function webhook(ctx: Context) {
  const body = ctx.request.body

  if (!body?.eventId || !body?.type) {
    ctx.status = 400
    ctx.body = { message: 'Invalid payload' }
    return
  }

  await ctx.clients.partnerApi.handleWebhook(body)
  ctx.status = 202
}

誤った例

export async function webhook(ctx: Context) {
  await ctx.clients.partnerApi.handleWebhook(ctx.request.body)
  ctx.status = 202
}

制約：機密データが誤ってルート境界を越えないようにする必要があります

ルートやインテグレーションでは、トークン、内部ヘッダー、下流からの未加工のペイロード、または別のアカウント、ワークスペース、ユーザーコンテキストに属するデータを漏えいさせてはなりません。

重要な理由

境界での情報漏えいは、デプロイ後に検出するのが難しく、想定された呼び出し元の範囲を大きく超えて情報が露出する可能性があります。

検出方法

ルートが下流からのレスポンスを未加工のまま返す、シークレットをログに記録する、または明示的なフィルタリングなしにコンテキストを混在させている場合は、作業を中断して、先に出力を絞り込みます。

正しい例

ctx.body = {
  orderId: order.id,
  status: order.status,
}

誤った例

ctx.body = order

制約：サービス間の呼び出しでは、信頼境界を明示する必要があります

あるサービスが別のサービスを呼び出す場合、呼び出し先の境界も実際のセキュリティ境界として扱い、明示的な検証とスコープを限定した前提を適用する必要があります。

重要な理由

内部のサービス間通信でも、不正な形式や範囲が広すぎるデータが含まれる可能性があります。「内部だから信頼できる」と考えると、セキュリティ対策が脆弱になり、異なるコンテキスト間での情報漏えいにつながります。

検出方法

あるサービスが、別のサービスから受け取ったデータの形式、スコープ、アカウントやワークスペースのコンテキストを検証せずに受け入れている場合は、作業を中断して、これらのチェックを明示します。

正しい例

if (ctx.vtex.account !== expectedAccount) {
  ctx.status = 403
  return
}

誤った例

await processPartnerPayload(ctx.request.body)

推奨パターン

セキュリティレビューは境界から始めます。

1. このルートを呼び出したり、このインテグレーションをトリガーしたりできるのは誰ですか？
2. システムに入ってくるデータは何ですか？
3. 直ちに検証すべきデータは何ですか？
4. システムから出ていくデータは何ですか？
5. アカウント、ワークスペース、ユーザーのコンテキストが境界を越えて漏えいする可能性はありますか？

リクエストとレスポンスの形を最小限にし、明示的な検証とスコープを限定したコンテキストチェックを行って、境界を安全に保ちます。

よくある失敗例

• パブリックルートを、信頼できる内部ハンドラーのように扱う。
• 必要以上のデータを露出する、下流からの未加工のペイロードを返す。
• シークレットやセキュリティ上重要なヘッダーをログに記録する。
• ハンドラーで ctx.vtex.logger の代わりに console.log を使用し、ログの構造化が不十分になり、機密データを漏えいするリスクを高める。
• 明示的なチェックなしにアカウントやワークスペースのコンテキストを混在させる。
• サービス間の通信は本質的に安全だと思い込む。

レビューチェックリスト

• 信頼境界は明確ですか？
• 外部入力は、ドメインロジックやインテグレーションロジックに渡る前に検証されていますか？
• レスポンスの形は意図的に最小限にされていますか？
• 機密情報がログやレスポンスに含まれないようになっていますか？
• アカウント、ワークスペース、ユーザーのコンテキストがこの境界を越えて漏えいする可能性はありますか？

参考資料

• サービス - ルートの公開とサービスの動作
• ポリシー - 認可関連の宣言に関するコンテキスト