KadGlobe 🌍

Español | English

KadGlobe es una herramienta de visualización avanzada en 3D para la red Kademlia en eMule. Permite monitorizar en tiempo real la salud de la red, la distribución geográfica de los nodos y la topología lógica (distancia XOR) de tu tabla de enrutamiento.

1. Descripción General

KadGlobe actúa como un "puesto de mando" visual para eMule. Se conecta a la WebUI de eMule para extraer estadísticas en vivo y analiza archivos de configuración locales (key_index.dat y nodes.dat) para proyectar tu vecindario Kademlia sobre un globo terráqueo interactivo. Su objetivo es ofrecer transparencia sobre cómo funciona el enrutamiento descentralizado y cuál es el estado real de tus conexiones.

2. Tecnologías y Arquitectura

El proyecto se divide en un backend de orquestación y un frontend de visualización premium:

• Backend (Python):

  • Scraper Avanzado: Inicia sesión en la WebUI de eMule para capturar telemetría (tráfico, búsquedas, estado UDP), y guarda los datos en un archivo JSON.

  

  • Identidad Dinámica: Detecta automáticamente tu IP pública y extrae tu KadID real de 128 bits directamente desde el tráfico UDP de tu eMule local.

  • Geolocalización: Procesa nodes.dat y utiliza una base de dato IP2Location para situar cada nodo de la red en el mapa.

  

  • Kad UDP Probe Inteligente: Implementa un motor de descubrimiento en 4 fases:

    1. Semilla (Seed): Obtiene contactos del eMule local.

    2. Selección RTT: Mide la latencia y selecciona a los 4 nodos más rápidos.

    3. Crawl 1-hop: Solicita contactos a esos líderes para expandir el mapa con nodos vivos de alta calidad (hasta un máximo de 100 nuevos nodos).

    4. Sondeo: Mide el RTT final e identifica tu propio nodo (Pilar Negro).

  

• Frontend (Web):

  • Visualización 3D: Basado en Globe.gl y Three.js para un renderizado fluido.

  • Interfaz Bilingüe: Soporte completo para Español e Inglés mediante un selector dinámico (ES/EN).

  • Contador en Tiempo Real: El botón de "Nodos Activos" muestra el número exacto de nodos que respondieron detectados en el último ciclo.

  • Gráficos: Utiliza Chart.js para representar la distribución de K-Buckets.

3. Componentes y Funcionalidades

• Mapa Térmico Inteligente: Al activarlo, el sistema realiza un descubrimiento recursivo basado en rendimiento. Los nodos se colorean según su latencia UDP:

Verde 🟢 (<150ms),

Amarillo 🟡 (<500ms),

Rojo 🔴 (>500ms)

Blanco ⚪ (sin respuesta).

Violeta 🟣 (Objetivo de alerta IDS / Amenaza detectada). Estos nodos también se visualizan con pilares más altos.

Nuestro propio nodo se destaca con un pilar negro ⬛ en el globo.

• Nodos por País: Un panel lateral que clasifica y ordena los nodos por ubicación geográfica.

• Distribución K-Buckets: Un histograma que muestra cuántos "contactos" (nodos) tienes en cada "cubo" (bucket) de enrutamiento (distancia XOR $0-127$). Es normal ver más nodos en los buckets lejanos ($B127$, $B126$, etc.) y muy pocos en los cercanos ($B0$ a $B10$).

Nota: Ten en cuenta que la probabilidad de que un nodo caiga en $B127$ es 50%, en $B126$ es 25%, en $B125$ es 12.5%, etc. Por eso virtualmente no verás nodos en los buckets más cercanos (la probabilidad es ínfima). La fórmula es: $$P(Bi) = \frac{1}{2^{128-i}}$$

• Top 10 Vecindario XOR: Al hacer clic en un nodo, se muestra una ventana con su IP, su ubicación y su Kad ID. También se se calculan sus 10 vecinos más cercanos criptográficamente (distancia XOR) y se trazan arcos dorados de conexión.

Por ejemplo, para un nodo cualquiera en Londres:

• Estado de la ID (Kad Status): Diferencia entre estado "Abierto (Open)" y "Tras cortafuegos (Firewalled)" usando terminología específica de Kademlia.

4. Sistema de Detección de Intrusiones (IDS)

KadGlobe incluye un motor IDS especializado (backend/ids_engine.py) que monitoriza anomalías en la red Kad para proteger tu nodo contra ataques comunes de redes DHT:

• Detección de Sybil/Eclipse: Analiza la distribución estadística de los buckets mediante la prueba de $\chi^2$ y alerta si un número inusual de nodos se concentra en buckets específicos intentando rodear tu ID.

