scagogogo/osv-schema-skills
GitHub: scagogogo/osv-schema-skills
一个集成了 Go SDK、CLI 和 AI Agent 技能的开源漏洞（OSV）数据解析、校验与查询工具库。
Stars: 0 | Forks: 1
# OSV Schema 技能
[](https://pkg.go.dev/github.com/scagogogo/osv-schema-skills)
[](https://goreportcard.com/report/github.com/scagogogo/osv-schema-skills)
[](https://github.com/scagogogo/osv-schema-skills/actions/workflows/ci.yml)
[](https://github.com/scagogogo/osv-schema-skills/actions/workflows/release.yml)
[](https://github.com/scagogogo/osv-schema-skills/releases)
[](LICENSE)
[简体中文](README.zh-CN.md) | **English**
```
graph TD
A["🤖 AI Agent Skills
7 auto-trigger skills"] C["🖥️ CLI
osv parse/validate/filter/query"] S["📦 Go SDK
OsvSchema generics"] CORE["Go Core Library
parse · validate · filter · query"] OSV["OSV Schema
CVE · GHSA · CVSS · affected · ranges"] A --> CORE C --> CORE S --> CORE CORE --> OSV ``` ## 🚀 AI Agent 快速开始 运行 CLI 的最快捷径。复制、粘贴、运行，一气呵成。 ``` # 1. 安装 CLI — 选择其一： # a) 预编译二进制文件 (Linux/macOS/Windows · amd64/arm64/arm) # 将 v0.1.0 替换为 Releases 页面中最新的 tag。 VERSION=v0.1.0 curl -fsSL -o osv.tar.gz \ https://github.com/scagogogo/osv-schema-skills/releases/download/${VERSION}/osv_${VERSION}_linux_amd64.tar.gz tar -xzf osv.tar.gz osv && chmod +x osv && sudo mv osv /usr/local/bin/ # 如果最新的 release 还没有预编译资产，请退回到 (b)。 # b) 或通过 Go go install github.com/scagogogo/osv-schema-skills/cmd/osv@latest # 2. 验证 osv version # 3. 解析真实的漏洞记录（内置样本） osv parse test_data/GHSA-vxv8-r8q2-63xw.json ``` 需要使用 Go SDK？ ``` go get -u github.com/scagogogo/osv-schema-skills ``` ``` import osv "github.com/scagogogo/osv-schema-skills" v, err := osv.UnmarshalFromJsonFile[any, any]("vulnerability.json") fmt.Println(v.ID, v.Aliases.GetCVE(), v.Severity.GetCVSS3()) ``` ## 🤖 AI Agent 技能 当 Claude Code 打开此代码库时，**7 个专用 skills 会自动激活** —— 无需任何集成代码。Agent 会根据意图自动调用相应的 `osv` 子命令。 | Skill | 用途 | 自动触发条件... | |-------|---------|---------------------| | [`osv-parse`](.claude/skills/osv-parse/SKILL.md) | 解析并展示 OSV JSON 数据 | 你提到解析漏洞文件或提取 CVE/GHSA 数据时 | | [`osv-validate`](.claude/skills/osv-validate/SKILL.md) | 验证 OSV JSON 文件 | 你要求检查 schema 合规性或验证漏洞文件时 | | [`osv-filter`](.claude/skills/osv-filter/SKILL.md) | 按 ecosystem / 引用类型 / 别名进行过滤 | 你想要对 npm/PyPI/Maven 进行过滤或获取 FIX 引用时 | | [`osv-query`](.claude/skills/osv-query/SKILL.md) | 提取严重程度、Maven、范围、事件 | 你需要 CVSS 分数、Maven GAV 或版本范围时 | | [`osv-severity`](.claude/skills/osv-severity/SKILL.md) | CVSS 严重程度分析 | 你在评估漏洞风险或严重程度时 | | [`osv-affected`](.claude/skills/osv-affected/SKILL.md) | 受影响的包及版本分析 | 你需要进行影响分析或检查版本范围时 | | [`osv-installation`](.claude/skills/osv-installation/SKILL.md) | 安装与设置指南 | 这是你第一次使用这些 skills 时 | 每个 skill 都是一个 `SKILL.md` 文件，包含 YAML frontmatter（`name`、`description`、`allowed-tools`、`argument-hint`）以及结构化的正文 —— 决策树、任务模式、API 参考。 ``` flowchart LR U["User mentions
a vulnerability"] --> P["osv-parse
parse JSON"] P --> F["osv-filter
by ecosystem"] F --> SEV["osv-severity
CVSS score"] SEV --> R["Report findings"] ``` **在你的项目中使用 skills** —— 克隆该仓库，skills 即刻生效： ``` git clone https://github.com/scagogogo/osv-schema-skills.git cd osv-schema-skills && claude # skills are active ``` ## 🖥️ CLI 预编译的二进制文件支持 **Linux / macOS / Windows** 平台上的 **amd64、arm64、arm** 架构。请参阅[下载](#-downloads)。 ``` # 解析 OSV JSON 文件 osv parse vulnerability.json # Key fields (text) osv parse -v vulnerability.json # All fields (dates, details, credits, ranges) osv parse -o json vulnerability.json # JSON output # 验证一个或多个文件（如果有任何无效则退出并返回 1 — 对 CI 友好） osv validate vulnerability.json osv validate file1.json file2.json osv validate -o json vulnerability.json # 按 ecosystem / reference type / alias pattern 过滤 osv filter -e PyPI vulnerability.json # By ecosystem osv filter -r FIX vulnerability.json # By reference type osv filter -a CVE vulnerability.json # By alias pattern osv filter -e PyPI -r FIX vulnerability.json # Combine # 查询特定的子信息 osv query --severity cvss3 vulnerability.json # CVSS v3 entry + parsed score (0.0 on a vector string) osv query --maven vulnerability.json # Maven groupId/artifactId osv query --ranges vulnerability.json # Version ranges osv query --events vulnerability.json # Event timeline (introduced/fixed/…) # 显示版本 osv version ``` | 全局标志 | 描述 | |-------------|-------------| | `-o, --output` | `text` (默认) 或 `json` | ## 📦 Go SDK ``` package main import ( "fmt" "log" osv "github.com/scagogogo/osv-schema-skills" ) func main() { v, err := osv.UnmarshalFromJsonFile[any, any]("vulnerability.json") if err != nil { log.Fatal(err) } fmt.Printf("ID: %s\n", v.ID) if cve := v.Aliases.GetCVE(); cve != "" { fmt.Printf("CVE: %s\n", cve) } if v.Affected.HasEcosystem(osv.EcosystemNpm) { fmt.Println("Affects npm packages") } if cvss3 := v.Severity.GetCVSS3(); cvss3 != nil { fmt.Printf("CVSS v3: %.1f\n", cvss3.GetScore()) } } ``` ### 核心方法 | 类型 | 方法 | 描述 | |------|--------|-------------| | `AffectedSlice` | `HasEcosystem(eco)` | 是否受该 ecosystem 影响 | | `AffectedSlice` | `FilterByEcosystem(eco)` | 筛选至单一 ecosystem | | `AffectedSlice` | `Filter(fn)` | 自定义谓词过滤器 | | `Aliases` | `GetCVE()` | 获取首个 `CVE-` 标识符 | | `Aliases` | `Filter(fn)` | 按谓词过滤别名 | | `SeveritySlice` | `GetCVSS3()` / `GetCVSS2()` | CVSS 严重程度条目 | | `Severity` | `GetScore()` | 将分数解析为 `float64` | | `References` | `FilterByType(t)` | 按 `ADVISORY` / `FIX` / … 过滤 | | `Package` | `IsMaven()` / `GetGroupID()` / `GetArtifactID()` | Maven 拆解 | | `Event` | `IsIntroduced/IsFixed/IsLastAffected/IsLimit` | 事件类型检查 | ### 核心类型 ``` type OsvSchema[EcosystemSpecific, DatabaseSpecific any] struct { SchemaVersion string ID string Modified time.Time Published time.Time Withdrawn string // string, not time.Time Aliases Aliases Related Related Summary string Details string Severity SeveritySlice Affected AffectedSlice[EcosystemSpecific, DatabaseSpecific] References References DatabaseSpecific DatabaseSpecific Credits *Credits } ``` 泛型参数 `EcosystemSpecific` 和 `DatabaseSpecific` 允许你为特定的 ecosystem 或漏洞数据库附加自定义数据。通用解析时请使用 `any`。 每个核心类型均原生支持 **JSON、YAML、mapstructure、GORM 和 BSON** 序列化。共有 **19 个 ecosystem** 被定义为常量（npm、PyPI、Maven、NuGet、RubyGems、Go、Cargo、Hex、Pub、Packagist 等）。 ## ⬇️ 下载 每个 tag 都会通过 goreleaser 发布预编译的二进制文件。请选择与你的平台相匹配的版本： | 操作系统 | 架构 | 压缩包格式 | |----|---------------|---------| | Linux | amd64, arm64, arm (v7) | `.tar.gz` | | macOS | amd64, arm64 | `.tar.gz` | | Windows | amd64, arm64 | `.zip` | - **所有发布版本：**
- **命名规则：** `osv___.tar.gz` (或 `.zip`)
- 每个发布版本都包含 `checksums.txt` (SHA-256) —— 使用前请进行验证：
```
sha256sum -c checksums.txt --ignore-missing
```
找不到适合的二进制文件？可以通过源码构建 —— 只需 Go 1.18+ 即可：
```
git clone https://github.com/scagogogo/osv-schema-skills.git
cd osv-schema-skills
go build -o osv ./cmd/osv/
```
## 📖 文档
- **官方网站** (完整指南与参考)：
7 auto-trigger skills"] C["🖥️ CLI
osv parse/validate/filter/query"] S["📦 Go SDK
OsvSchema generics"] CORE["Go Core Library
parse · validate · filter · query"] OSV["OSV Schema
CVE · GHSA · CVSS · affected · ranges"] A --> CORE C --> CORE S --> CORE CORE --> OSV ``` ## 🚀 AI Agent 快速开始 运行 CLI 的最快捷径。复制、粘贴、运行，一气呵成。 ``` # 1. 安装 CLI — 选择其一： # a) 预编译二进制文件 (Linux/macOS/Windows · amd64/arm64/arm) # 将 v0.1.0 替换为 Releases 页面中最新的 tag。 VERSION=v0.1.0 curl -fsSL -o osv.tar.gz \ https://github.com/scagogogo/osv-schema-skills/releases/download/${VERSION}/osv_${VERSION}_linux_amd64.tar.gz tar -xzf osv.tar.gz osv && chmod +x osv && sudo mv osv /usr/local/bin/ # 如果最新的 release 还没有预编译资产，请退回到 (b)。 # b) 或通过 Go go install github.com/scagogogo/osv-schema-skills/cmd/osv@latest # 2. 验证 osv version # 3. 解析真实的漏洞记录（内置样本） osv parse test_data/GHSA-vxv8-r8q2-63xw.json ``` 需要使用 Go SDK？ ``` go get -u github.com/scagogogo/osv-schema-skills ``` ``` import osv "github.com/scagogogo/osv-schema-skills" v, err := osv.UnmarshalFromJsonFile[any, any]("vulnerability.json") fmt.Println(v.ID, v.Aliases.GetCVE(), v.Severity.GetCVSS3()) ``` ## 🤖 AI Agent 技能 当 Claude Code 打开此代码库时，**7 个专用 skills 会自动激活** —— 无需任何集成代码。Agent 会根据意图自动调用相应的 `osv` 子命令。 | Skill | 用途 | 自动触发条件... | |-------|---------|---------------------| | [`osv-parse`](.claude/skills/osv-parse/SKILL.md) | 解析并展示 OSV JSON 数据 | 你提到解析漏洞文件或提取 CVE/GHSA 数据时 | | [`osv-validate`](.claude/skills/osv-validate/SKILL.md) | 验证 OSV JSON 文件 | 你要求检查 schema 合规性或验证漏洞文件时 | | [`osv-filter`](.claude/skills/osv-filter/SKILL.md) | 按 ecosystem / 引用类型 / 别名进行过滤 | 你想要对 npm/PyPI/Maven 进行过滤或获取 FIX 引用时 | | [`osv-query`](.claude/skills/osv-query/SKILL.md) | 提取严重程度、Maven、范围、事件 | 你需要 CVSS 分数、Maven GAV 或版本范围时 | | [`osv-severity`](.claude/skills/osv-severity/SKILL.md) | CVSS 严重程度分析 | 你在评估漏洞风险或严重程度时 | | [`osv-affected`](.claude/skills/osv-affected/SKILL.md) | 受影响的包及版本分析 | 你需要进行影响分析或检查版本范围时 | | [`osv-installation`](.claude/skills/osv-installation/SKILL.md) | 安装与设置指南 | 这是你第一次使用这些 skills 时 | 每个 skill 都是一个 `SKILL.md` 文件，包含 YAML frontmatter（`name`、`description`、`allowed-tools`、`argument-hint`）以及结构化的正文 —— 决策树、任务模式、API 参考。 ``` flowchart LR U["User mentions
a vulnerability"] --> P["osv-parse
parse JSON"] P --> F["osv-filter
by ecosystem"] F --> SEV["osv-severity
CVSS score"] SEV --> R["Report findings"] ``` **在你的项目中使用 skills** —— 克隆该仓库，skills 即刻生效： ``` git clone https://github.com/scagogogo/osv-schema-skills.git cd osv-schema-skills && claude # skills are active ``` ## 🖥️ CLI 预编译的二进制文件支持 **Linux / macOS / Windows** 平台上的 **amd64、arm64、arm** 架构。请参阅[下载](#-downloads)。 ``` # 解析 OSV JSON 文件 osv parse vulnerability.json # Key fields (text) osv parse -v vulnerability.json # All fields (dates, details, credits, ranges) osv parse -o json vulnerability.json # JSON output # 验证一个或多个文件（如果有任何无效则退出并返回 1 — 对 CI 友好） osv validate vulnerability.json osv validate file1.json file2.json osv validate -o json vulnerability.json # 按 ecosystem / reference type / alias pattern 过滤 osv filter -e PyPI vulnerability.json # By ecosystem osv filter -r FIX vulnerability.json # By reference type osv filter -a CVE vulnerability.json # By alias pattern osv filter -e PyPI -r FIX vulnerability.json # Combine # 查询特定的子信息 osv query --severity cvss3 vulnerability.json # CVSS v3 entry + parsed score (0.0 on a vector string) osv query --maven vulnerability.json # Maven groupId/artifactId osv query --ranges vulnerability.json # Version ranges osv query --events vulnerability.json # Event timeline (introduced/fixed/…) # 显示版本 osv version ``` | 全局标志 | 描述 | |-------------|-------------| | `-o, --output` | `text` (默认) 或 `json` | ## 📦 Go SDK ``` package main import ( "fmt" "log" osv "github.com/scagogogo/osv-schema-skills" ) func main() { v, err := osv.UnmarshalFromJsonFile[any, any]("vulnerability.json") if err != nil { log.Fatal(err) } fmt.Printf("ID: %s\n", v.ID) if cve := v.Aliases.GetCVE(); cve != "" { fmt.Printf("CVE: %s\n", cve) } if v.Affected.HasEcosystem(osv.EcosystemNpm) { fmt.Println("Affects npm packages") } if cvss3 := v.Severity.GetCVSS3(); cvss3 != nil { fmt.Printf("CVSS v3: %.1f\n", cvss3.GetScore()) } } ``` ### 核心方法 | 类型 | 方法 | 描述 | |------|--------|-------------| | `AffectedSlice` | `HasEcosystem(eco)` | 是否受该 ecosystem 影响 | | `AffectedSlice` | `FilterByEcosystem(eco)` | 筛选至单一 ecosystem | | `AffectedSlice` | `Filter(fn)` | 自定义谓词过滤器 | | `Aliases` | `GetCVE()` | 获取首个 `CVE-` 标识符 | | `Aliases` | `Filter(fn)` | 按谓词过滤别名 | | `SeveritySlice` | `GetCVSS3()` / `GetCVSS2()` | CVSS 严重程度条目 | | `Severity` | `GetScore()` | 将分数解析为 `float64` | | `References` | `FilterByType(t)` | 按 `ADVISORY` / `FIX` / … 过滤 | | `Package` | `IsMaven()` / `GetGroupID()` / `GetArtifactID()` | Maven 拆解 | | `Event` | `IsIntroduced/IsFixed/IsLastAffected/IsLimit` | 事件类型检查 | ### 核心类型 ``` type OsvSchema[EcosystemSpecific, DatabaseSpecific any] struct { SchemaVersion string ID string Modified time.Time Published time.Time Withdrawn string // string, not time.Time Aliases Aliases Related Related Summary string Details string Severity SeveritySlice Affected AffectedSlice[EcosystemSpecific, DatabaseSpecific] References References DatabaseSpecific DatabaseSpecific Credits *Credits } ``` 泛型参数 `EcosystemSpecific` 和 `DatabaseSpecific` 允许你为特定的 ecosystem 或漏洞数据库附加自定义数据。通用解析时请使用 `any`。 每个核心类型均原生支持 **JSON、YAML、mapstructure、GORM 和 BSON** 序列化。共有 **19 个 ecosystem** 被定义为常量（npm、PyPI、Maven、NuGet、RubyGems、Go、Cargo、Hex、Pub、Packagist 等）。 ## ⬇️ 下载 每个 tag 都会通过 goreleaser 发布预编译的二进制文件。请选择与你的平台相匹配的版本： | 操作系统 | 架构 | 压缩包格式 | |----|---------------|---------| | Linux | amd64, arm64, arm (v7) | `.tar.gz` | | macOS | amd64, arm64 | `.tar.gz` | | Windows | amd64, arm64 | `.zip` | - **所有发布版本：**
标签：AI智能体, Claude, CVE检测, EVTX分析, Go, Ruby工具, 开源漏洞库(OSV), 数据校验, 日志审计, 漏洞数据解析