Back to Details

deal-with-security-advisory

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Security Vulnerability Response Instructions

安全漏洞响应指南

⚠️ CRITICAL: This is a security vulnerability. Everything about this process is confidential until the advisory is published. Do not mention the vulnerability details in any public commit message, PR title, branch name, or comment. Do not push anything to a public branch. Do not discuss specifics in any public channel. Assume anything on the public repo is visible to attackers who will exploit the window between disclosure and user upgrades.

⚠️ 重要提示：这是安全漏洞。在公告发布前，整个流程的所有内容均需保密。请勿在任何公开提交信息、PR标题、分支名称或评论中提及漏洞细节。请勿向公开分支推送任何内容。请勿在任何公开渠道讨论具体信息。假设公开仓库中的任何内容都能被攻击者看到，他们会利用漏洞披露到用户升级之间的时间窗口进行攻击。

Context

背景信息

A security vulnerability has been reported via GitHub Security Advisory:
  • Advisory: {{ghsaId}} (e.g. GHSA-x8hx-rhr2-9rf7)
  • Reporter: {{reporterHandle}}
  • Severity: {{severity}}
  • Notes: {{notes}}
已通过GitHub Security Advisory报告了一个安全漏洞：
  • 漏洞公告ID： {{ghsaId}}（例如：GHSA-x8hx-rhr2-9rf7）
  • 报告者： {{reporterHandle}}
  • 严重程度： {{severity}}
  • 备注： {{notes}}

Step 0: Fetch the Advisory Details

步骤0：获取漏洞公告详情

Pull the full advisory so you understand the vulnerability before doing anything else:
gh api repos/paperclipai/paperclip/security-advisories/{{ghsaId}}
Read the 
description
, 
severity
, 
cvss
, and 
vulnerabilities
fields. Understand the attack vector before writing code.
先拉取完整的漏洞公告，在开展任何工作前先了解漏洞情况：
gh api repos/paperclipai/paperclip/security-advisories/{{ghsaId}}
阅读
description
、
severity
、
cvss
和
vulnerabilities
字段。在编写代码前先理解攻击路径。

Step 1: Acknowledge the Report

步骤1：确认收到报告

⚠️ This step requires a human. The advisory thread does not have a comment API. Ask the human operator to post a comment on the private advisory thread acknowledging the report. Provide them this template:
Thanks for the report, @{{reporterHandle}}. We've confirmed the issue and are working on a fix. We're targeting a patch release within {{timeframe}}. We'll keep you updated here.
Give your human this template, but still continue
Below we use 
gh
tools - you do have access and credentials outside of your sandbox, so use them.
⚠️ 此步骤需要人工操作。漏洞公告线程没有评论API。请操作人员在私有漏洞公告线程中发布评论确认收到报告。提供以下模板：
感谢您的报告，@{{reporterHandle}}。我们已确认该问题，正在修复中。我们计划在{{timeframe}}内发布补丁版本。会在此处及时更新进度。
向操作人员提供此模板后，继续后续步骤
以下我们会使用
gh
工具 - 您在沙箱外拥有访问权限和凭据，请直接使用。

Step 2: Create the Temporary Private Fork

步骤2：创建临时私有分支

This is where all fix development happens. Never push to the public repo.
gh api --method POST \
  repos/paperclipai/paperclip/security-advisories/{{ghsaId}}/forks
This returns a repository object for the private fork. Save the 
full_name
and 
clone_url
.
Clone it and set up your workspace:
undefined
所有修复开发工作都将在此进行。切勿推送到公开仓库。
gh api --method POST \
  repos/paperclipai/paperclip/security-advisories/{{ghsaId}}/forks
该命令会返回私有分支的仓库对象。保存
full_name
和
clone_url
。
克隆分支并设置工作区：
undefined

Clone the private fork somewhere outside ~/paperclip

在~/paperclip目录外克隆私有分支

git clone <clone_url_from_response> ~/security-patch-{{ghsaId}} cd ~/security-patch-{{ghsaId}} git checkout -b security-fix

