kevgeoleo/npm-vuln-scanner
GitHub: kevgeoleo/npm-vuln-scanner
一款 CLI 漏洞扫描工具，支持跨多漏洞数据库在自定义时间窗口内查询 npm 包漏洞并按 CVSS 评分过滤输出结构化报告。
Stars: 0 | Forks: 0
# npm-vuln-scanner
一款 CLI 工具，可在可配置的时间窗口内查询多个漏洞数据库中的 **npm 包漏洞**，根据 CVSS 分数或严重程度进行过滤，并将结果写入结构化的 JSON 文件。
设置可以在 `config.json` 中定义，并可通过 CLI 参数在每次运行时进行选择性覆盖。
## 支持的来源
| 来源 | 是否需要密钥？ | 备注 |
| ---------------------- | ------------------------- | --------------------------------------------------------------- |
| **GitHub Advisory DB** | 可选（`GITHUB_TOKEN`） | 默认来源。Token 可将速率限制从 60 提升至 5,000 请求/小时 |
| **NVD (NIST)** | 可选（`NVD_API_KEY`） | 关键字搜索 `npm` 的 CVE。无密钥：5 请求/30 秒 |
| **OSV (osv.dev)** | 无 | 开放，无需身份验证 |
## 环境要求
`node v24+`
## 安装
```
npm install
npm link #optional - enables user to directly call CLI tool using nvs command
```
## 测试
```
npm test
```
## API 密钥
将密钥添加到 **`.env`**：
```
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
NVD_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```
- **GitHub token**: https://github.com/settings/tokens (获取公开建议数据无需任何 scope)
- **NVD API key**: https://nvd.nist.gov/developers/request-an-api-key
## 配置
所有持久化设置均位于 **`config.json`** 中。其中任何设置都可以使用 CLI 参数针对单次运行进行覆盖 — 请参阅下方的 [CLI 参数](#cli-flags) 部分。
### 时间窗口
使用以下两种模式之**一**：
```
// Mode A — last N hours (here: last 24 h)
"time_window": {
"last_hours": 24 // default - null
}
// Mode B — explicit date range (inclusive)
"time_window": {
"date_range": {
"from": "01-01-2025", // DD-MM-YYYY
"to": "31-01-2025" // default - null
}
}
```
### 数据库
```
"databases": {
"github_advisory": true, // always a good default
"nvd": false, // set true if you have NVD_API_KEY
"osv": false // free, no key needed
}
```
### CVSS 过滤
```
// Option A — numeric threshold (overrides severity_filter)
"cvss": {
"version": "any", // "v3" | "v4" | "any"
"min_score": 7.0 // include scores >= 7.0
}
// Option B — named severities (used when min_score is null)
"cvss": {
"version": "any",
"min_score": null,
"severity_filter": ["CRITICAL", "HIGH"]
}
```
### 输出
```
"output": {
"file": "output/vulnerabilities.json",
"pretty_print": true
}
```
## 用法
### 使用 config.json 默认值运行
```
node src/index.js
# 或
npm run scan --
# 或
nvs # if you have run npm link to make nvs globally available
```
### 使用 CLI 覆盖参数运行
您传递的任何参数都仅针对该次运行覆盖 `config.json` 中的相应值。未传递的参数将回退到配置文件。
```
# 最近 5 小时，而不是 config.json 中指定的任何内容
node src/index.js --hours 5
# 显式日期范围
node src/index.js --from 01-06-2025 --to 10-06-2025
# 查询 github 和 osv，不管 config 如何
node src/index.js --sources github,osv
# 仅限严重漏洞
node src/index.js --severity CRITICAL
# 数字分数阈值 + 指定的 CVSS 版本
node src/index.js --min-score 7.5 --cvss-version v3
# 写入到不同的输出文件
node src/index.js --output results/daily.json
# 自由组合 — 未指定的选项仍从 config.json 中获取
node src/index.js --hours 24 --sources github,osv --severity CRITICAL,HIGH
# 完全使用不同的 config 文件
node src/index.js --config ./configs/weekly.json
```
## CLI 参数
所有参数都是可选的。提供时它们会覆盖 `config.json`；省略时则使用配置值。控制台输出会用 `(CLI)` 标记被覆盖的设置，以便您一目了然地了解各个配置的来源。
### 时间窗口 — 选择其一
| 参数 | 值 | 示例 |
| --------------------- | ------------------------------------------- | ------------------- |
| `--hours ` | 距今过去 N 小时 | `--hours 5` |
| `--from ` | 日期范围的开始 | `--from 01-06-2025` |
| `--to ` | 日期范围的结束（必须与 `--from` 搭配使用） | `--to 10-06-2025` |
### 来源
| 参数 | 值 | 示例 |
| ------------------ | --------------------------------------- | ---------------------- |
| `--sources
- ` | 逗号分隔：`github`, `nvd`, `osv` | `--sources github,osv` |
`github` 是 `github_advisory` 的别名。
### CVSS 过滤 — 在 `--severity` / `--min-score` 中选择其一
| 参数 | 值 | 示例 |
| ---------------------- | ----------------------------------- | -------------------------- |
| `--severity
- ` | `CRITICAL`, `HIGH`, `MEDIUM`, `LOW` | `--severity CRITICAL,HIGH` |
| `--min-score
标签：Cilium, GNU通用公共许可证, MITM代理, Node.js, NPM, XSS, 依赖安全, 数据可视化, 漏洞情报, 自定义脚本