deal-with-security-advisory

セキュリティ脆弱性への対応手順

⚠️ 重大：これはセキュリティ脆弱性です。勧告が公開されるまで、このプロセスに関する情報はすべて機密です。公開コミットメッセージ、PR タイトル、ブランチ名、コメントで脆弱性の詳細に触れてはいけません。公開ブランチには何もプッシュしないでください。公開チャンネルで具体的な内容を話し合わないでください。公開リポジトリ上の情報はすべて攻撃者に見られ、開示からユーザーがアップグレードするまでの隙を突かれる可能性があると想定してください。

---

背景

GitHub Security Advisory を通じてセキュリティ脆弱性が報告されています。

• 勧告： {{ghsaId}}（例：GHSA-x8hx-rhr2-9rf7）
• 報告者： {{reporterHandle}}
• 深刻度： {{severity}}
• メモ： {{notes}}

---

ステップ 0：勧告の詳細を取得する

ほかの作業を始める前に、勧告の全文を取得して脆弱性を理解してください。

gh api repos/paperclipai/paperclip/security-advisories/{{ghsaId}}

description、severity、cvss、vulnerabilities フィールドを確認してください。コードを書く前に、攻撃経路を理解してください。

ステップ 1：報告を受領したことを伝える

⚠️ このステップには人間の対応が必要です。 勧告スレッドにはコメント API がありません。担当者に、非公開の勧告スレッドで報告を受領したことを伝えるコメントを投稿するよう依頼してください。次のテンプレートを渡してください。

ご報告ありがとうございます、@{{reporterHandle}} さん。問題を確認し、修正に取り組んでいます。{{timeframe}} 以内のパッチリリースを予定しています。こちらで随時状況をお知らせします。

担当者にこのテンプレートを渡し、その後も作業を続けてください。

以下では gh ツールを使用します。サンドボックスの外部ではアクセス権と認証情報を利用できますので、使用してください。

ステップ 2：一時的な非公開フォークを作成する

ここで修正作業をすべて行います。公開リポジトリには絶対にプッシュしないでください。

gh api --method POST \
  repos/paperclipai/paperclip/security-advisories/{{ghsaId}}/forks

これにより、非公開フォークのリポジトリオブジェクトが返されます。full_name と clone_url を保存してください。

クローンを作成し、作業環境を設定してください。

# Clone the private fork somewhere outside ~/paperclip
git clone <clone_url_from_response> ~/security-patch-{{ghsaId}}
cd ~/security-patch-{{ghsaId}}
git checkout -b security-fix

~/paperclip は編集しないでください — 開発サーバーは ~/paperclip の master ブランチで稼働しており、そこには手を加えたくありません。作業はすべて、非公開フォークのクローン内で行ってください。

ヒント：

• pnpm-lock.yaml はコミットしないでください — リポジトリにはこれを管理するアクションがあります
• 脆弱性の内容が漏れるような説明的なブランチ名は使わないでください（例：fix-dns-rebinding-rce は避けてください）。security-fix のような汎用的な名前を使ってください
• 公開までは、すべての作業を非公開フォーク内にとどめてください
• CI/GitHub Actions は一時的な非公開フォークでは実行されません — これは GitHub の仕様です。テストはローカルで実行する必要があります

ステップ 3：修正を実装して検証する

パッチを作成してください。通常の PR と同じ品質基準を満たす必要があります。

• 機能的に正しく動作する必要があります — 非公開フォークでは CI が実行されないため、テストをローカルで実行してください
• 限定的な脆弱性の経路だけでなく、コードベース全体を考慮してください。一つの攻撃経路を塞いでも別の経路を開いてしまうパッチは、何も修正しないより悪いものです
• データベースとの後方互換性を確保するか、変更によって何が壊れるのかを明示してください
• 修正によって UI コンポーネントに影響がある場合は、引き続き正しく表示されることを確認してください
• 修正は最小限に絞り、対象を限定してください。セキュリティパッチに無関係な変更を含めないでください。レビュー担当者（および報告者）が差分を読み、何が、なぜ変わったのかを正確に理解できるようにしてください

セキュリティ修正に固有の注意事項：

• 勧告に記載された攻撃経路を実際に塞げているか確認してください。まず報告者の説明に基づいて脆弱性を再現し、その後、パッチで防止できることを確認してください
• 隣接する攻撃経路も検討してください。問題が DNS リバインディングであれば、同じ種類の問題を抱えるほかのエンドポイントやモードがないか確認してください
• 絶対に必要な場合を除き、新しい依存関係を追加しないでください。セキュリティパッチでの新たな依存関係の追加は、疑念を招きます

