安全漏洞修復技能 Security Vulnerability Fix Skill

修復 npm 依賴與 GitHub Code Scanning 程式碼安全漏洞的標準化工作流程。 A standardized workflow for fixing npm dependency and GitHub Code Scanning vulnerabilities.

適用情境 When to Use

• 收到 Dependabot security alerts
• 收到 GitHub Code Scanning／CodeQL alerts
• 執行 npm audit 發現漏洞
• 需要升級有 CVE 的套件
• 需要修復 CodeQL 指出的安全程式碼 finding
• 發布安全修補版本 (PATCH release)

不要把單純「有較新版本」的 Dependabot Version Update PR 視為安全漏洞。Dependabot 與 Code Scanning 都沒有 open alert，且 npm audit 為 0 時，改用一般依賴升級流程，不要自動 bump 專案版本或發布安全修補版。

工作流程 Workflow

Phase 1: 漏洞分析 Vulnerability Analysis

1. 查詢所有 Dependabot 安全警告

   gh api --paginate 'repos/{owner}/{repo}/dependabot/alerts?state=open&per_page=100' --jq '.[] | {number: .number, state: .state, severity: .security_advisory.severity, package: .security_vulnerability.package.name, summary: .security_advisory.summary}'
   

2. 查詢所有 GitHub Code Scanning 警告

   gh api --paginate 'repos/{owner}/{repo}/code-scanning/alerts?state=open&per_page=100' --jq '.[] | {number: .number, state: .state, rule: .rule.id, severity: .rule.security_severity_level, tool: .tool.name, path: .most_recent_instance.location.path, line: .most_recent_instance.location.start_line, summary: .rule.description}'
   

3. 深入分析特定警告

   Dependabot alert：取得 CVE、GHSA、修復版本與 CVSS 分數。

   gh api repos/{owner}/{repo}/dependabot/alerts/{alert_number}
   

   Code Scanning alert：取得規則、CWE、精確位置、訊息、commit 與掃描工具版本，並閱讀命中位置的原始碼與相關測試；不得只看摘要就判定誤報或 dismiss。

   gh api repos/{owner}/{repo}/code-scanning/alerts/{alert_number}
   

4. 確認目前安裝版本（依賴 finding）

   npm ls {package_name}
   

5. 本地漏洞掃描（與 Dependabot 交叉比對）

   npm audit
   

   只有在 Dependabot 與 Code Scanning 都沒有 open alert，且 npm audit 為 0 時，才能停止安全修補流程並回報沒有安全 finding。npm audit 為 0 不代表 Code Scanning 為 0。

6. 評估風險

   • Critical/High: 立即修復
   • Medium: 排程修復
   • Low: 評估是否需要

7. 判斷 finding 類型與修復路徑

   • 直接依賴 (direct) → 直接升級 package.json 中的版本
   • 間接依賴 (transitive) → 先升級最近的直接／上游依賴；只有沒有安全相容版本時才使用精確、最小範圍的 overrides
   • devDependency → 仍需分析實際 build／CI 暴露面；不要只因是開發依賴就忽略漏洞
   • Code Scanning → 修正命中位置的根因並補足相稱的回歸測試；只有能以原始碼、資料流與實際執行條件證明是 false positive 時，才提出 dismissal 方案

Phase 2: 版本規劃 Version Planning

1. 遵循語意化版本規則：

   • 純安全修補 → PATCH (x.y.Z)
   • 含新功能 → MINOR (x.Y.0)
   • 有 breaking changes → MAJOR (X.0.0)

2. 檢查修復版本是否可用（依賴 finding）

   npm view {package_name} versions --json | tail -5
   

3. 提出修復方案並取得核准

   • 列出 Dependabot Alert／CVE／GHSA 或 Code Scanning Alert／rule／CWE、嚴重度、受影響依賴路徑或原始碼位置。
   • 說明直接升級、overrides 或原始碼修正的選擇及相容性風險。
   • 提出 SemVer、雙語 CHANGELOG 草稿、測試範圍與預定 vX.Y.Z。
   • 未取得修正核准前，不修改 dependency、版本或 CHANGELOG。

Phase 3: 實施修復 Implementation

1. 在功能分支修復 finding 並更新版本

   • 直接依賴：修改 dependencies / devDependencies 中的版本。
   • 間接依賴：只在無法由上游安全版本解決時使用精確、最小範圍的 overrides。
   • Code Scanning：以最小變更修正根因並新增或調整可驗證行為的測試，不以註解、忽略規則或無根據 dismissal 掩蓋 finding。
   • 使用 npm version {VERSION} --no-git-tag-version 同步更新 package.json 與 package-lock.json；此時禁止建立 tag。

   // 間接依賴使用 overrides 範例
   "overrides": {
       "flatted": "3.4.2"
   }
   

