Imported from yhy0/ghsa-skill-builder (SKILL.md). Install upstream with npx skills add yhy0/ghsa-skill-builder. Copyright stays with the author.

Vulnerability Pattern Skill Builder

从多个数据源拉取高危漏洞，分析模式，自动生成/更新审计 Skills：

• GHSA（GitHub Advisory Database）→ 按语言生态分类的代码审计 skills（vuln-patterns-*, go-vuln-*）
• HackerOne Hacktivity（公开 Bug Bounty 报告）→ 按漏洞类型分类的渗透测试 skills（pentest-*）

前置检查

开始工作前，检查以下依赖：

1. GitHub 认证: 脚本会自动检查，未认证会提示
2. writing-skills: 生成 Skill 时需要遵循质量规范。检查 superpowers 插件是否已安装：

ls ~/.claude/plugins/cache/*/superpowers/*/skills/writing-skills/SKILL.md 2>/dev/null

如果不存在，提示用户安装：

superpowers 插件未安装。建议先执行 /plugin install superpowers@superpowers-marketplace 安装，其中的 writing-skills 技能可确保生成的 Skills 符合质量规范。也可以跳过，但生成的 Skill 质量可能不稳定。

如果已安装，在 Step 3 生成 Skill 文件时，同时参考 writing-skills 的规范（frontmatter 格式、Progressive Disclosure、CSO 关键词优化、目录结构）。

使用场景

模式 A：全量构建

Step 1: 拉取数据

阶段 1 — 批量拉取索引（快速，几分钟）：

python3 scripts/fetch_ghsa.py PIP --since 3y
python3 scripts/fetch_ghsa.py GO --since 3y
python3 scripts/fetch_ghsa.py NPM --since 3y

保存到 data/{ecosystem}.json（索引级：GHSA ID、CVSS、CWE、summary）。参数：--min-cvss(默认8), --severity(默认CRITICAL,HIGH), --since(如3y/1y/6m/30d)。

阶段 2 — 按 CWE 拉取完整详情（逐条 REST API）：

# 注入类全量详情
python3 scripts/fetch_details.py data/pip.json --cwe "77|78|89|94"

# 路径遍历类
python3 scripts/fetch_details.py data/pip.json --cwe "22|23|73"

# 反序列化类
python3 scripts/fetch_details.py data/pip.json --cwe "502"

# 认证绕过类
python3 scripts/fetch_details.py data/pip.json --cwe "287|288|306"

# 不过滤 CWE，全量拉取所有详情
python3 scripts/fetch_details.py data/pip.json

# 只想快速测试可以加 --top 限制
python3 scripts/fetch_details.py data/pip.json --cwe "77|78|89|94" --top 10

保存到 data/{ecosystem}_details_{cwe}.json（含完整 description、patch commit URL）。

Step 2: 分析候选

