incu-way-security-validation

セキュリティ検証プロセス

コード全体（モジュール、サービス、または現在のブランチでの変更）を、確立されたセキュリティルールセット（OWASP Top 10、OWASP ASVS、OWASP API Security Top 10、CWE Top 25）に照らして、管理策ごとに確認し、その結果を追跡可能なコンプライアンスレポートにまとめる、ゲート主導のワークフローです。出力は docs/security/validation/{slug}/VALIDATION.md に保存されます。

これは snyk-remediation とは異なる、標準／ルールセットのレビューです。

• snyk-remediation は自動 SAST／SCA スキャナーを実行し、検出された問題を修正します。
• このフローでは、選択した標準に対して手動で管理策ごとに検証します。スキャナーが見逃す設計やロジックの問題（アクセス制御の不備、安全でないビジネスフロー、認可チェックの欠落、脆弱な暗号方式の選択など）を検出し、各管理策にコードを対応付けて、合否判定と証拠を示します。

網羅性を高めるため、両方を実行してください。このフローは評価を行います。デフォルトでは修正しません。具体的な修正は、後続の incu-way-development／incu-way-bugs／snyk-remediation の作業項目です。

呼び出し方法は2通りあります。

• 単独実行（標準に照らした監査）： 独自のブランチ assess/secval-{slug} を作成し、develop に PR を出します。
• 別のフローへの組み込み： 呼び出し元の現在のブランチ／ワークツリーに書き込み、レポートはそのフローの PR に含めます。別のブランチや PR は作成しません。例：incu-way-development で Gate 3 にて新しいコードを検証し、Snyk／Sonar スキャンと併せて実施します。

これは評価フローです。incu-way-docs と同様、.ways/state.json は管理しません。

---

リポジトリの適格性チェック（最初に実施）

Phase 0 の前に、現在のリポジトリが ~/.ways/config.yaml の blacklist に該当するか確認します（形式は incu-base の global-config ルールに準拠し、常時インストールされています）。該当する場合は、このリポジトリが incu-way のブラックリストに登録されていることをユーザーに伝え、例外として今回のみ続行するか、中止するかを尋ねます。回答があるまでは、どのフェーズも実行しないでください。ファイルが存在しない場合、または該当しない場合は、通常どおり続行します。

---

Phase 0 — スコープとルールセットの選定

目標： 何を、どの標準に照らして検証するかを、評価を始める前に決定します。 読み取り専用です。

事前確認

1. 対象を確認します。リポジトリ全体、モジュール／サービス、または現在のブランチの差分（新しいコード — git diff develop...HEAD）のいずれかです。
2. 対象と技術に応じて、ルールセットを選択します。
   • OWASP Top 10 (2021) — 一般的な Web アプリのベースライン（ほとんどのコードでデフォルト）。
   • OWASP API Security Top 10 (2023) — 対象が API を公開する場合。
   • OWASP ASVS — 正式な検証レベル（L1／L2／L3）が必要な場合。
   • CWE Top 25 — 言語に依存しない脆弱性のベースライン。
3. 既存のセキュリティコンテキスト（docs/security/、過去の VALIDATION.md、脅威モデル、CLAUDE.md のセキュリティセクション）を先に確認し、決着済みの項目を再検討しないようにするとともに、すでに作成された脅威モデルとの整合性を取ります（incu-way-threat-model を参照）。

対象の調査

この段階では評価せず、調査のみ行います。エントリーポイントとルート、認証とセッション管理、認可チェック、入力処理と検証、出力エンコーディング、データアクセス（クエリ、ORM の使用）、シークレットと設定、暗号の使用、ファイル／ネットワーク／外部呼び出し、エラー処理とログ記録（機密データが漏えいしないかも含む）、使用中の依存関係を調査します。

Phase 0 の終了条件

Gate 1 の前に、Claude は次の内容を説明できる必要があります。

• 対象と、それがリポジトリ全体、モジュール、ブランチ差分のいずれであるか
• 適用するルールセット（複数可）、および（ASVS の場合）適用するレベルとその理由
• 対象に含まれる関連エントリーポイント、信頼境界、機密性の高い操作
• 参照した既存のセキュリティ文書／脅威モデル
• 不明点がある領域と、推測で済ませず未解決の質問として記載する項目

