APIドキュメントのセキュリティ: Gitで仕様は安全か？

APIドキュメントのセキュリティは、APIプログラムのほとんど誰も監査しない部分です。認証、レート制限、セキュリティテストでAPI自体を強化します。しかし、そのAPIを説明するドキュメント、OpenAPI仕様、Swagger UIページ、認証フローを説明するマークダウンは、設定された日から誰もレビューしていないGitリポジトリや静的ホストに置かれていることがよくあります。2026年5月20日、GitHubは、攻撃者が約3,800の内部コードリポジトリからデータを盗んだことを確認しました。侵入経路は、GitHub従業員のラップトップにインストールされた、不正なVS Code拡張機能でした。この侵害は、あなた自身のセットアップについて不快な質問を投げかける良い理由となります。もし誰かがあなたの公開APIドキュメントを密かに変更できたとしたら、あなたはそれに気づくでしょうか、そしてあなたのAPI利用者は気づくでしょうか？

TL;DR（要約）

セキュアなAPIドキュメントとは、ドキュメントにアクセス制御、バージョン履歴、検証可能な整合性、監査証跡があることを意味します。これにより、侵害されたリポジトリやホストが、開発者が本番環境にコピーする誤ったエンドポイント、トークン、または認証手順を密かに供給することができなくなります。GitでのDocs-as-codeは多くのチームにとって問題なく、無料でレビューと履歴を提供します。しかし、リポジトリがアクセス制御なしで公開されている場合、古い仕様がライブAPIから乖離している場合、または改ざんされた例が検出されずに利用者に届いた場合、それは負債となります。Apidogのようなマネージドドキュメントレイヤーは、パスワード保護、IPおよびメールの許可リスト、カスタムドメイン、バージョン管理、そしてAPI設計と同期された仕様を真の情報源として追加します。

GitHubの侵害がAPIドキュメントを見直すべき理由

GitHubのインシデントは、パニックになる前に理解しておく価値があります。脅威グループTeamPCPはGitHubの内部リポジトリを流出し、現在、そのデータセットをアンダーグラウンドフォーラムで5万ドル以上で販売しています。BleepingComputerの報道は、悪意のあるVS Code拡張機能が公式マーケットプレイスから直接提供され、従業員のデバイスで実行されたことを確認しています。GitHubは、内部リポジトリ以外の顧客データへの影響を示す証拠は見つかっておらず、調査は継続中であると述べています。

この侵害は、あなたに一つのきっかけを与えます。それは、あなたのAPIドキュメントがどこでどのように存在し、それが改ざんされる可能性があるかどうかを確認するためのものです。ほとんどのチームはこれまでこの問いを発したことがありませんでした。彼らは3年前にSwagger UIをGitHub Pagesに公開し、CNAMEを指して、次に進みました。リポジトリは公開されています。仕様は最後にマージされたものです。アプリケーションコードに適用するのと同じくらいの注意を払ってドキュメントサイトの変更をレビューする人はいません。

このギャップが重要になるのは、APIドキュメントが指示だからです。開発者があなたのAPIと統合する際、彼らはエンドポイントのパス、リクエストの形式、認証ヘッダー、そして多くの場合、サンプル値をドキュメントから直接コードにコピーします。もし攻撃者がこれらの指示を変更できた場合、彼らはマーケティングページを改ざんしているのではありません。彼らは、他の人が実行するコードを編集しているのです。同じ論理は、他の2026年の侵害のインシデント後レビューにも見られます。Vercel侵害から得られたAPIセキュリティの教訓に関する私たちの記事では、信頼された表面での小さな変更がどのように波及するかを説明しています。

この記事では、以下の4つのことについて説明します。侵害されたAPIドキュメントが利用者に具体的にどのような損害を与えるか、GitでのDocs-as-codeが本当に問題ない場合と、それが負債になる場合、「セキュアなAPIドキュメント」が実際にはどのようなチェックリストを意味するか、そしてマネージドドキュメントレイヤーがどのようにギャップを埋めるかです。関連する角度については、さらに2つの記事で詳しく掘り下げています。GitHubの侵害が自己ホスト型APIツールに与える意味とVS Code拡張機能のAPIキーセキュリティです。

