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：创建临时私有 Fork

所有修复开发都在此处进行。切勿推送到公开仓库。

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

这会返回一个私有 Fork 的仓库对象。保存 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 分支运行，我们不想动它。所有工作都在私有 Fork 的克隆仓库中进行。

提示：

• 请勿提交 pnpm-lock.yaml——仓库已有操作来管理此文件
• 请勿使用会泄露漏洞信息的描述性分支名称（例如，不要使用 fix-dns-rebinding-rce）。请使用 security-fix 之类的通用名称
• 发布之前，所有工作都必须留在私有 Fork 中
• CI/GitHub Actions 不会在临时私有 Fork 上运行——这是 GitHub 的设计限制。你必须在本地运行测试

步骤 3：开发并验证修复

编写补丁。内容标准与任何 PR 相同：

• 必须确保功能正常——由于 CI 不会在私有 Fork 上运行，请在本地运行测试
• 考虑整个代码库，而不只是狭窄的漏洞路径。只修复一种攻击途径却引入另一种问题，甚至比不修复更糟
• 确保数据库向后兼容，或明确说明会有哪些破坏性变更
• 如果修复涉及 UI 组件，请确保它们仍能正常显示
• 修复应尽量精简且有针对性——不要在安全补丁中捆绑不相关的变更。审查者（和报告者）应能阅读差异并确切理解改了什么以及为什么要改

安全修复的特别要求：

• 验证修复确实封堵了公告中描述的攻击途径。先复现漏洞（使用报告者的描述），再确认补丁能够阻止漏洞
• 考虑相邻的攻击途径——如果问题出在 DNS 重绑定，是否还有其他端点或模式存在同类问题？
• 除非绝对必要，否则不要引入新的依赖——在安全补丁中加入新依赖会引起质疑

将修复推送到私有 Fork：

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 可能需要几小时才能传播。

步骤 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
• 将临时私有分支合并到你的代码库
• 触发 CVE 分配（如果已在步骤 5 中申请）

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