Skip to content

Commit 5c390d7

Browse files
CC11001100CC11001100
committed
🔀 合并远程更改并解决冲突
- 合并了远程分支的最新更改 - 解决了README.md和TODO.md的合并冲突 - 保留了文档网站链接和本地开发说明 - 整合了项目的最新功能和改进
2 parents 78e9078 + 9592994 commit 5c390d7

36 files changed

+6421
-1004
lines changed

‎.cursor/rules/datasource-guide.mdc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: false
5+
---

‎.cursor/rules/documentation-standards.mdc‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: false
5+
---
6+
# CPE库文档规范
7+
8+
本项目采用详细的中文注释，为每个公共方法和类型提供全面的文档说明。
9+
10+
## 注释格式
11+
12+
方法注释应包含以下几个部分：
13+
14+
```go
15+
// MethodName 方法的简短中文描述
16+
//
17+
// 功能描述:
18+
// - 详细说明方法的功能和用途
19+
// - 可能的使用场景
20+
// - 实现的核心逻辑
21+
//
22+
// 参数:
23+
// - paramName type: 参数的详细说明
24+
// * 补充说明1
25+
// * 补充说明2
26+
//
27+
// 返回值:
28+
// - type: 返回值的详细说明
29+
// * 可能的返回状态
30+
//
31+
// 错误处理:
32+
// - 可能返回的错误类型及触发条件
33+
//
34+
// 使用示例:
35+
// // 示例代码
36+
// result, err := MethodName(param)
37+
//
38+
// 性能考虑:
39+
// - 性能相关的注意事项
40+
//
41+
// 关联方法:
42+
// - 相关的其他方法
43+
```
44+
45+
## 已注释文件
46+
47+
以下文件已按规范添加中文注释：
48+
49+
- [validation.go](mdc:validation.go) - 验证和标准化方法
50+
- [storage.go](mdc:storage.go) - 存储接口和管理器
51+
52+
## 注释示例
53+
54+
```go
55+
// NormalizeCPE 对CPE对象进行标准化处理
56+
//
57+
// 功能描述:
58+
// - 对CPE对象的所有组件值进行标准化处理
59+
// - 创建一个新的CPE对象，保持原始对象不变(非破坏性操作)
60+
// - 根据标准化后的组件值重新生成CPE 2.3格式字符串
61+
//
62+
// 参数:
63+
// - cpe *CPE: 待标准化的CPE对象指针，可以为nil
64+
//
65+
// 返回值:
66+
// - *CPE: 标准化后的新CPE对象，如果输入为nil则返回nil
67+
```

