Shift-Left Security: Catching API Drift at the Local Tunnel Ingress

• undocumentedエンドポイントの変更が本番の利用者を壊さないようにしましょう。最新のローカルトンネルを設定して、実行時のペイロードをOpenAPI仕様と自動的に検査し、localhostを離れる前にAPIドリフトを防ぐ方法を学びましょう。*

現代のソフトウェア開発の超高速化の世界では、CI/CDパイプラインがコードの出荷速度を根本的に変えています。しかし、その裏には隠れたコスト、すなわちAPIドリフトがあります。開発者がローカルアプリケーションロジックを迅速に反復する中で、そのAPIの動作を詳細に記述したドキュメントはしばしば遅れがちです。フィールドが追加されたり、データ型が変更されたり、エンドポイントがコード上で非推奨になったりしても、公式のOpenAPI仕様はそのままです。

これらの未ドキュメントの変更がステージングや本番環境に到達すると、フロントエンドアプリケーションを壊し、サードパーティの利用者に連鎖的な障害を引き起こし、セキュリティチームにとって巨大な盲点となります。従来はこれらの差異を発見するのに手動のコードレビューや遅れた統合テスト、あるいはエンドユーザーからの怒りのバグ報告に頼っていました。

しかし今、トンネルの入口で自動的にドリフトを検知する新しいパラダイムが登場しています。開発者がローカル環境を公開するために使うリバーストンネル—ngrokエージェントのエンドポイントやCloudflare TunnelのAPI Shieldなどのツール—を活用し、セキュリティをソフトウェアライフサイクルの最も早い段階に押し上げることが可能になっています。この記事では、runtime OpenAPI検証を用いた入口スキーマの強制を実現し、ローカルトンネルをインテリジェントなAPIドリフト検知プロキシに変える方法を解説します。

---

APIドリフトの構造とその影響

APIドリフト、またはスキーマドリフトは、実稼働中のAPI実装が仕様と乖離することを指します。設計優先のアーキテクチャでは、OpenAPI仕様は唯一の真実の源泉として機能します：必要なヘッダーは何か、許容されるパラメータは何か、リクエストとレスポンスのJSON構造はどうなっているか。

しかし、実際の開発現場では状況は異なります。開発者は迅速にuser_statusフィールドをJSONレスポンスに追加し、フロントエンドエンジニアのためにローカルで検証し、コードをプッシュして次に進みます。別のディレクトリにあるOpenAPI YAMLファイルは忘れ去られます。

未ドキュメントの変更の波及効果

壊れた利用者契約。 本番システムやモバイルアプリ、B2Bパートナーが特定のスキーマに依存している場合、IDフィールドが整数から文字列に変わるなどの静かな型変更は、自動パーサーのクラッシュやサービスダウンを引き起こします。

シャドウAPIやゾンビAPI。 未ドキュメントのエンドポイント（シャドウAPI）や非推奨だがまだアクティブなエンドポイント（ゾンビAPI）は、リスクの最上位に正式に位置付けられています。OWASP API Security Top 10 2023では、これらはAPI9:2023 — 不適切なインベントリ管理としてリストされており、APIのドキュメントや監視が不十分なため、攻撃者に悪用されるシャドウAPIが生まれやすくなっています。セキュリティ監査では、組織のAPIの実態の30〜40％がシャドウまたはゾンビAPIで占められ、APIインベントリに対する自信を持つ組織はわずか15％です。

認証の脆弱性。 APIドリフトはしばしばBroken Object Level Authorization（BOLA）や大量割り当ての脆弱性を引き起こします。BOLAは2019年以来OWASP API Security Top 10の第一位を占めており、API攻撃の約40％に関係しています。開発者がis_adminのような内部フィールドをレスポンスに誤って公開し、スキーマを更新しなかった場合、セキュリティチームはそのデータ漏洩を検知するための基準を持ちません。

この問題の規模は理論的なものではありません。Salt Securityの2025年第1四半期APIセキュリティ状況レポートによると、200人以上のIT・セキュリティ専門家と匿名化された顧客データの調査から、99％の組織が過去12ヶ月でAPIセキュリティの問題に直面し、55％はAPIセキュリティの懸念から新規アプリの展開を遅らせたと報告しています。別途、Salt Securityの2025年第2四半期レポートでは、386人のセキュリティ専門家の調査から、33％が過去1年でAPIセキュリティインシデントを経験し、95％の攻撃が認証済みセッションから発生していることが確認されており、境界防御だけでは不十分であることが示されています。

これに対抗するため、業界では「shift-left security」（左側シフトセキュリティ）という概念が生まれました。これは脆弱性の検知をできるだけ早い段階、開発ライフサイクルの最初に移すことを意味します。しかし従来のshift-leftは静的アプリケーションセキュリティテスト（SAST）に大きく依存してきました。SASTはコードの静止状態を分析し、実際のトラフィック下でのAPIの動的挙動を理解しません。ここで、ローカルトンネルが重要な防御ラインに進化します。

---

2025–2026年のOpenAPIエコシステム

ローカルトンネルがスキーマをどのように強制するかを理解する前に、仕様エコシステムの現状を把握しましょう。

