snyk-remediation

Snyk の修正プロセス

Snyk が検出したセキュリティ脆弱性を、対象範囲や許容リスクについて推測せずに発見し、修正するためのゲート駆動型ワークフローです。インテークとスキャンのコンテキストを確認してから、スキャン、トリアージ、計画、修正、検証を行い、重要な判断ポイントでユーザーの明示的な確認を得て PR を作成します。承認済みの計画なしに修正を適用することはありません。

---

リポジトリの適格性チェック（何よりも先に実施）

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

---

Phase 0 — インテークとスキャン

目標： SAST および SCA スキャンで検出された、現在のすべての脆弱性を収集します。

手順

1. スキャン前に、インテークのコンテキストを確認します。
   • スキャン対象のプロジェクトの絶対パス
   • ユーザーが希望するのはレビューのみ、トリアージ、修正のいずれか
   • すでに把握している緊急度、環境、ビジネス上の制約
   • 考慮してほしい過去のスキャンコンテキスト
2. プロジェクトフォルダーがまだ信頼されていない場合は、まず絶対パスを指定して snyk_trust を呼び出します。
3. snyk_code_scan MCP ツールを使用して SAST スキャンを実行します。

   path: <absolute project path>
   severity_threshold: low
   

4. snyk_sca_scan MCP ツールを使用して SCA スキャンを実行します。

   path: <absolute project path>
   severity_threshold: low
   all_projects: true
   

5. 両方の結果からすべての問題を収集します。

snyk_trust、snyk_code_scan、または snyk_sca_scan が利用できない場合、あるいは検出結果が返る前に失敗した場合は、Gate 1 の前に停止し、正確にどのツールが見つからないか、またはどのような失敗が起きたかを報告して、Snyk のインストールまたは設定をユーザーに依頼するか、スキャン出力の提供を求めてください。検出結果を捏造したり、古いデータに基づいて修正計画に進んだりしないでください。

Phase 0 のガードレール

• ユーザーがすべての検出結果の修正を望んでいると決めつけないでください。スキャンで証拠を確立し、対象範囲はユーザーが決定します。
• 技術的な深刻度だけでビジネス上の優先度を決めつけないでください。
• パス、スキャン対象、または希望する修正範囲が不明確な場合は、先に確認してください。

Phase 0 の終了条件

Phase 1 に進む前に、Claude が次の内容を明示できるようにします。

• 使用したプロジェクトパスとスキャン対象
• ユーザーが希望するのはレビューのみ、トリアージ、修正のいずれか
• すでに把握しているビジネス上または環境上の制約
• 検出結果の一覧が推測ではなく、実際のスキャン結果を反映していること

---

Phase 1 — 検出結果のレポート

目標： すべての検出結果を、明確で実行可能な形式でユーザーに提示します。

レポート形式

検出結果ごとに 1 行の Markdown テーブルを作成します。

# Snyk Security Findings — {YYYY-MM-DD}

## Summary
- SAST issues: {N} (Critical: X, High: X, Medium: X, Low: X)
- SCA issues: {N} (Critical: X, High: X, Medium: X, Low: X)
- Total: {N}

## Findings

| # | Type | Severity | Title | File / Package | CWE / CVE | Impact | Fix available |
|---|------|----------|-------|----------------|-----------|--------|---------------|
| 1 | SAST | High | SQL Injection | `lib/db/queries/contacts.ts:42` | CWE-89 | Attacker can exfiltrate DB data via crafted input | Yes — sanitize input |
| 2 | SCA  | Critical | Prototype Pollution | `[email protected]` | CVE-2019-10744 | Remote code execution via crafted payload | Yes — upgrade to `[email protected]` |

列の定義：

• 種類： SAST（ソースコード）または SCA（依存関係）
• 深刻度： Critical／High／Medium／Low
• タイトル： Snyk の問題タイトル
• ファイル／パッケージ： SAST の場合は filePath:line。SCA の場合は package@version
• CWE／CVE： SAST の場合は CWE、SCA の場合は CVE（利用可能な場合）
• 影響： 悪用された場合に攻撃者が何を実行できるかを 1 文で説明
• 修正の有無： あり（簡単な説明付き）またはなし

Gate 1 — 対象範囲の確認

テーブルを提示した後：