‎.cursor/rules/project-structure.mdc‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: false
5+
---
6+
# CPE库项目结构
7+
8+
本项目是一个Go语言实现的CPE (Common Platform Enumeration) 库，用于处理CPE标识符的解析、验证、标准化和搜索。
9+
10+
## 核心文件
11+
12+
### 主要功能文件
13+
- [cpe.go](mdc:cpe.go) - 定义CPE基本结构和核心功能
14+
- [wfn.go](mdc:wfn.go) - 实现WFN (Well-Formed Name) 格式处理
15+
- [validation.go](mdc:validation.go) - 包含CPE对象和组件值的验证与标准化功能
16+
- [set.go](mdc:set.go) - 实现CPE集合相关功能
17+
- [search.go](mdc:search.go) - 提供CPE搜索和匹配功能
18+
- [advanced_matching.go](mdc:advanced_matching.go) - 高级匹配功能实现
19+
- [applicability.go](mdc:applicability.go) - 实现CPE适用性语言功能
20+
21+
### 存储相关文件
22+
- [storage.go](mdc:storage.go) - 定义存储接口和存储管理器
23+
- [file_storage.go](mdc:file_storage.go) - 文件系统存储实现
24+
- [memory_storage.go](mdc:memory_storage.go) - 内存存储实现
25+
- [dictionary.go](mdc:dictionary.go) - CPE字典功能
26+
27+
### 数据来源和外部集成
28+
- [datasource.go](mdc:datasource.go) - 数据源接口定义和实现
29+
- [nvd.go](mdc:nvd.go) - 美国国家漏洞数据库(NVD)集成
30+
- [cve.go](mdc:cve.go) - CVE(Common Vulnerabilities and Exposures)数据处理
31+
32+
### 解析器
33+
- [parser_2.2.go](mdc:parser_2.2.go) - CPE 2.2版本解析器
34+
- [parser_2.3.go](mdc:parser_2.3.go) - CPE 2.3版本解析器
35+
36+
### 组件类型定义
37+
- [part.go](mdc:part.go) - CPE部件类型(应用、操作系统、硬件)
38+
- [vendor.go](mdc:vendor.go) - 供应商组件
39+
- [product.go](mdc:product.go) - 产品组件
40+
- [version.go](mdc:version.go) - 版本组件
41+
- [update.go](mdc:update.go) - 更新组件
42+
- [edition.go](mdc:edition.go) - 版本组件
43+
- [language.go](mdc:language.go) - 语言组件
44+
45+
### 错误处理
46+
- [errors.go](mdc:errors.go) - 定义各种类型的错误和异常处理
47+
48+
## 主要类型和接口
49+
50+
- `CPE` - 表示一个Common Platform Enumeration对象
51+
- `Storage` - 存储接口，定义了CPE和CVE数据的存取方法
52+
- `StorageManager` - 管理主存储和缓存存储的对象，提供缓存加速功能
53+
- `DataSource` - 数据源接口，用于从外部获取CPE和CVE数据
54+
- `CPESet` - CPE集合，用于管理多个CPE及其关系
55+
- `MatchOptions` - 定义CPE匹配选项
56+
- `AdvancedMatchOptions` - 高级匹配选项
57+
- `CVEReference` - CVE引用数据结构
58+
59+
## 命名规范
60+
61+
- 类型名称使用驼峰命名法，如 `CPE`、`StorageManager`
62+
- 方法名称也使用驼峰命名法，如 `ValidateCPE`、`NormalizeComponent`
63+
- 变量和字段使用小驼峰命名法，如 `cpe`、`primaryStorage`
64+
65+
## 代码注释
66+
67+
- 所有方法和重要类型都有详细的中文注释
68+
- 注释包括功能描述、参数说明、返回值说明、错误处理、使用示例等