名前やコメントだけを根拠に、管理策に合格したと判断してはいけません。コードで管理策が実証されていない場合は、不合格とするか、未解決の質問として扱います。合格と推定してはいけません。

ゲート 1 — ルールセットと範囲の確認

対象とルールセットを提示します。

## Proposed security validation

- **Target:** {repo | module X | current branch diff}
- **Ruleset(s):** {OWASP Top 10 2021 | OWASP API Top 10 2023 | OWASP ASVS L{1/2/3} | CWE Top 25}
- **Relevant surface:** {entry points / APIs / auth / data access in scope}
- **Out of scope:** {what this pass will not cover}
- **Relationship to scans:** {complements Snyk SAST/SCA — not a replacement}
- **Open questions:** {anything ambiguous}

• 次のように尋ねます。「これは、{target} のセキュリティ検証の範囲とルールセットです。検証を開始する前に確認してください。」
• 停止します。ユーザーが範囲とルールセットを確認するまで、検証を実施してはいけません。

---

分離の設定（スタンドアロンモードのみ）

別のフローに組み込まれている場合は、これをスキップし、既存のブランチ／ワークツリーに書き込みます。

スタンドアロンで実行する場合は、書き込む前に作業をどのように分離するかをユーザーに尋ねます。

現在のチェックアウトに新しいブランチを作成して作業しますか。それとも、別の git worktree を作成しますか。

ユーザーの回答をそのまま使用します。 質問した後は停止し、ユーザーが選択するまでブランチやワークツリーを作成してはいけません。

現在のチェックアウトに未コミットの変更がある場合は、ブランチの切り替えやワークツリーの作成を行う前に停止し、確認を求めます。

オプション A — 現在のチェックアウトにブランチを作成

# Run from the repo root
git switch develop
git pull --ff-only
git switch -c assess/secval-{slug}

オプション B — 別のワークツリー

ワークツリーは .worktrees/ の下にのみ作成します。ユーザーにパスを尋ねてはいけません。

# Run from the repo root
git fetch origin develop
mkdir -p .worktrees
git worktree add .worktrees/assess-secval-{slug} -b assess/secval-{slug} origin/develop

{slug} は {YYYY-MM-DD}-{kebab-target} です（例：2026-06-17-checkout-api）。すべての出力は、選択した作業場所内に書き込み、コミットします。

---

フェーズ 2 — コントロールごとに検証

目標： 選択したルールセットの各コントロールを実際のコードに照らして確認し、VALIDATION.md を作成します。

検証ルール（必須）

• すべてのコントロールに判定を付けます。 Pass／Fail／N/A／Needs review のいずれかとします。コントロールを黙って省略してはいけません。
• 追跡可能にします。 Pass ではコントロールを実装しているコード（path:line）を示し、Fail では脆弱なコードを示します。N/A では、そのコントロールが該当しない理由を明記します。読者が各判定を検証できるようにします。
• 根拠なしに Pass と判定しません。 根拠がない場合は Pass ではありません。コントロールを確認できない場合は Pass ではなく Needs review とします。
• ラベルだけでなく影響を記載します。 各 Fail には、攻撃者が何を実行できるか、および CWE を記載します。
• 修正ではなく推奨を行います。 各 Fail に具体的な修正案を示します。このフローではコードを変更しません。

VALIDATION.md の構成

# Security Validation — {target}

## Scope
- Target: {repo | module | branch diff}
- Ruleset(s): {…}  (ASVS level: {L1/L2/L3} if applicable)
- Date: {YYYY-MM-DD}
- Branch validated: {branch}

## Summary
- Controls evaluated: {N}  (Pass: X, Fail: Y, N/A: Z, Needs review: W)
- Findings by severity: Critical X, High Y, Medium Z, Low W

## Control checklist — {ruleset name}
| Control | Verdict | Evidence | Notes |
|---------|---------|----------|-------|
| A01 Broken Access Control | Fail | `src/api/orders.ts:30` — no ownership check on GET /orders/:id | IDOR: any user reads any order |
| A02 Cryptographic Failures | Pass | `src/auth/hash.ts:8` — bcrypt cost 12 | |
| A03 Injection | Pass | parameterized queries throughout `src/db/` | |
| … | … | … | … |

