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

### 2. 拼写错误劫持（生成式检查 + 编辑距离回退）

**攻击方式：** 攻击者在 npm 上注册 `expresz` – 与 `express` 仅一字之差。可能是 AI 生成的，也可能是开发者手误。该包存在，通过存在性检查，然后安装恶意软件。

**sloppy-joe 如何阻止：** sloppy-joe 先运行 10 项生成式检查，再回退到编辑距离。每项生成式检查都会对依赖名称产生特定的变异（交换字符、合并重复、去除后缀、单词重排、标准化分隔符、替换同形字、检查作用域），并针对已知流行包进行精确匹配测试。这种方法受 [Rust 基金会 Typomania](https://github.com/rustfoundation/typomania) 库的启发，几乎无误报，因为它仅在变异后精确匹配时才触发。

Levenshtein 编辑距离作为最后的安全网，用于处理未预料到的新型变异。两者结合，既精确覆盖已知攻击模式，又广泛覆盖未知模式。```
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` 与 `python_dateutil` 与 `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. Scope squatting（npm、PHP、Go、JVM）

**攻击方式：** 攻击者在npm上注册 `@typos/lodash` —— 与 `@types/lodash` 仅差一个字符。或者在 Packagist 上注册 `larvael/framework` —— 与 `laravel/framework` 差两个字符。或者在 Go 上注册 `github.com/gooogle/protobuf` —— 多了一个 `o`。乍看之下，该作用域看起来很合法。包能正常解析，恶意软件随之安装。

这种情况虽罕见但确实可能发生——而“罕见但可能”正是 sloppy-joe 存在的意义。2021 年的 `ua-parser-js` 事件就与作用域相关。如果它能发生在周下载量数百万的软件包上，那么同样可能发生在你的包上。

**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. 非规范包（不是攻击——而是一致性门禁）

**攻击描述：** 这不是攻击——而是一个一致性问题。AI 选择了 `moment`，因为它在训练数据中很流行，但你的团队使用 `dayjs`。不同团队使用不同的包来完成相同的工作会导致维护债务和依赖膨胀。

**sloppy-joe 如何阻止：** 你的配置将每个规范包映射到其被拒绝的替代品。如果某个依赖项匹配了替代品，构建就会失败。```
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`** — 针对已审查的相似性误报，精确指定包/候选包/生成器的抑制规则。在某个特定的相似性边是错误的但你仍然希望对该包执行正常检查时使用。

**`metadata_exceptions`** — 精确的已审查元数据抑制规则。当前仅支持 `metadata/maintainer-change`，并要求精确匹配包/版本/前发布者/当前发布者。

当你需要审查维护者变更阻断时，使用 `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`** — 允许使用 npm v5/v6 的 `lockfileVersion: 1` npm 锁定文件（在低置信度模式下）。默认值：`false`。除非你有意停留在旧版 npm 并能接受明显警告加上降低的可信 npm 传递覆盖范围，否则请保持关闭。

**`python_enforcement`** — 控制 Python 信任策略。`prefer_poetry`（默认）信任 Poetry 项目和 uv 项目，信任完全哈希锁定的 pip-tools 需求文件仅当提交的需求图精确绑定了 `--index-url` 和任何非 PyPI 的 `--extra-index-url` 值，否则将 pip-tools 降级为低置信度。每次运行都会对未哈希的 `requirements*.txt`、`Pipfile`、`setup.cfg`、`setup.py` 以及非 Poetry/non-uv 的 `pyproject.toml` 等传统清单发出警告。`poetry_only` 则阻止这些非 Poetry 的 Python 工作流，并要求使用 Poetry。

### 配置安全

**配置永远不会从项目目录读取**。拥有 shell 访问权限的 AI 智能体可以重写仓库内的配置，从而允许其想要的任何东西。

配置解析顺序：
1. `--config /path/to/config.json` — 本地文件（CLI 标志，最高优先级）
2. `--config https://example.com/config.json` — 从 URL 获取
3. `SLOPPY_JOE_CONFIG=...` — 环境变量（文件路径或 URL）
4. 无配置时 = 仅执行存在性、相似性和元数据检查

格式错误的配置会**硬失败**并给出可操作错误消息——损坏的配置绝不会静默回退到无保护状态。

完整格式参考、CI 集成模式和示例请参见 [CONFIG.md](https://github.com/brennhill/sloppy-joe/blob/main/CONFIG.md)。

引导配置：```bash
sloppy-joe init --greenfield --ecosystem npm
sloppy-joe init --from-current
sloppy-joe init --from-current --register
sloppy-joe init --register

#### 操作输入

| 输入 | 描述 | 默认值 |
|-------|-------------|---------|
| `config` | 配置文件路径或HTTPS URL | *(无)* |
| `dir` | 要扫描的项目目录 | `.` |
| `type` | 生态系统 (`npm`, `pypi`, `cargo`, `go`, `ruby`, `php`, `jvm`, `dotnet`) | auto-detect |
| `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

或者无需框架，直接使用简单的 shell 钩子：```bash
#!/bin/sh
sloppy-joe check || exit 1

相似性检查运行4个阶段：
- **阶段0：作用域抢注** — 本地检查，无需网络。通过莱文斯坦距离比较作用域/命名空间与已知安全的作用域。
- **阶段1：清单内部** — 本地检查。当同一清单中的两个依赖项互为变异时标记。
- **阶段2：注册表查询** — 生成变异，批量查询注册表是否存在，缓存结果（7天TTL）。
- **阶段3：元数据丰富** — 获取匹配项的下载次数和发布日期，以向报告添加证据。

每个变异生成器都会标记其输出，因此报告检查类型（例如 `similarity/homoglyph`）是确定性的——当多个生成器产生相同候选时，严重性最高的生成器获胜。

## CI 可靠性

sloppy-joe 专为不可接受间歇性失败的 CI 流水线设计。

**带退避的重试。** 所有注册表 HTTP 调用在遇到瞬时故障（5xx、超时、连接错误）时会以指数退避（200毫秒、400毫秒、800毫秒）重试3次。单次网络波动不会导致构建失败。

**查询错误时故障关闭。** 如果注册表或 OSV 查询失败，sloppy-joe 会发出阻塞性 `registry-unreachable` 错误，而不是静默跳过检查。扫描不再依赖每个生态系统的阈值或样本量截断来阻塞。

**相似性缓存。** 变异存在性结果缓存7天。首次扫描后，大多数查询来自缓存，无需网络调用。只有新依赖项才会触发注册表查询。

**锁文件感知解析。** 当存在受支持的锁文件且可信时（`package-lock.json`、`npm-shrinkwrap.json`、`Cargo.lock`、`Gemfile.lock`、用于 Poetry 项目的 `poetry.lock`、用于 uv 项目的 `uv.lock`、`composer.lock`、`gradle.lockfile`、`packages.lock.json`），sloppy-joe 会从中解析准确版本，而不是从范围推测。完全哈希锁定的 `requirements*.txt` 也可以提供精确的固定版本，当提交的需求图绑定了自己的 `--index-url` 和精确的可信 `--extra-index-url` 值时，它们会被完全信任。

## 测试

测试套件涵盖相似性检查、元数据信号、OSV行为、配置解析与验证、锁文件解析、清单与锁文件预检策略、报告格式化以及HTTP重试逻辑。```bash
cargo test