公開ドキュメントの鍵漏えいを防ぐ：開発者ポータル向け実装ガイド

HNで話題になった「公開ドキュメント上の管理キー露出」は、特定企業だけの事故ではありません。開発者向け情報公開を行う組織なら、どこでも起こり得る供給側セキュリティ事故です。

多くの組織は本番CI/CDの秘密管理には投資しています。一方で、ドキュメント生成・公開パイプラインは後回しになりがちです。この差が漏えいの主要経路になっています。

漏えいが起きる典型経路

• 実運用環境変数をそのままサンプルへ貼る
• SDK自動生成時に検証用実キーが混入
• markdown移行で過去スニペットが再露出
• 検索インデクサが非公開下書きを取り込む

発見時には既にクローラやミラーへ拡散していることが多く、被害最小化が難しくなります。

予防アーキテクチャ（4層）

1. 執筆時ガードレール

• エディタ拡張で高確度パターン検出
• プレースホルダ強制テンプレート（YOUR_API_KEY など）
• docsリポジトリのpre-commitスキャン

2. ビルド時強制

• docs CIで秘密情報スキャンをハードフェイル
• 差分対象だけでなく生成HTMLも検査
• エントロピー＋文脈正規表現の併用

3. 公開時ポリシー

• 重大検知が残る場合はデプロイ停止
• 例外はチケット化して期限付き許可
• 公開物に provenance（生成経路）を付与

4. 公開後監視

• 本番ドメインの定期再スキャン
• クロール観測に基づくスナップショット検査
• 露出確認時の自動失効と通知

サンプルキー設計ルール

マスクでは不十分です。実在しないことを機械的に保証するフォーマットを採用します。

• サンプル専用プレフィックス
• バックエンド検証で必ず弾くチェックサム
• SDK内で EXAMPLE_ONLY=true を保持

これにより、利用者にも検知器にも曖昧さを残しません。

体制設計

責任分界を明示します。

• DevRel：テンプレート衛生管理
• Platform：CIゲートとPolicy as Code
• Security：検知ロジック・失効手順
• Product：上流fixtureの安全性

「みんなで見る」は、実務では「誰も見ない」になりがちです。

KPI

• 発見から失効までの時間
• 重大検知による公開ブロック件数
• 検知器の誤検知率
• 強制ゲート適用済みdocs repo比率
• チーム別再発率

まとめ

ドキュメントは非本番資産ではなく、攻撃面を持つ本番資産です。執筆・ビルド・公開・事後失効を一体運用し、アプリコード同様にバージョン管理することが、漏えい再発を最短で減らす現実解です。