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

查詢所有安全警告

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}'

深入分析特定警告 (取得 CVE、修復版本、CVSS 分數)
```
gh api repos/{owner}/{repo}/dependabot/alerts/{alert_number}
```
確認目前安裝版本
```
npm ls {package_name}
```
本地漏洞掃描（與 Dependabot 交叉比對）
```
npm audit
```
評估風險
- Critical/High: 立即修復
- Medium: 排程修復
- Low: 評估是否需要
判斷依賴類型
- 直接依賴 (direct) → 直接升級 package.json 中的版本
- 間接依賴 (transitive) → 使用 overrides 欄位強制升級
- devDependency → 風險較低但仍應修復，使用 overrides

Phase 2: 版本規劃 Version Planning

遵循語意化版本規則：
- 純安全修補 → PATCH (x.y.Z)
- 含新功能 → MINOR (x.Y.0)
- 有 breaking changes → MAJOR (X.0.0)

檢查修復版本是否可用

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

Phase 3: 實施修復 Implementation

更新 package.json
- 更新專案版本號（PATCH bump）
- 直接依賴：修改 dependencies / devDependencies 中的版本
- 間接依賴：在 overrides 區塊新增版本覆蓋
```
// 間接依賴使用 overrides 範例
"overrides": {
    "flatted": ">=3.4.0"
}
```

更新 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}

安裝並驗證

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

驗證測試失敗為既有問題（如有測試失敗）
```
# 暫存修改，用原始版本跑測試比對
git stash
npm test
git stash pop
```
若原始版本同樣失敗，確認為既有問題，與本次修改無關。
產生 VSIX (VS Code 擴充功能專案)
```
npx @vscode/vsce package
```

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: 發布流程 Release Process

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

Git 提交 (遵循 Conventional Commits)

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

建立標籤

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

推送至遠端
```
git push origin {branch} --follow-tags
```

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

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

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

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

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

Phase 6: 驗證修復 Verification

確認警告狀態

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

本地最終確認

npm audit  # 應顯示 found 0 vulnerabilities

如果警告未自動關閉 (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