APIドキュメントのセキュリティは、API本体ほど監査されません。認証、レート制限、セキュリティテストは整備していても、OpenAPI仕様、Swagger UI、認証フローを説明するMarkdownは、古いGitリポジトリや静的ホストに置かれたままになりがちです。2026年5月20日、GitHubは、悪意あるVS Code拡張機能を経由して約3,800の内部コードリポジトリからデータが盗まれたことを確認しました。このインシデントをきっかけに、自分のAPIドキュメントについて確認すべきです。もし誰かが公開APIドキュメントを密かに変更できた場合、あなたやAPI利用者はそれに気づけるでしょうか。
TL;DR
セキュアなAPIドキュメントには、少なくとも次の4つが必要です。
- アクセス制御: 誰が読めるかを制御できる
- バージョン管理: APIバージョンごとのドキュメントを維持できる
- 整合性: 公開ドキュメントが正しいAPI定義と一致している
- 監査証跡: 誰が、いつ、何を変更したか追跡できる
GitベースのDocs-as-codeは有効です。レビュー、履歴、CIを活用できます。ただし、リポジトリが公開されている、ドキュメントがライブAPIから乖離している、または改ざんされたサンプルが検出されずに利用者へ届く場合、それはリスクになります。
Apidogのようなマネージドドキュメントレイヤーを使うと、パスワード保護、IP許可リスト、メール許可リスト、カスタムドメイン、バージョン管理、API設計と同期された仕様をドキュメント公開フローに組み込めます。
GitHubの侵害がAPIドキュメント監査のきっかけになる理由
GitHubのインシデントでは、脅威グループTeamPCPがGitHubの内部リポジトリを流出させ、そのデータセットをアンダーグラウンドフォーラムで販売していると報じられています。BleepingComputerの報道によると、侵入経路は公式マーケットプレイスから提供された悪意あるVS Code拡張機能でした。GitHubは、内部リポジトリ以外の顧客データへの影響を示す証拠は見つかっていないと述べています。
この話から学ぶべきことは、「GitHubを使うな」ではありません。確認すべきなのは次の点です。
- APIドキュメントはどこで管理されているか
- 誰が書き込み権限を持つか
- 公開済みドキュメントを誰が読めるか
- 公開された内容がレビュー済みソースと一致するか
- API仕様がライブAPIと同期しているか
APIドキュメントは単なる説明ではありません。利用者はエンドポイントURL、リクエスト形式、認証ヘッダー、サンプルコードをそのまま実装にコピーします。攻撃者がそれらを変更できれば、マーケティングページを改ざんしているのではなく、他人が本番環境で実行するコードの指示を書き換えていることになります。
同じ観点は、Vercel侵害から得られたAPIセキュリティの教訓でも扱っています。また、関連するテーマとして、GitHubの侵害が自己ホスト型APIツールに与える意味とVS Code拡張機能のAPIキーセキュリティも参照してください。
APIドキュメントが侵害された場合に起こること
APIドキュメントは次の場所に存在します。
- Gitリポジトリ
- CI/CDパイプライン
- 静的ホスト
- ドキュメント生成ツール
- OpenAPI仕様ファイル
- 公開済みHTMLページ
このどれかが侵害されると、実装者に直接影響します。
1. 改ざんされたエンドポイントが本番コードに入る
攻撃者がドキュメントリポジトリまたはホストに書き込める場合、次のような変更が可能です。
-
https://api.payments.acme.com/v2/chargeを攻撃者のドメインに変更する - OAuthトークン交換URLを別のURLに書き換える
- サンプルのBearerトークンやAPIキーの扱いを変更する
- SDK生成元のOpenAPI
serversURLを書き換える
例:
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 を変更した場合、OpenAPI仕様からクライアントを再生成する利用者は、意図せず攻撃者のドメインへリクエストを送る可能性があります。
差分は小さくても、影響は大きくなります。
- url: https://api.acme-pay.com
+ url: https://api-acme-pay.example-attacker.com
レビューで「ただのドキュメント変更」として流すと、この種の変更は見逃されます。
2. 内部エンドポイントが流出する
ドキュメントリポジトリには、次のような情報が混ざりがちです。
- 管理者向けAPI
- デバッグ用エンドポイント
- パートナー専用API
- 未公開の新機能
- 内部パラメータ
- 本番環境の実URL
- テスト用トークンやサンプル資格情報
公開リポジトリ、設定ミスした静的ホスト、または侵害されたプライベートリポジトリにこれらが含まれていると、攻撃者にAPIの地図を渡すことになります。
この観点で棚卸しする場合は、2026年APIセキュリティテストチェックリストのように、エンドポイント、認証、権限、データ露出をまとめて確認してください。
3. 公開GitHub Pagesにはアクセス制御がない
GitHub Pagesは便利な静的ホストです。ただし、アクセス制御はありません。
公開APIなら問題ありません。しかし、次のようなドキュメントには不十分です。
- 有料顧客向けAPI
- パートナー限定API
- 社内API
- ベータ機能
- 契約者だけに見せる仕様
「URLを知っている人だけがアクセスできる」はアクセス制御ではありません。URLは次の経路で漏れます。
- ブラウザ履歴
- リファラーヘッダー
- プロキシログ
- 共有ブックマーク
- チャットログ
- スクリーンショット
- サポートチケット
アクセス制御が必要なドキュメントをGitHub Pagesだけで配信する場合、別途ゲートを設計する必要があります。
4. 古いドキュメントと改ざんの区別がつかなくなる
攻撃者がいなくても、APIドキュメントは簡単に古くなります。
よくある原因:
- API変更後にOpenAPI仕様を更新していない
- 手動編集したMarkdownが実装と乖離している
- v1/v2の仕様が混ざっている
- 廃止済みエンドポイントが残っている
- サンプルレスポンスが現在のスキーマと違う
問題は、ドキュメントが古いのか、改ざんされたのかを判断できなくなることです。
確認すべき問い:
- このエンドポイントURLはいつ変更されたか
- 誰が変更したか
- 変更はレビューされたか
- ライブAPIと仕様は一致しているか
- 公開済みHTMLはレビュー済みソースから生成されたか
これに答えられない場合、ドキュメントは検証不能です。
GitでのDocs-as-codeが有効な場合
Docs-as-codeは有効な運用です。OpenAPI仕様とMarkdownをGitで管理し、CIでSwagger UIやRedocをビルドし、静的ホストへデプロイする構成にはメリットがあります。
メリット:
- Pull Requestでレビューできる
- Git履歴が残る
- コードとドキュメントを同じフローで管理できる
- CIでlintやスキーマ検証を実行できる
- 変更差分を明確に確認できる
この方式が適している条件は次のとおりです。
- APIが完全に公開されている
- ドキュメントに隠すべき情報がない
- リポジトリにブランチ保護がある
- 変更には必須レビューがある
- 書き込み権限を持つ人数が最小限
- CIのデプロイ資格情報が最小権限
- 外部GitHub ActionsやCIステップを固定バージョンで使っている
- OpenAPI仕様がライブAPIから生成、またはライブAPIに対して検証されている
- ドキュメント更新の責任者が明確
この条件を満たすなら、Gitベースのドキュメントは透明性が高く、レビュー可能な仕組みです。
GitでのDocs-as-codeが負債になる場合
同じ構成でも、次の状態ならリスクが高くなります。
- パートナー限定ドキュメントを実質公開URLで配信している
- 「リンクを知られなければ安全」と考えている
- 書き込み権限を持つユーザーやCIトークンが多い
- ドキュメント変更が十分にレビューされない
- OpenAPI仕様を手動で編集している
- ライブAPIとの同期確認がない
- 内部APIと公開APIが同じ仕様ファイルに混在している
- 公開済みサイトがどのコミットから生成されたか追跡できない
- デプロイ後の改ざん検知がない
Gitは変更履歴を提供しますが、リポジトリ自体が流出した場合の機密性は提供しません。また、静的ホストに公開された内容がレビュー済みソースと一致しているかは、別途検証が必要です。
自己ホスト型ドキュメントの選択肢を比較したい場合は、自己ホスト型APIドキュメント比較を参照してください。
セキュアなAPIドキュメントのチェックリスト
「セキュアなAPIドキュメント」を実装レベルに分解すると、次の4つです。
1. アクセス制御
確認すること:
- 誰がドキュメントを読めるか説明できるか
- 退職者や契約終了したパートナーのアクセスをすぐ取り消せるか
- 公開、顧客限定、社内限定を分離しているか
- URLの不明瞭さに依存していないか
実装例:
- パスワード保護
- IP許可リスト
- メール許可リスト
- SSO
- カスタム認証
- VPN経由のアクセス制限
2. バージョン管理
確認すること:
- v1利用者がv1ドキュメントを見られるか
- v2公開後も古いドキュメントが消えないか
- 特定の日付のドキュメント内容を再現できるか
- 破壊的変更が明示されているか
実装例:
/docs/v1
/docs/v2
/docs/beta
または、ドキュメントツール側で複数バージョンを並行公開します。
3. 整合性
確認すること:
- 公開ドキュメントは信頼できるAPI定義から生成されているか
- OpenAPI仕様はライブAPIと一致しているか
- 手動編集されたMarkdownが仕様と矛盾していないか
- 公開後にファイルが直接書き換えられていないか
CIで最低限入れたい検証:
# 例: OpenAPI仕様のlint
name: Validate OpenAPI
on:
pull_request:
paths:
- "openapi.yaml"
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Lint OpenAPI
run: npx @redocly/cli lint openapi.yaml
加えて、servers.url や認証URLの変更はレビューで目視確認すべきです。
4. 監査証跡
確認すること:
- 誰が変更したか分かるか
- いつ公開されたか分かるか
- どのバージョンが公開中か分かるか
- 過去90日間の変更ログを出せるか
- デプロイ済みサイトとソースの対応を追跡できるか
Git履歴だけでなく、公開ステップの履歴も必要です。
ApidogでセキュアなAPIドキュメントを公開する
Apidogは、API設計、デバッグ、テスト、モック、ドキュメント作成をまとめて扱うAPIプラットフォームです。ドキュメントはAPI設計から生成されるため、手動Markdownだけで運用するよりも仕様との乖離を抑えやすくなります。
試す場合は、Apidogをダウンロードし、API定義を含むプロジェクトを開きます。
手順1: API設計からドキュメントを生成する
Apidogでは、エンドポイント、スキーマ、認証設定をプロジェクト内で管理します。その定義からドキュメントを自動生成できます。
基本フロー:
- Apidogでプロジェクトを開く
- APIエンドポイント、リクエスト、レスポンス、認証を定義する
- ドキュメントプレビューで内容を確認する
- 公開設定を選ぶ
- ドキュメントを公開する
公開されたドキュメントには、インタラクティブな「試す」コンソールやコードサンプルを含められます。
手順2: アクセス制御を設定する
Apidogでは、公開時に表示範囲を選択できます。
利用できる主な方法:
- 公開: リンクを知っている人が閲覧できる。完全公開API向け。
- パスワード保護: パスワードを知っている人だけが閲覧できる。
- IP許可リスト: オフィス、VPN、特定ネットワークからのみアクセスを許可する。
- メール許可リスト: 許可したメールアドレスまたはドメインのユーザーだけがアクセスできる。
- カスタムログイン: 独自認証システムと接続し、JWTなどでアクセスを制御する。
例:
公開API -> 公開
顧客向けAPI -> メール許可リスト
社内API -> IP許可リスト + VPN
一時共有 -> パスワード保護
独自認証が必要 -> カスタムログイン
詳細はAPIドキュメントアクセス制御ガイドを参照してください。
手順3: カスタムドメインを設定する
公開ドキュメントは独自ドメインで提供できます。たとえば次のようなURLです。
https://developer.yourcompany.com
https://docs.yourcompany.com
Apidogは、DNS CNAMEまたはリバースプロキシ経由のカスタムドメインをサポートしています。
カスタムドメイン自体はアクセス制御ではありませんが、ドキュメントの所在を明確にし、利用者が公式ドキュメントを識別しやすくなります。
手順4: OpenAPI仕様を同期する
ドキュメントの乖離を防ぐには、API設計を信頼できる情報源にする必要があります。
Apidogでは次の形式を扱えます。
- OpenAPI 3.0
- OpenAPI 3.1
- Swagger 2.0
外部仕様をインポートし、スケジュールされたインポートで最新状態を保つ運用もできます。
現在、GitリポジトリでOpenAPI仕様を手動管理している場合は、次を確認してください。
- 仕様の更新責任者は誰か
- ライブAPIとの検証はあるか
- 変更レビューは必須か
- 公開ドキュメントは最新仕様から生成されているか
SwaggerHubから移行する場合は、SwaggerHub APIドキュメントをApidogに移行するガイドを参照してください。
手順5: ドキュメントをバージョン管理する
Apidogは複数バージョンのドキュメント公開をサポートしています。
例:
v1: 既存顧客向け
v2: 新規利用者向け
beta: パートナー検証向け
v2を公開した後も、v1利用者はv1ドキュメントを参照できます。これにより、古いAPI利用者が誤って新しい仕様を実装するリスクを減らせます。
ドキュメントホスティングオプションの比較
| 特性 | 公開GitHub Pages（Swagger UI / Redoc） | 自身のサーバーでの自己ホスト型ドキュメント | マネージド型ドキュメント（Apidog） |
|---|---|---|---|
| アクセス制御 | なし；URLの不明瞭さのみ | 構築・維持するものによる | 組み込み：パスワード、IP、メール、カスタムログイン |
| バージョン管理 | 手動；個別のビルドまたはブランチ | 手動 | 組み込み；バージョンは並行して公開 |
| 整合性 | Gitレビュー + 履歴（強制されている場合） | パイプラインによる | 管理されたAPI設計からドキュメントを生成 |
| 監査証跡 | リポジトリのGit履歴、デプロイ用ではない | ロギングによる | 設計および公開ドキュメントの変更履歴 |
| メンテナンスコスト | セットアップは低いが、パイプラインの維持には継続的な費用 | 高い；スタック全体を所有 | 低い；プラットフォームがホスティングとゲートを処理 |
| 最適な用途 | 完全に公開されたAPI、規律のあるパイプライン | 厳格な自己ホスティング要件を持つチーム | 運用オーバーヘッドなしでアクセス制御が必要なチーム |
公開APIで、CI/CDとレビューが厳格に運用されているなら、GitHub Pagesは十分な選択肢です。厳しい分離要件やデータ所在地要件があるなら、自己ホスト型も選択肢になります。
より詳しい比較は、自己ホスト型APIドキュメント比較とScalar vs SwaggerHub vs Apidog比較を参照してください。
重要なのは、昔作ったドキュメント公開フローをそのまま放置しないことです。
今すぐ実施する監査手順
まず、ドキュメントの公開場所を棚卸しします。
- GitHub Pages
- S3 / CloudFront
- Netlify / Vercel
- 社内Wiki
- Swagger UI
- Redoc
- Apidog
- 顧客向けポータル
- README内のAPI説明
次に、それぞれについて確認します。
1. 誰が読めるか
2. 誰が書き込めるか
3. 変更レビューはあるか
4. 公開済み内容はどのソースから生成されたか
5. OpenAPI仕様はライブAPIと一致しているか
6. 内部エンドポイントが混ざっていないか
7. 過去のバージョンを参照できるか
8. アクセス権をすぐ取り消せるか
最後に、ギャップを埋めます。
- アクセス制御がない → パスワード、IP制限、メール許可リスト、SSOを追加
- 仕様が古い → API設計とドキュメント生成元を統一
- バージョンがない → v1/v2を分離して公開
- レビューが弱い → URL、認証、サンプルコードの変更を必須レビュー対象にする
- 公開先が不明 → カスタムドメインと所有者を明確化
結論
GitHubの侵害は、Docs-as-codeをやめる理由ではありません。見直すべきなのは、APIドキュメントがどこにあり、誰が変更でき、誰が読めるかです。
API利用者は、あなたのドキュメントを信頼してコードを書きます。だからこそ、API本体と同じようにドキュメントにもアクセス制御、バージョン管理、整合性、監査証跡が必要です。
次のアクションはシンプルです。
- APIドキュメントの公開場所をすべてリストアップする
- 4つの特性で評価する
- 最大のギャップから修正する
- アクセス制御が不足している場合は、Apidogでパスワード保護またはメール許可リスト付きのドキュメント公開を試す
Top comments (0)