### Nix```bash
nix profile install github:brennhill/sloppy-joe

### 2. Тайпсквоттинг (генеративные проверки + резервное расстояние Левенштейна)

**Атака:** Злоумышленник регистрирует `expresz` в npm — на один символ отличается от `express`. ИИ генерирует его, или разработчик случайно ошибается в наборе. Пакет существует, проходит проверку на существование и устанавливает вредоносное ПО.

**Как sloppy-joe это блокирует:** sloppy-joe запускает 10 генеративных проверок перед переходом к расстоянию редактирования. Каждая генеративная проверка создаёт специфическую мутацию имени зависимости (меняет местами символы, схлопывает повторения, удаляет суффиксы, переупорядочивает слова, нормализует разделители, заменяет гомоглифы, проверяет области видимости) и проверяет точное совпадение с известными популярными пакетами. Этот подход, вдохновлённый библиотекой [Rust Foundation's Typomania](https://github.com/rustfoundation/typomania), имеет почти нулевой уровень ложных срабатываний, поскольку срабатывает только при точных совпадениях после мутации.

Расстояние Левенштейна выполняется последним в качестве страховочной сети для новых мутаций, которые не были предусмотрены ни одной конкретной проверкой. Вместе они покрывают как известные шаблоны атак (точно), так и неизвестные (в целом).```
ERROR expresz [similarity/edit-distance]
      'expresz' is 1 character away from 'express'. This could be a typosquat.
 Fix: If you meant 'express', fix the name in your manifest.

### 4. Путаница с разделителями

**Атака:** `python-dateutil` vs `python_dateutil` vs `pythondateutil`. В некоторых реестрах это разные пакеты. Злоумышленник регистрирует вариант.

**Как sloppy-joe блокирует это:** Нормализует все разделители (`-`, `_`, `.`) перед сравнением. Если нормализованная форма совпадает с известным пакетом, он помечается.```
ERROR socket_io [similarity/separator-confusion]
      'socket_io' matches 'socket.io' after normalizing separators.
 Fix: Use the canonical name 'socket.io' with the correct separators.

### 6. Перестановки соседних символов

**Атака:** `reqeust` вместо `request`. Два соседних символа переставлены местами — распространённая опечатка, которую атакующие используют в своих целях.

**Как sloppy-joe блокирует это:** Генерирует все варианты перестановок соседних символов имени зависимости и проверяет каждый по корпусу.```
ERROR reqeusts [similarity/char-swap]
      'reqeusts' matches 'requests' with two adjacent characters swapped.
 Fix: Use 'requests' — two characters are transposed.

### 8. Омоглифы (визуально похожие символы)

**Атака:** `rеquests` с кириллической `е` (U+0435) вместо латинской `e` (U+0065). Визуально идентично. Имя пакета выглядит в точности как `requests`, но ссылается на другой, вредоносный пакет.

**Как sloppy-joe блокирует это:** Заменяет 17 известных омоглифов (кириллица, полноширинные символы, варианты прописных) на их латинские эквиваленты и проверяет, совпадает ли результат с известным пакетом.```
ERROR rеquests [similarity/homoglyph]
      'rеquests' contains characters that look identical to 'requests'
      but are different Unicode codepoints (homoglyphs).
 Fix: Replace the lookalike characters with standard ASCII.

### 10. Атаки с использованием вариантов регистра (чувствительные к регистру реестры)

**Атака:** В Go, Maven и Ruby пакеты `Rails` и `rails` считаются разными. Злоумышленник регистрирует вариант с заглавной буквы.

**Как sloppy-joe блокирует это:** В реестрах, чувствительных к регистру, любой вариант регистра известного пакета помечается как ошибка. В реестрах, не чувствительных к регистру (npm, PyPI, Cargo, NuGet, PHP), варианты регистра безопасны и пропускаются.```
ERROR Rails [similarity/case-variant]
      'Rails' differs from 'rails' only in letter casing.
      On case-sensitive registries (ruby) these resolve to different packages.
 Fix: Use the exact casing 'rails' in your manifest.

### 12. Сквоттинг области видимости (npm, PHP, Go, JVM)

**Атака:** Злоумышленник регистрирует `@typos/lodash` в npm — на одну букву от `@types/lodash`. Или `larvael/framework` на Packagist — на две буквы от `laravel/framework`. Или `github.com/gooogle/protobuf` в Go — одна лишняя `o`. Область видимости с первого взгляда выглядит легитимной. Пакет устанавливается. Вредоносное ПО внедряется.

Это редко, но возможно — и именно для таких случаев существует sloppy-joe. Инцидент с `ua-parser-js` в 2021 году был связан с областью видимости. Если это может случиться с пакетом с миллионами еженедельных загрузок, это может случиться и с вашим.

**Как sloppy-joe это блокирует:** Извлекает область видимости/пространство имен из имени зависимости и сравнивает его со списком известных доверенных областей с помощью расстояния редактирования. Работает для npm (`@scope`), PHP (`vendor/`), Go (`github.com/org`) и JVM (`com.group`).```
ERROR @typos/lodash [similarity/scope-squatting]
      Scope '@typos' is 1 character away from the known scope '@types'.
      Scope squatting is a known supply chain attack vector.
 Fix: If you meant '@types/lodash', fix the scope in your manifest.

### 13. Неканонические пакеты (не атака — шлюз согласованности)

**The attack:** Не атака — проблема согласованности. ИИ выбирает `moment`, потому что он был популярен в обучающих данных, но ваша команда использует `dayjs`. Разные команды, использующие разные пакеты для одной и той же задачи, создают долг по обслуживанию и разбухание зависимостей.

**How sloppy-joe blocks it:** Ваша конфигурация сопоставляет каждый канонический пакет с его отклоненными альтернативами. Если зависимость совпадает с альтернативой, сборка завершается неудачей.```
ERROR moment [canonical]
      'moment' is not the approved package for this purpose.
      Your team uses 'dayjs'.
 Fix: Replace 'moment' with 'dayjs' in your manifest file.

### 15. Совершенно новые пакеты

**Атака:** Пакет, созданный вчера, с 3 загрузками, имя которого похоже на популярный пакет. Высокая вероятность того, что это тайпсквот или заполнитель для будущей атаки.

**Как sloppy-joe блокирует это:** Помечает любой пакет, созданный менее 30 дней назад.```
ERROR sketchy-lib [metadata/new-package]
      'sketchy-lib' was first published 2 days ago.
      New packages are higher risk.
 Fix: Verify 'sketchy-lib' at its registry page and source repository.

---

## Поддерживаемые экосистемы

| Экосистема | Манифест | Политика лок-файлов | Существование | Метаданные | Возрастной шлюз |
|-----------|----------|-----------------|:---------:|:--------:|:--------:|
| npm | package.json | Требуется `package-lock.json` или `npm-shrinkwrap.json` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| PyPI | `pyproject.toml`, `requirements*.txt`, `Pipfile`, `setup.cfg`, `setup.py` | Poetry доверен с `poetry.lock`, uv доверен с `uv.lock`, полностью хэш-блокированный pip-tools доверен только когда зафиксированный граф зависимостей привязывает `--index-url` и точные разрешённые значения `--extra-index-url`, а видимые в репозитории пользовательские индексы Poetry/uv можно доверять только по точному разрешённому списку `trusted_indexes.pypi`; устаревшие манифесты предупреждают при каждом запуске, если `python_enforcement` не установлен в `poetry_only` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Cargo | Cargo.toml | Требуется `Cargo.lock` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Go | go.mod | `go.sum` требуется для внешних зависимостей; не требуется для стандартной библиотеки или полностью локальных `replace` | :white_check_mark: | :x: | :x: |
| Ruby | Gemfile | Требуется `Gemfile.lock` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| PHP | composer.json | Требуется `composer.lock` | :white_check_mark: | :x: | :x: |
| JVM (Gradle) | build.gradle / build.gradle.kts | Требуется `gradle.lockfile` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| JVM (Maven) | pom.xml | только предупреждение: строгого контроля лок-файлов нет | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| .NET | *.csproj | Требуется `packages.lock.json` | :white_check_mark: | :x: | :x: |

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

## Быстрый старт```bash
# Install
cargo install sloppy-joe

# Check current project (auto-detects ecosystem)
sloppy-joe check

# Check with canonical enforcement and age gate
sloppy-joe check --config /etc/sloppy-joe/config.json

# Output as JSON for CI
sloppy-joe check --json

**`canonical`** — ключи — это одобренные пакеты; значения — отвергнутые альтернативы.

**`internal`** — пакеты вашей организации. Пропускать ВСЕ проверки. Они постоянно меняются.

**`allowed`** — проверенные внешние пакеты. Пропускать проверки на существование и сходство, но всё ещё подвержены проверке возраста версии.

**`similarity_exceptions`** — точные подавления package/candidate/generator для проверенных ложных срабатываний сходства. Используйте это, когда одно конкретное сходство неверно, но вы всё ещё хотите нормальные проверки для пакета.

**`metadata_exceptions`** — точные проверенные подавления метаданных. В настоящее время поддерживает только `metadata/maintainer-change` и требует точного совпадения package/version/previous-publisher/current-publisher.

Используйте `sloppy-joe check --review-exceptions`, когда нужно просмотреть блокировки смены мейнтейнера. Сканирование по-прежнему блокирует нормально, но в выводе для человека добавляется раздел `REVIEW EXCEPTIONS` с владельцами, URL репозитория и готовым к вставке фрагментом `metadata_exceptions`. `--json` включает те же данные в поле `review_candidates` верхнего уровня.

**`min_version_age_hours`** — блокировать любую версию, опубликованную менее этого количества часов назад. По умолчанию: 72 (3 дня). Установите 0, чтобы отключить. Внутренние пакеты освобождены.

**`allow_legacy_npm_v1_lockfile`** — разрешить lock-файлы npm `lockfileVersion: 1` от npm v5/v6 в режиме пониженного доверия. По умолчанию: `false`. Оставьте выключенным, если вы не застряли на устаревшем npm и не принимаете громкие предупреждения плюс сниженное покрытие доверенных транзитивных зависимостей npm.

**`python_enforcement`** — управляет политикой доверия Python. `prefer_poetry` (по умолчанию) доверяет проектам Poetry и uv, полностью доверяет требованиям pip-tools с хеш-локом только когда зафиксированный граф требований привязывает `--index-url` и любые значения `--extra-index-url` не из PyPy точно, в противном случае понижает pip-tools до пониженного доверия. Устаревшие манифесты, такие как `requirements*.txt` без хешей, `Pipfile`, `setup.cfg`, `setup.py` и `pyproject.toml` без Poetry/uv, предупреждают при каждом запуске. `poetry_only` блокирует такие не-Poetry Python-процессы и требует Poetry.

### Безопасность конфигурации

Конфигурация **никогда не читается из директории проекта**. AI-агент с доступом к оболочке мог бы перезаписать конфигурацию внутри репозитория, чтобы разрешить всё, что угодно.

Разрешение конфигурации:
1. `--config /path/to/config.json` — локальный файл (флаг CLI, наивысший приоритет)
2. `--config https://example.com/config.json` — загрузка по URL
3. `SLOPPY_JOE_CONFIG=...` — переменная окружения (путь к файлу или URL)
4. Нет конфигурации = только проверки существования + сходства + метаданных

Некорректные конфигурации **жёстко падают** с информативными сообщениями об ошибках — сломанная конфигурация никогда не возвращается молча к отсутствию защиты.

См. [CONFIG.md](https://github.com/brennhill/sloppy-joe/blob/HEAD/CONFIG.md) для полного справочника по формату, шаблонов интеграции CI и примеров.

Конфигурация начальной загрузки (bootstrap):```bash
sloppy-joe init --greenfield --ecosystem npm
sloppy-joe init --from-current
sloppy-joe init --from-current --register
sloppy-joe init --register

#### Входные данные действия

| Вход | Описание | По умолчанию |
|-------|-------------|---------|
| `config` | Путь к конфигурационному файлу или URL HTTPS | *(нет)* |
| `dir` | Каталог проекта для сканирования | `.` |
| `type` | Экосистема (`npm`, `pypi`, `cargo`, `go`, `ruby`, `php`, `jvm`, `dotnet`) | автоопределение |
| `deep` | Включить проверки сходства транзитивных зависимостей | `false` |
| `paranoid` | Включить мутации с переворотом битов | `false` |
| `args` | Дополнительные аргументы CLI | *(нет)* |
| `version` | Версия sloppy-joe для установки | `latest` |

#### Примеры```yaml
# Minimal — CI-oriented scan, auto-detect ecosystem, no config
- uses: brennhill/[email protected]

# With org config from a URL
- uses: brennhill/[email protected]
  with:
    config: https://raw.githubusercontent.com/yourorg/configs/main/sloppy-joe.json

# Deep scan with paranoid mode
- uses: brennhill/[email protected]
  with:
    config: ${{ secrets.SLOPPY_JOE_CONFIG }}
    deep: true
    paranoid: true

# Scan a subdirectory, pin to a specific version
- uses: brennhill/[email protected]
  with:
    dir: ./packages/api
    version: '1.1.0'

### pre-commit

sloppy-joe работает с фреймворком [pre-commit](https://pre-commit.com).
Добавьте его в свой `.pre-commit-config.yaml`:```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/brennhill/sloppy-joe
    rev: v1.1.0
    hooks:
      - id: sloppy-joe

Или используйте простой хук оболочки без фреймворка:```bash
#!/bin/sh
sloppy-joe check || exit 1

Поиск сходства выполняется в 4 этапа:
- **Этап 0: Сквоттинг области видимости** — локальная проверка, без сети. Сравнивает область/пространство имён с известными корректными областями через расстояние Левенштейна.
- **Этап 1: Внутриманифестная проверка** — локальная проверка. Помечает, когда две зависимости в одном манифесте являются мутациями друг друга.
- **Этап 2: Запрос к реестру** — генерирует мутации, пакетно опрашивает реестр на существование, кэширует результаты (TTL 7 дней).
- **Этап 3: Обогащение метаданными** — получает количество загрузок и даты публикации для совпадений, чтобы добавить доказательства в отчёты.

Каждый генератор мутаций помечает свой вывод, поэтому отображаемый тип проверки (например, `similarity/homoglyph`) детерминирован — генератор с наибольшей серьёзностью побеждает, когда несколько генераторов выдают одного и того же кандидата.

## Надёжность CI

sloppy-joe разработан для CI-конвейеров, где неприемлемы нестабильные сбои.

**Повтор с экспоненциальной задержкой.** Все HTTP-вызовы к реестру повторяются 3 раза с экспоненциальной задержкой (200ms, 400ms, 800ms) при временных сбоях (5xx, тайм-ауты, ошибки соединения). Одиночный сетевой сбой не приведёт к сбою вашей сборки.

**Блокировка при ошибках запроса.** Если запросы к реестру или OSV завершаются сбоем, sloppy-joe выдаёт блокирующую ошибку `registry-unreachable` вместо того, чтобы молча пропускать проверки. Сканирование больше не полагается на пороговые значения для каждой экосистемы или ограничения по размеру выборки перед блокировкой.

**Кэш сходства.** Результаты существования мутаций кэшируются на 7 дней. После первого сканирования большинство запросов обслуживаются из кэша без сетевых вызовов. Только новые зависимости инициируют запросы к реестру.

**Разрешение зависимостей с учётом lock-файла.** Когда присутствует и является надёжным поддерживаемый lock-файл (`package-lock.json`, `npm-shrinkwrap.json`, `Cargo.lock`, `Gemfile.lock`, `poetry.lock` для проектов Poetry, `uv.lock` для проектов uv, `composer.lock`, `gradle.lockfile`, `packages.lock.json`), sloppy-joe определяет точные версии из него, а не угадывает по диапазонам. Полностью хэш-заблокированные `requirements*.txt` также могут предоставлять точные закреплённые версии, и они становятся полностью доверенными, когда зафиксированный граф требований связывает собственный `--index-url` и точные разрешённые значения `--extra-index-url`.

## Тесты

Набор тестов охватывает проверки сходства, сигналы метаданных, поведение OSV, разбор и валидацию конфигурации, разрешение lock-файлов, политику предварительной проверки манифестов и lock-файлов, форматирование отчётов и логику повторных HTTP-запросов.```bash
cargo test