安全漏洞修復技能 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

查詢所有 Dependabot 安全警告

``bash gh api --paginate 'repos/{owner}/{repo}/dependabot/alerts?state=open&perpage=100' --jq '.[] | {number: .number, state: .state, severity: .securityadvisory.severity, package: .securityvulnerability.package.name, summary: .securityadvisory.summary}' ``

查詢所有 GitHub Code Scanning 警告

``bash gh api --paginate 'repos/{owner}/{repo}/code-scanning/alerts?state=open&perpage=100' --jq '.[] | {number: .number, state: .state, rule: .rule.id, severity: .rule.securityseveritylevel, tool: .tool.name, path: .mostrecentinstance.location.path, line: .mostrecentinstance.location.startline, summary: .rule.description}' ``

深入分析特定警告

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

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

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

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

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

``bash npm ls {package_name} ``

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

``bash npm audit ``

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

評估風險

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

判斷 finding 類型與修復路徑

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

Phase 2: 版本規劃 Version Planning

遵循語意化版本規則：

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

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

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

提出修復方案並取得核准

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

Phase 3: 實施修復 Implementation

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

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

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

更新 CHANGELOG.md (雙語格式)

```markdown ## [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 改用對應條目：

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

安裝並驗證

``bash 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。

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

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

禁止本機正式發布產物

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

Phase 4: 更新 SECURITY.md Maintenance

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

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

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

更新 Supported Versions 區塊

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

更新 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](...).

---

_Last updated: YYYY-MM-DD_

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

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

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

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

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

取得發布核准後建立 PR

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

同步 master 並驗證版本契約

``bash 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。

建立並單獨推送 annotated tag

``bash 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。

等待 GitHub Actions CD

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

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

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

依發布契約復原失敗

- 單一發布端失敗時只重跑失敗 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

確認警告狀態

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

本地與發布端最終確認

``bash npm audit ``

- GitHub Release 必須是正確版本，包含版本化 VSIX、.sha256 與雙語 notes。 - VS Code Marketplace 與 Open VSX 必須顯示同一版本。 - 下載 GitHub Release VSIX 與 .sha256 並驗證。使用 pinned local vsce 與官方 Open VSX checksum endpoint 取得另外兩端的值：

``bash 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。

如果警告未自動轉為 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](./assets/changelog-template.md) 撰寫同一 PR 內的版本 CHANGELOG。
[release-notes-template.md](./assets/release-notes-template.md) 只作為內容參考；不得在本機建立正式 release notes 或呼叫 gh release create。Actions 會從對應 CHANGELOG 區段產生 GitHub Release notes。

security-vulnerability-fix

Installation

Similar popular skills

Also in this package

Agent compatibility

Skill metadata

Package contents

History

SKILL.md