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

### 2. Typosquatting (verificações generativas + fallback de distância de edição)

**O ataque:** Um invasor registra `expresz` no npm — um caractere diferente de `express`. A IA o gera, ou um desenvolvedor o digita errado. O pacote existe, passa na verificação de existência e instala malware.

**Como o sloppy-joe bloqueia:** o sloppy-joe executa 10 verificações generativas antes de recorrer à distância de edição. Cada verificação generativa produz uma mutação específica do nome da dependência (trocar caracteres, colapsar repetições, remover sufixos, reordenar palavras, normalizar separadores, substituir homóglifos, verificar escopos) e testa uma correspondência exata com pacotes populares conhecidos. Esta abordagem, inspirada na biblioteca [Typomania da Rust Foundation](https://github.com/rustfoundation/typomania), tem quase zero falsos positivos porque só dispara em correspondências exatas após a mutação.

A distância de edição de Levenshtein é executada por último como uma rede de segurança para mutações novas que nenhuma verificação específica antecipou. Juntos, eles cobrem tanto padrões de ataque conhecidos (precisamente) quanto desconhecidos (amplamente).```
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. Confusão de separadores

**O ataque:** `python-dateutil` vs `python_dateutil` vs `pythondateutil`. Em alguns registros, esses são pacotes diferentes. Um invasor registra a variante.

**Como o sloppy-joe bloqueia isso:** Normaliza todos os separadores (`-`, `_`, `.`) antes da comparação. Se a forma normalizada corresponder a um pacote conhecido, ele é sinalizado.```
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. Trocas de caracteres adjacentes

**O ataque:** `reqeust` em vez de `request`. Dois caracteres adjacentes transpostos — um erro de digitação comum que atacantes exploram.

**Como o sloppy-joe bloqueia:** Gera todas as variantes de troca adjacente do nome da dependência e verifica cada uma em relação ao corpus.```
ERROR reqeusts [similarity/char-swap]
      'reqeusts' matches 'requests' with two adjacent characters swapped.
 Fix: Use 'requests' — two characters are transposed.

### 8. Homoglifos (aparências visuais)

**O ataque:** `rеquests` com um `е` cirílico (U+0435) em vez do `e` latino (U+0065). Visualmente idênticos. O nome do pacote parece exatamente com `requests`, mas resolve para um pacote diferente e malicioso.

**Como o sloppy-joe bloqueia:** Substitui 17 caracteres homoglifos conhecidos (cirílico, largura total, variantes de script) por seus equivalentes latinos e verifica se o resultado corresponde a um pacote conhecido.```
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. Ataques de variação de maiúsculas/minúsculas (registros sensíveis a maiúsculas/minúsculas)

**O ataque:** No Go, Maven e Ruby, `Rails` e `rails` são pacotes diferentes. Um invasor registra a variante capitalizada.

**Como o sloppy-joe bloqueia:** Em registros sensíveis a maiúsculas/minúsculas, qualquer variação de maiúsculas/minúsculas de um pacote conhecido é sinalizada como erro. Em registros insensíveis a maiúsculas/minúsculas (npm, PyPI, Cargo, NuGet, PHP), as variações de maiúsculas/minúsculas são seguras e ignoradas.```
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. Ataque de escopo (npm, PHP, Go, JVM)

**O ataque:** Um atacante registra `@typos/lodash` no npm — um caractere diferente de `@types/lodash`. Ou `larvael/framework` no Packagist — dois caracteres diferentes de `laravel/framework`. Ou `github.com/gooogle/protobuf` no Go — um `o` extra. O escopo parece legítimo à primeira vista. O pacote é resolvido. O malware é instalado.

Isso é raro, mas plausível — e "raro, mas plausível" é exatamente para o que sloppy-joe existe. O incidente com `ua-parser-js` em 2021 estava relacionado ao escopo. Se pode acontecer com um pacote com milhões de downloads semanais, pode acontecer com o seu.

**Como sloppy-joe bloqueia:** Extrai o escopo/namespace do nome da dependência e o compara com uma lista de escopos conhecidos como confiáveis usando distância de edição. Funciona em 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.

### 13. Pacotes não canônicos (não é um ataque — uma barreira de consistência)

**O ataque:** Não é um ataque — um problema de consistência. IA escolhe `moment` porque era popular nos dados de treinamento, mas sua equipe usa `dayjs`. Diferentes equipes usando pacotes diferentes para a mesma tarefa cria dívida de manutenção e inchaço de dependências.

**Como o sloppy-joe bloqueia isso:** Seu config mapeia cada pacote canônico para suas alternativas rejeitadas. Se uma dependência corresponder a uma alternativa, a build falha.```
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. Pacotes Novos

**O ataque:** Um pacote criado ontem com 3 downloads que tem um nome semelhante a um pacote popular. Alta probabilidade de ser um typosquat ou um placeholder para um ataque futuro.

**Como o sloppy-joe bloqueia:** Sinaliza qualquer pacote criado há menos de 30 dias.```
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.

---

## Ecossistemas Suportados

| Ecossistema | Manifesto | Política de Lockfile | Existência | Metadados | Validação de Idade |
|-----------|----------|-----------------|:---------:|:--------:|:--------:|
| npm | package.json | `package-lock.json` ou `npm-shrinkwrap.json` obrigatório | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| PyPI | `pyproject.toml`, `requirements*.txt`, `Pipfile`, `setup.cfg`, `setup.py` | Poetry é confiável com `poetry.lock`, uv é confiável com `uv.lock`, pip-tools totalmente bloqueado por hash é confiável apenas quando o grafo de requisitos commitado vincula `--index-url` e valores exatos de `--extra-index-url` na lista de permissões, e índices personalizados do Poetry/uv visíveis no repositório podem ser confiáveis apenas pela lista de permissões exata `trusted_indexes.pypi`; manifestos legados emitem aviso a cada execução a menos que `python_enforcement` seja `poetry_only` | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Cargo | Cargo.toml | `Cargo.lock` obrigatório | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| Go | go.mod | `go.sum` obrigatório para dependências externas; não obrigatório para stdlib-only ou `replace` totalmente local | :white_check_mark: | :x: | :x: |
| Ruby | Gemfile | `Gemfile.lock` obrigatório | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| PHP | composer.json | `composer.lock` obrigatório | :white_check_mark: | :x: | :x: |
| JVM (Gradle) | build.gradle / build.gradle.kts | `gradle.lockfile` obrigatório | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| JVM (Maven) | pom.xml | apenas aviso: sem imposição rigorosa de lockfile | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| .NET | *.csproj | `packages.lock.json` obrigatório | :white_check_mark: | :x: | :x: |

Todos os ecossistemas recebem verificações de existência + similaridade + canônicas. Metadados e validação de idade dependem do que a API do registro expõe. O suporte a lockfile permite a varredura de dependências transitivas e a resolução exata de versões onde o ecossistema fornece um modelo de lockfile local confiável ao projeto.

## Início Rápido```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`** — as chaves são pacotes aprovados; os valores são alternativas rejeitadas.

**`internal`** — os pacotes da sua organização. Pule TODAS as verificações. Eles mudam constantemente.

**`allowed`** — pacotes externos verificados. Pule existência + similaridade, mas ainda sujeito ao limite de idade da versão.

**`similarity_exceptions`** — supressões exatas de pacote/candidato/gerador para falsos positivos de similaridade revisados. Use isso quando uma aresta de similaridade específica estiver errada, mas você ainda quer verificações normais no pacote.

**`metadata_exceptions`** — supressões exatas de metadados revisados. Atualmente, isso só suporta `metadata/maintainer-change`, e requer uma correspondência exata de pacote/versão/publicador-anterior/publicador-atual.

Use `sloppy-joe check --review-exceptions` quando você precisa revisar os bloqueadores de mudança de mantenedor. A varredura ainda bloqueia normalmente, mas a saída legível adiciona uma seção `REVIEW EXCEPTIONS` com proprietários, URL do repositório e um trecho `metadata_exceptions` pronto para colar. `--json` inclui os mesmos dados em um campo `review_candidates` de nível superior.

**`min_version_age_hours`** — bloqueie qualquer versão publicada há menos de N horas. Padrão: 72 (3 dias). Defina como 0 para desabilitar. Pacotes internos são isentos.

**`allow_legacy_npm_v1_lockfile`** — permitir lockfiles npm `lockfileVersion: 1` do npm v5/v6 em modo de confiança reduzida. Padrão: `false`. Mantenha desligado, a menos que você esteja intencionalmente preso ao npm legado e aceite avisos altos e cobertura reduzida de confiança de dependências transitivas npm.

**`python_enforcement`** — controla a política de confiança do Python. `prefer_poetry` (padrão) confia em projetos Poetry e uv, confia em requisitos pip-tools totalmente bloqueados por hash apenas quando o grafo de requisitos commitado vincula explicitamente `--index-url` e quaisquer valores não-PyPI de `--extra-index-url`, e caso contrário rebaixa pip-tools para confiança reduzida. Manifestos legados como `requirements*.txt` sem hash, `Pipfile`, `setup.cfg`, `setup.py` e `pyproject.toml` não-Poetry/não-uv avisam a cada execução. `poetry_only` bloqueia esses workflows Python não-Poetry e exige Poetry.

### Segurança da Configuração

A configuração **nunca é lida do diretório do projeto**. Um agente de IA com acesso ao shell poderia reescrever uma configuração no repositório para permitir o que quisesse.

Resolução da configuração:
1. `--config /path/to/config.json` — arquivo local (flag CLI, prioridade mais alta)
2. `--config https://example.com/config.json` — buscar da URL
3. `SLOPPY_JOE_CONFIG=...` — variável de ambiente (caminho de arquivo ou URL)
4. Sem configuração = apenas verificações de existência + similaridade + metadados

Configurações malformadas **falham fortemente** com mensagens de erro acionáveis — uma configuração quebrada nunca retorna silenciosamente para nenhuma proteção.

Veja [CONFIG.md](https://github.com/brennhill/sloppy-joe/blob/main/CONFIG.md) para referência completa de formato, padrões de integração CI e exemplos.

Configuração de inicialização:```bash
sloppy-joe init --greenfield --ecosystem npm
sloppy-joe init --from-current
sloppy-joe init --from-current --register
sloppy-joe init --register

#### Entradas da Ação

| Input | Descrição | Padrão |
|-------|-----------|--------|
| `config` | Caminho do arquivo de configuração ou URL HTTPS | *(nenhum)* |
| `dir` | Diretório do projeto a ser escaneado | `.` |
| `type` | Ecossistema (`npm`, `pypi`, `cargo`, `go`, `ruby`, `php`, `jvm`, `dotnet`) | auto-detect |
| `deep` | Ativar verificações de similaridade de dependências transitivas | `false` |
| `paranoid` | Ativar mutações de bitflip | `false` |
| `args` | Argumentos adicionais de CLI | *(nenhum)* |
| `version` | versão do sloppy-joe a ser instalada | `latest` |

#### Exemplos```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 funciona com o framework [pre-commit](https://pre-commit.com).
Adicione-o ao seu `.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

Ou use um simples shell hook sem o framework:```bash
#!/bin/sh
sloppy-joe check || exit 1

Similaridade executa 4 fases:
- **Fase 0: Scope squatting** — verificação local, sem rede. Compara escopo/namespace com escopos conhecidos como seguros via distância de Levenshtein.
- **Fase 1: Intra-manifesto** — verificação local. Sinaliza quando duas dependências no mesmo manifesto são mutações uma da outra.
- **Fase 2: Consulta ao registro** — gera mutações, consulta o registro em lote para verificar existência, armazena resultados em cache (TTL de 7 dias).
- **Fase 3: Enriquecimento de metadados** — busca contagens de downloads e datas de publicação para correspondências, adicionando evidências aos relatórios.

Cada gerador de mutação marca sua saída, de modo que o tipo de verificação reportado (por exemplo, `similarity/homoglyph`) é determinístico — o gerador de maior severidade vence quando múltiplos geradores produzem o mesmo candidato.

## Confiabilidade CI

sloppy-joe é projetado para pipelines de CI onde falhas instáveis são inaceitáveis.

**Repetição com backoff.** Todas as chamadas HTTP do registro são repetidas 3 vezes com backoff exponencial (200ms, 400ms, 800ms) em falhas transitórias (5xx, timeouts, erros de conexão). Um único pico de rede não falhará sua build.

**Falha fechada em erros de consulta.** Se as consultas ao registro ou OSV falharem, sloppy-joe emite um erro bloqueante `registry-unreachable` em vez de pular verificações silenciosamente. A varredura não depende mais de limites por ecossistema ou cortes de tamanho de amostra antes de bloquear.

**Cache de similaridade.** Resultados de existência de mutação são armazenados em cache por 7 dias. Após a primeira varredura, a maioria das consultas é servida a partir do cache, sem chamadas de rede. Apenas dependências novas acionam consultas ao registro.

**Resolução ciente de lockfile.** Quando um lockfile suportado está presente e confiável (`package-lock.json`, `npm-shrinkwrap.json`, `Cargo.lock`, `Gemfile.lock`, `poetry.lock` para projetos Poetry, `uv.lock` para projetos uv, `composer.lock`, `gradle.lockfile`, `packages.lock.json`), sloppy-joe resolve versões exatas a partir dele em vez de adivinhar a partir de intervalos. Arquivos `requirements*.txt` totalmente bloqueados por hash também podem fornecer versões exatas fixadas, e eles se tornam totalmente confiáveis quando o grafo de requisitos versionado vincula seu próprio `--index-url` e valores de `--extra-index-url` explicitamente na lista de permissões.

## Testes

O conjunto de testes cobre verificações de similaridade, sinais de metadados, comportamento OSV, análise e validação de configuração, resolução de lockfile, política de pré-verificação de manifesto e lockfile, formatação de relatório e lógica de repetição HTTP.```bash
cargo test