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

### 2. タイポスクワッティング（生成的チェック＋編集距離フォールバック）

**攻撃の内容:** 攻撃者は `express` から一文字変えて `expresz` をnpmに登録します。AIが生成するか、開発者がタイポしてしまいます。そのパッケージは存在するため、存在チェックを通過し、マルウェアをインストールします。

**sloppy-joeによる防御:** sloppy-joeは編集距離にフォールバックする前に、10種類の生成的チェックを実行します。各生成的チェックは依存関係名の特定の変異（文字の入れ替え、繰り返しの圧縮、サフィックスの除去、単語の並び替え、セパレータの正規化、ホモグリフの置換、スコープのチェック）を生成し、既知の人気パッケージとの完全一致をテストします。このアプローチは、[Rust Foundationの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` の代わりに使用。隣接する2文字が入れ替わる——攻撃者が悪用する一般的なタイプミス。

**sloppy-joe の防御方法:** 依存関係名のすべての隣接入れ替えバリアントを生成し、それぞれをコーパスと照合します。```
ERROR reqeusts [similarity/char-swap]
      'reqeusts' matches 'requests' with two adjacent characters swapped.
 Fix: Use 'requests' — two characters are transposed.

### 8. ホモグリフ（視覚的に類似した文字）

**攻撃の仕組み:** ラテン文字の `e` (U+0065) の代わりにキリル文字の `е` (U+0435) を使用した `rеquests`。見た目はまったく同じです。パッケージ名は `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)

**攻撃手法:** 攻撃者は 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. Brand-new packages

**攻撃:** 昨日作成され、ダウンロード数が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 は、コミットされた requirements グラフが `--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` が必要；stdlibのみまたはすべてローカルの `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 requirements は、requirements グラフが `--index-url` と任意の非 PyPI `--extra-index-url` の値を正確にバインドしている場合のみ信頼し、それ以外は pip-tools を信頼度低減に格下げします。ハッシュ化されていない `requirements*.txt`、`Pipfile`、`setup.cfg`、`setup.py`、Poetry/uv 以外の `pyproject.toml` などのレガシーマニフェストは、実行ごとに警告を表示します。`poetry_only` は、これら non-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. 設定なし = 存在確認＋類似性＋メタデータチェックのみ

不正な設定は**厳格に失敗**し、実用的なエラーメッセージが表示されます。壊れた設定が無警告で保護なしにフォールバックすることはありません。

完全な形式リファレンス、CI統合パターン、例については [CONFIG.md](https://github.com/brennhill/sloppy-joe/blob/HEAD/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 | *(none)* |
| `dir` | スキャン対象のプロジェクトディレクトリ | `.` |
| `type` | エコシステム（`npm`、`pypi`、`cargo`、`go`、`ruby`、`php`、`jvm`、`dotnet`） | auto-detect |
| `deep` | 推移的依存関係の類似性チェックを有効にする | `false` |
| `paranoid` | ビットフリップミューテーションを有効にする | `false` |
| `args` | 追加のCLI引数 | *(none)* |
| `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

Similarityは4つのフェーズで実行されます:
- **Phase 0: Scope squatting** — ローカルチェック、ネットワークなし。スコープ/名前空間を既知の正当なスコープとレーベンシュタイン距離を使って比較します。
- **Phase 1: Intra-manifest** — ローカルチェック。同じマニフェスト内の2つの依存関係が互いにミューテーションである場合にフラグを立てます。
- **Phase 2: Registry query** — ミューテーションを生成し、レジストリに一括クエリして存在を確認し、結果をキャッシュします（7日間のTTL）。
- **Phase 3: Metadata enrichment** — 一致するもののダウンロード数と公開日を取得して、レポートに証拠を追加します。

各ミューテーションジェネレーターは出力にタグを付けるため、報告されるチェックタイプ（例: `similarity/homoglyph`）は決定論的です。複数のジェネレーターが同じ候補を生成した場合、最も重大度の高いジェネレーターが優先されます。

## CIの信頼性

sloppy-joeは、不安定な失敗が許されないCIパイプライン向けに設計されています。

**リトライとバックオフ。** すべてのレジストリHTTP呼び出しは、一時的な障害（5xx、タイムアウト、接続エラー）に対して指数バックオフ（200ms、400ms、800ms）で3回リトライします。1回のネットワーク不具合でビルドが失敗することはありません。

**クエリエラーでのフェイルクローズド。** レジストリまたは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`も正確な固定バージョンを提供でき、コミットされたrequirementsグラフが自身の`--index-url`と正確に許可された`--extra-index-url`の値をバインドする場合、それらは完全に信頼されるようになります。

## テスト

テストスイートは、類似性チェック、メタデータシグナル、OSV動作、設定の解析と検証、ロックファイル解決、マニフェストとロックファイルの事前チェックポリシー、レポートフォーマット、HTTPリトライロジックをカバーしています。```bash
cargo test