OpenAPI 3.2.0は2025年9月19日にOpenAPI Initiativeによってリリースされました。これは3.1に対して破壊的な変更なく拡張し、階層化されたタグ（summary、parent、kind）やストリーミングメディアタイプ（Server-Sent Events、JSON Lines、multipart）などの新機能を導入しています。これらは仕様内で直接表現可能です。カスタムHTTPメソッド（additionalOperations）やOAuth 2.0デバイス認証フローの正式サポートも含まれます。主要なツール（バリデータ、コードジェネレーター、ゲートウェイ統合）は2025年第4四半期または第1四半期に3.2対応を完了しています。現時点では、OpenAPI 3.1.xと3.2.0の両方が実運用に適していますが、新規プロジェクトには長期的に3.2を推奨します。

Arazzo Specification（バージョン1.0.0、2025年1月にパッチv1.0.1）は、コア仕様が表現できなかったワークフロー内のAPI呼び出しの関係性を扱います。複数ステップのインタラクション（顧客作成、支払い方法作成、チャージ開始など）を正式に記述できるArazzoドキュメントは、OpenAPI仕様とリンクし、状態を持つシーケンスの検証を可能にします。これにより、ドリフト検知は個々のエンドポイントだけでなく、シーケンス全体の整合性も確認できます。

大きな変化の一つは、OpticのGitHubリポジトリが2026年1月12日にアーカイブされたことです。これは、Test trafficからOpenAPI仕様を生成・差分検出していたツールで、2024年4月のAtlassian買収後に最終リリース（v1.0.9）を迎え、その後は開発停止となっています。useoptic.comは解決しなくなり、Atlassian Compassへの統合も実現しませんでした。Opticに依存していたCIの仕様差分ツールは、oasdiff（オープンソースCLIとGitHub Action、Apache 2.0ライセンス、積極的にメンテナンス中）やSpecShield（ホスト型Web UI、CLI、GitHubアプリ）に移行する必要があります。特定のTrafficからOpenAPIを生成するワークフローは、代替手段を採用する必要があります。

---

ダンプなトンネルからインテリジェントなエージェントエンドポイントへ

長年、開発者はngrokのようなツールを使ってローカル開発サーバーをインターネットに公開してきました。これはWebhookのテストや同僚へのプレビューに便利な逆方向トンネルです。これらは「ダンプ」なパイプで、TCPやHTTPトラフィックを公開URLからlocalhost:8080に転送するだけでした。

しかし、そのアーキテクチャは大きく変わっています。提供者はローカルトンネルを、深くプログラム可能なAPIゲートウェイへと進化させています。用語も変わり、かつての「トンネル」は今や「エージェントエンドポイント」と呼ばれることが一般的です。

ngrokのTraffic Policyエンジンはその最たる例です。2025年5月に一般提供にアップデートされたこのエンジンは、JSONまたはYAMLで定義されたカスタムルールをリクエストライフサイクルの3段階（on_tcp_connect、on_http_request、on_http_response）で検証します。ルール式はCEL（Common Expression Language）で記述され、URL、クエリ文字列、ヘッダー、クッキー、ジオロケーションなどにアクセス可能です。アクションにはJWT検証、OAuth/OIDC、レートリミット、URL書き換え、ヘッダー変更、外部監視プラットフォームへのロギングなどがあります。これにより、クラウドエンドポイントのポリシーと同じ設定をローカルエージェントに適用でき、「自分のマシンで動いたのに本番では動かない」問題を解消します。

一方、Cloudflare API Shieldは、Cloudflareのエッジで本番レベルのスキーマ検証を提供します。OpenAPI v3.0仕様をアップロードすると、API Shieldは正のセキュリティモデルを作成します。サポートされるエンドポイントとメソッドは保護され、対応しないリクエストはログまたはブロックされます。さらに、schema learningを継続的に行い、過去72時間の2xxレスポンスのトラフィックからパラメータを推測し、それをOpenAPI仕様としてエクスポート可能です。現在、API ShieldはOAS 3.0.xをサポートし、3.1は未対応です。

これらのアーキテクチャのポイントは同じです：これらのエージェントエンドポイントは開発者のマシンや組織のエッジに位置し、すべてのHTTPリクエストとレスポンスを仲介します。これにより、アップストリームのバックエンドに到達する前にペイロードを検査し、レスポンスを出る前に検証できる理想的な位置となっています。

---

ingressでのruntime OpenAPI検証の仕組み

ローカルトンネルレベルでの入口スキーマ強制を実現するには、OpenAPI仕様を直接プロキシ設定にバインドします。外部またはシミュレートされたテストリクエストがトンネルURLに到達すると、エージェントは複数段階の検査を行い、リクエストがバックエンドに届く前に検証します。

ステップ1：スキーマの読み込みとルートのマッチング

開発者はトンネルエージェントに現在のOpenAPI .yamlまたは.jsonファイルのパスを設定します。トンネル起動時にスキーマを内部ルーティングテーブルに解析します。例えばPOST /api/v1/usersのリクエストが来た場合、エージェントはこのルートとHTTPメソッドが仕様に記載されているか即座に確認します。

エンドポイントが未ドキュメントの場合、トンネルは404 Not Foundまたは403 Forbiddenで拒否し、開発者にシャドウAPIにアクセスしていることを通知します。この単一の検査だけでも、OWASP API9:2023（不適切なインベントリ管理）に直接対応します。

ステップ2：リクエストペイロードの検査

ルートが既知の場合、トンネルはリクエスト内容を検査します：コンテンツタイプ、必要なヘッダー（Authorizationやカスタムテレメトリタグなど）、リクエストボディを定義されたJSON Schemaと比較します。文字列長、数値フォーマット、必須フィールド、enumのメンバーシップなどをリクエスト前にチェックします。例えば、スキーマがageは数値と定めているのに対し、ペイロードが`