Revera

Кредитный рейтинг для npm-пакетов.

Revera помогает решить, стоит ли устанавливать пакет, прежде чем вы выполните npm install. Она анализирует качество пакета, сопровождение, безопасность, состояние экосистемы и доверие к издателю — и теперь транзитивно распространяет риск на весь граф зависимостей — после чего формирует объяснимый байесовский отчёт о репутации.

Демо

Смотрите, как 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

Аудит только production-зависимостей:

revera audit --prod

Аудит только прямых зависимостей, пропуская транзитивные:

revera audit --direct

5. Аутентификация GitHub

Авторизуйтесь в GitHub, чтобы увеличить лимиты API (60 запросов в час анонимно против 5 000 в час при аутентификации). Вы можете выбрать авторизацию через браузер OAuth2 или вручную ввести Personal Access Token. После авторизации revera безопасно шифрует и сохраняет токен в системной связке ключей (Windows DPAPI, macOS Keychain или 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   ← транзитивная

Этап 2 — Оценка каждого пакета (байесовские бета-апостериоры)

Каждая из 8 категорий оценки начинается с специфичного для архетипа априорного распределения (framework, cli, types-only, utility), а не с плоского неинформативного базового уровня. Наблюдаемые сигналы обновляют апостериорное бета-распределение — это означает, что таймаут или отсутствие данных расширяет доверительный интервал, а не молча принимает значение «чисто».

Итоговая оценка пакета — это взвешенная по уверенности агрегация апостериорных распределений категорий (взвешивание по обратной дисперсии), дающая как точечную оценку, так и 95% доверительный интервал.

Этап 3 — Вето-проверки

Три жёстких переопределения полностью обходят байесовский скоринг и немедленно отклоняют пакет:

Этап 4 — Транзитивное распространение риска

После вычисления оценок всех пакетов риск распространяется снизу вверх по DAG (в топологическом порядке, сначала листья):

• Если effectiveRisk зависимости превышает порог, риск родительского узла ограничивается снизу значением 0.8 (помечается как заражённый).
• Радиус поражения каждого узла = effectiveRisk × количество транзитивных зависимостей.
• Худший подпуть отслеживается и выводится в результатах аудита, чтобы вы точно знали, какая цепочка зависимостей вызвала предупреждение.

Этап 5 — Синтез отчёта

Итоговый отчёт аудита объединяет собственные оценки, унаследованное заражение, доверительные интервалы и радиусы поражения в единый ранжированный вывод. Общая оценка рабочего пространства — это среднее, взвешенное по радиусу поражения.

Базы данных уязвимостей

Revera запрашивает три независимые базы данных уязвимостей параллельно при каждой проверке. Результаты объединяются и дедуплицируются по алиасам CVE/GHSA перед использованием в оценке.

Если источник не отвечает или выдаёт ошибку, остальные продолжают работу независимо. VulnResult показывает, какие источники ответили (sources), а какие завершились ошибкой (failedSources), чтобы байесовский скоринг мог соответствующим образом расширить интервал неопределённости, а не предполагать «чисто».

Архитектура и структура

.github/              # CI-конфигурации
docs/                 # Архитектурные спецификации и диаграммы алгоритмов
src/
  ├── commands/       # Обработчики CLI-команд (check, why, add, audit, config, cache, update)
  ├── engine/
  │   ├── dag.ts          # Построение DAG + топологическая сортировка + вычисление радиуса поражения
  │   ├── propagation.ts  # Транзитивное распространение риска снизу вверх
  │   ├── scoring.ts      # Байесовские бета-апостериоры, априорные распределения архетипов, вето-проверки
  │   ├── vuln.ts         # Агрегатор уязвимостей из нескольких источников (OSV + GitHub + npm)
  │   ├── trust.ts        # База данных инцидентов доверия к издателям
  │   ├── typosquat.ts    # Обнаружение typosquat-атак по расстоянию Левенштейна
  │   ├── npm.ts          # Получение данных из npm registry + статистики загрузок
  │   └── github.ts       # Получение статистики репозитория GitHub + README
  ├── ui/             # Шаблоны консольного вывода (форматтеры отчётов, стили тем)
  └── utils/          # Вспомогательные функции файловой системы (кэширование, конфигурация, менеджеры пакетов)
tests/                # Наборы модульных тестов
benchmarker/          # Крупномасштабный набор бенчмарков (100k+ пакетов)

Бенчмарки

Revera поставляется со встроенным крупномасштабным набором бенчмарков в benchmarker/, который тестирует 100k+ npm-пакетов параллельно и создаёт единый отчёт, читаемый на GitHub.

Запуск бенчмарка

cd benchmarker
npm install
npm run fetch-dataset          # однократно: загружает ~100k пакетов в datasets/npm.jsonl
./benchmark.sh --workers 16   # запускает полный набор

Каждый запуск создаёт самодостаточный выходной каталог со следующими файлами:

Последний бенчмарк (алгоритм v2, эталонный набор данных)

Бенчмарк v1 был запущен до внедрения вето-проверок v2. Показатели по меткам malicious/typosquat отражают работу устаревшего алгоритма. Полный повторный прогон v2 будет опубликован в следующем релизе.

Дорожная карта

• Оценка репутации пакета
• Объяснимые отчёты об оценке
• Аудит прямых и транзитивных зависимостей проекта
• Проверка инцидентов доверия к издателю
• Предупреждения typosquat по Левенштейну
• Байесовский скоринг по бета-апостериорам (v2)
• Транзитивное распространение риска по DAG (v2)
• Агрегация уязвимостей из нескольких источников (OSV + GitHub + npm)
• Отчёты бенчмарков, читаемые на GitHub (BENCHMARK.md)
• Команды сравнения нескольких пакетов
• Официальный GitHub Action для CI-проверок
• Официальное расширение для VS Code
• Нативная поддержка pnpm
• Нативная поддержка Yarn

FAQ

Как избежать ограничений GitHub API?

Без токена анонимные запросы ограничены 60 запросами в час. Вы можете указать Personal Access Token в вашей конфигурации:

revera config set githubToken ghp_YOUR_TOKEN

Что произойдёт, если я офлайн?

Revera переключается на использование кэшированных файлов. Вы можете явно запускать команды в автономном режиме с флагом --offline. Если источник уязвимостей недоступен, байесовский скоринг расширяет доверительный интервал для этого пакета, а не предполагает «чисто».

Изменяет ли команда add мой проект?

Revera действует как обёртка командной оболочки. После проверки она запускает настоящий установщик пакетов.

Что такое «заражённый» пакет в выводе аудита?

Пакет помечается как заражённый, когда одна из его транзитивных зависимостей вызвала вето или получила критически низкую оценку. Вывод аудита показывает худший подпуть, чтобы вы могли проследить точную цепочку зависимостей, вызвавшую предупреждение.

Как уязвимости дедуплицируются между тремя базами данных?

Каждая уязвимость идентифицируется по её CVE ID, GHSA ID или npm advisory ID. Когда одна и та же уязвимость встречается в нескольких источниках, она объединяется в одну каноническую запись. Данные OSV имеют приоритет для текстовых полей (сводка, детали); наивысший уровень серьёзности и наиболее полный диапазон исправленных версий сохраняются из всех источников.

Участие в разработке

Пожалуйста, ознакомьтесь с Руководством по участию, чтобы начать работу с настройкой, правилами стиля и рекомендациями по pull request.

Отказ от ответственности

Revera предоставляет оценку репутации, основанную на наблюдаемых сигналах проекта и исторических данных. Она предназначена для помощи в принятии инженерных решений и не должна рассматриваться как окончательный аудит безопасности.

Лицензия

Revera распространяется под лицензией MIT.