開発者向けのセキュリティ文書を書き、レビューする

## 開発者がすぐ使える助言を、セキュリティの話に絞って書く セキュリティ専門家ではなく、開発者に向けて書く。ガイダンスは正確、実践的、簡潔で、明確な見解を示すものにする。理論上は最善でも複雑すぎて実行しにくい助言より、開発者が適用できる良い助言を優先する。 すべての推奨事項を、その文書のセキュリティ脅威モデルの範囲内に保つ。一般的なコード品質、性能、アーキテクチャに関する助言は、セキュリティリスクを直接抑える場合を除き、別の場所で扱う。 すべての執筆ツールに対し、コントリビューション規則を必須として扱う。リポジトリにおける正式な人間向けプロセスと執筆ガイドを維持し、短いエージェント向けガイドは運用上の要約としてのみ使う。 ## 引用する情報源を全部読み、主張を裏づけているか確かめる 引用する情報源はすべて取得して読み、対象の主張を正確に裏づけていることを確認する。URLを創作したり推測したりしてはならず、無関係なランディングページへ転送されるページを引用してはならない。また、学習時の記憶や要約に頼ってはならない。裏づけとなる証拠を含む具体的なページまたはセクションへリンクする。 内部の相互リンクは使用前に確認する。存在しない文書やアンカーを参照してはならない。 引用密度のゲートが適用される場合、新しい各H2セクションに少なくとも1件のインラインHTTPS引用を含める。新規性がある、意外性がある、特定のパラメータに依存する、または異論の余地がある主張には、それぞれ独立した根拠を示す。確立された一般的慣行については、すべての文に引用を付ける必要はない。情報源は本文内に置いても、参考文献セクションにまとめてもよい。 標準規格、政府または業界のセキュリティガイダンス、公式のプロジェクト文書やベンダー文書、十分に保守されたプラットフォーム資料、正本となるソースリポジトリ、査読済み研究を優先する。検索流入だけを狙ったマーケティングサイトは避ける。引用ゲートは最低条件であり、内容の正しさを証明するものではない。 ## 脅威ごとに対策を書き、防げない事もはっきり書く 引用は必要だが、それだけでは十分ではない。すべての脅威に具体的な対策を対応づけ、その制御が何を防ぎ、何を防がないのかを明示する。 明確な注意書きなしに、定められた脅威モデルの外にある攻撃を持ち込んではならない。ある層に対する制御を、別の層での侵害まで防ぐものとして提示してはならない。 実際にセキュリティ制御またはセキュリティリスクに当たるガイダンスだけを追加する。正しさ、開発者にとっての実用性、トピックとの関連性は個別にレビューする。十分に引用されていても誤った推奨事項は却下しなければならない。 ## 1回の変更を小さく保ち、同じ内容はコピーせずリンクする 1件の変更は、1つのガイダンス文書、または小規模で明確に連携した文書群に限定する。リポジトリが上限として定めている場合、承認済みの追跡用Issueがなければ、コンテンツ文書3件または純増1,500行を超えてはならない。依存関係、オートメーション、誤字だけの変更には、それぞれ固有の範囲規則を適用する。 デフォルトブランチを基にしたクリーンなブランチから始め、1ブランチにつき1トピックに絞る。無関係な変更が相互に混入する可能性があるため、同じブランチから2件の変更リクエストを作ってはならない。新しいガイダンス文書や大幅に書き直した文書を提案する前に、承認済みのIssueを必須とする。 ついでの書式変更、一括編集、無関係な修正をまとめてはならない。セクションを追加する前に、現在の文書、関連文書、リポジトリの索引を検索する。既存のガイダンスを再掲せず、リンクして参照する。 意図して設計されたハブ・アンド・スポーク型の文書群は維持する。連携した相互リンクは有効だが、別文書のガイダンスをコピーしてはならない。内容が別のトピックに属する場合、現在の範囲を無理に広げず、適切な既存文書または新規文書へ移す。 ## 設計の考え方を先に書き、コードは必要な話題だけに使う 一般的なトピックでは、言語固有のコードより、アーキテクチャパターン、設計原則、セキュリティ上の判断を優先する。コードはすぐに古くなり、切り離されたスニペットは本来の文脈なしにコピーされると安全でない場合がある。 トピックが本質的に特定言語向け、インジェクション対策、パラメータ化、または具体的な堅牢化に関するものであれば、コードを積極的に使う。実行可能な詳細自体がセキュリティガイダンスであり、付随的な定型コードではない場合は、コードの比率が高くてもよい。 例示用コードは短く保ち、実用上可能ならフェンス付きブロックに言語を指定する。実運用向けの基準で設計・レビューされていない例を、実運用向けとして提示してはならない。 ## 中身のない前置きを省き、1つのやり方をはっきり勧める 一般論だけの前置き、繰り返しの背景説明、網羅的な選択肢一覧、流行に乗っただけで中身のない導入は省く。特定の方法を推奨し、開発者が安全に適用するために必要な文脈だけを説明する。 米国英語を使い、スペルと用語のチェックを実行し、非ネイティブの読者にも理解しやすい文にする。自明でない略語は最初の使用時に定義する一方、スタイルガイドが認める場合は、広く知られたプロトコルやロケーターの略語を説明しなくてもよい。 一般的な自動生成文のように見える文章は書き直すか、対象から外す。簡潔にするために、制約、例外、脅威の境界、または推奨事項の方が安全である理由を失ってはならない。 ## リポジトリのMarkdownと画像の決まりに従う Markdownを使い、`details`や`summary`など明示的に許可された要素を除いて、生のHTMLは避ける。ハイフンの箇条書き、Markdownの太字、引用ブロックを一貫して使う。すべての見出しの後に空行を置く。 一般的な文書は1つのH1と「はじめに」で始まり、焦点を絞ったH2セクションへ続き、最後に参考文献を置くことがある。H2セクションは3〜6件が有用な既定値だが、厳格な上限ではない。公開ツールが目次を生成する場合、手動の目次を追加してはならない。 リポジトリのファイル名規約に従う。文字、数字、ハイフン、アンダースコアだけを使い、`_Cheat_Sheet.md`など必須の接尾辞は維持する。新しい文書は承認済みテンプレートから始める。 アセットは指定されたアセットディレクトリに保存する。承認済みの画像形式を使い、意味のある代替テキストを付け、正しい相対パスでアセットを参照する。リンクは内容が分かるラベルとともにインラインで記述し、可能な限りHTTPSを使う。 ## レビューを頼む前に、リントとリンクのチェックを通す 変更を提案する前に、リポジトリで定められたMarkdownリント、用語チェック、リンクチェッカーを実行する。変更したコンテンツに適用される範囲、引用密度、その他のポリシーゲートも実行する。 ローカルまたは継続的インテグレーションのチェック失敗は、ゲートを回避する理由ではなく、調査すべき不具合として扱う。生成処理や自動処理による変更に無関係な編集が紛れていないか、最終差分をレビューする。 自動化の限界を理解する。機械的チェックは、不正なMarkdown、許可されていない用語、無効なリンク、過大な範囲、引用パターンの不足を検出できる。しかし、情報源が主張を裏づけているか、助言が正しいか、そのトピックが文書に含まれるべきか、既存ガイダンスと重複しているかは判断できない。 ## AIを使った事を書き、いくつもの観点でレビューする 重要なAI支援は変更リクエストの説明で開示する。リポジトリで指定された開示セクションに、ツール名、判明しているバージョン、プロンプトを記録する。この要件はすべてのAIツールに適用され、開示しなければコントリビューションが無効になる場合がある。 セキュリティガイダンスを、セキュリティ上の正しさ、開発者にとっての実用性、情報源とリンクの品質、重複と配置、文章の品質という別々の観点からレビューする。専門分野ごとのレビュー担当者が個別に作業してもよいが、指摘は証拠に基づく1つの判定へ統合する。 承認、変更要求、終了など、明示的な結果を使う。ブロック対象の指摘には具体的な証拠を示し、機械的な失敗と判断上の失敗を区別する。引用や自動チェックが存在するという理由だけで承認してはならない。