APIドキュメントのリポジトリまたはホストが侵害された場合に起こること

脅威モデルから始めましょう。あなたのAPIドキュメントは、Gitリポジトリ、それらを構築するCIパイプライン、そしてそれらを提供するホストといった表面上に存在します。これらのいずれかが侵害されると、いくつかの特定の悪い結果が引き起こされます。これらは理論上の話ではありません。

ドキュメントの改ざんが本番コードに到達する

これは最悪のシナリオであり、最も気づきにくいものです。ドキュメントリポジトリまたは構築済みサイトを提供するホストへの書き込みアクセスを持つ攻撃者が、小さな編集を加えます。彼らはhttps://api.payments.acme.com/v2/chargeを彼らが制御するドメインに変更します。彼らは「はじめに」ページにあるサンプルのベアラー・トークンを、彼らのプロキシを経由するトークンに交換します。彼らはOAuthセクションの1文を書き換え、トークン交換が誤ったURLに投稿されるようにします。

これらのいずれもあなたのサイトを壊しません。ページは依然としてレンダリングされます。CIは依然として合格します。なぜなら、仕様はまだ有効なYAMLだからです。しかし、次にあなたのAPIと統合する開発者は、そのエンドポイントまたはそのフローを自分のサービスにコピーします。その変更は彼らの本番環境で実行され、彼らはそれが公式ドキュメントから来たものだからと信頼していました。

現実的なOpenAPIの断片を考えてみましょう。あるチームは支払いエンドポイントを次のように文書化しています。

paths:
  /v2/payment-intents:
    post:
      summary: Create a payment intent
      servers:
        - url: https://api.acme-pay.com
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentRequest'
      responses:
        '201':
          description: Payment intent created

侵害されたアカウントを通じてマージされた、またはハイジャックされたホストにプッシュされたservers URLへのたった1回の編集で、仕様からクライアントを再生成するすべての利用者が、クレジットカードデータを攻撃者のドメインに送信することになります。違いは2単語です。ドキュメントのコミットで2単語を指摘する人はいません。

内部および未文書化のエンドポイントが流出する

ドキュメントのリポジトリには様々なものが蓄積されます。公開APIとして始まった仕様は、公開されるべきではなかった内部専用パス、管理エンドポイント、デバッグルート、またはパートナー専用の操作を含むように成長することがよくあります。リポジトリが公開されている場合、または設定ミスによって公開された場合、これらのエンドポイントはあなたの攻撃対象領域をスキャンする誰にとっても地図となります。

プライベートリポジトリであっても問題はあります。GitHubの侵害のような事態は、プライベートリポジトリを流出させます。内部API仕様が盗まれたリポジトリに存在した瞬間、攻撃者はあなたのエンドポイント、パラメータ、および期待されるペイロードの正確なインベントリを手に入れます。彼らは推測する必要はありません。あなたがスキーマを彼らに手渡したのです。他の誰かがこれらのギャップを見つける前に、自分で見つけるためのフレームワークが必要な場合は、私たちの2026年APIセキュリティテストチェックリストが、まさにこの種の表面レビューを中心に構築されています。

公開GitHub Pagesにはアクセス制御がない

GitHub Pagesは静的ホストです。ファイルを配信するだけで、誰がそれらを読んでいるかという概念はありません。真に公開されたAPIにとっては、それは正しく問題ありません。しかし、有料顧客、特定のパートナー、または自社のチームにのみ表示されるべきドキュメントの場合、それは不適切なツールです。なぜなら、そこにゲートが全くないからです。

チームは「推測しにくいURLによるセキュリティ」でこれを回避します。ドキュメントは誰もリンクしないパスに置かれます。しかし、それはアクセス制御ではありません。URLはブラウザの履歴、リファラーヘッダー、プロキシログ、共有ブックマークを通じて漏洩します。リンクを見つけた人は誰でも、すべてを永遠に見ることができ、あなたには彼らがそうしたことを知る術がありません。

古くて検証不能なドキュメント