读取 data/*_details_*.json，对每个候选：

1. 读 description 提取漏洞根因和攻击路径
2. 如果有 patch_urls，用 gh api repos/{owner}/{repo}/commits/{sha} -H "Accept: application/vnd.github.diff" 获取 diff
3. 从 description + diff 中提取结构化信息：
   • Source: 用户输入的具体入口
   • Sink: 触发危害的具体函数
   • Sanitization Gap: 为什么 source→sink 路径上没有有效防护
   • 漏洞代码: 关键的危险代码模式
   • 为什么扫描器会漏掉: CodeQL/Bandit/Gosec 漏检的具体原因
   • 检测方法: 如何在未知代码中发现此类漏洞

筛选标准：

1. 根因模式独特、常规扫描器会漏掉的优先
2. description 中有具体代码/PoC 的优先
3. AI/LLM/MCP/Agent 相关漏洞优先
4. 同一根因模式只保留最典型的 1-2 个代表

跳过： 纯 DoS (CWE-400)、内存损坏无代码模式、description 为空或过短。

CWE 到 Skill 映射：

Step 3: 生成 Skill 文件

对每个 CWE 分组生成 vuln-skills/skills/vuln-patterns-{category}/SKILL.md + vuln-skills/skills/vuln-patterns-{category}/references/cases.md。

生成顺序——先写组级策略，再填 Case：

第一步：Detection Strategy（组级通用检测模型）

从该组所有候选中归纳通用的 Sources、Sinks、Sanitization 列表和检测路径。这是 Skill 的核心——Agent 审计时首先依据此策略定位候选漏洞点。

第二步：3-8 个 Case 写入 references/cases.md

每个 Case 代表一种独特的漏洞变体模式。选择标准：

• 每个 Case 的 source→sink 路径应不同于其他 Case
• 优先选择通用规则难以覆盖的边缘情况
• 同根因模式的多个 CVE 用 **Similar Vulnerabilities** 聚合

第三步：Detection Checklist + False Positive Exclusion Guide

从 Cases 中提炼可操作的检查项和误报排除条件。

遵循 references/skill-structure.md 和 references/case-template.md。

约束：

• SKILL.md 放检测策略 + Checklist + 误报指南（核心内容）
• Cases 拆到 references/cases.md（按需加载）
• 每个 Case 聚焦于如何发现此类漏洞，而非如何修复
• 每个 Case 必须包含 Source → Sink 路径 和 "Why Standard Scanners Miss It"
• Detection Strategy 不可省略

Step 4: 校验

# GHSA ID 去重 + Case 数量检查
python3 scripts/check_existing_skills.py --skills-dir .

# vuln-patterns-* skills 静态测试（frontmatter、结构）
python3 scripts/test_vuln_patterns_skills.py

# go-vuln-* skills 静态测试 + 场景定义
python3 scripts/test_go_vuln_skills.py

详见下方「测试脚本说明」章节。

模式 B：增量检查

# 对比已有数据，检查新增漏洞
python3 scripts/fetch_ghsa.py PIP --diff
python3 scripts/fetch_ghsa.py GO --diff

如果有新增：

1. 对新增漏洞按 CWE 分类，拉取详情：python3 scripts/fetch_details.py data/pip.json --cwe "..." --top 10
2. 判断是否值得加入现有 Skill
3. 按 Step 2-3 分析并更新
4. 全量拉取更新本地缓存：python3 scripts/fetch_ghsa.py PIP

模式 C：单条分析

gh api /advisories/{GHSA_ID} --jq '.'

分析后按 CWE 归入对应 Skill，按 Step 2-3 处理。

补充：覆盖未发布到包管理器的项目

gh api repos/{owner}/{repo}/security-advisories \
  --jq '.[] | "\(.ghsa_id) | \(.severity) | \(.cvss.score) | \(.summary)"'

模式 D：HackerOne Hacktivity 构建

从 HackerOne 公开的 Bug Bounty 报告中提取漏洞模式，生成渗透测试 Skills（pentest-*）。

Step 1: 拉取 Hacktivity 索引

# 拉取全部 critical/high 公开报告（默认最近 3 年，最多 3000 条）
python3 scripts/fetch_h1_hacktivity.py

# 按严重度过滤
python3 scripts/fetch_h1_hacktivity.py --severity critical

# 按 CWE/漏洞类型关键词过滤
python3 scripts/fetch_h1_hacktivity.py --cwe "SQL Injection"
python3 scripts/fetch_h1_hacktivity.py --cwe "SSRF"

# 按时间范围
python3 scripts/fetch_h1_hacktivity.py --since 1y

# 组合过滤
python3 scripts/fetch_h1_hacktivity.py --severity critical --cwe "XSS" --max 200

保存到 data/h1_hacktivity.json（索引级：标题、CWE、严重度、CVE ID、bounty、报告 URL）。无需认证，使用 HackerOne 公开 GraphQL API。

Step 2: 补充报告详情

# 按 CWE 过滤并从 NVD 获取 CVE 描述
python3 scripts/fetch_h1_details.py data/h1_hacktivity.json --cwe "79|89|94"

# 只取前 N 条（按 bounty 降序）
python3 scripts/fetch_h1_details.py data/h1_hacktivity.json --top 30

# 可选：启用 Playwright 抓取报告全文（需要 pip install playwright）
python3 scripts/fetch_h1_details.py data/h1_hacktivity.json --cwe "918" --scrape

保存到 data/h1_hacktivity_details_{cwe}.json。有 CVE ID 的报告会从 NVD 补充漏洞描述和参考链接。

Step 3: 按分类拆分

将详情数据按漏洞类型归入分类文件：

ls data/h1_by_category/
# access-control.json  auth-bypass.json  business-logic.json
# command-injection.json  deserialization-xxe.json  idor.json
# info-disclosure.json  memory-corruption.json  path-traversal.json
# request-forgery.json  sqli.json  ssrf.json  xss.json

H1 分类到 Skill 映射：

Step 4: 分析并生成 Skill

对每个分类的数据，按模式 A 的 Step 2-3 相同流程处理：

1. 从 hacktivity_summary + nvd_description 提取漏洞根因和攻击路径
2. 归纳 Detection Strategy（Sources → Sinks → Sanitization）
3. 写入 vuln-skills/skills/pentest-{category}/SKILL.md + references/cases.md

H1 数据特点（与 GHSA 的区别）：

• H1 报告通常包含更详细的攻击步骤和 PoC
• hacktivity_summary 是 AI 生成的摘要，可能不完整，需结合 NVD 描述
• Bounty 金额可用于评估漏洞严重程度和影响力
• 部分报告无 CVE ID，仅有 H1 报告链接

Step 5: 校验

python3 scripts/test_pentest_skills.py

详见下方「测试脚本说明」章节。

测试脚本说明

生成 Skill 后需要运行测试确保质量。测试分两层：

• 静态测试（python3 直接运行）：frontmatter 合规、章节结构完整性
• 子代理场景测试（通过 Agent 工具执行）：Retrieval / Application / Gap 真实场景验证

三套测试脚本

用法

# 运行静态测试（全部可直接执行）
python3 scripts/test_vuln_patterns_skills.py
python3 scripts/test_go_vuln_skills.py
python3 scripts/test_pentest_skills.py

# 查看 go-vuln 子代理场景定义（人类可读）
python3 scripts/test_go_vuln_skills.py --scenes

# 导出场景定义为 JSON（供程序消费）
python3 scripts/test_go_vuln_skills.py --json-scenes

子代理场景测试执行方式（go-vuln）

test_go_vuln_skills.py 的 SCENARIOS 列表定义了 21 个场景（每 skill 3 个：retrieval + application + gap）。每个场景包含：

• skill: 对应的 skill 名称
• type: 测试类型（retrieval / application / gap）
• scenario: 给子代理的场景描述（含 Go 代码片段）
• expected: 子代理输出应包含的关键点列表

执行方式：在主对话中读取 skill 内容 + 场景定义，通过 Agent 工具启动子代理，将 skill 内容注入 prompt，让子代理产出审计分析，然后评估输出是否满足 expected 中的各期望点。

静态测试检查项

所有三套脚本的静态测试均检查：

• Compliance: frontmatter 存在、大小 ≤1024B、仅 name + description 字段、name 格式合法、description 以 "Use when" 开头且 ≤500 字符
• Structure: Detection Strategy / Detection Checklist / False Positive 章节存在、Sources/Sinks/Sanitization 模型、grep 代码块、checklist 条目 ≥5、cases.md 存在且 ≥5 个 case