🌵 MIRAGEM — Validador de Dependências (Anti-Slopsquatting)

Pacotes alucinados por IA são miragens: parecem reais, mas não existem — até um atacante registrar o nome com malware dentro. O Miragem é o olho que enxerga através delas.

👁️ O Miragem em ação

Lote sujo no PyPI — três pacotes alucinados detectados antes do pip install, incluindo o typo requets com sugestão do nome correto:

Lote sujo no npm — dois pacotes inexistentes e um typosquat real (expres, registrado no npm há mais de uma década imitando o express):

Valide pacotes PyPI e npm antes de instalar, contra o ataque de slopsquatting: criminosos registram nos repositórios oficiais nomes de pacotes que as IAs (ChatGPT, Claude, Gemini, Copilot...) costumam alucinar ao sugerir código. Você roda o pip install confiando na IA — e o repositório oficial entrega o malware direto no seu terminal.

O Miragem fecha essa janela: analisa cada pacote e emite um veredito antes de qualquer instalação.

✨ O que ele verifica

Verificação	Sinal de alerta
Existe no repositório oficial?	Não existe = provável alucinação de IA
Idade do pacote	Criado há poucos dias/semanas
Histórico de releases	1 ou 2 releases apenas
Downloads recentes	Volume muito baixo
Mantenedor e repositório vinculado	Ausentes
Similaridade com pacotes populares	Possível typosquatting (requets ≈ requests)

Vereditos: 🟢 OK · 🟡 ATENÇÃO · 🔴 PERIGO · 🟣 ALUCINADO (não existe)

🚀 Uso

Zero dependências — 100% biblioteca padrão do Python 3.8+.

Interface gráfica

python miragem.py

Cole nomes de pacotes, um requirements.txt ou um package.json, escolha o ecossistema (PyPI/npm) e clique ANALISAR. Exporte o relatório em CSV ou copie o comando de instalação contendo apenas os pacotes aprovados.

Linha de comando (ideal para CI e agentes de IA)

# valida um requirements.txt
python miragem.py --cli requirements.txt

# pacotes avulsos
python miragem.py --cli --pkg requests selenium pyautogui

# ecossistema npm
python miragem.py --cli --npm --pkg express axios

# relatório em JSON
python miragem.py --cli requirements.txt --json-out relatorio.json

Códigos de saída (para automação):

Código	Significado
0	Aprovado — nenhum indicador de risco
1	Alertas — revise antes de instalar
2	Perigo ou pacote inexistente — não instale

Exemplo de gate em script:

python miragem.py --cli requirements.txt && pip install -r requirements.txt

🤖 Integração com agentes de IA (Claude Code, Codex, etc.)

Adicione ao seu AGENTS.md / instruções do agente:

Antes de qualquer pip install ou npm install de pacote desconhecido, execute python miragem.py --cli --pkg <nome> e só prossiga se o código de saída for 0.

📋 Observações

• Downloads via pypistats.org e api.npmjs.org — em redes que bloqueiam esses domínios a coluna exibe N/D sem penalizar o pacote.
• O Miragem reduz o risco, não o elimina: pacote antigo e popular também pode ser comprometido. Mantenha o senso crítico.
• Ferramenta defensiva, sem coleta de dados: as únicas requisições saem da sua máquina para as APIs públicas dos repositórios.

📄 Licença

MIT — use, modifique e distribua à vontade.