• Detección de Poisoning: Utiliza un análisis Z-Score normalizado por la distribución teórica de Kademlia ($1/2^{128-i}$). Filtra el ruido natural en los buckets comunes ($B127$, $B126$...) y prioriza la detección de anomalías en el "vecindario XOR" cercano ($B0-B10$), donde los ataques son críticos para la salud del nodo.

• Monitor de Lookup DoS: Vigilancia del tráfico de control (overhead). Detecta inundaciones de paquetes mediante el análisis de ratios de tráfico y curvas de crecimiento exponencial, filtrando picos legítimos durante tus propias búsquedas.

Important

Periodo de Estabilización (Warm-Up): Al arrancar KadGlobe (primeros 10 ciclos / ~5 minutos), el motor IDS permanece en modo de "aprendizaje" y no emite alertas. Esto permite que las estadísticas de red y la geolocalización se estabilicen, eliminando falsos positivos causados por el ruido inicial de la red Kad al conectar.

Tip

Las alertas del IDS se clasifican en INFO, WARNING y CRITICAL. Las alertas se muestran en el panel de la UI.

Algunos ejemplos:

5. Requisitos y Configuración

Para que KadGlobe funcione correctamente, debes configurar los siguientes puntos:

1. eMule WebUI: Debes tener activada la "Interfaz Web" en las opciones de eMule (Opciones -> Opciones Adicionales o Interfaz Web según versión) y establecer una contraseña de administrador.

2. Dependencias: Instala los módulos de Python necesarios:

   pip install -r requirements.txt

3. Variables de Entorno: Configura el archivo .env (puedes copiar de .env.windows.example o .env.linux.example según tu sistema) para personalizar el comportamiento:
   • ADMIN_PASS: La contraseña que pusiste en la WebUI de eMule.
   • KADGLOBE_HTTP_PORT: (Opcional) El puerto donde verás el mapa (por defecto 8000).
   • WEBUI_PORT: (Opcional) El puerto de la WebUI de eMule/aMule (por defecto 4711 para eMule, 4712 para aMule).
   • EMULE_KAD_UDP_PORT: (Opcional) El puerto UDP de tu red Kademlia (por defecto 16005).
   • IP2LOCATION_DB_PATH: Ruta a la base de datos .BIN de IP2Location para la geolocalización.
   • EMULE_NODES_DAT_PATH: (Opcional) Ruta a tu nodes.dat. Si se deja vacío, se intenta detectar automáticamente.
   • EMULE_KEY_INDEX_PATH: (Opcional) Ruta a key_index.dat. Solo necesario para forzar tu KadID en la UI (el pinger lo auto-detecta vía UDP).

6. Aclaración sobre la Latencia y Persistencia de Datos

KadGlobe obtiene la información de los nodos de dos fuentes complementarias:

• Nodos base (offline): Se obtienen mediante el análisis binario del archivo nodes.dat de eMule. Estos contactos representan una "foto" de la tabla de rutas del último cierre de eMule, por lo que las posiciones geográficas y las distancias XOR del mapa base pueden no reflejar el estado actual de la red en tiempo real.

• Nodos "frescos" (en vivo): Para el Mapa Térmico, KadGlobe envía un KADEMLIA2_BOOTSTRAP_REQ directamente al proceso de eMule local para obtener contactos verificados y activos de su tabla de rutas en memoria. Esto garantiza que los nodos sondeados están realmente conectados a la red Kad en ese momento.

Las estadísticas de tráfico y el estado de la conexión se capturan en tiempo real a través del scrapeo de la WebUI de eMule. Las latencias del Heat Map se miden con paquetes KADEMLIA2_PING/PONG nativos del protocolo (vía UDP), ofreciendo una medición real a nivel de aplicación — no solo a nivel de red (ICMP).

Esta arquitectura permite monitorizar la salud de la red Kademlia de forma no invasiva, sin requerir acceso directo a la memoria ni inyección de procesos.

---

Automatización

1. Configuración Inicial (Recomendado)

El proyecto incluye un script de configuración que automatiza la instalación de dependencias, asegura que la estructura de carpetas sea correcta y te ayuda a descargar la base de datos de IP2Location.

Windows: Haz doble clic en setup.bat.
Linux: Ejecuta ./setup.sh en tu terminal.

# Dar permisos de ejecución (solo la primera vez)
chmod +x setup.sh

# Ejecutar el asistente de configuración
./setup.sh

2. Ejecución de KadGlobe

Una vez configurado, puedes lanzar todos los componentes en un solo paso:

Windows: Ejecuta Script.bat.
Linux: Ejecuta launcher.sh.

Caution

NO ejecutes launcher.sh con sudo.
Ejecutarlo como root provocará errores de "Permiso denegado" en /run/user/0 y errores de pantalla (X11) ya que las aplicaciones gráficas como aMule deben correr en tu sesión de usuario normal.