• ユーザーに次のように尋ねます。「これが検出結果です。どの深刻度のものを修正しますか？（例：Critical + High、またはすべて）。回答に合わせて修正計画の対象範囲を定めます。」
• 停止します。ユーザーが対象範囲を決めるまで先に進まないでください。

スキャン出力だけで修正の承認が得られたものと見なさないでください。Gate 1 で、実際に対象とする検出結果を決定します。

---

分離環境の設定（Gate 1 の直後）

ファイルを作成する前に、作業をどのように分離するかユーザーに確認してください。

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

ユーザーの回答どおりに進めてください。 質問したら停止し、ユーザーが選択するまでブランチや worktree を作成しないでください。

現在のチェックアウトに未コミットの変更がある場合は、ブランチの切り替えや worktree の作成を行う前に停止して確認してください。

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

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

以降の作業（ドキュメント、コード、コミット）はすべて、現在のチェックアウトにあるこのブランチで行います。develop または main に直接ファイルを書き込まないでください。

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

ワークツリーは .worktrees/ の下にのみ作成します。ユーザーにパスを尋ねないでください。

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

以降の作業（ドキュメント、コード、コミット）はすべて、このワークツリー内でのみ行います。develop または main に直接ファイルを書き込まないでください。

---

状態の追跡 — .ways/state.json

ways/v1alpha1 state contract に従ってください。これは、プロジェクトに ways add が追加する、正式な .ways/state.json 形式（schemaVersion 2）であり、常時有効な state-contract ルールとして、すでにコンテキストに含まれているため、参照するパスはありません。メンテナー向けの、このリポジトリ内のソースは ways/rulepacks/state-contract/ です。このスキル内でスキーマをコピーしたり、独自に作成したりしないでください。

フロー固有の値：

• flow：security
• way：incu/security · discipline：security（任意で way マニフェストから wayVersion）
• ブランチのパターン：fix/security-{slug}
• 初期 phase：findings
• isolationType：分離方法の選択に応じて branch または worktree
• ドキュメント：docs/security/{slug}/FINDINGS.md、docs/security/{slug}/PLAN.md、docs/security/{slug}/RESOLUTION.md
• ゲート：plan、resolution、pr-develop、pr-main

セッション開始時に、.ways/state.json が存在する場合は読み込みます。その branch が現在の fix/security-{slug} ブランチと一致する場合は、現在のフェーズ、次のステップ、保留中のゲートを報告し、その状態から再開します。存在しない場合、または存在するものの branch が一致しない場合（マージ済みの作業項目から古いファイルが引き継がれた場合）は、Phase 0 から開始し、Gate 1 の後、選択した分離方法の設定直後に .ways/state.json を作成または上書きします。フェーズが移行するたびに、離れるフェーズを lastPhase にも更新します。

更新タイミング（フェーズ → 書き込む内容）：

タイミング	phase	ドキュメント／ゲート／ステップ
FINDINGS.md の作成時	findings	FINDINGS.md → approved
PLAN.md の草案作成時	plan	PLAN.md → in-review
Gate 2（plan）通過時	implementation	PLAN.md → approved、ゲート plan → passed、steps を生成 — 対象範囲内の調査結果ごとに 1 エントリを作成し、すべて todo にする
各調査結果の修正時	implementation	該当するステップを in-progress → done（または blocked）に更新 — 状態ファイルは調査結果ごとに直ちに書き込み、最後にまとめて更新しない
RESOLUTION.md の作成時	validation	RESOLUTION.md → approved
Gate 3（resolution）通過時	validation	ゲート resolution → passed
fix→develop の PR を作成した時	pr-develop	ゲート pr-develop → 引き続き pending、url に PR リンクを設定
PR が develop にマージされた時	pr-develop	ゲート pr-develop → passed
develop→main の PR を作成した時	pr-main	ゲート pr-main → 引き続き pending、url に PR リンクを設定
PR が main にマージされた時	done	ゲート pr-main → passed

Gate 2 で生成する steps（対象範囲内の調査結果ごとに 1 つ）は、ボードに修正の進捗として表示されます。

.ways/state.json を自分でコミットしないでください。書き込みのみ行ってください。ユーザーがチェックポイントを永続化したい場合は、incu-way-prepare-pr を呼び出し、該当する移行のドキュメント／コードと一緒にコミットするよう提案してください。

---

Phase 2 — 調査結果の文書化

目標： 調査結果レポートを、監査証跡の起点として保存します。