2. 更新 CHANGELOG.md (雙語格式)

   ## [x.y.z] - YYYY-MM-DD
   
   ### 安全性修復 Security Fixes
   
   - **修復 {套件名稱} {漏洞類型} (CVE-XXXX-XXXX)** (Fix {package} {vulnerability type})
       - 升級 `{package}` 從 x.x.x 至 x.x.x
         Upgraded `{package}` from x.x.x to x.x.x
       - 嚴重程度 Severity: {severity} (CVSS: x.x)
       - 關閉 Dependabot Alert #{number}
         Closes Dependabot Alert #{number}
   

   Code Scanning finding 改用對應條目：

   - **修復 CodeQL {rule_id} ({CWE})** (Fix CodeQL {rule_id})
       - 修正 `{path}:{line}` 的 {vulnerability type}
         Fixed {vulnerability type} in `{path}:{line}`
       - 嚴重程度 Severity: {severity}
       - 關閉 Code Scanning Alert #{number}
         Closes Code Scanning Alert #{number}
   

3. 安裝並驗證

   npm install
   npm ci
   npm audit
   npm ls {package}
   npm run ci:static
   npm run test:unit:ci
   npm run test:release
   npm run release:prepare
   

   依賴 Alert／CVE 必須從 lockfile 與 npm audit 消失；Code Scanning finding 必須先以原始碼檢查與測試驗證，並在 PR 的新 CodeQL 掃描中消失。Critical／High finding 必須為 0。若仍有與本次無關且無可用修復的 Medium／Low finding，列出 dependency path 或 code location、影響與緩解措施，取得使用者明確的殘餘風險核准；不得把仍有任何來源 finding 的結果描述成 0 vulnerabilities。

4. 驗證測試失敗為既有問題（如有測試失敗）

   使用 merge-base／原始 commit 的隔離暫存 worktree 或乾淨 clone，重新執行 npm ci 與相同測試。不要用 git stash／stash pop 搬動使用者工作區，也不要共用修復後的 node_modules。只有原始版本在相同環境也失敗，才能判定為既有問題。

5. 禁止本機正式發布產物

   • 不執行本機正式 vsce package、ovsx publish 或 vsce publish。
   • 不建立準備上傳的正式 VSIX。PR CI 會做 package smoke test；正式發布只使用 GitHub Actions 建置的唯一 artifact。

Phase 4: 更新 SECURITY.md Maintenance

如果專案根目錄有 SECURITY.md 文件，需同步更新：

1. 檢查是否有 Known Issues 區塊記錄此漏洞

   • 如有記錄「等待上游修復」的漏洞，現已修復 → 移除該區塊
   • 如果是全新漏洞且無法立即修復 → 新增到 Known Issues

2. 更新 Supported Versions 區塊

   • 確保支援版本與目前發布版本一致
   • 範例：0.51.x → 0.52.x

3. 更新 Last updated 日期

範例格式：

# Security Policy

## Supported Versions

| Version | Supported          |
| ------- | ------------------ |
| 0.52.x  | :white_check_mark: |
| < 0.51  | :x:                |

## Reporting a Vulnerability

