Metadata-Version: 2.4
Name: pkgxray
Version: 0.1.1
Summary: Analyze PyPI packages for suspicious behavior before installing them
Project-URL: Homepage, https://github.com/maip-fred/pkgxray
Project-URL: Repository, https://github.com/maip-fred/pkgxray
Project-URL: Issues, https://github.com/maip-fred/pkgxray/issues
Author: pkgxray contributors
License: MIT
License-File: LICENSE
Keywords: analysis,malware,package,pypi,security,supply-chain
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

![PyPI](https://img.shields.io/pypi/v/pkgxray)
![Python](https://img.shields.io/pypi/pyversions/pkgxray)
![License](https://img.shields.io/pypi/l/pkgxray)
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/maip-fred/pkgxray/blob/main/notebooks/pkgxray_tutorial.ipynb)

# 🔬 pkgxray

**Analiza paquetes de PyPI en busca de comportamiento sospechoso antes de instalarlos.**

Cuando ejecutas `pip install un-paquete`, confías ciegamente en que el código es seguro.
pkgxray descarga el paquete **sin instalarlo**, extrae el código fuente y ejecuta
8 analizadores especializados basados en AST para detectar patrones maliciosos —
todo esto antes de que una sola línea del paquete se ejecute en tu máquina.

---

## Características

pkgxray detecta **8 categorías** de comportamiento sospechoso:

| # | Analizador | Qué detecta | Severidad máxima |
|---|------------|-------------|-----------------|
| 1 | `code_exec` | Llamadas a `eval()`, `exec()`, `compile()` | CRITICAL |
| 2 | `network` | Conexiones de socket, solicitudes HTTP, importaciones de red sospechosas | HIGH |
| 3 | `filesystem` | Escritura/borrado de archivos, rutas sensibles (`/etc/passwd`, `~/.ssh/`) | CRITICAL |
| 4 | `env_access` | Acceso a variables de entorno (API keys, tokens, contraseñas) | HIGH |
| 5 | `subprocess` | `subprocess.Popen()`, `os.system()`, ejecución de comandos de shell | CRITICAL |
| 6 | `obfuscation` | `exec(base64.b64decode(...))`, strings con escape hexadecimal, codificación rot13 | CRITICAL |
| 7 | `setup_scripts` | Hooks post-instalación en `setup.py` que ejecutan código al instalar | CRITICAL |
| 8 | `dynamic_imports` | `__import__()`, `importlib.import_module()` con argumentos dinámicos | HIGH |

---

## Instalación

```bash
pip install pkgxray
```

---

## Inicio rápido

### Interfaz de línea de comandos

```bash
# Analizar un paquete (salida en terminal con colores)
pkgxray scan requests

# Obtener salida en JSON
pkgxray scan requests --format json

# Guardar reporte HTML en archivo
pkgxray scan requests --format html -o reporte.html

# Analizar una versión específica
pkgxray scan requests --version 2.28.0
```

### API de Python

```python
from pkgxray import scan
from pkgxray.reporter import generate_report

# Analizar un paquete
result = scan("requests")

print(f"Puntaje de riesgo: {result.risk_score}/100")
print(f"Nivel de riesgo: {result.risk_level}")
print(f"Archivos analizados: {result.files_analyzed}")
print(f"Hallazgos totales: {len(result.findings)}")

# Inspeccionar hallazgos individuales
for finding in result.findings:
    print(f"[{finding.severity.value.upper()}] {finding.analyzer_name}")
    print(f"  {finding.filename}:{finding.line_number}")
    print(f"  {finding.description}")

# Exportar como JSON
json_report = generate_report(result, format="json")

# Guardar reporte HTML
generate_report(result, format="html", output_path="reporte.html")
```

---

## Docker

```bash
# Ejecutar los tests dentro de Docker
docker-compose run test

# Analizar el paquete "requests"
docker-compose run scan

# Analizar "requests" y obtener salida JSON
docker-compose run scan-json
```

O construir y ejecutar directamente:

```bash
docker build -t pkgxray .
docker run pkgxray scan requests
docker run pkgxray scan requests --format json
```

---

## Cómo funciona

```
pkgxray scan <paquete>
      |
      v
1. DESCARGA   -> Consulta la API JSON de PyPI
                Descarga el .tar.gz o .whl (sin instalarlo)
      |
      v
2. EXTRACCIÓN -> Descomprime el archivo
                Extrae todos los archivos .py (incluyendo setup.py)
      |
      v
3. ANÁLISIS   -> Ejecuta 8 analizadores basados en AST en cada archivo
                El parseo AST es robusto: no puede evadirse renombrando variables
      |
      v
4. PUNTUACIÓN -> Pondera hallazgos por severidad:
                LOW=1  MEDIUM=3  HIGH=7  CRITICAL=15
                Puntaje final: 0–100
      |
      v
5. REPORTE    -> Salida en terminal (con colores), JSON o HTML
```

**¿Por qué AST en lugar de regex?**
- Entiende la estructura del código, no solo el texto
- Más difícil de evadir: renombrar una variable no lo engaña
- Sin dependencias adicionales — usa el módulo `ast` integrado de Python

---

## Analizadores

| Analizador | Descripción | Rango de severidad |
|------------|-------------|-------------------|
| `code_exec` | Detecta ejecución dinámica de código con `eval()`, `exec()`, `compile()` | HIGH – CRITICAL |
| `network` | Detecta importaciones de socket, `requests.get()`, `urlopen()`, conexiones directas | MEDIUM – HIGH |
| `filesystem` | Detecta escritura de archivos, `os.remove()`, `shutil.rmtree()`, acceso a `/etc/passwd`, `~/.ssh/` | MEDIUM – CRITICAL |
| `env_access` | Detecta `os.environ`, `os.getenv()`, acceso a tokens/contraseñas/API keys | MEDIUM – HIGH |
| `subprocess` | Detecta `subprocess.Popen()`, `os.system()`, `os.popen()`, `os.execvp()` | MEDIUM – CRITICAL |
| `obfuscation` | Detecta `exec(base64.b64decode(...))`, `bytes.fromhex()`, strings con escape hexadecimal | MEDIUM – CRITICAL |
| `setup_scripts` | Detecta hooks post-instalación en `setup.py` que sobreescriben `install.run()` | HIGH – CRITICAL |
| `dynamic_imports` | Detecta `__import__()` e `importlib.import_module()` con argumentos dinámicos | MEDIUM – HIGH |

---

## Desarrollo

```bash
# Clonar e instalar en modo desarrollo
git clone https://github.com/maip-fred/pkgxray.git
cd pkgxray
pip install -e ".[dev]"

# Ejecutar tests unitarios (rápidos, sin red)
pytest tests/ -v -m "not slow"

# Ejecutar todos los tests incluyendo los de integración
pytest tests/ -v

# Ejecutar con cobertura
pytest tests/ --cov=pkgxray --cov-report=html -m "not slow"
```

---

## ¿Por qué no usar pip-audit?

| Herramienta | Qué hace |
|-------------|---------|
| `pip-audit` / `safety` | Busca **CVEs conocidos** — vulnerabilidades ya reportadas |
| `bandit` | Analiza **tu código**, no paquetes de terceros antes de instalarlos |
| **`pkgxray`** | **Análisis de comportamiento** de paquetes de terceros **antes** de instalarlos |

pkgxray es la única herramienta instalable con pip que realiza análisis AST estático
sobre paquetes de PyPI antes de que los instales.

---

## Licencia

MIT — ver [LICENSE](LICENSE)