より静かな障害モードでは、攻撃者は全く必要ありません。Gitリポジトリ内のドキュメントは乖離します。誰かがAPIの変更をリリースし、仕様の更新を忘れると、マークダウンは本番環境で異なる動作をするエンドポイントを記述することになります。利用者は文書化された動作に対して統合し、実際の動作に遭遇し、デバッグに1日を費やします。

ドキュメントが侵害されると、この問題はさらに悪化します。なぜなら、乖離と改ざんを区別する能力を失うからです。そのエンドポイントは常に間違っていたのか、それとも誰かが変更したのか？実際のAPI設計に紐づく検証可能な履歴がなければ、それに答えることはできません。ドキュメントは検証不能になり、検証不能なドキュメントはドキュメントがないのと大差ありません。

GitでのDocs-as-codeが問題ない場合と、それが負債になる場合

Docs-as-codeは正当で一般的な実践であり、このセクションはそれに対する反対意見ではありません。OpenAPI仕様とマークダウンをGitリポジトリに置き、CIでSwagger UIやRedocを構築し、静的ホストにデプロイすることは、実際のメリットをもたらします。ドキュメントの変更に対するプルリクエストレビューが得られます。誰がいつ何を変更したかの完全な履歴が得られます。コードと並行してドキュメントがバージョン管理されます。これらの特性こそが、ワークフローが遵守されている場合に改ざんを検出可能にするものです。

したがって、問題は「Gitか否か」ではありません。それは「この特定のセットアップがこの特定のAPIにとって安全か」ということです。ここに2つのケースの分割を示します。

GitでのDocs-as-codeが問題ない場合

この方法は、特定の条件でうまく機能します。

• APIが完全に公開されており、隠すものがなく、アクセス制御も不要である。
• リポジトリにブランチ保護、必須レビュー、そして少数の監査された書き込みアクセス権を持つ人々が設定されている。
• ドキュメントの変更がコードと同じ厳密なレビューを通過するため、URLやトークンの入れ替えがレビューで検出される。
• ビルドパイプラインが厳重にロックダウンされており、固定されたアクション、未レビューのサードパーティーステップなし、スコープが限定されたデプロイ資格情報が使用されている。
• 仕様が実際のAPIから生成されるか、それに対して検証され、手動で編集されたものではない。
• 誰かが仕様を最新の状態に保つ責任を負っており、乖離が蓄積されない。

これらのすべてが満たされていれば、Gitホスト型のドキュメントは強力で透明性の高いシステムです。履歴が監査証跡となり、レビューが整合性チェックとなります。

GitでのDocs-as-codeが負債になる場合

同じセットアップでも、条件が緩むとリスクが高まります。

• ドキュメントはプライベートまたはパートナー限定であるべきだが、ホストにアクセス制御がなく、「プライベート」とは「リンクされていない」ことを意味するだけである。
• 書き込みアクセスが広範囲にわたるか、誰も追跡していないサービスアカウントやCIトークンが含まれている。
• 「ただのドキュメントだから」という理由でドキュメントのコミットがゴム印のように承認され、悪意のある変更がすり抜ける。
• 仕様が手動で管理され、ライブAPIから乖離するため、利用者が信頼できない。
• リポジトリが公開エンドポイントと並んで内部または未文書化のエンドポイントを保持している。
• 整合性シグナルがなく、展開されたサイトがレビューされたソースと一致するかどうかを誰も答えられない。

GitHubの侵害は、これらの障害モードに直接当てはまります。攻撃は開発者のエンドポイントを介して内部リポジトリに到達しました。もしあなたのプライベートAPI仕様がそれらのリポジトリの一つに存在していた場合、あなたのレビュープロセスがいかに慎重であったとしても、侵害はあなたのスキーマを露出させました。Gitは透明性を提供しますが、リポジトリ自体が盗まれた場合、機密性を提供しません。異なる自己ホスト型ドキュメントアプローチがこれらのトレードオフにどう対応するかについての詳細な比較については、自己ホスト型APIドキュメント比較をご覧ください。