Please report security vulnerabilities by opening a [GitHub Security Advisory](https://github.com/Shen-Ming-Hong/singular-blockly/security/advisories/new).

---

_Last updated: YYYY-MM-DD_

Phase 5: PR 與 Actions 發布流程 Release Process

本階段必須同時遵循 git-workflow 與 pr-review-release；後者是發布契約的唯一權威。任何遠端操作前都必須完成其本地 review、修正核准與發布前核准 gate。

1. 在同一功能分支提交完整發布內容

   package.json、package-lock.json、雙語 CHANGELOG.md、必要的 SECURITY.md 與依賴修正必須進入同一 PR。使用 Conventional Commits 與繁體中文描述，例如：

   git add package.json package-lock.json CHANGELOG.md SECURITY.md
   git commit -m "chore(deps): 修復 {package} {漏洞類型} ({CVE})"
   

2. 取得發布核准後建立 PR

   • 不得直接 push master，也不得在 PR 合併前建立正式 tag。
   • PR 描述列出 Dependabot／Code Scanning Alert、CVE／GHSA／CodeQL rule、修復版本、雙語 CHANGELOG 摘要、npm audit、測試與 CodeQL 結果。
   • 等待 CI Gate、CodeQL、review 對話與受保護分支條件全部通過。
   • 只使用 squash merge，並刪除遠端功能分支。

3. 同步 master 並驗證版本契約

   git switch master
   git fetch origin
   git merge --ff-only origin/master
   git status --short
   git rev-parse HEAD
   git rev-parse origin/master
   npm ci
   npm run release:prepare
   

   工作區必須乾淨，且 HEAD 必須等於 origin/master。不得在合併後補做版本或 CHANGELOG commit。

4. 建立並單獨推送 annotated tag

   git ls-remote --tags origin "refs/tags/v{VERSION}"
   git tag -a v{VERSION} -m "Release v{VERSION}"
   git cat-file -t v{VERSION}
   git push origin v{VERSION}
   

   git cat-file -t 必須輸出 tag。若 tag 已存在就停止；禁止刪除、移動、覆寫或重建正式 tag，也禁止使用 --follow-tags。

5. 等待 GitHub Actions CD

   .github/workflows/publish.yml 必須從 annotated tag 建置唯一 VSIX，並把同一 artifact 發布至 GitHub Releases、VS Code Marketplace 與 Open VSX。GitHub Release notes 由同版本雙語 CHANGELOG 區段產生。

   gh run list --workflow publish.yml --branch v{VERSION} --limit 1
   gh run watch {RUN_ID} --exit-status
   gh run view {RUN_ID} --json status,conclusion,jobs,url
   

   不得執行本機正式打包、全域安裝 vsce／ovsx 或 gh release create。

6. 依發布契約復原失敗

   • 單一發布端失敗時只重跑失敗 jobs，不重建 tag、不重發已成功的發布端。
   • tag run 在發布前因 workflow 缺陷失敗時，先以新 PR 修正，再從 master 手動 dispatch 原 annotated tag。
   • 上一點的一般 rerun 規則有一個明確例外：市集已成功而 GitHub Release 失敗時，不得 rerun 任何市集 job；使用 recover-github-release.yml 與原失敗 run 的同一 artifact，只補 GitHub Release。

Phase 6: 驗證修復 Verification

1. 確認警告狀態

   gh api repos/{owner}/{repo}/dependabot/alerts/{number} --jq '{state: .state, fixed_at: .fixed_at}'
   gh api repos/{owner}/{repo}/code-scanning/alerts/{number} --jq '{state: .state, fixed_at: .fixed_at, rule: .rule.id}'
   

2. 本地與發布端最終確認

   npm audit
   

   • GitHub Release 必須是正確版本，包含版本化 VSIX、.sha256 與雙語 notes。

   • VS Code Marketplace 與 Open VSX 必須顯示同一版本。

   • 下載 GitHub Release VSIX 與 .sha256 並驗證。使用 pinned local vsce 與官方 Open VSX checksum endpoint 取得另外兩端的值：

     npm exec -- vsce show Singular-Ray.singular-blockly --json
     curl -fsSL "https://open-vsx.org/api/Singular-Ray/singular-blockly/{VERSION}/file/Singular-Ray.singular-blockly-{VERSION}.sha256"
     

     從 Marketplace JSON 讀取最新版的 Microsoft.VisualStudio.Services.VsixSha256。三個值都必須等於 Actions 唯一 artifact 的 SHA-256。

3. 如果警告未自動轉為 fixed

   • Dependabot：先確認修復後的 package-lock.json 已在 default branch，且實際 dependency path 不再落入 vulnerable range。
   • Code Scanning：先確認修正 commit 已在 default branch、該 commit 的 CodeQL workflow 成功，且新掃描涵蓋相同語言與 alert 位置。
   • 等待 Dependabot 或 Code Scanning 重新掃描並再次查詢；掃描延遲不代表修復失敗。
   • 不得把真實漏洞手動 dismiss 成已處理。只有確認為 false positive、不可觸及程式碼或接受風險，並取得使用者明確核准後，才使用與事實相符的 dismissal reason 與完整註解。

雙語內容範本 Bilingual Content Templates

• 使用 changelog-template.md 撰寫同一 PR 內的版本 CHANGELOG。
• release-notes-template.md 只作為內容參考；不得在本機建立正式 release notes 或呼叫 gh release create。Actions 會從對應 CHANGELOG 區段產生 GitHub Release notes。

檢查清單 Checklist

• 查詢並分析 Dependabot 與 Code Scanning 安全警告
• 確認修復版本可用
• 更新 package.json 與 lockfile（版本；依賴 finding 才變更 dependency）
• 更新 CHANGELOG.md (雙語格式)
• 更新 SECURITY.md (移除已修復漏洞、更新支援版本)
• 目標依賴與 Code Scanning 漏洞已排除、Critical／High 為 0；任何剩餘 Medium／Low finding 已明確核准
• ci:static、unit tests、release tests 與 release:prepare 通過
• 本地 review、修正核准、re-review 與發布前核准完成
• 版本、lockfile、雙語 CHANGELOG 與安全修正已進入同一 PR
• PR 通過 CI Gate、CodeQL 並已 squash merge
• annotated tag 已驗證為 tag 並單獨推送
• Actions 使用唯一 VSIX 完成 GitHub Release、Marketplace 與 Open VSX
• 三端版本與 SHA-256 一致；本機未重建正式產物
• 失敗時只復原失敗發布端，未刪除或重建 tag
• 驗證 Dependabot 與 Code Scanning 警告已關閉 (state: fixed)
• 最終 Dependabot、Code Scanning 與 npm audit 結果已如實回報，未隱藏或誤稱剩餘 finding

相關工具 Related Tools

• gh api - 查詢 Dependabot 與 Code Scanning alerts
• npm audit - 本地漏洞掃描
• npm ls - 查看依賴樹
• npm run release:prepare - 驗證 tag 前版本與 CHANGELOG 契約
• gh pr - 建立、檢查與 squash merge PR
• gh run - 監看與復原 GitHub Actions 發布