superior-api-security

優れた API セキュリティ

文書化された契約を維持しながら、サーバー側の信頼境界で API を保護します。実際のアクター、リソース、ビジネスへの影響、デプロイトポロジー、既存のセキュリティアーキテクチャに基づいて制御を決定し、チェックリストを満たすためだけにセキュリティミドルウェアを追加しないでください。

セキュリティ契約を確立する

コードを変更する前に、次の点を特定します。

• 公開されている操作、バージョン、利用者。
• パブリック、認証済み、特権付き、内部、Webhook、マシン間の各呼び出し元。
• 機密性の高いリソース、プロパティ、アクション、ビジネスフロー。
• ID が確立される場所と、認可が適用される場所。
• プロキシ、ゲートウェイ、キャッシュ、キュー、サードパーティーサービス、アウトバウンドのネットワークアクセス。
• 想定されるトラフィック、バースト時の挙動、ペイロードサイズ、操作のコスト、障害への許容度。
• インフラストラクチャが担うセキュリティ制御と、アプリケーションが担うセキュリティ制御。

実際のリクエスト経路をたどります。設定と挙動を確認するまでは、ゲートウェイ、フレームワークのデフォルト、クライアント側のチェックが要件を適用していると思い込まないでください。

リスクに基づいて制御を選択する

認証、オブジェクト／機能／プロパティの認可、入力と出力の境界、リソース消費、機密性の高いビジネスフロー、SSRF、ブラウザー向けの制御、エラー、シークレット、インベントリ、サードパーティー API の利用については、references/api-security-controls.md を参照してください。

呼び出し元が次のことを行えないようにする制御を優先します。

• 他人の ID として、または付与された権限の範囲外で動作する。
• 別の主体のオブジェクトを読み取る、または変更する。
• アクセスが許可されていないプロパティを設定する、または受け取る。
• 特権付きの操作を呼び出す、またはワークフローの不変条件を回避する。
• 計算リソース、ストレージ、帯域幅、有料連携、または希少な在庫を枯渇させる。
• サーバーに意図しない宛先へアクセスさせる。
• 応答、ログ、タイミング、メタデータを通じて機密性の高い内部情報を知る。

保守されている ID、暗号化、スキーマ検証、シークレット管理のライブラリを維持してください。トークン形式、署名方式、パスワード保存方式、暗号化プロトコルを独自に考案しないでください。

セッション、ベアラートークン、更新またはリセット用の認証情報、API キー、署名付き Webhook、キーのローテーション、失効、リプレイ耐性が対象となる場合は、references/session-token-and-webhook-security.md を参照してください。

レート制限と不正利用対策を慎重に適用する

レート制限、スロットリング、クォータ、同時実行数の上限、認証情報への攻撃、スクレイピング、スパム、列挙、コストの高い操作、機密性の高いビジネスフローの自動化が対象となる場合は、references/rate-limiting-and-abuse-controls.md を参照してください。

有効な制限では、次のすべてを定義します。

• 制御対象の操作と、それによる被害。
• 計上に使用する ID の要素。
• 継続的な許容量、バースト時の許容量、同時実行数、コストの重み付け。
• カウンターの保存場所と、分散インスタンス間の連携方法。
• リミッターまたはカウンターストアが障害を起こした場合の挙動。
• 拒否時の契約、可観測性、例外、復旧手順。
• 制限の適用と、正当なバーストへの許容の両方を実証するテスト。

認証済みまたは分散型の不正利用に対して、IP アドレスごとのリクエスト数だけでは不十分なことがほとんどです。リクエストレートを制限しても、ペイロードサイズ、クエリの複雑さ、バッチサイズ、実行時間、下流のコスト、同時処理中の作業は制限できません。

レスポンスとテレメトリを安全に保つ

• 確立された HTTP セマンティクスとプロジェクトのエラースキーマを使用します。アプリケーションレベルのレート制限による拒否には 429 Too Many Requests を返し、意味のある再試行時刻がわかっている場合は Retry-After を含めます。
• スタックトレース、シークレット、クエリ、内部ホスト名、トークンの内容、認可ポリシーの詳細を漏らすことなく、クライアントに安定した、対処可能なエラー識別子を返します。
• セキュリティに関わる結果は、リクエストまたはトレースの相関情報、許可される場合はアクターとテナントの識別子、制御上の判断、サニタイズ済みの理由コードとともに記録します。
• 認証情報、セッショントークン、API キー、生の認可ヘッダー、パスワードリセット用の成果物、不要な機密ペイロードは記録しません。
• クライアントに表示する詳細と診断用の詳細を分離し、リポジトリのプライバシーおよび保持に関するルールに従います。

保護を主張する前に検証する

脅威に基づくテストマトリクスについては、references/security-verification.md を参照してください。これには、認可の否定テスト、トークン検証、スキーマ変更、リソース制限、リミッターの動作、並行実行、SSRF、エラー情報の開示、プロキシ境界の確認が含まれます。

セキュリティ対応の完了には、実際に有効な適用ポイントでの証拠が必要です。範囲を絞った有意義な自動テストに加え、デプロイ後の経路を検証する設定チェックまたは統合チェックを実行します。設計のみの作業では、テストを保護の証拠ではなく、提案された検証計画として明記します。他の場所で適用される制御、未検証の前提、ロールアウトのリスク、リリース後に必要なモニタリングを報告します。

スキルを必要な範囲に絞って組み合わせる

• セキュリティが、より広範な差分、ブランチ、またはプルリクエストのレビューにおけるリスク領域の一つである場合は、superior-code-review を使用します。
• 業務上の不変条件、永続化、トランザクション、冪等性、またはドメインの動作も変更する場合は、superior-logic を使用します。
• 適用がテナントスコープのスキーマ、制約、クエリの所有権、インデックス、マイグレーション、または機密データの保存に依存する場合は、superior-database を使用します。
• セキュリティ関連のリソース制御に、代表的な容量、レイテンシ、または飽和度の測定が必要な場合は、superior-performance を使用します。
• セキュリティ境界をパイプラインの ID、アーティファクトの来歴、公開、またはデプロイ用認証情報が担う場合は、superior-delivery を使用します。
• 不正利用、依存関係の障害、または復旧において、明示された可用性目標を維持する必要がある場合は、superior-reliability を使用します。
• セキュリティ上の否定テスト用フィクスチャ、分離、並行実行、またはデプロイ済み境界のテスト設計が主な懸念事項である場合は、superior-testing を使用します。
• セキュリティモデル、公開契約、運用設定、またはインシデント対応に関わる手順を継続的に変更する場合は、superior-docs を使用します。
• 不要なセキュリティ機構を避けるには superior-lean を使用します。ただし、特定したリスクに必要な制御を簡略化して取り除いてはなりません。

明示的な許可がない限り、セキュリティレビューを無関係な侵入テスト、インフラストラクチャの変更、本番トラフィックを使った実験に拡大しないでください。