結論は意図的にバランスが取られています。APIが公開されており、パイプラインが規律されている場合はDocs-as-codeを維持してください。ドキュメントにアクセス制御が必要な場合、レビュープロセスがドキュメントを二流扱いしている場合、または「ライブサイトがレビューされたソースと一致しているか」に答えられない場合は、再検討してください。

「セキュアなAPIドキュメント」が実際に意味するもの

「セキュアなAPIドキュメント」という言葉は、確認できる特性に分解するまで漠然としています。その中で重要なのは次の4つです。

アクセス制御

ドキュメントは、見るべき人にだけ表示されます。公開APIの場合は公開、顧客限定、パートナー限定、または内部ドキュメントの場合は制限付きです。制限は、不明瞭なURLではなく、実際のゲート、パスワード、IP許可リスト、メール許可リスト、またはSSOである必要があります。テスト：今現在、あなたのドキュメントを誰が読めるかを正確に挙げることができ、そのうちの一人のアクセス権を1分以内に取り消すことができますか？

バージョン管理

公開されたドキュメントのすべてのバージョンは保存され、識別可能です。v1 APIの利用者はv1ドキュメントを見ます。v2の利用者はv2を見ます。特定の日付にドキュメントが何と書かれていたかを示すことができます。テスト：古いAPIバージョンと統合している開発者は、v2に密かに更新されたドキュメントではなく、そのバージョンに対する正確なドキュメントをまだ見つけることができますか？

整合性

公開されたドキュメントが意図したものと一致していることを検証できます。ドキュメントが管理された信頼できる情報源から生成されているか、または不正な変更が際立つほど強力なレビューおよび履歴の証跡があるかのどちらかです。テスト：もし誰かが1時間前にライブドキュメント上のエンドポイントURLを一つ変更した場合、何かがそれを教えてくれますか？

監査証跡

ドキュメントを誰が、何を、いつ変更したかに答えることができます。Git履歴はリポジトリについてこれを提供しますが、デプロイ段階も攻撃ポイントであるため、公開された表面についてもそれが必要です。テスト：過去90日間の公開ドキュメントの変更ログを作成できますか？

これら4つすべてを満たすセットアップがセキュアなドキュメントです。Gitホスト型のドキュメントは、ブランチ保護と履歴を通じてバージョン管理、整合性、監査証跡を満たすことができます。静的ホストでは通常アクセス制御が欠けており、そのギャップがマネージドドキュメントレイヤーの役割となります。

ApidogがセキュアなAPIドキュメントを提供する仕組み

Apidogは、APIの設計、デバッグ、テスト、モック、ドキュメント作成のためのオールインワンAPIプラットフォームです。ドキュメント作成は、上記の4つの特性がボルトオンではなくデフォルトとなるように構築されています。試すには、Apidogをダウンロードし、API定義を含む任意のプロジェクトを開いてください。

管理された信頼できる情報源からの公開ドキュメント

Apidogでは、ドキュメントはプロジェクト内のAPI設計から生成されます。視覚的なデザイナーでエンドポイント、スキーマ、認証を設計すると、Apidogがその定義からドキュメントを自動生成します。「公開」をクリックすると、「試す」コンソールと多言語コードサンプルを含むインタラクティブなドキュメントサイトが作成されます。

整合性の利点は構造的です。公開されたドキュメントは、それ自体が乖離したり改ざんされたりする可能性のある個別に編集可能なマークダウンではありません。それらはAPI定義を反映しています。定義を変更すれば、ドキュメントもそれに従います。利用者が目にするものを変更するには、静的ホスト上の散在したファイルを編集する代わりに、プロジェクト内の設計を変更します。これには独自の権限と変更履歴があります。

ドキュメントのアクセス制御

ここでApidogはGitHub Pagesのギャップを埋めます。公開する際、表示設定を選択します。そのオプションは、不明瞭さではなく、実際のゲートとして機能します。

• 公開: リンクを知っている人なら誰でも閲覧できます。真にオープンなAPIに適切です。
• パスワード保護: パスワードを設定（またはランダムなものを生成）し、関係者と共有します。パスワードを持つ人のみがアクセスできます。
• IP許可リスト: オフィスやVPNなど、特定のIPまたは範囲にアクセスを制限します。内部ドキュメントに便利です。
• メール許可リスト: 許可するメールアドレスまたはドメインをリストアップします。ユーザーはワンタイムコードで認証します。*@yourcompany.comのようなワイルドカードは組織全体をカバーします。
• カスタムログイン: 独自の認証システムを接続します。サーバーがJWTを発行し、Apidogがそれを検証し、アクセスは有効性によって決まります。

