belphegor 0.1.0

                                   ____       __      __                         
                                  / __ )___  / /___  / /_  ___  ____ _____  _____
                                 / __  / _ \/ / __ \/ __ \/ _ \/ __ `/ __ \/ ___/
                                / /_/ /  __/ / /_/ / / / /  __/ /_/ / /_/ / /    
                               /_____/\___/_/ .___/_/ /_/\___/\__, /\____/_/     
                                           /_/               /____/              

Belphegor es una herramienta de enumeración de contenido (directorios, vhosts y subdominios) pensada para correr en Linux (BlackArch / Kali). No reinventa el motor de fuzzing: orquesta los que ya funcionan bien (gobuster, ffuf) y les suma la inteligencia y el flujo — detección de comodín, recursión y una salida que se integra a cualquier pipeline. Hace una cosa y la hace bien.

📑 Contenido

• ✨ Features
• 📦 Instalación
• 🚀 Uso
• 🔎 Módulo de enumeración
• 🗂️ Estructura
• 🗺️ Roadmap
• 📄 Licencia

✨ Features

• 🖥️ Modo dual — menú interactivo si lo corrés pelado, o flags por CLI para scriptearlo.
• 🎨 Salida con color vía rich: tablas, paneles y status HTTP coloreados.
• 🧪 Preflight inteligente — resuelve DNS y autodetecta http/https antes de disparar el escaneo, así no te comés errores crípticos de gobuster.
• 📊 Salida limpia — durante el escaneo, un spinner con el conteo de posibles hallazgos y el tiempo; al terminar, una tabla ordenada. Con -v además imprime cada hallazgo en vivo, apenas aparece (ideal para CTF).
• 🎯 Detección de respuesta comodín — cuando un target responde igual a todo (WAF, catch-all 403, SPA), separa los hallazgos que rompen el patrón del ruido y te ofrece re-correr filtrando por tamaño (--exclude-length).
• 🛡️ Chequeo de dependencias — avisa si falta una herramienta externa y corta con un mensaje claro antes de romper.
• 📥 Auto-instalación consentida — si falta gobuster, detecta tu gestor de paquetes y te ofrece instalarlo, mostrándote el comando exacto antes de correr nada. Nunca instala en silencio.
• 🔌 Motores intercambiables — el fuzzing lo hace gobuster o ffuf (--engine) detrás de una interfaz común; Belphegor pone el flujo y la inteligencia, no reinventa el motor.
• 🔁 Recursión automática — -r entra solo en los directorios que encuentra, con profundidad configurable, dedup y tope de seguridad.
• 🎯 Auto-calibración de comodín — --calibrate le pega a rutas random antes de escanear; si el server tiene catch-all, excluye ese tamaño de entrada.
• ✨ Hallazgos jugosos — resalta rutas de interés conocidas (/admin, /.git, .env, backups, api…) con ★ en la tabla y interesting en el JSON.
• 🔗 Encadenamiento — belphegor chain <dominio>: descubre subdominios (dns), se queda con los hosts vivos y corre el dir scan sobre cada uno, todo en un comando y con control de scope (--max-hosts).
• 🧵 Salida pipeable — --json (o automático al redirigir/pipear) emite JSONL por stdout para encadenar con jq, httpx, nuclei; todo el diagnóstico va a stderr, así el pipe queda limpio.
• 🧩 Arquitectura limpia — modelo de datos tipado y motores detrás de una interfaz común (Scanner), fácil de extender y respaldado por tests.

📦 Instalación

Belphegor se instala como comando del sistema (belphegor). No hace falta llamar a Python a mano.

git clone https://github.com/facundogomezuy/belphegor.git
cd belphegor

# Recomendado: pipx (queda aislado, no te ensucia el Python del sistema)
pipx install .

# Alternativa con pip
pip install .

# Para desarrollo (editás el código sin reinstalar, + dependencias de test)
pip install -e ".[dev]"
pytest        # corre la suite de tests

Dependencias externas

Los defaults de wordlist apuntan a rutas de SecLists (/usr/share/seclists/…). Si no lo tenés instalado, pasá tu propia wordlist con -w.

Las dependencias de Python (rich, pyfiglet, requests) se instalan solas con el paquete — el requirements.txt está solo por comodidad; la fuente de verdad es pyproject.toml.

📥 Auto-instalación de herramientas

Si vas a correr un módulo y falta su herramienta externa (ej: gobuster), Belphegor te ofrece instalarla en vez de solo abandonar:

1. Detecta el gestor de paquetes de tu distro (apt · pacman · dnf · zypper · apk).
2. Te muestra el comando exacto que ejecutaría (con sudo solo si no sos root).
3. Instala únicamente si confirmás (el default es no).
4. Si declinás, no hay gestor soportado, o la instalación falla → cae al mensaje de instalación manual, sin romper.

En entornos no interactivos (scripts, CI, cron) no pregunta nunca. Y si querés desactivar el ofrecimiento del todo, pasá --no-install:

belphegor enum pepito.com -m dir --no-install

🚀 Uso

Modo interactivo

Corriendo belphegor sin argumentos entrás al modo interactivo: te va preguntando el objetivo, el modo (dir/vhost/dns), la wordlist, la profundidad de recursión, etc., y arranca el escaneo.

belphegor

💡 belphegor -v entra al modo interactivo con verbose activado: el escaneo va mostrando los hallazgos en vivo. En CLI el flag va igual: belphegor enum pepito.com -m dir -v.

CLI directo (scripteable)

# Enumeración de directorios (autodetecta http/https)
belphegor enum pepito.com -m dir

# Subdominios por fuerza bruta DNS
belphegor enum pepito.com -m dns

# vhosts, forzando https y guardando en JSON
belphegor enum https://pepito.com -m vhost --protocol https -o out.json --format json

# dir con nivel medio, extensiones y 20 hilos
belphegor enum pepito.com -m dir -L full -x php,html,bak -t 20

# dir con wordlist propia (ignora el nivel)
belphegor enum pepito.com -m dir -w /ruta/wordlist.txt

# salida JSONL para encadenar con otras tools (el diagnóstico va a stderr)
belphegor enum pepito.com -m dir --json | jq -r '.path'

# recursión: entrar en cada directorio encontrado, hasta 3 niveles
belphegor enum pepito.com -m dir -r --depth 3

# usar ffuf como motor, con auto-calibración de comodín
belphegor enum pepito.com -m dir --engine ffuf --calibrate

# encadenar: subdominios → hosts vivos → dir (hasta 25 hosts), con recursión
belphegor chain pepito.com -r --max-hosts 25 --json | jq -r '.path'

💡 Sin instalar, desde el repo: python -m belphegor equivale al comando belphegor.

🔎 Módulo de enumeración (gobuster)

Envuelve gobuster en sus 3 modos (dir, vhost, dns) con un preflight que evita los errores típicos antes de disparar el escaneo:

   input del usuario
          │
          ▼
  ┌─────────────────┐   ¿ya trae esquema?
  │ 1. Normalizar   │──────────► respetarlo
  │    dominio/URL  │
  └────────┬────────┘
           ▼
  ┌─────────────────┐   no resuelve → corta con
  │ 2. Resolver DNS │──────────► mensaje claro
  └────────┬────────┘
           ▼
  ┌─────────────────┐   HTTPS ok → https
  │ 3. Autodetectar │   timeout   → http
  │    protocolo    │   --protocol → forzar
  └────────┬────────┘
           ▼
      gobuster 🚀

1. Normaliza el target — acepta dominio pelado (pepito.com), con esquema (https://pepito.com), con o sin www. Si ponés esquema, se respeta.
2. Resuelve DNS con socket.getaddrinfo() (IPv4/IPv6). Si no resuelve, corta con un mensaje claro en vez de dejar que gobuster tire un error críptico.
3. Autodetecta el protocolo — prueba HTTPS primero (timeout ~5s, verify=False por los certificados self-signed habituales en pentest). Si contesta cualquier cosa, usa https; si no, cae a http. Sigue redirects y se queda con el esquema final.
4. --protocol http|https fuerza el esquema y saltea la autodetección.

Flags principales

🎚️ Niveles de wordlist

En vez de acordarte rutas de SecLists, elegís un nivel y Belphegor resuelve la wordlist sola. Cada nivel prueba varias rutas candidatas y usa la primera que exista (aguanta Kali y BlackArch, que a veces las guardan distinto):

belphegor enum pepito.com -m dir -L full     # nivel medio
belphegor enum pepito.com -m dns -L deep     # subdominios, a fondo

¿No usás SecLists o querés tu propia lista? Pasá -w y manda la tuya (tiene prioridad, el nivel se ignora):

belphegor enum pepito.com -m dir -w /ruta/a/mi-wordlist.txt

Si el nivel elegido no encuentra ninguna wordlist en tu sistema, te avisa cuáles rutas probó y te sugiere instalar SecLists o usar -w.

Durante el escaneo se muestra un spinner con el conteo de posibles hallazgos y el tiempo transcurrido (nada de scroll infinito); al terminar, los hallazgos van a una tabla con color que separa lo que rompe el patrón del ruido comodín. Si preferís ver cada hallazgo apenas aparece —por ejemplo en un CTF, donde querés reaccionar rápido— pasá -v. Ctrl+C corta el escaneo de forma limpia sin dejar procesos colgados.

# ver cada hallazgo en vivo, y si aparece un comodín filtrarlo solo
belphegor enum pepito.com -m dir -v --auto-filter

🗂️ Estructura

belphegor/                    # raíz del repo
├── belphegor/                # el paquete
│   ├── __init__.py
│   ├── __main__.py           # habilita python -m belphegor
│   ├── cli.py                # entry point: menú + argparse
│   ├── banner.py             # ASCII art + disclaimer
│   ├── _console.py           # consolas stdout (resultado) / stderr (diagnóstico)
│   ├── models.py             # Finding: hallazgo normalizado, agnóstico del motor
│   ├── engines.py            # interfaz Scanner + GobusterScanner (backends)
│   ├── installer.py          # auto-instalación consentida de herramientas
│   ├── preflight.py          # chequeo de herramientas + validación de target
│   ├── utils.py              # comodín + tablas + guardado (txt/json/jsonl)
│   └── modules/
│       ├── __init__.py
│       ├── enumeration.py    # orquestador dir / vhost / dns
│       └── chain.py          # encadenamiento dns → vivos → dir
├── tests/                    # suite de pytest (lógica pura, sin red)
├── ROADMAP.md                # hoja de ruta por fases
├── pyproject.toml            # metadata + entry point del comando `belphegor`
├── requirements.txt
├── .gitignore
├── LICENSE
└── README.md

🗺️ Roadmap

Belphegor se enfoca en enumeración de contenido, sin dispersarse en otros dominios (para recon pasivo o port scanning ya hay herramientas dedicadas, y belphegor se encadena con ellas vía su salida JSONL). Detalle en ROADMAP.md:

• 🔎 Enumeración dir / vhost / dns.
• 🔌 Motores intercambiables — gobuster y ffuf.
• 🔁 Recursión automática en directorios.
• 🎯 Detección/calibración de comodín y hallazgos jugosos.
• 🧵 Salida JSONL pipeable + suite de tests (pytest).
• 🔗 Encadenamiento subdominios → hosts vivos → dir (belphegor chain).

📄 Licencia

Distribuido bajo licencia MIT. Ver LICENSE para más detalle.