保存先

選択した作業場所内に保存します。

docs/security/{YYYY-MM-DD}-{short-slug}/FINDINGS.md

Slug： 主な問題の種類を表す 2〜4 語のケバブケース形式の要約。例：

• 2026-05-15-xss-sqli-drizzle
• 2026-03-10-prototype-pollution-deps

FINDINGS.md の構成

# Security Findings — {YYYY-MM-DD}

## Scan metadata
- Date: {YYYY-MM-DD}
- Tool: Snyk (SAST + SCA)
- Branch scanned: {branch name}
- Scope agreed: {e.g., Critical + High}

## Findings table
{paste the full table from Phase 1}

## Out of scope
{List findings the user chose NOT to fix, with a brief reason}

保存後：

• 次のように伝えます：「調査結果を docs/security/{slug}/FINDINGS.md に記録しました。合意済みの対象範囲に基づいて、修正計画を作成します。」
• Phase 3 に直接進みます（ゲートはありません。Gate 1 ですでにユーザーが対象範囲を確認済みです）。

---

Phase 3 — 修正計画

目標： 対象範囲内の調査結果それぞれについて、具体的でレビュー可能な修正を設計します。

保存先

docs/security/{slug}/PLAN.md

PLAN.md の構成

# Remediation Plan — {YYYY-MM-DD}

## Branch
`fix/security-{slug}`

## Isolation mode
current checkout branch | separate worktree

## Findings to fix

