Revera

npm 包的信用评分。

Revera 帮助你在运行 npm install 之前判断某个包是否值得安装。它分析包质量、维护状况、安全性、生态健康度和发布者可信度——现在还能在整个依赖图中传递风险——并生成一份可解释的贝叶斯信誉报告。

演示

revera CLI Demo 实时查看 revera 检查并解释包。

快速开始

无需安装即可立即运行 revera：

npx revera check react

示例

检查像 request（已于 2020 年弃用）这样的包时，会立即给出具体原因警告你：

$ revera why request

  ▲ revera EXPLAIN
  ──────────────────────────────────────────────────
  Package:   [email protected]
  Overall:   38/100  Not Recommended

  Score Breakdown

    Maintenance             15/100  ███░░░░░░░░░░░░░░░░░
                           Release cadence, commit activity, issue responsiveness, maintainer count

    Stability               90/100  ██████████████████░░
                           SemVer compliance, major version history, API volatility over time

    Security               100/100  ████████████████████
                           Known CVEs, install scripts, repository transparency

    Package Quality         40/100  ████████░░░░░░░░░░░░
                           README completeness, license, test coverage indicators, exports

    Ecosystem              100/100  ████████████████████
                           Weekly download volume, GitHub stars, community forks

    Documentation           90/100  ██████████████████░░
                           README length, code examples, API references, external docs presence

    Developer Experience    40/100  ████████░░░░░░░░░░░░
                           TypeScript support, ESM compatibility, CLI tooling

    Publisher Trust        100/100  ████████████████████
                           Known malicious releases, protestware history, supply-chain incidents

  Why it scores well
    +  Stable API (v1.0.0+)
    +  Low API volatility
    +  Zero known vulnerabilities
    +  Permissive open-source license
    +  Code examples in README
    +  Structured API documentation
    +  No known publisher trust incidents

  Minor deductions
    -  Last release was 59 months ago
    -  Single maintainer (bus factor of 1)
    -  Missing native type definitions
    -  Legacy CommonJS only
    -  No native typings (bad TypeScript DX)

  Warnings
    !  Last release: 59 months ago. No recent updates detected. This may be normal for mature, stable libraries.
    !  Package has been officially marked as deprecated by the maintainer.

  Verdict
    Request has low confidence. revera recommends looking for alternatives due to security, activity, or stability concerns.

安装

全局安装，以便从任何目录访问可执行文件：

npm install -g @aaravmaloo/revera

用法

1. 检查包信誉

分析包并获取高层次的摘要报告：

revera check lodash

使用缓存文件以离线模式运行：

revera check express --offline

2. 解释包评分

获取分数的深度剖析、积极信号和扣分项：

revera why node-ipc

3. 筛查并添加依赖

在安装前筛查包，当信誉低于你配置的阈值时发出警告：

revera add express

你可以直接将标志传给包管理器：

revera add typescript --save-dev

4. 审计本地工作区

审计当前项目中的所有包（包括传递依赖），并计算整体项目健康评分：

revera audit

仅审计生产依赖：

revera audit --prod

仅审计直接依赖，跳过传递依赖：

revera audit --direct

5. GitHub 认证

通过 GitHub 认证以提高 API 速率限制（匿名 60 次/小时，认证后 5,000 次/小时）。你可以选择基于浏览器的 OAuth2 或手动输入 Personal Access Token。授权后，revera 会将令牌安全加密并存储在操作系统的密钥环中（Windows DPAPI、macOS 钥匙串或 Linux Secret Service）：

revera login

6. CLI 设置

管理保存在 ~/.revera/config.json 中的本地设置：

revera config
revera config set minScoreThreshold 75
revera config get minScoreThreshold

7. 系统诊断

验证环境设置、API 状态和网络连接延迟：

revera doctor

8. 缓存控制

检查或清除本地元数据缓存：

revera cache
revera cache clear

9. 更新检查

验证你是否正在运行 revera 引擎的最新版本：

revera update

对比

评分引擎（v2）

Revera v2 用四阶段贝叶斯 DAG 流水线取代了旧的扁平加权求和模型。

阶段 1 — 依赖图（DAG）

项目中的所有依赖都会被解析为有向无环图。每个节点跟踪其完整的传递依赖集，以便后续阶段计算准确的爆炸半径。

lodash ──► your-app
express ──► your-app
axios ──► some-lib ──► your-app   ← transitive

阶段 2 — 单包评分（贝叶斯 Beta 后验分布）

8 个评分类别中的每一个都从特定原型的先验（framework、cli、types-only、utility）开始，而不是平坦的无信息基线。观测到的信号会更新 Beta 分布的后验——这意味着超时或数据缺失会扩大可信区间，而不是默默默认为"干净"。

最终的每包评分是类别后验的置信度加权聚合（逆方差加权），同时产生点估计和 95% 可信区间。

阶段 3 — 否决检查

三种硬性覆盖会完全绕过贝叶斯评分并立即判定包不合格：

否决项	触发条件

阶段 4 — 传递风险传播

在计算完每包评分后，风险通过 DAG 自下而上传播（按拓扑顺序，先叶子节点）：

如果依赖项的 effectiveRisk 超过阈值，其父节点的风险将被下限锁定为 0.8（标记为受污染）。
每个节点的爆炸半径 = effectiveRisk × transitive_dependent_count。
审计输出中会追踪并展示最差子路径，让你确切知道是哪条依赖链导致了标记。

阶段 5 — 报告合成

