therayyanawaz/VulnScanner

# 🔎 VulnScanner [](https://github.com/therayyanawaz/VulnScanner/actions/workflows/ci.yml) [](https://github.com/therayyanawaz/VulnScanner/actions/workflows/release.yml) [](https://www.python.org/downloads/) [](LICENSE) [](#-output-formats) **面向现代依赖风险工作流的本地优先漏洞情报工具。** VulnScanner 接入公开漏洞情报（NVD、KEV、EPSS），在 SQLite 中丰富本地 CVE 数据，并通过确定性的 CI 策略门禁、离线缓存模式和基线差异比对来扫描 lockfile/manifest 文件。 ## ✨ 为什么选择 VulnScanner - 🧠 **高信号量**：严重性 + KEV 利用状态 + EPSS 概率。 - 🏠 **本地优先**：基于 SQLite 的缓存，支持重复扫描。 - 🛡️ **CI 就绪门禁**：根据严重性、KEV、EPSS、严格缓存和仅限新增差异策略决定是否失败。 - ⚡ **运维硬化**：重试、退避、有界并发和明确的退出代码。 - 📦 **生态系统覆盖**：支持 npm + Python lockfile。 ## 🧭 目录 - [🧩 功能集](#-feature-set) - [🏗️ 架构](#️-architecture) - [📡 数据源](#-data-sources) - [🚀 快速开始](#-quick-start) - [📘 手册页](#-manual-page) - [🛠️ 命令参考](#️-command-reference) - [📏 策略与报告](#-policy--reporting) - [🔢 退出代码](#-exit-codes) - [⚙️ 配置](#️-configuration) - [🗄️ 数据库模型](#️-database-model) - [🧪 CI/CD 示例](#-cicd-example) - [🛣️ 路线图](#️-roadmap) - [🤝 贡献](#-contributing) - [📄 许可证](#-license) ## 🧩 功能集 ### ✅ 已实现的命令 - `vulnscanner nvd-sync` - `vulnscanner kev-sync` - `vulnscanner epss-sync` - `vulnscanner scan-deps` - `vulnscanner state show` - `vulnscanner state reset` - `vulnscanner cache stats` - `vulnscanner cache clear` ### 🧠 功能说明 - `nvd-sync`：具有速率限制感知重试功能的增量 NVD CVE 接入。 - `kev-sync`：导入 CISA KEV 并将匹配的 CVE 标记为已知被利用。 - `epss-sync`：导入 EPSS 并用分数 + 百分位丰富 CVE 信息。 - `scan-deps`：扫描依赖清单，丰富发现结果，渲染报告并执行策略。 - `state show/reset`：检查或重置同步检查点元数据。 - `cache stats/clear`：检查或清除缓存表，并进行一致性更新。 ### 📦 支持的依赖清单 - `package-lock.json` - `yarn.lock` - `pnpm-lock.yaml` - `poetry.lock` - `uv.lock` - `Pipfile.lock`（精确锁定版本：`==version` 或 `===version`） - `requirements.txt`（精确锁定版本：`pkg==version`；支持 extras/markers/哈希后缀） ## 🏗️ 架构 ``` flowchart LR A[Manifests\npackage-lock.json\nyarn.lock\npnpm-lock.yaml\npoetry.lock\nuv.lock\nPipfile.lock\nrequirements.txt] --> B[scan-deps] B --> C[OSV API] B --> D[(SQLite cache)] E[nvd-sync] --> F[NVD API] E --> D G[kev-sync] --> H[CISA KEV] G --> D I[epss-sync] --> J[EPSS] I --> D D --> K[Policy Engine\nseverity / KEV / EPSS / baseline] K --> L[Output\nTable / JSON / CSV / Markdown / SARIF] K --> M[CI Exit Code] ``` ## 📡 数据源 | 来源 | 用途 | URL | | --- | --- | --- | | NVD API | 规范化 CVE 接入 | `https://services.nvd.nist.gov/rest/json/cves/2.0` | | CISA KEV | 已知被利用的 CVE | `https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json` | | EPSS CSV | 漏洞利用可能性评分 | `https://epss.empiricalsecurity.com/epss_scores-current.csv.gz` | | OSV API | 包漏洞映射 | `https://api.osv.dev/v1/querybatch` | ## 🚀 快速开始 ### 1) 安装 ``` git clone https://github.com/therayyanawaz/VulnScanner.git cd VulnScanner python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e . ``` ### 2) （可选）设置 NVD API Key ``` export NVD_API_KEY="your-nvd-api-key" ``` ### 3) 同步情报 ``` vulnscanner nvd-sync --since "2024-08-01T00:00:00Z" vulnscanner kev-sync vulnscanner epss-sync ``` ### 4) 运行扫描 + 策略 ``` vulnscanner scan-deps package-lock.json --policy strict ``` ## 📘 手册页 快速 CLI 帮助： ``` vulnscanner -h vulnscanner scan-deps -h ``` 项目 man page： ``` man ./docs/man/vulnscanner.1 ``` ## 🛠️ 命令参考 ### `vulnscanner nvd-sync` ``` vulnscanner nvd-sync --since "2024-08-01T00:00:00Z" --until "2024-08-02T00:00:00Z" vulnscanner nvd-sync --since 7d --until now ``` 选项： - `--since`：带时区的 ISO8601 时间，或相对值（`7d`、`12h`、`today`、`yesterday`、`now`） - `--until`：带时区的 ISO8601 时间，或相对值（`7d`、`12h`、`today`、`yesterday`、`now`） - `--debug` 故障排除： - 如果遇到 NVD `429 Too Many Requests`，请使用更短的时间窗口重试： `vulnscanner nvd-sync --since 90d` - 如果在使用 API key 时 NVD 返回 `HTTP 404`，请将其视为密钥/认证问题： `unset NVD_API_KEY` `vulnscanner nvd-sync --since 7d --until now` （然后在 `https://nvd.nist.gov/developers/request-an-api-key` 重新生成密钥） - 如果同步在较长的时间窗口内报告 0 个 CVE，请在 NVD 同步后刷新丰富化缓存： `vulnscanner kev-sync --force` `vulnscanner epss-sync --force` `vulnscanner state show` ### `vulnscanner kev-sync` ``` vulnscanner kev-sync vulnscanner kev-sync --force ``` 选项： - `--force` ### `vulnscanner epss-sync` ``` vulnscanner epss-sync vulnscanner epss-sync --force ``` 选项： - `--force` ### `vulnscanner state show` ``` vulnscanner state show vulnscanner state show --format json ``` 选项： - `--format [table|json]` ### `vulnscanner state reset` ``` vulnscanner state reset vulnscanner state reset --key nvd_last_mod ``` 选项： - `--key [nvd_last_mod|kev_last_sync|epss_last_sync]`（可重复；省略则重置全部） ### `vulnscanner cache stats` ``` vulnscanner cache stats vulnscanner cache stats --format json ``` 选项： - `--format [table|json]` ### `vulnscanner cache clear` ``` vulnscanner cache clear vulnscanner cache clear --target kev --target epss vulnscanner cache clear --all ``` 选项： - `--target [osv|osv-vuln|kev|epss]`（可重复；默认：`osv` + `osv-vuln`） - `--all` ### `vulnscanner scan-deps` ``` vulnscanner scan-deps package-lock.json vulnscanner scan-deps requirements.txt --format json --output reports/deps.json vulnscanner scan-deps Pipfile.lock --format sarif --output reports/deps.sarif vulnscanner scan-deps poetry.lock --no-network --strict-cache vulnscanner scan-deps package-lock.json --sort-by epss --top 10 vulnscanner scan-deps package-lock.json --baseline reports/prev.json --new-only vulnscanner scan-deps package-lock.json --baseline reports/prev.json --fail-on high --fail-on-new-only vulnscanner scan-deps package-lock.json --save-baseline reports/new-baseline.json ``` 选项： - `--format [table|json|csv|markdown|sarif]` - `--output FILE` - `--top N` - `--summary-only` - `--sort-by [severity|epss|package|id]` - `--baseline FILE` - `--save-baseline FILE` - `--new-only`（需要 `--baseline`） - `--fail-on-new-only`（需要 `--baseline`） - `--min-severity [low|medium|high|critical]` - `--kev-only` - `--epss-min 0.0..1.0` - `--fail-on [low|medium|high|critical]` - `--fail-on-kev` - `--fail-on-epss 0.0..1.0` - `--policy [none|balanced|strict]` - `--no-network` - `--strict-cache`（需要 `--no-network`） - `--debug` ## 📏 策略与报告 ### 🎯 策略预设 - `none`：无默认值 - `balanced`：`severity>=critical`，`epss>=0.9`（除非明确覆盖） - `strict`：`severity>=high`，`epss>=0.7`（除非明确覆盖） ### 💡 实用工作流 ``` # 高危及以上时失败 vulnscanner scan-deps package-lock.json --fail-on high # 优先处理可能被利用的问题 vulnscanner scan-deps package-lock.json --min-severity high --kev-only --epss-min 0.5 # 离线确定性门禁 vulnscanner scan-deps poetry.lock --no-network --strict-cache # PR diff 门禁：仅针对新发现 vulnscanner scan-deps package-lock.json --baseline reports/prev.json --new-only # 保留完整输出，仅对新出现的高危及以上问题设置门禁 vulnscanner scan-deps package-lock.json --baseline reports/prev.json --fail-on high --fail-on-new-only ``` ### 📤 输出格式 - `table`：终端可读摘要 - `json`：自动化友好的结构化数据 - `csv`：电子表格 / BI 导出 - `markdown`：PR 就绪报告输出 - `sarif`：GitHub 代码扫描 / 安全工具 ## 🔢 退出代码 | 代码 | 含义 | | ---: | --- | | `10` | 策略失败（`--fail-on`、`--fail-on-kev`、`--fail-on-epss`） | | `11` | 严格缓存未命中失败（`--no-network --strict-cache`） | | `12` | Feed 同步失败（`nvd-sync`、`kev-sync`、`epss-sync`） | | `13` | 依赖扫描执行失败 | ## ⚙️ 配置 | 变量 | 默认值 | 描述 | | --- | --- | --- | | `VULNSCANNER_DB` | `vulnscanner.db` | SQLite 数据库路径 | | `NVD_API_KEY` | 未设置 | 启用更高的 NVD 请求配额 | | `NVD_MAX_PER_30S` | `5`（无密钥）或 `50`（有密钥） | 每 30 秒的 NVD 请求数 | | `NVD_MAX_DAYS_PER_REQUEST` | `3` | NVD 分块窗口（天） | | `OSV_TTL_HOURS` | `12` | OSV 缓存 TTL | | `OSV_HTTP_TIMEOUT_SECONDS` | `60` | OSV HTTP 超时 | | `OSV_HTTP_RETRIES` | `3` | OSV 瞬态重试次数 | | `OSV_VULN_DETAIL_CONCURRENCY` | `20` | OSV 详情查找并发数 | | `KEV_TTL_HOURS` | `24` | KEV 同步 TTL | | `EPSS_TTL_HOURS` | `720` | EPSS 同步 TTL | | `VULNSCANNER_UA` | 项目 UA | 上游 User-Agent | ## 🗄️ 数据库模型 核心表： - `cves`：规范化 CVE 记录 + 丰富信息（`is_known_exploited`、`epss_score`、`epss_percentile`） - `meta`：同步状态（`nvd_last_mod`、`kev_last_sync`、`epss_last_sync`） - `osv_cache`：包/版本 OSV 查询缓存 - `osv_vuln_cache`：OSV 漏洞详情缓存 - `kev`：KEV Feed 记录 - `epss`：EPSS Feed 记录 SQLite 设置： - WAL 模式 - 启用外键 - 在 CVE 来源 + 修改时间戳上建立索引 ## 🧪 CI/CD 示例 ``` name: Dependency Risk Gate on: [push, pull_request] jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "3.12" - run: pip install -e . - name: Refresh intelligence env: NVD_API_KEY: ${{ secrets.NVD_API_KEY }} run: | vulnscanner nvd-sync --since "2024-01-01T00:00:00Z" vulnscanner kev-sync vulnscanner epss-sync - name: Enforce policy run: vulnscanner scan-deps package-lock.json --policy strict ``` ## 🛣️ 路线图 ### ✅ 已完成 - NVD 增量同步 + 弹性控制 - KEV 同步和被利用 CVE 丰富化 - EPSS 同步和评分丰富化 - 策略驱动的依赖扫描和多格式报告 ### ⏭️ 下一步 - 容器/文件系统扫描（`scan-image`） - SBOM 接入和分析（`scan-sbom`） - 丰富的 HTML 治理报告 - 可选的自托管情报集成 ## 🤝 贡献 ``` git clone https://github.com/therayyanawaz/VulnScanner.git cd VulnScanner python -m venv .venv source .venv/bin/activate pip install -e ".[dev]" pytest -q ``` 极佳的贡献方向： - 额外生态系统的解析器支持 - 扫描器适配器（容器、SBOM、IaC） - 策略/报告用户体验增强 - 存储和性能优化 ## 📄 许可证 MIT。详见 [LICENSE](LICENSE)。

标签：DevSecOps, EPSS, KEV, Lerna, Lockfile, npm, NVD, Python, SARIF, SQLite, XSS, 上游代理, 云安全监控, 依赖扫描, 加密, 图数据库, 基线比对, 文档安全, 无后门, 模型提供商, 漏洞情报, 漏洞扫描器, 离线缓存, 策略执行, 结构化查询, 网络安全, 自动化安全, 软件开发工具包, 逆向工具, 隐私保护, 静态分析, 风险量化