修正を非公開フォークにプッシュしてください。

git add -A
git commit -m "Fix security vulnerability"
git push origin security-fix

ステップ 4：報告者と連絡を取る

⚠️ このステップには人間の対応が必要です。 人間のオペレーターにアドバイザリースレッドへの投稿を依頼し、修正が準備できたことを報告者に伝えて、レビューの機会を設けてください。以下のテンプレートを提供してください。

@{{reporterHandle}} — 修正はプライベートフォークに用意できています。公開前にレビューをご希望の場合はご確認ください。{{timeframe}}以内にリリースする予定です。

進む

ステップ 5：CVE を申請する

これにより、脆弱性スキャナー（npm audit、Snyk、Dependabot）がユーザーにアップグレードを促す警告を表示します。申請しないと、自動通知は届きません。

gh api --method POST \
  repos/paperclipai/paperclip/security-advisories/{{ghsaId}}/cve

GitHub は CVE 番号採番機関であり、自動的に CVE を割り当てます。アドバイザリーの公開後、CVE が反映されるまで数時間かかる場合があります。

ステップ 6：すべてを同時に公開する

これらはすべて同時に行います。手順を分けて実行しないでください。目標は、脆弱性が公知になってから修正が利用可能になるまでの空白期間をゼロにすることです。

6a. 公開前に報告者のクレジットを確認する

gh api repos/paperclipai/paperclip/security-advisories/{{ghsaId}} --jq '.credits'

報告者がクレジットされていない場合は、追加してください。

gh api --method PATCH \
  repos/paperclipai/paperclip/security-advisories/{{ghsaId}} \
  --input - << 'EOF'
{
  "credits": [
    {
      "login": "{{reporterHandle}}",
      "type": "reporter"
    }
  ]
}
EOF

6b. パッチ適用済みバージョンでアドバイザリーを更新し、公開する

gh api --method PATCH \
  repos/paperclipai/paperclip/security-advisories/{{ghsaId}} \
  --input - << 'EOF'
{
  "state": "published",
  "vulnerabilities": [
    {
      "package": {
        "ecosystem": "npm",
        "name": "paperclip"
      },
      "vulnerable_version_range": "< {{patchedVersion}}",
      "patched_versions": "{{patchedVersion}}"
    }
  ]
}
EOF

アドバイザリーを公開すると、同時に以下が行われます。

• GHSA が公開される
• 一時的なプライベートフォークがリポジトリにマージされる
• （ステップ 5 で申請した場合）CVE の割り当てが開始される

6c. マージ直後にリリースを作成する

cd ~/paperclip
git pull origin master

gh release create v{{patchedVersion}} \
  --repo paperclipai/paperclip \
  --title "v{{patchedVersion}} — Security Release" \
  --notes "## Security Release

This release fixes a critical security vulnerability.

### What was fixed
{{briefDescription}} (e.g., Remote code execution via DNS rebinding in \`local_trusted\` mode)

### Advisory
https://github.com/paperclipai/paperclip/security/advisories/{{ghsaId}}

### Credit
Thanks to @{{reporterHandle}} for responsibly disclosing this vulnerability.

### Action required
All users running versions prior to {{patchedVersion}} should upgrade immediately."

ステップ 7：公開後の確認

# Verify the advisory is published and CVE is assigned
gh api repos/paperclipai/paperclip/security-advisories/{{ghsaId}} \
  --jq '{state: .state, cve_id: .cve_id, published_at: .published_at}'

# Verify the release exists
gh release view v{{patchedVersion}} --repo paperclipai/paperclip

CVE がまだ割り当てられていなくても、問題ありません。割り当てには数時間かかる場合があります。

⚠️ 人間の対応が必要なステップ： 人間のオペレーターにアドバイザリースレッドへの最終コメントの投稿を依頼し、公開が完了したことを確認して、報告者に感謝を伝えてください。

タスクにコメントを投稿して、実施内容を人間のオペレーターに伝えてください。以下を含めます。

• 公開済みアドバイザリーの URL：https://github.com/paperclipai/paperclip/security/advisories/{{ghsaId}}
• リリースの URL
• CVE が割り当てられたかどうか
• プルリクエストまたはブランチの URL（すべて）