Apidogは、これら5つの方法すべてをAPIドキュメントアクセス制御ガイドで文書化しています。これはアクセス制御テストに直接答えます。誰がドキュメントを読めるかを明確に述べることができ、パスワードを取り消したり、許可リストからメールをすぐに削除したりできます。

カスタムドメイン

公開されたドキュメントを独自のドメインで提供できるため、利用者は一般的なURLではなくdeveloper.yourcompany.comを目にすることになります。Apidogは、DNS CNAME（推奨されるパス）またはリバースプロキシを介したカスタムドメインをサポートしています。カスタムドメイン単独ではセキュリティ制御ではありませんが、ドキュメントを誰も所有していないホストに散在させるのではなく、あなたが管理・統制するインフラストラクチャ上に保持します。

API設計と同期されたOpenAPI仕様

乖離は、ドキュメントを検証不能にするため、ドキュメントセキュリティの問題です。ApidogはAPI設計を唯一の信頼できる情報源として扱い、設計が変更されるとドキュメントを同期させます。ApidogはOpenAPI 3.0、3.1、Swagger 2.0をインポートし、外部仕様が自動的に最新に保たれるようにスケジュールされたインポートをサポートしています。

もし現在、Gitリポジトリで仕様を手動で保守しているのであれば、それは最も乖離が大きく、検証が最も難しい設定です。仕様をApidogに信頼できる情報源として移動させることは、公開されたドキュメントが常にあなたが制御する定義と一致することを意味します。SwaggerHubから移行するチームは、SwaggerHub APIドキュメントをApidogに移行するガイドを参照してください。

ドキュメントのバージョン管理

Apidogはドキュメントのバージョン管理をサポートしており、複数のバージョンを並行して公開・保持できます。v1 APIと統合している利用者は、v2がリリースされた後でも、正確なv1ドキュメントを読みます。バージョン管理はブランチと変更履歴に紐づいているため、APIとそのドキュメントの進化は追跡されます。これにより、バージョン管理と監査証跡の両方のテストがカバーされます。

これらのいずれも、TeamPCPが開発者のラップトップを侵害するのを止めることはできませんでした。しかし、これらは異なることを意味します。誰があなたのドキュメントを読めるか、公開されたバージョンがあなたの設計と一致するか、そして時間が経つにつれて何が変更されたかについての明確な答えを提供します。これこそが、GitHubの侵害があなたに実施を促すべき監査です。

ドキュメントホスティングオプションの比較

一般的なアプローチと4つのセキュリティ特性の簡単な比較表です。

普遍的に正しい選択肢というものはありません。公開GitHub Pagesは、規律のあるパイプラインを持つ公開APIにとって良い選択肢です。自己ホスティングは、厳しいレジデンシーまたは分離要件を持つチームに適しています。自己ホスト型APIドキュメント比較とScalar vs SwaggerHub vs Apidog比較は、これらのトレードオフを詳細に説明しています。重要なのは、3年前のセットアップをそのまま受け継いで二度と見直さないのではなく、4つの特性に対して意図的に選択することです。

結論

GitHubの侵害は、Docs-as-codeを放棄したり、GitHubを不信に思ったりする理由ではありません。それは、ほとんどのチームが見過ごしてきた表面、つまりあなたのAPIドキュメントがどこに存在し、それが改ざんされる可能性があるかどうかを監査するきっかけです。

次のステップ：あなたのAPIドキュメントが公開されているすべての場所をリストアップし、それぞれを4つの特性と照らし合わせて確認し、最も広いギャップを埋めてください。もしアクセス制御がギャップであるなら、Apidogをダウンロードし、いずれかのプロジェクトのドキュメントをパスワードまたはメール許可リストで公開して、マネージドレイヤーがそれをどのように処理するかを確認してください。