最终审计报告将固有评分、继承的污染、可信区间和爆炸半径合并为单一排序输出。整体工作区评分是按爆炸半径加权的平均值。

漏洞数据库

Revera 在每次检查时并行查询三个独立的漏洞数据库。结果在用于评分之前按 CVE/GHSA 别名进行合并和去重。

如果某个来源超时或出错，其他来源仍会独立继续。VulnResult 会暴露哪些来源已响应（sources）以及哪些失败（failedSources），以便贝叶斯评分器适当扩大不确定性区间，而不是假设为干净。

架构与结构

.github/              # CI configurations
docs/                 # Architecture specs and algorithm diagrams
src/
  ├── commands/       # CLI command handlers (check, why, add, audit, config, cache, update)
  ├── engine/
  │   ├── dag.ts          # DAG construction + topological sort + blast-radius computation
  │   ├── propagation.ts  # Bottom-up transitive risk propagation
  │   ├── scoring.ts      # Bayesian Beta posteriors, archetype priors, veto checks
  │   ├── vuln.ts         # Multi-source vuln aggregator (OSV + GitHub + npm)
  │   ├── trust.ts        # Publisher trust incident database
  │   ├── typosquat.ts    # Edit-distance typosquat detection
  │   ├── npm.ts          # npm registry + download stats fetcher
  │   └── github.ts       # GitHub repo stats + README fetcher
  ├── ui/             # Console view templates (reporter formatters, theme styles)
  └── utils/          # Filesystem helpers (caching, configuration, package managers)
tests/                # Unit test suites
benchmarker/          # Large-scale benchmark suite (100k+ packages)

基准测试

Revera 在 benchmarker/ 中内置了一套大规模基准测试套件，可并行测试 10 万多个 npm 包，并生成一份 GitHub 可读的报告。

运行基准测试

cd benchmarker
npm install
npm run fetch-dataset          # one-time: pulls ~100k packages into datasets/npm.jsonl
./benchmark.sh --workers 16   # runs the full suite

每次运行都会生成一个自包含的输出目录，包含：

路线图

常见问题

如何避免 GitHub API 速率限制？

没有令牌时，匿名查询的速率限制为每小时 60 次请求。你可以通过配置设置 Personal Access Token：

revera config set githubToken ghp_YOUR_TOKEN

如果离线会发生什么？

Revera 会回退到使用缓存文件。你可以使用 --offline 标志显式以离线模式运行命令。如果某个漏洞来源不可用，贝叶斯评分器会扩大该包的可信区间，而不是假设为干净。

add 命令会修改我的项目吗？

Revera 充当 shell 包装器。它会在筛查后运行真正的包安装程序。

审计输出中的"受污染"（tainted）包是什么？

当包的某个传递依赖触发了否决或评分极低时，该包会被标记为受污染。审计输出会显示最差子路径，以便你追踪导致标记的确切依赖链。

三个数据库之间的漏洞如何去重？

每个漏洞通过其 CVE ID、GHSA ID 或 npm advisory ID 进行标识。当同一漏洞出现在多个来源中时，会合并为一个规范条目。OSV 数据在文本字段（摘要、详情）中优先；所有来源中最高的严重性评级和最完整的已修复版本范围将被保留。

贡献

请查阅贡献指南，了解环境搭建、代码风格规则和 PR 指南。

免责声明

Revera 基于可观测的项目信号和历史数据提供信誉评分。它旨在辅助工程决策，不应被视为确定性的安全审计。

许可证

Revera 根据 MIT 许可证分发。

CVE 漏洞	✔	✔	✔	✔
多个漏洞数据库	✖	部分	✔	✔
生态信誉	✖	✖	部分	✔
可解释评分	✖	✖	部分	✔
发布者可信度检查	✖	✖	部分	✔
仿冒包检测	✖	✖	部分	✔
传递风险传播	✖	✖	✖	✔
贝叶斯置信区间	✖	✖	✖	✔

安全性	20%	活跃 CVE（3 个数据库）、安装脚本、仓库透明度
发布者可信度	15%	Protestware 历史、蓄意破坏、账户劫持事件
维护状况	13%	发布节奏、近期提交、未解决问题响应率
稳定性	12%	SemVer 合规性、主版本频率、预 1.0 成熟度
包质量	13%	源文件大小、许可证、exports 配置
生态系统	13%	周下载量（对数缩放）、GitHub Star、贡献者数量
文档	9%	README 完整性、代码示例、API 参考覆盖度
开发者体验	5%	原生 TS 类型定义、ESM exports、tree-shaking 支持

OSV (osv.dev)	Google 开源安全	✖	聚合 NVD、GitHub Advisory、RUSTSEC 等
GitHub Advisory DB	GitHub 安全	✖	丰富的 CVSS 评分 + 已修复版本范围
npm Advisory	registry.npmjs.org	✖	与 `npm audit` 相同的数据；有时比 OSV 更早发布

`BENCHMARK.md`	单份 GitHub 可读报告（准确率、按标签检测、分数分布、延迟）
`report.html`	带图表的交互式浏览器报告
`summary.json`	机器可读的聚合统计
`results.jsonl`	所有测试包的逐包结果
`comparison.json`	与上次运行的差异（回归 + 改进）

`trusted`	7,051	96.6%
`malicious`	9	22.2% （v1 基线 — v2 否决检查修复了此问题）
`typosquat`	20	35.0% （v1 基线 — v2 编辑距离否决修复了此问题）
总体（已标注）	7,085	96.5%

revera

最受欢迎