**Do not edit `~/paperclip`** — the dev server is running off the `~/paperclip` master branch and we don't want to touch it. All work happens in the private fork clone.

**TIPS:**

* Do not commit `pnpm-lock.yaml` — the repo has actions to manage this
* Do not use descriptive branch names that leak the vulnerability (e.g., no `fix-dns-rebinding-rce`). Use something generic like `security-fix`
* All work stays in the private fork until publication
* CI/GitHub Actions will NOT run on the temporary private fork — this is a GitHub limitation by design. You must run tests locally
git clone <clone_url_from_response> ~/security-patch-{{ghsaId}} cd ~/security-patch-{{ghsaId}} git checkout -b security-fix

**请勿编辑`~/paperclip`** —— 开发服务器基于`~/paperclip`的master分支运行，我们不应改动它。所有工作都在私有分支的克隆版本中进行。

**提示：**

* 请勿提交`pnpm-lock.yaml` —— 仓库有专门的Action来管理该文件
* 请勿使用会泄露漏洞信息的分支名称（例如：不要用`fix-dns-rebinding-rce`）。使用通用名称如`security-fix`
* 所有工作在公告发布前都需保留在私有分支中
* CI/GitHub Actions不会在临时私有分支上运行 —— 这是GitHub的设计限制。您必须在本地运行测试

Step 3: Develop and Validate the Fix

步骤3：开发并验证修复方案

Write the patch. Same content standards as any PR:
  • It must functionally work — run tests locally since CI won't run on the private fork
  • Consider the whole codebase, not just the narrow vulnerability path. A patch that fixes one vector but opens another is worse than no patch
  • Ensure backwards compatibility for the database, or be explicit about what breaks
  • Make sure any UI components still look correct if the fix touches them
  • The fix should be minimal and focused — don't bundle unrelated changes into a security patch. Reviewers (and the reporter) should be able to read the diff and understand exactly what changed and why
