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

### 2. Typosquatting (controlli generativi + fallback basato sulla distanza di edit)

**L'attacco:** Un utente malintenzionato registra `expresz` su npm — un carattere diverso da `express`. L'IA lo genera, o uno sviluppatore lo scrive a tastiera. Il pacchetto esiste, supera il controllo di esistenza e installa malware.

**Come sloppy-joe lo blocca:** sloppy-joe esegue 10 controlli generativi prima di ricorrere alla distanza di edit. Ogni controllo generativo produce una mutazione specifica del nome della dipendenza (scambia caratteri, comprime ripetizioni, rimuovi suffissi, riordina parole, normalizza separatori, sostituisci omoglifi, controlla gli scope) e testa una corrispondenza esatta con pacchetti popolari noti. Questo approccio, ispirato alla libreria [Typomania della Rust Foundation](https://github.com/rustfoundation/typomania), ha falsi positivi quasi nulli perché si attiva solo su corrispondenze esatte dopo la mutazione.

La distanza di edit di Levenshtein viene eseguita per ultima come rete di sicurezza per mutazioni inedite che nessun controllo specifico aveva previsto. Insieme, coprono sia schemi di attacco noti (con precisione) sia quelli sconosciuti (in modo ampio).```
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. Confusione dei separatori

**L'attacco:** `python-dateutil` vs `python_dateutil` vs `pythondateutil`. In alcuni registri, questi sono pacchetti diversi. Un attaccante registra la variante.

**Come sloppy-joe lo blocca:** Normalizza tutti i separatori (`-`, `_`, `.`) prima del confronto. Se la forma normalizzata corrisponde a un pacchetto noto, viene segnalato.```
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. Scambi di caratteri adiacenti

**L'attacco:** `reqeust` invece di `request`. Due caratteri adiacenti trasposti — un errore di battitura comune che gli attaccanti sfruttano.

**Come sloppy-joe lo blocca:** Genera tutte le varianti di scambio adiacente del nome della dipendenza e controlla ciascuna rispetto al corpus.```
ERROR reqeusts [similarity/char-swap]
      'reqeusts' matches 'requests' with two adjacent characters swapped.
 Fix: Use 'requests' — two characters are transposed.

### 8. Omoglifi (somiglianze visive)

**L'attacco:** `rеquests` con una `е` cirillica (U+0435) invece della `e` latina (U+0065). Visivamente identico. Il nome del pacchetto sembra esattamente `requests` ma risolve in un pacchetto diverso e malevolo.

**Come sloppy-joe lo blocca:** Sostituisce 17 caratteri omoglifi noti (cirillici, a larghezza intera, varianti script) con i loro equivalenti latini e controlla se il risultato corrisponde a un pacchetto noto.```
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. Attacchi con varianti di maiuscole/minuscole (registry case-sensitive)

**L'attacco:** Su Go, Maven e Ruby, `Rails` e `rails` sono pacchetti diversi. Un attaccante registra la variante con iniziale maiuscola.

**Come sloppy-joe lo blocca:** Nei registry case-sensitive, qualsiasi variante di maiuscole/minuscole di un pacchetto noto viene segnalata come errore. Nei registry case-insensitive (npm, PyPI, Cargo, NuGet, PHP), le varianti di maiuscole/minuscole sono sicure e vengono saltate.```
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)

**L'attacco:** Un attaccante registra `@typos/lodash` su npm — un carattere di differenza da `@types/lodash`. Oppure `larvael/framework` su Packagist — due caratteri di differenza da `laravel/framework`. Oppure `github.com/gooogle/protobuf` su Go — una `o` in più. Lo scope sembra legittimo a prima vista. Il pacchetto viene risolto. Il malware si installa.

È raro ma plausibile — e "raro ma plausibile" è esattamente ciò per cui esiste sloppy-joe. L'incidente `ua-parser-js` del 2021 era legato allo scope. Se può accadere a un pacchetto con milioni di download settimanali, può accadere al vostro.

**Come sloppy-joe lo blocca:** Estrae lo scope/namespace dal nome della dipendenza e lo confronta con un elenco di scope noti come affidabili utilizzando la distanza di modifica. Funziona su npm (`@scope`), PHP (`vendor/`), Go (`github.com/org`) e 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.

© 2021 Aidan Holland```

### 13. Pacchetti non canonici (non è un attacco — un gate di coerenza)

**L'attacco:** Non è un attacco — un problema di coerenza. L'IA sceglie `moment` perché era popolare nei dati di addestramento, ma il tuo team usa `dayjs`. Team diversi che usano pacchetti diversi per lo stesso compito creano debito di manutenzione e gonfiore delle dipendenze.

**Come sloppy-joe lo blocca:** La tua configurazione mappa ogni pacchetto canonico alle sue alternative rifiutate. Se una dipendenza corrisponde a un'alternativa, la build fallisce.```
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. Pacchetti nuovissimi

**L'attacco:** Un pacchetto creato ieri con 3 download che ha un nome simile a un pacchetto popolare. Alta probabilità che si tratti di un typosquat o di un segnaposto per un futuro attacco.

**Come sloppy-joe lo blocca:** Segnala qualsiasi pacchetto creato meno di 30 giorni fa.```
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.

---

## Ecosistemi Supportati

| Ecosistema | Manifesto | Politica del Lockfile | Esistenza | Metadati | Controllo Età |
|-----------|----------|-----------------|:---------:|:--------:|:--------:|
| npm | package.json | `package-lock.json` o `npm-shrinkwrap.json` richiesto | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| PyPI | `pyproject.toml`, `requirements*.txt`, `Pipfile`, `setup.cfg`, `setup.py` | Poetry è considerato affidabile con `poetry.lock`, uv è considerato affidabile con `uv.lock`, pip-tools con hash completamente bloccato è considerato affidabile solo quando il grafo delle dipendenze committato vincola `--index-url` e valori esatti di `--extra-index-url` nella allowlist, e gli indici personalizzati di Poetry/uv visibili nel repository possono essere considerati affidabili solo tramite la allowlist esatta di `trusted_indexes.pypi`; i manifesti legacy avvisano a ogni esecuzione a meno che `python_enforcement` non sia `poetry_only` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Cargo | Cargo.toml | `Cargo.lock` richiesto | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Go | go.mod | `go.sum` richiesto per dipendenze esterne; non richiesto per solo stdlib o per tutti i `replace` locali | :white_check_mark: | :x: | :x: |
| Ruby | Gemfile | `Gemfile.lock` richiesto | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| PHP | composer.json | `composer.lock` richiesto | :white_check_mark: | :x: | :x: |
| JVM (Gradle) | build.gradle / build.gradle.kts | `gradle.lockfile` richiesto | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| JVM (Maven) | pom.xml | solo avviso: nessuna applicazione rigorosa del lockfile | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| .NET | *.csproj | `packages.lock.json` richiesto | :white_check_mark: | :x: | :x: |

Tutti gli ecosistemi ricevono controlli di esistenza, similarità e canonicità. I metadati e il controllo età dipendono da ciò che espone l'API del registro. Il supporto al lockfile abilita la scansione delle dipendenze transitive e la risoluzione esatta delle versioni dove l'ecosistema fornisce un modello di lockfile locale al progetto attendibile.

## Avvio Rapido```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`** — le chiavi sono pacchetti approvati; i valori sono alternative rifiutate.

**`internal`** — i pacchetti della tua organizzazione. Salta TUTTI i controlli. Questi cambiano costantemente.

**`allowed`** — pacchetti esterni verificati. Salta esistenza + similarità, ma ancora soggetti al gate dell'età della versione.

**`similarity_exceptions`** — soppressioni esatte di pacchetto/candidato/generatore per falsi positivi di similarità revisionati. Usa questo quando uno specifico bordo di similarità è sbagliato ma desideri comunque i controlli normali sul pacchetto.

**`metadata_exceptions`** — soppressioni esatte di metadati revisionati. Attualmente questo supporta solo `metadata/maintainer-change`, e richiede una corrispondenza esatta di pacchetto/versione/editore-precedente/editore-attuale.

Usa `sloppy-joe check --review-exceptions` quando hai bisogno di revisionare i blocchi per cambiamento del manutentore. La scansione blocca ancora normalmente, ma l'output umano aggiunge una sezione `REVIEW EXCEPTIONS` con proprietari, URL del repository e un frammento `metadata_exceptions` pronto da incollare. `--json` include gli stessi dati in un campo `review_candidates` di primo livello.

**`min_version_age_hours`** — blocca qualsiasi versione pubblicata meno di questo numero di ore fa. Default: 72 (3 giorni). Imposta a 0 per disabilitare. I pacchetti interni sono esenti.

**`allow_legacy_npm_v1_lockfile`** — consenti i lockfile npm `lockfileVersion: 1` da npm v5/v6 in modalità fiducia ridotta. Default: `false`. Tienilo disattivato a meno che tu non sia intenzionalmente bloccato su npm legacy e accetti avvisi rumorosi più una copertura di fiducia ridotta delle dipendenze transitive npm.

**`python_enforcement`** — controlla la politica di fiducia per Python. `prefer_poetry` (default) si fida dei progetti Poetry e uv, si fida dei requisiti pip-tools completamente bloccati da hash solo quando il grafico dei requisiti committato lega esattamente `--index-url` e qualsiasi valore `--extra-index-url` non PyPI, e altrimenti declassa pip-tools a fiducia ridotta. I manifest legacy come `requirements*.txt` senza hash, `Pipfile`, `setup.cfg`, `setup.py` e `pyproject.toml` non Poetry/non uv avvertono a ogni esecuzione. `poetry_only` blocca quei flussi di lavoro Python non Poetry e richiede Poetry.

### Sicurezza della Configurazione

La configurazione **non viene mai letta dalla directory del progetto**. Un agente AI con accesso shell potrebbe riscrivere una configurazione nel repository per inserire nella whitelist ciò che desidera.

Risoluzione della configurazione:
1. `--config /path/to/config.json` — file locale (flag CLI, priorità massima)
2. `--config https://example.com/config.json` — recupera da URL
3. `SLOPPY_JOE_CONFIG=...` — variabile d'ambiente (percorso file o URL)
4. Nessuna configurazione = solo controlli di esistenza + similarità + metadati

Configurazioni malformate **falliscono duramente** con messaggi di errore utilizzabili — una configurazione rotta non ricade mai silenziosamente su nessuna protezione.

Vedi [CONFIG.md](https://github.com/brennhill/sloppy-joe/blob/HEAD/CONFIG.md) per il riferimento completo al formato, modelli di integrazione CI ed esempi.

Configurazione di bootstrap:```bash
sloppy-joe init --greenfield --ecosystem npm
sloppy-joe init --from-current
sloppy-joe init --from-current --register
sloppy-joe init --register

#### Input di azione

| Input | Descrizione | Default |
|-------|-------------|---------|
| `config` | Percorso del file di configurazione o URL HTTPS | *(nessuno)* |
| `dir` | Directory del progetto da analizzare | `.` |
| `type` | Ecosistema (`npm`, `pypi`, `cargo`, `go`, `ruby`, `php`, `jvm`, `dotnet`) | rilevamento automatico |
| `deep` | Abilita i controlli di somiglianza delle dipendenze transitive | `false` |
| `paranoid` | Abilita mutazioni bitflip | `false` |
| `args` | Argomenti CLI aggiuntivi | *(nessuno)* |
| `version` | versione di sloppy-joe da installare | `latest` |

#### Esempi```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 funziona con il framework [pre-commit](https://pre-commit.com).
Aggiungilo al tuo `.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

Oppure usa un semplice hook di shell senza il framework:```bash
#!/bin/sh
sloppy-joe check || exit 1

La similarità esegue 4 fasi:
- **Fase 0: Scope squatting** — controllo locale, senza rete. Confronta lo scope/namespace con scopes noti come sicuri tramite la distanza di Levenshtein.
- **Fase 1: Intra-manifest** — controllo locale. Segnala quando due dipendenze nello stesso manifest sono mutazioni l'una dell'altra.
- **Fase 2: Query al registry** — genera mutazioni, interroga in batch il registry per verificarne l'esistenza, memorizza nella cache i risultati (TTL di 7 giorni).
- **Fase 3: Arricchimento dei metadati** — recupera i conteggi dei download e le date di pubblicazione per le corrispondenze, per aggiungere prove ai report.

Ogni generatore di mutazioni etichetta il proprio output, quindi il tipo di controllo riportato (es. `similarity/homoglyph`) è deterministico — il generatore con la severità più alta vince quando più generatori producono lo stesso candidato.

## Affidabilità della CI

sloppy-joe è progettato per pipeline CI in cui fallimenti intermittenti sono inaccettabili.

**Riprova con backoff.** Tutte le chiamate HTTP al registry riprovano 3 volte con backoff esponenziale (200ms, 400ms, 800ms) in caso di errori transitori (5xx, timeout, errori di connessione). Un singolo problema di rete non farà fallire la build.

**Fail-closed sugli errori di query.** Se le query al registry o a OSV falliscono, sloppy-joe emette un errore bloccante `registry-unreachable` invece di saltare silenziosamente i controlli. La scansione non si basa più su soglie per ecosistema o limiti di dimensione del campione prima di bloccarsi.

**Cache di similarità.** I risultati sull'esistenza delle mutazioni vengono memorizzati nella cache per 7 giorni. Dopo la prima scansione, la maggior parte delle query viene servita dalla cache senza chiamate di rete. Solo le nuove dipendenze attivano query al registry.

**Risoluzione basata su lockfile.** Quando un lockfile supportato è presente e attendibile (`package-lock.json`, `npm-shrinkwrap.json`, `Cargo.lock`, `Gemfile.lock`, `poetry.lock` per progetti Poetry, `uv.lock` per progetti uv, `composer.lock`, `gradle.lockfile`, `packages.lock.json`), sloppy-joe risolve le versioni esatte da esso invece di indovinare dagli intervalli. I file `requirements*.txt` completamente bloccati tramite hash possono anche fornire versioni esatte bloccate, e diventano completamente attendibili quando il grafico delle dipendenze impegnato vincola il proprio `--index-url` e i valori esatti di `--extra-index-url` consentiti.

## Test

La suite di test copre i controlli di similarità, i segnali di metadati, il comportamento di OSV, l'analisi e la validazione della configurazione, la risoluzione dei lockfile, la politica di preflight per manifest e lockfile, la formattazione dei report e la logica di ripetizione HTTP.```bash
cargo test