kriskimmerle/wheelaudit# Scanner de Segurança para Arquivos Python Wheel — analisa arquivos .whl em busca de problemas de segurança antes da instalação. Detecta path traversal (CVE-2026-24049), adulteração de RECORD, shadowing de comandos, segredos e zip bombs. Zero dependências.
Scanner de Segurança para Arquivos Python Wheel — analise arquivos .whl em busca de problemas de segurança antes da instalação.
Motivado por CVEs recentes no tratamento de wheels em Python:
Zero dependências. Arquivo único. Python 3.9+.
O pip-audit verifica se seus pacotes possuem CVEs conhecidos. O wheelaudit verifica se um arquivo wheel em si é estruturalmente malicioso — path traversal, hashes RECORD adulterados, segredos embutidos, sombreamento de comandos, zip bombs e muito mais. É a diferença entre "este pacote é conhecidamente ruim?" e "este pacote parece ruim?"
Execute antes do pip install. Execute no CI. Execute em wheels baixados que você não confia.
# Apenas copie o arquivo
curl -O https://raw.githubusercontent.com/kriskimmerle/wheelaudit/main/wheelaudit.py
chmod +x wheelaudit.py
# Ou clone o repositório
git clone https://github.com/kriskimmerle/wheelaudit.git
cd wheelaudit
# Analisar um arquivo wheel
python3 wheelaudit.py package-1.0.0-py3-none-any.whl
# Analisar múltiplos wheels
python3 wheelaudit.py *.whl
# Analisar um diretório de wheels
python3 wheelaudit.py ./wheels/
# Modo CI: sair com código 1 se a pontuação estiver abaixo do limite
python3 wheelaudit.py package.whl --check --min-score 80
# Saída JSON para integração com ferramentas
python3 wheelaudit.py package.whl --json
# Modo verboso com detalhes
python3 wheelaudit.py package.whl -v
# Filtrar por severidade
python3 wheelaudit.py package.whl --severity high
# Ignorar regras específicas
python3 wheelaudit.py package.whl --ignore WH11
# Ler da entrada padrão
cat package.whl | python3 wheelaudit.py --stdin
| Regra | Severidade | Descrição |
|---|---|---|
| WH01 | CRÍTICA | Path traversal em nomes de arquivo (../, caminhos absolutos, bytes nulos) |
| WH02 | CRÍTICA-ALTA | Integridade do arquivo RECORD (ausente, hashes adulterados, arquivos não listados) |
| WH03 | ALTA-BAIXA | Tipos de arquivo suspeitos (executáveis, pickle, arquivos compactados, arquivos ocultos) |
| WH04 | CRÍTICA | Sombreamento de comandos de entry point (pip, python, sudo, etc.) |
| WH05 | CRÍTICA | Segredos embutidos (chaves de API, tokens, chaves privadas) |
| WH06 | CRÍTICA-BAIXA | Problemas de permissão de arquivo (SUID/SGID, gravável por todos, dados executáveis) |
| WH07 | ALTA-MÉDIA | Consistência de metadados (METADATA/WHEEL ausentes, problemas estruturais) |
| WH08 | ALTA | Detecção de zip bomb (taxas de compressão extremas, arquivos superdimensionados) |
| WH09 | ALTA-MÉDIA | Conformidade com PEP 427 (formato do nome do arquivo, incompatibilidade nome/versão) |
| WH10 | CRÍTICA | Colisão de namespace (sombreamento de módulos da stdlib) |
| WH11 | ALTA-MÉDIA | Padrões de código malicioso (eval, exec, os.system, acesso a credenciais) |
| WH12 | MÉDIA-BAIXA | Problemas com arquivos de dados (scripts em .data/, arquivos superdimensionados) |
| WH13 | ALTA | Manipulação de CRC32 (padrão de bypass CVE-2025-1889) |
| WH14 | ALTA | Incompatibilidade de extensão (binário ELF/PE disfarçado de .py/.txt) |
| WH15 | ALTA-MÉDIA | Symlinks e nomes de arquivo duplicados |
CRÍTICA (20 pontos): Path traversal, bits SUID, segredos embutidos, sombreamento de comandos, sombreamento da stdlib, adulteração de hash RECORD
ALTA (12 pontos): RECORD ausente, executáveis suspeitos, zip bombs, manipulação de CRC, incompatibilidade de extensão, symlinks, padrões de coleta de credenciais
MÉDIA (6 pontos): Caminhos com barra invertida, metadados ausentes, problemas de PEP 427, padrões de subprocess/rede
BAIXA (2 pontos): Arquivos ocultos, arquivos de dados executáveis, arquivos grandes
INFO (0 pontos): Extensões nativas legítimas, acesso a variáveis de ambiente
============================================================
requests 2.32.5 — B (88/100)
============================================================
[ALTA]
WH11 Padrão suspeito: __import__() — importação dinâmica (requests/packages.py)
Resumo: 1 alta
============================================================
evil-pip 99.0.0 — F (0/100)
============================================================
[CRÍTICA]
WH01 Path traversal no arquivo wheel (../../../etc/crontab)
WH04 Entry point sombreia comando do sistema: 'pip'
WH04 Entry point sombreia comando do sistema: 'python'
WH05 Segredo embutido: GitHub Personal Access Token (pip/__init__.py)
[ALTA]
WH02 Arquivo não listado no RECORD (../../../etc/crontab)
WH03 Tipo de arquivo suspeito: .exe (pip/payload.exe)
WH11 Padrão suspeito: os.system() — execução de comando shell
WH11 Padrão suspeito: chamada eval() — execução dinâmica de código
WH11 Padrão suspeito: referência ao diretório SSH
Resumo: 4 críticas, 5 altas, 2 médias, 2 baixas
{
"version": "0.1.0",
"results": [
{
"path": "package-1.0.0-py3-none-any.whl",
"score": 88,
"grade": "B",
"metadata": {
"name": "package",
"version": "1.0.0",
"file_count": 15,
"total_uncompressed_bytes": 45000
},
"findings": [
{
"rule": "WH11",
"severity": "high",
"message": "Suspicious pattern: __import__() — dynamic import",
"file": "package/compat.py"
}
],
"summary": {
"high": 1
}
}
]
}
- name: Audit wheel
run: |
python3 wheelaudit.py dist/*.whl --check --min-score 80
pip download some-package --no-deps -d /tmp/wheels
python3 wheelaudit.py /tmp/wheels/*.whl --check
pip install /tmp/wheels/*.whl
O wheelaudit trata cada arquivo .whl como um arquivo zip não confiável. Ele:
Nenhum arquivo é extraído para o disco. Toda a análise ocorre em memória.
| Recurso | wheelaudit | pip-audit | safety | GuardDog |
|---|---|---|---|---|
| Zero dependências | ✅ | ❌ | ❌ | ❌ |
| Analisa conteúdo do wheel | ✅ | ❌ | ❌ | ✅ |
| Detecção de path traversal | ✅ | ❌ | ❌ | ❌ |
| Integridade do RECORD | ✅ | ❌ | ❌ | ❌ |
| Banco de dados de CVEs | ❌ | ✅ | ✅ | ❌ |
| Operação offline | ✅ | ❌ | ❌ | ❌ |
| Python 3.9+ | ✅ | ✅ | ✅ | ✅ |
O wheelaudit complementa o pip-audit/safety — eles verificam vulnerabilidades conhecidas, o wheelaudit verifica o próprio wheel.
MIT