Specific to security fixes:
  • Verify the fix actually closes the attack vector described in the advisory. Reproduce the vulnerability first (using the reporter's description), then confirm the patch prevents it
  • Consider adjacent attack vectors — if DNS rebinding is the issue, are there other endpoints or modes with the same class of problem?
  • Do not introduce new dependencies unless absolutely necessary — new deps in a security patch raise eyebrows
Push your fix to the private fork:
git add -A
git commit -m "Fix security vulnerability"
git push origin security-fix
编写补丁。遵循与普通PR相同的内容标准：
  • 功能必须正常工作 —— 在本地运行测试，因为CI不会在私有分支上运行
  • 考虑整个代码库，而不仅仅是漏洞的直接路径。修复了一个攻击路径但打开另一个的补丁比没有补丁更糟
  • 确保数据库的向后兼容性，或明确说明哪些功能会被破坏
  • 如果修复涉及UI组件，确保组件显示正常
  • 修复应尽可能精简聚焦 —— 不要在安全补丁中包含无关更改。审核人员（和报告者）应能通过diff准确理解更改内容和原因
安全修复的特殊要求：
  • 验证修复是否真正阻断了公告中描述的攻击路径。先复现漏洞（使用报告者提供的描述），再确认补丁能阻止该攻击
  • 考虑相邻的攻击路径 —— 如果问题是DNS重绑定，是否有其他端点或模式存在同类问题？
  • 除非绝对必要，否则不要引入新依赖 —— 安全补丁中的新依赖会引发质疑
将修复推送到私有分支：
git add -A
git commit -m "Fix security vulnerability"
git push origin security-fix

Step 4: Coordinate with the Reporter

步骤4：与报告者协调

⚠️ This step requires a human. Ask the human operator to post on the advisory thread letting the reporter know the fix is ready and giving them a chance to review. Provide them this template:
@{{reporterHandle}} — fix is ready in the private fork if you'd like to review before we publish. Planning to release within {{timeframe}}.
Proceed
⚠️ 此步骤需要人工操作。请操作人员在公告线程中告知报告者修复已完成，并邀请他们在发布前审核。提供以下模板：
@{{reporterHandle}} —— 修复已在私有分支中完成，若您想在发布前审核请告知。我们计划在{{timeframe}}内发布版本。
继续后续步骤

Step 5: Request a CVE

步骤5：申请CVE

This makes vulnerability scanners (npm audit, Snyk, Dependabot) warn users to upgrade. Without it, nobody gets automated notification.
gh api --method POST \
  repos/paperclipai/paperclip/security-advisories/{{ghsaId}}/cve
GitHub is a CVE Numbering Authority and will assign one automatically. The CVE may take a few hours to propagate after the advisory is published.
这会让漏洞扫描工具（npm audit、Snyk、Dependabot）提醒用户升级。没有CVE的话，用户无法收到自动通知。
gh api --method POST \
  repos/paperclipai/paperclip/security-advisories/{{ghsaId}}/cve
GitHub是CVE编号机构，会自动分配编号。CVE在公告发布后可能需要几小时才能同步到各个平台。

Step 6: Publish Everything Simultaneously

步骤6：同步发布所有内容

This all happens at once — do not stagger these steps. The goal is zero window between the vulnerability becoming public knowledge and the fix being available.
所有步骤必须同时进行 —— 不要分步执行。目标是消除漏洞公开与修复版本可用之间的时间窗口。

6a. Verify reporter credit before publishing

6a. 发布前确认报告者的署名

gh api repos/paperclipai/paperclip/security-advisories/{{ghsaId}} --jq '.credits'
If the reporter is not credited, add them:
gh api --method PATCH \
  repos/paperclipai/paperclip/security-advisories/{{ghsaId}} \
  --input - << 'EOF'
{
  "credits": [
    {
      "login": "{{reporterHandle}}",
      "type": "reporter"
    }
  ]
}
EOF

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. Update the advisory with the patched version and publish

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
Publishing the advisory simultaneously:
  • Makes the GHSA public
  • Merges the temporary private fork into your repo
  • Triggers the CVE assignment (if requested in step 5)
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. Cut a release immediately after merge

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.
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

What was fixed

{{briefDescription}} (e.g., Remote code execution via DNS rebinding in `local_trusted` mode)
{{briefDescription}} (e.g., Remote code execution via DNS rebinding in `local_trusted` mode)

Advisory

Advisory

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

Credit

Credit

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

Action required

Action required

All users running versions prior to {{patchedVersion}} should upgrade immediately."
undefined
All users running versions prior to {{patchedVersion}} should upgrade immediately."
undefined

Step 7: Post-Publication Verification

步骤7：发布后验证

undefined
undefined

Verify the advisory is published and CVE is assigned

验证漏洞公告已发布且CVE已分配

gh api repos/paperclipai/paperclip/security-advisories/{{ghsaId}}
--jq '{state: .state, cve_id: .cve_id, published_at: .published_at}'
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

If the CVE hasn't been assigned yet, that's normal — it can take a few hours.

⚠️ **Human step:** Ask the human operator to post a final comment on the advisory thread confirming publication and thanking the reporter.

Tell the human operator what you did by posting a comment to this task, including:

* The published advisory URL: `https://github.com/paperclipai/paperclip/security/advisories/{{ghsaId}}`
* The release URL
* Whether the CVE has been assigned yet
* All URLs to any pull requests or branches
gh release view v{{patchedVersion}} --repo paperclipai/paperclip

如果CVE尚未分配，属于正常情况 —— 可能需要几小时。

⚠️ **人工步骤：** 请操作人员在漏洞公告线程中发布最终评论，确认已发布并感谢报告者。

在此任务中发布评论告知操作人员您已完成的工作，包括：

* 已发布的漏洞公告URL：`https://github.com/paperclipai/paperclip/security/advisories/{{ghsaId}}`
* 版本发布URL
* CVE是否已分配
* 所有PR或分支的URL