## Findings (the fails, detailed)
| # | Control | Severity | CWE | Finding | Evidence | Impact | Remediation |
|---|---------|----------|-----|---------|----------|--------|-------------|
| 1 | A01 | High | CWE-639 | IDOR on order read | `src/api/orders.ts:30` | Any user reads any order | Enforce ownership/authz check before returning the record |
| 2 | … | … | … | … | … | … | … |

## Needs review
Controls that could not be confirmed and need a human/code answer.

## Out of scope
Controls or areas deliberately not covered, with reason.

複数のルールセットを検証する場合は、ルールセットごとにコントロールチェックリストの表を繰り返し、検出事項の表は 1 つにまとめます。

---

フェーズ 3 — 検出事項と修正の引き継ぎ

• 検出事項を優先順位付けし（Critical／High を先に）、それぞれ検出事項番号に紐付けた簡潔な修正リストを作成します。
• 修正の割り当て先を明示します。このフローでは修正を実装しません。
  • 依存関係の脆弱性／スキャナーで検出可能な問題 → snyk-remediation
  • 既存の動作に関するロジック／アクセス制御／設計の修正 → incu-way-bugs
  • 開発中の機能に関する修正 → 該当する incu-way-development 項目に含めます
• 引き継ぎ先が明確になるよう、各検出事項に割り当て先を記載します。

---

ゲート 2 — レビュー

検証結果を記載した後：

• パス、集計数、重大度別の Fail、および Needs review の一覧を提示します。
• 次のように伝えます。「セキュリティ検証の準備ができました。docs/security/validation/{slug}/VALIDATION.md を確認してください。検出事項は修正先に割り当て済みで、未解決の項目は一覧に記載しています。レビューをお願いします。」
• 停止します。ユーザーのレビューを待ってから次に進みます。

組み込みで実行している場合は、呼び出し元フローの検証／レビューゲートに制御を戻します。レポートはそこでレビューされ、そのフローの PR に含まれます。以下のスタンドアロン向け PR 手順はスキップします。

---

フェーズ 4 — PR（スタンドアロンモードのみ）

assess/secval-{slug} をプッシュして PR を作成するには、incu-way-prepare-pr の実行を提案します。自分でプッシュしたり、gh pr create を実行したりしてはいけません。

incu-way-prepare-pr で使用する PR のタイトル／本文の案：

Title: assess(security): validate {target} against {ruleset}

PR の本文には次を含めます。

• 範囲： 対象、ルールセット、および該当する場合は ASVS レベル。
• 概要： Pass／Fail の件数と、重大度別の検出事項。
• 検出事項と割り当て先： 優先順位付けされた Fail と、それぞれの修正の割り当て先。
• Needs review： チームの確認が必要な未確定のコントロール。

作成後、PR の URL を共有します。停止します。ユーザーの承認を得るまでマージしてはいけません。

---

クイックリファレンス — ゲート

ゲート	トリガー	伝える内容	ブロック解除の条件
1	ルールセットとスコープの提案	「これは {target} のセキュリティ検証スコープとルールセットです。開始前に確認してください。」	ユーザーの確認
2	検証内容の作成	「セキュリティ検証が docs/security/validation/{slug}/VALIDATION.md に用意できました。確認してください。」	ユーザーのレビュー
3	（単独の場合）レビュー済み	PR assess/secval-{slug} → develop に対して incu-way-prepare-pr を提案し、ユーザーが実行したら URL を共有	ユーザーの承認

---

作成されるもの

docs/security/validation/{slug}/
  VALIDATION.md   # per-ruleset control checklist + detailed findings + remediation routing

---

してはいけないこと

• ゲート 1 でスコープとルールセットが確認される前に、検証内容を作成しないでください。
• 証拠なしに管理項目を Pass と判定しないでください。未確認の場合は Needs review とし、決して Pass にしないでください。
• 追跡できない判定をしないでください。それぞれにコードを引用するか、該当しない理由を記載してください。
• これを Snyk SAST/SCA スキャンの代替として扱わないでください。スキャンを補完するものです。
• ここで修正を実装しないでください。検証し、修正対応に振り分け、対象のフローで変更を進めてください。
• 別のフローに組み込まれている場合、個別の PR を作成しないでください。レポートは呼び出し元の PR とともに提出されます。
• 単独モードでは develop または main に直接書き込まないでください。assess/secval-{slug} を使用してください。