security-vulnerability-fix

name	security-vulnerability-fix
description	修復 npm 依賴安全漏洞的完整工作流程。當使用者提到安全警告、Dependabot alerts、CVE 漏洞、npm audit 問題時自動啟用。包含查詢漏洞、升級依賴、驗證修復、發布版本的完整流程。Fixes npm dependency security vulnerabilities with a complete workflow including Dependabot alert analysis, package upgrades, build verification, version release following semantic versioning.
metadata	{"author":"singular-blockly","version":"1.1.0","category":"security"}

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

修復 npm 依賴安全漏洞的標準化工作流程。 A standardized workflow for fixing npm dependency security vulnerabilities.

適用情境 When to Use

• 收到 Dependabot security alerts
• 執行 npm audit 發現漏洞
• 需要升級有 CVE 的套件
• 發布安全修補版本 (PATCH release)

工作流程 Workflow

Phase 1: 漏洞分析 Vulnerability Analysis

1. 查詢所有安全警告

   gh api repos/{owner}/{repo}/dependabot/alerts --jq '.[] | {number: .number, state: .state, severity: .security_advisory.severity, package: .security_vulnerability.package.name, summary: .security_advisory.summary}'
   

2. 深入分析特定警告 (取得 CVE、修復版本、CVSS 分數)

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

3. 確認目前安裝版本

   npm ls {package_name}
   

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

   npm audit
   

5. 評估風險

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

6. 判斷依賴類型

   • 直接依賴 (direct) → 直接升級 package.json 中的版本
   • 間接依賴 (transitive) → 使用 overrides 欄位強制升級
   • devDependency → 風險較低但仍應修復，使用 overrides

Phase 2: 版本規劃 Version Planning

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

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

2. 檢查修復版本是否可用

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

Phase 3: 實施修復 Implementation

1. 更新 package.json

   • 更新專案版本號（PATCH bump）
   • 直接依賴：修改 dependencies / devDependencies 中的版本
   • 間接依賴：在 overrides 區塊新增版本覆蓋

   // 間接依賴使用 overrides 範例
   "overrides": {
       "flatted": ">=3.4.0"
   }
   

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}
   

3. 安裝並驗證

   npm install
   npm audit          # 確認 0 vulnerabilities
   npm ls {package}   # 確認實際安裝版本已升級
   npm run package    # 或 npm run build
   npm run test
   

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

   # 暫存修改，用原始版本跑測試比對
   git stash
   npm test
   git stash pop
   

   若原始版本同樣失敗，確認為既有問題，與本次修改無關。

5. 產生 VSIX (VS Code 擴充功能專案)

   npx @vscode/vsce package
   

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

---

_Last updated: YYYY-MM-DD_

Phase 5: 發布流程 Release Process

⚠️ 此階段包含不可逆的遠端操作。如果是由 AI agent 自動執行，應在使用者明確確認後才進行（除非使用者指示不需要停下來確認）。

1. Git 提交 (遵循 Conventional Commits)

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

2. 建立標籤

   git tag -a v{version} -m "Release v{version} - Security patch for {CVE}"
   

3. 推送至遠端

   git push origin {branch} --follow-tags
   

4. 建立 GitHub Release (雙語發布說明)

   gh release create v{version} --title "{Project} v{version} - 安全修補 / Security Patch" --notes-file release-notes.md {vsix_file}
   

5. 清理暫存檔案（必須執行！）

   # 移除 VSIX 安裝包與暫時發布說明
   Remove-Item -Force release-notes.md -ErrorAction SilentlyContinue
   Remove-Item -Force *.vsix -ErrorAction SilentlyContinue
   

   ⚠️ VSIX 必須清除：GitHub Release 已附加此檔案，本地保留無意義且容易混淆後續版本。

Phase 6: 驗證修復 Verification

1. 確認警告狀態

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

2. 本地最終確認

   npm audit  # 應顯示 found 0 vulnerabilities
   

3. 如果警告未自動關閉 (Dependabot 掃描延遲)

   • 先確認 package-lock.json 在 GitHub 上版本正確
   • 手動關閉警告：

   gh api repos/{owner}/{repo}/dependabot/alerts/{number} -X PATCH -f state="dismissed" -f dismissed_reason="fix_started" -f dismissed_comment="Upgraded to {version} in commit {sha}. See v{release_version} release."
   

經驗提示：auto_dismissed 狀態的 Dependabot 警告在推送修復後通常會自動轉為 fixed。

雙語發布說明範本 Bilingual Release Notes Template

參考 release-notes-template.md 建立發布說明。

檢查清單 Checklist

• 查詢並分析安全警告
• 確認修復版本可用
• 更新 package.json (依賴 + 版本號)
• 更新 CHANGELOG.md (雙語格式)
• 更新 SECURITY.md (移除已修復漏洞、更新支援版本)
• npm install + build + test 通過
• 產生 VSIX (如適用)
• Git commit 遵循 Conventional Commits
• 建立版本標籤
• 推送至遠端
• 建立 GitHub Release (雙語發布說明)
• 本地 VSIX 已移除 (Remove-Item -Force *.vsix)
• release-notes.md 已移除 (Remove-Item -Force release-notes.md)
• 驗證 Dependabot 警告已關閉 (state: fixed)
• npm audit 顯示 0 vulnerabilities

相關工具 Related Tools

• gh api - GitHub CLI API 操作
• npm audit - 本地漏洞掃描
• npm ls - 查看依賴樹
• npx @vscode/vsce package - VS Code 擴充功能打包