‎.cursor/rules/storage-guide.mdc‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: false
5+
---
6+
# CPE存储功能指南
7+
8+
CPE库提供了全面的存储功能，用于管理CPE和CVE数据。相关文件包括：
9+
10+
- [storage.go](mdc:storage.go) - 定义存储接口和存储管理器
11+
- [file_storage.go](mdc:file_storage.go) - 基于文件系统的存储实现
12+
- [memory_storage.go](mdc:memory_storage.go) - 基于内存的存储实现
13+
- [dictionary.go](mdc:dictionary.go) - CPE字典功能
14+
15+
## 核心接口
16+
17+
### Storage 接口
18+
19+
`Storage` 接口定义了CPE和CVE数据的存储和检索方法:
20+
21+
```go
22+
type Storage interface {
23+
Initialize() error
24+
Close() error
25+
StoreCPE(cpe *CPE) error
26+
RetrieveCPE(id string) (*CPE, error)
27+
UpdateCPE(cpe *CPE) error
28+
DeleteCPE(id string) error
29+
SearchCPE(criteria *CPE, options *MatchOptions) ([]*CPE, error)
30+
AdvancedSearchCPE(criteria *CPE, options *AdvancedMatchOptions) ([]*CPE, error)
31+
StoreCVE(cve *CVEReference) error
32+
RetrieveCVE(cveID string) (*CVEReference, error)
33+
// 更多方法...
34+
}
35+
```
36+
37+
## 存储实现
38+
39+
### 文件存储
40+
41+
文件存储 (`FileStorage`) 将CPE和CVE数据持久化到文件系统中：
42+
43+
```go
44+
fileStorage, err := cpe.NewFileStorage("/path/to/data", true)
45+
if err != nil {
46+
log.Fatalf("创建文件存储失败: %v", err)
47+
}
48+
err = fileStorage.Initialize()
49+
```
50+
51+
### 内存存储
52+
53+
内存存储 (`MemoryStorage`) 提供高性能但非持久化的存储：
54+
55+
```go
56+
memStorage, err := cpe.NewMemoryStorage()
57+
err = memStorage.Initialize()
58+
```
59+
60+
## 存储管理器
61+
62+
`StorageManager` 是一个管理主存储和缓存存储的封装类，主要方法包括:
63+
64+
- `NewStorageManager(primary Storage) *StorageManager` - 创建存储管理器
65+
- `SetCache(cache Storage)` - 设置缓存存储
66+
- `GetCPE(id string) (*CPE, error)` - 优先从缓存获取CPE
67+
- `StoreCPE(cpe *CPE) error` - 存储CPE到主存储和缓存
68+
- `GetCVE(cveID string) (*CVEReference, error)` - 优先从缓存获取CVE
69+
- `Search(criteria *CPE, options *MatchOptions) ([]*CPE, error)` - 搜索CPE
70+
- `AdvancedSearch(criteria *CPE, options *AdvancedMatchOptions) ([]*CPE, error)` - 高级搜索CPE
71+
- `InvalidateCache(id string)` - 使指定CPE的缓存失效
72+
- `ClearCache() error` - 清空缓存
73+
- `GetStats() (*StorageStats, error)` - 获取统计信息
74+
75+
## 使用示例
76+
77+
创建存储管理器:
78+
```go
79+
// 创建主存储
80+
fileStorage, _ := cpe.NewFileStorage("/path/to/data", true)
81+
fileStorage.Initialize()
82+
83+
// 创建存储管理器
84+
manager := cpe.NewStorageManager(fileStorage)
85+
86+
// 可选: 添加内存缓存
87+
memCache, _ := cpe.NewMemoryStorage()
88+
memCache.Initialize()
89+
manager.SetCache(memCache)
90+
```
91+
92+
检索CPE:
93+
```go
94+
cpeID := "cpe:2.3:o:microsoft:windows:10:*:*:*:*:*:*:*"
95+
windowsCPE, err := manager.GetCPE(cpeID)
96+
```
97+
98+
搜索CPE:
99+
```go
100+
// 搜索所有Microsoft Windows 10产品
101+
criteria := &cpe.CPE{
102+
Vendor: cpe.Vendor("microsoft"),
103+
ProductName: cpe.Product("windows"),
104+
Version: cpe.Version("10"),
105+
}
106+
options := &cpe.MatchOptions{}
107+
results, err := manager.Search(criteria, options)
108+
```
109+
110+
## 缓存策略
111+
112+
- 读取操作优先从缓存获取，缓存未命中再从主存储获取
113+
- 写入操作同时更新主存储和缓存
114+
- 支持单个缓存项失效和整个缓存清空
115+
- 默认缓存过期时间为1小时，可通过CacheTTLSeconds字段调整
116+
117+
## 数据字典
118+
119+
`CPEDictionary` 提供了管理CPE字典的功能：
120+
121+
```go
122+
// 创建字典
123+
dict := &cpe.CPEDictionary{
124+
Name: "NVD CPE Dictionary",
125+
Description: "National Vulnerability Database CPE Dictionary",
126+
Version: "1.0",
127+
Items: []*cpe.CPEDictionaryItem{...},
128+
}
129+
130+
// 存储字典
131+
err := storage.StoreDictionary(dict)
132+
133+
// 检索字典
134+
dict, err := storage.RetrieveDictionary()
135+
```