### Finding #1 — {Title} ({Severity})
- **Type:** SAST / SCA
- **Location:** {file:line or package@version}
- **Root cause:** {one sentence}
- **Fix approach:** {concrete action: upgrade X to Y / sanitize input at line Z / replace API call / etc.}
- **Risk of fix:** Low / Medium / High — {why}
- **Verification:** {how to confirm it's fixed: re-scan + specific test}

### Finding #2 — ...

Gate 2 — プランの承認

プランを作成した後：

• 次のように伝えます：「修正プランを docs/security/{slug}/PLAN.md に用意しました。コーディングを開始する前に、各検出事項への修正方針をご確認ください。」
• 停止します。ユーザーが OK と言うまで先に進まないでください。

---

Phase 4 — 実装

目標： ユーザーが選択した分離ブランチまたはワークツリーで修正を適用します。

セットアップ

Phase 2 の前に選択した分離モードを継続します。ユーザーからモードの変更を求められない限り、2 つ目のブランチまたはワークツリーを作成しないでください。

ルール

• 検出事項を 1 件ずつ修正します。各修正の後、incu-way-prepare-pr を呼び出してコミットするよう提案します。自分ではコミットしないでください：

  fix(security): {finding title} — {CWE or CVE}
  
  Resolves finding #{N} from docs/security/{slug}/FINDINGS.md
  Fix: {one-line description of what changed}
  

• SCA のアップグレードの場合： package.json を更新し、pnpm install を実行して、peer dependency の破損がないことを確認します。
• SAST の修正の場合： コードを変更し、脆弱なパスを実行するテストを追加または更新します。
• 各修正の後、コミットを提案する前に pnpm typecheck && pnpm lint && pnpm test を実行します。

進捗の追跡

作業を進めながら PLAN.md を更新し、修正済みの各検出事項にコミット SHA を記載します：

- **Status:** Fixed in `abc1234`

---

Phase 5 — 検証

目標： すべての修正が有効であり、リグレッションが発生していないことを確認します。

手順

1. SAST スキャンを再実行します：

   snyk_code_scan — path: <absolute path to the selected working location>, severity_threshold: low
   

2. SCA スキャンを再実行します：

   snyk_sca_scan — path: <absolute path to the selected working location>, severity_threshold: low, all_projects: true
   

3. テストスイート全体を実行します：pnpm typecheck && pnpm lint && pnpm test && pnpm build

解決レポート

docs/security/{slug}/RESOLUTION.md を保存します：

# Resolution Report — {YYYY-MM-DD}

## Re-scan results
- SAST re-scan: {N issues remaining} (was {N before})
- SCA re-scan: {N issues remaining} (was {N before})
- Fixed: {list of finding titles resolved}
- Remaining (out of scope): {list}

## Test suite
- `pnpm typecheck`: ✅ / ❌
- `pnpm lint`: ✅ / ❌
- `pnpm test`: ✅ / ❌
- `pnpm build`: ✅ / ❌

## Evidence
{Paste key output from re-scans — zero-issue confirmation or remaining out-of-scope items}

Gate 3 — 検証の承認

解決レポートを作成した後：

• 次のように伝えます：「修正を適用し、検証しました。解決レポートは docs/security/{slug}/RESOLUTION.md にあります。対象範囲の検出事項はすべて解決済みで、テストはすべて成功しています。PR を作成する前にご確認ください。」
• 停止します。ユーザーの確認を待ってください。

---

Phase 6 — プルリクエスト

目標： レビュー済みの PR を通じてセキュリティ修正を統合します。

ブランチの流れ

fix/security-{slug}  →  develop  →  main
                         (PR 1)     (PR 2)

PR 1 — fix/security-{slug} → develop

Gate 3 の承認後、incu-way-prepare-pr を呼び出して fix/security-{slug} をプッシュし、develop 向けの PR を作成するよう提案します。自分ではプッシュしたり gh pr create を実行したりしないでください。

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

Title: fix(security): {short summary of what was fixed}

PR の本文には次の内容を含めてください：

• 概要： 修正した脆弱性の内容（種類、深刻度、件数）。
• 検出事項： docs/security/{slug}/FINDINGS.md へのリンク。
• プラン： docs/security/{slug}/PLAN.md へのリンク。
• 解決レポート： docs/security/{slug}/RESOLUTION.md へのリンク。
• チェックリスト： snyk-code ✅、snyk-deps ✅、typecheck ✅、lint ✅、tests ✅、build ✅。

作成したら、PR の URL を共有します。停止します。ユーザーの承認があるまでマージしないでください。

PR 2 — develop → main

PR 1 がマージされた後、develop → main の PR を作成するため、再度 incu-way-prepare-pr を呼び出すよう提案します：

Title: release(security): {slug}
Body: Promotes security remediations from fix/security-{slug}. See docs/security/{slug}/ for full audit trail.

作成したら、URL を共有してユーザーの承認を待ちます。

---

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

ゲート	トリガー	伝える内容	進行を止める条件
1	検出事項の表を提示	「どの深刻度レベルを修正しますか？」	ユーザーが対象範囲を指定する
2	PLAN.md を作成	「プランを docs/security/{slug}/PLAN.md に用意しました。ご確認ください。」	ユーザーが OK と言う
3	RESOLUTION.md を作成	「修正を検証しました。PR の前に解決レポートをご確認ください。」	ユーザーが OK と言う
4	ユーザーが確認	PR fix→develop 用に incu-way-prepare-pr を提案し、ユーザーが実行したら URL を共有する	ユーザーが PR を承認する
5	PR 1 がマージ	PR develop→main 用に incu-way-prepare-pr を提案し、ユーザーが実行したら URL を共有する	ユーザーが PR を承認する

---

スキャンごとのドキュメント構成

docs/security/{YYYY-MM-DD}-{slug}/
  FINDINGS.md    — raw scan results + agreed scope  (Phase 2)
  PLAN.md        — fix approach per finding          (Phase 3)
  RESOLUTION.md  — re-scan evidence + test results   (Phase 5)

---

禁止事項

• ゲート 2（計画の承認）が完了する前に、修正を適用しないでください。
• ユーザーに事前に確認せず、スコープ外の指摘事項を修正しないでください。
• ユーザーから明示的な指示がない限り、修正のスコープ、許容されるリスク、ビジネス上の優先順位を決めつけないでください。
• 対応範囲や修正に伴うトレードオフがまだ不明確な場合、スキャン結果をそのまま修正計画に反映しないでください。
• フェーズ 5 で再スキャンを省略しないでください。テストに合格しただけでは、脆弱性が解消されたことの確認にはなりません。
• クリーンな再スキャン結果が RESOLUTION.md に示されていない状態で、PR を作成しないでください。
• 直接マージせず、些細な依存関係の更新であっても、必ず PR を経由してください。
• ユーザーの明示的な指示がない限り、.snyk の無視ルールで Snyk の指摘事項を抑制しないでください。
• 分離モードを選択する前に、develop／main に FINDINGS.md、PLAN.md、その他のファイルを書き込まないでください。ゲート 1 の直後にブランチまたはワークツリーを設定し、最初からすべてのファイルを選択した作業場所に置いてください。