alejandrosaenz117/fetch-cwe-list
GitHub: alejandrosaenz117/fetch-cwe-list
一个 Node.js 模块，用于从 MITRE 实时拉取并解析最新或指定版本的 CWE 列表，解决本地维护权威弱点库繁琐且易过期的问题。
Stars: 10 | Forks: 2
# 获取 CWE 列表
一个简单、安全的 Node.js 模块，用于获取并解析最新的通用弱点枚举（CWE）列表，来源为 MITRE。
## 快速开始
```
npm install fetch-cwe-list
```
```
const fetchCweList = require('fetch-cwe-list')
// Fetch latest CWE list
const cweList = await fetchCweList()
console.log(`Fetched ${cweList.length} CWE entries`)
// Fetch specific version
const cweListV413 = await fetchCweList('4.13')
```
仅此而已。每个条目都包含解析后的 CWE 数据以及丰富的对外引用。
## 功能特性
- **实时数据** — 始终最新，直接从 MITRE 获取
- **丰富** — 包含 CAPEC 映射、CVE 上下文、层级关系与对外引用
- **缓存** — 可选 1 小时 TTL 缓存（可配置）
- **查询助手** — `findById`、`findByName`、`findByCapec` 用于常见查找
- **安全** — 30 秒超时、100MB 大小限制、XXE 防护、无共享状态
- **TypeScript** — 包含完整的类型定义
## 使用方法
### 获取并迭代
```
const cweList = await fetchCweList()
cweList.forEach(cwe => {
console.log(`${cwe.ID}: ${cwe.Name}`)
})
```
### 使用查询助手
```
const { findById, findByName, findByCapec } = require('fetch-cwe-list')
const cweList = await fetchCweList()
const cwe79 = findById(cweList, '79')
const injections = findByName(cweList, 'injection')
const xssCwes = findByCapec(cweList, '209') // CAPEC-209: XSS Using MIME Type Mismatch
```
### 访问丰富数据
```
const cweList = await fetchCweList()
const cwe79 = findById(cweList, '79')
// CAPEC attack patterns
console.log(cwe79.CAPEC_IDs) // ['63', '85', '209', '588', '591', '592']
// Hierarchy (parent weaknesses)
console.log(cwe79.Hierarchy.parents) // ['74']
// Known CVEs
cwe79.Known_CVEs.forEach(({ id, description }) => {
console.log(`${id}: ${description}`)
})
```
### 缓存控制
```
const { clearCache } = require('fetch-cwe-list')
const list1 = await fetchCweList() // Downloads, caches for 1 hour
const list2 = await fetchCweList() // Instant (cached)
// Bypass cache
const fresh = await fetchCweList('latest', { cache: false })
// Invalidate cache
clearCache()
```
## API 参考
### `fetchCweList([version], [opts])`
**参数：**
- `version`（字符串，可选） — 要获取的 CWE 版本（例如 `'4.13'`）。默认为 `'latest'`。
- `opts`（对象，可选） — 选项：
- `cache`（布尔值，可选） — 设为 `false` 可绕过缓存。默认：`true`
**返回值：**
- 解析为 CWE 对象数组的 Promise
**异常：**
- 如果下载失败、超时或版本未找到，将抛出错误
### `clearCache()`
清除内存缓存。缓存实例本身不会暴露，以防止通过 `cache.set()` 外部注入污染。
### `findById(cweList, id)`
按 ID 字符串查找单个 CWE。
**参数：**
- `cweList` — `fetchCweList()` 返回的数组
- `id`（字符串） — CWE ID，例如 `'79'`
**返回值：**
- CWE 对象或 `undefined`
### `findByName(cweList, pattern)`
查找名称中包含给定字符串（不区分大小写）的所有 CWE。
**参数：**
- `cweList` — `fetchCweList()` 返回的数组
- `pattern`（字符串） — 不区分大小写的子字符串
**返回值：**
- CWE 对象数组
**注意：** 出于防止 ReDoS 攻击的考虑，不支持正则表达式。
### `findByCapec(cweList, capecId)`
查找映射到给定 CAPEC ID 字符串的所有 CWE。
**参数：**
- `cweList` — `fetchCweList()` 返回的数组
- `capecId`（字符串） — CAPEC ID，例如 `'86'`
**返回值：**
- CWE 对象数组
## 数据结构
每个 CWE 条目包含 MITRE 的字段以及 v0.1.0 后的丰富数据：
| 字段 | 类型 | 始终存在 | 描述 |
|------|------|----------|------|
| `ID` | `string` | 是 | CWE ID（从数值解析器输出标准化） |
| `CAPEC_IDs` | `string[]` | 是 | 映射的 CAPEC 攻击模式 ID 数组（若无则为空） |
| `Known_CVEs` | `{ id, description }[]` | 是 | 来自 Observed_Examples 的 CVE（若无则为空数组） |
| `Hierarchy` | object | 否 | 父级关系（若无 Related_Weaknesses 则不存在） |
| `References.Full_Details` | object[] | 否 | 丰富的对外引用对象数组 |
示例条目：
```
{
ID: "79",
Name: "Improper Neutralization of Input During Web Page Generation ('Cross-site Scripting')",
Status: "Stable",
Description: "...",
CAPEC_IDs: ['63', '85', '209', '588', '591', '592'],
Known_CVEs: [
{ id: 'CVE-2021-1879', description: '...' }
],
Hierarchy: {
parents: ['74'],
relationships: [
{ nature: 'ChildOf', cweId: '74', viewId: '1000', ordinal: 'Primary' }
]
},
References: {
Reference: [{ External_Reference_ID: "REF-2" }],
Full_Details: [
{
Reference_ID: "REF-2",
Author: "OWASP",
Title: "Cross Site Scripting (XSS)",
URL: "https://www.owasp.org/..."
}
]
}
}
```
**注意：** 单个引用会自动规范化为数组，并像多个引用一样进行丰富。所有 ID 均标准化为字符串，以保证跨所有 API 表面的一致性。
## 许可证
MIT
## 作者
[Alejandro Saenz](https://github.com/alejandrosaenz117)
标签：CAPEC, CVE, GNU通用公共许可证, MITM代理, MITRE, Node.js, XML 请求, XXE防护, 代码安全, 外部引用, 安全, 安全开发, 安全配置, 数字签名, 数据获取, 查询辅助, 漏洞映射, 漏洞枚举, 类型定义, 缓存, 自定义脚本, 超时处理