‎.cursor/rules/validation-guide.mdc‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: false
5+
---
6+
# CPE验证和标准化指南
7+
8+
CPE (Common Platform Enumeration) 库提供了全面的验证和标准化功能，确保CPE数据符合规范。相关文件包括：
9+
10+
- [validation.go](mdc:validation.go) - 核心验证和标准化功能
11+
- [errors.go](mdc:errors.go) - 验证错误类型定义
12+
- [wfn.go](mdc:wfn.go) - 形式良好名称(WFN)处理
13+
- [parser_2.3.go](mdc:parser_2.3.go) - CPE 2.3格式解析
14+
15+
## 主要方法
16+
17+
### 验证方法
18+
19+
- `ValidateComponent(value string, componentName string) error` - 验证单个CPE组件值是否合法
20+
- `ValidateCPE(cpe *CPE) error` - 验证整个CPE对象是否合法
21+
22+
### 标准化方法
23+
24+
- `NormalizeComponent(value string) string` - 标准化CPE组件值，如转换为小写、替换空格为下划线
25+
- `NormalizeCPE(cpe *CPE) *CPE` - 标准化整个CPE对象的所有字段
26+
27+
### 格式转换方法
28+
29+
- `FSStringToURI(fs string) string` - 将文件系统安全的CPE字符串转换为标准URI格式
30+
- `URIToFSString(uri string) string` - 将CPE URI转换为文件系统安全的字符串格式
31+
- `FormatCpe23(cpe *CPE) string` - 将CPE对象格式化为CPE 2.3 URI格式字符串
32+
33+
## CPE格式支持
34+
35+
库支持多种CPE格式：
36+
37+
1. **CPE 2.3 URI格式**：`cpe:2.3:a:microsoft:windows:10:*:*:*:*:*:*:*`
38+
2. **CPE 2.2 URI格式**：`cpe:/a:microsoft:windows:10`
39+
3. **格式化字符串**：`cpe:2.3:a:microsoft:windows:10:-:-:-:-:-:-:-`
40+
4. **文件系统安全格式**：`cpe___2.3_a_microsoft_windows_10_-_-_-_-_-_-_-`
41+
42+
## 验证规则
43+
44+
组件验证检查以下内容：
45+
46+
- 非法字符：`!@#$%^&(){}[]|\;'"<>?`
47+
- 控制字符：ASCII值小于32或大于126的字符
48+
- 特殊值：`*`(任意值)和`-`(不适用)
49+
50+
## 使用示例
51+
52+
验证CPE对象:
53+
```go
54+
cpe := &CPE{
55+
Part: PartType{ShortName: "a"},
56+
Vendor: "microsoft",
57+
ProductName: "windows",
58+
Version: "10"
59+
}
60+
err := ValidateCPE(cpe)
61+
if err != nil {
62+
log.Printf("CPE验证失败: %v", err)
63+
}
64+
```
65+
66+
标准化CPE对象:
67+
```go
68+
// 创建原始CPE对象
69+
originalCpe := &CPE{
70+
Vendor: "Microsoft", // 大写
71+
ProductName: "Windows 10", // 包含空格
72+
}
73+
74+
// 标准化
75+
normalizedCpe := NormalizeCPE(originalCpe)
76+
// 结果: normalizedCpe.Vendor = "microsoft"
77+
// 结果: normalizedCpe.ProductName = "windows_10"
78+
```
79+
80+
格式转换:
81+
```go
82+
// URI转文件系统安全格式
83+
fsString := URIToFSString("cpe:2.3:a:microsoft:windows:10:-:-:-:-:-:-:-")
84+
// 结果: "cpe___2.3_a_microsoft_windows_10_-_-_-_-_-_-_-"
85+
86+
// 文件系统安全格式转URI
87+
uriString := FSStringToURI("cpe___2.3_a_microsoft_windows_10_-_-_-_-_-_-_-")
88+
// 结果: "cpe:2.3:a:microsoft:windows:10:-:-:-:-:-:-:-"
89+
```
90+
91+
## 标准化过程
92+
93+
标准化处理包括：
94+
- 将所有字母转换为小写
95+
- 将空格替换为下划线
96+
- 将多个连续下划线替换为单个下划线
97+
- 特殊值(`*`和`-`)保持不变
98+
- 非破坏性操作，创建新对象而不修改原始对象
99+
100+
## 错误类型
101+
102+
验证错误包括：
103+
- `InvalidFormatError` - 格式错误
104+
- `InvalidPartError` - Part字段值无效
105+
- `InvalidAttributeError` - 组件字段包含非法字符

0 commit comments

Comments
 (0)