From f4d3a01c6bbbc70258107e3bfba6de78690de711 Mon Sep 17 00:00:00 2001 From: juakoknife <162052088+inlutec@users.noreply.github.com> Date: Thu, 20 Nov 2025 20:17:27 +0100 Subject: [PATCH] Create README.md --- README.md | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..74b2953 --- /dev/null +++ b/README.md @@ -0,0 +1,168 @@ +JNC-NetTools // Versión ADA - Documentación Técnica +1. Introducción +JNC-NetTools es una suite integral de diagnóstico y gestión de redes diseñada para sistemas Linux . Proporciona una interfaz gráfica de usuario (GUI) para tareas de red avanzadas que normalmente requieren interacciones complejas en la línea de comandos. +Capacidades Clave: + • Gestión de Interfaces de Red (IP, Subred, Puerta de Enlace). + • Bridging Avanzado (Trunks VLAN, Passthrough, Wi-Fi a Ethernet). + • Escaneo de Redes y Puertos (Integración con Nmap). + • Análisis de Tráfico y Sniffing de Paquetes (Integración con Scapy). + • Diagnóstico de Red (Ping, Traceroute, DNS). + • Generación Automatizada de Informes (HTML). + +2. Requisitos del Sistema +Sistema Operativo + • Linux (Probado en Linux Mint / Ubuntu / Debian). + • Privilegios de Root: Requeridos para la mayoría de las operaciones (manipulación de interfaces, escaneo de sockets raw, sniffing). +Dependencias de Software +La aplicación depende de herramientas de red estándar de Linux y bibliotecas de Python: + • Python: 3.8 o superior. + • Herramientas del Sistema: + ◦ iproute2 (comando ip) + ◦ nmap (Mapeador de Redes) + ◦ tcpdump (Captura de paquetes) + ◦ dnsmasq (Servidor DHCP) + ◦ hostapd (Punto de Acceso Wi-Fi) + ◦ iw (Configuración inalámbrica) + ◦ ethtool (Estadísticas de interfaz - opcional) +Bibliotecas de Python + • PyQt6: Framework GUI. + • python-nmap: Wrapper de Python para Nmap. + • scapy: Manipulación y sniffing de paquetes. + • psutil: Monitoreo del sistema. + • pyroute2: Redes avanzadas en Linux (Netlink). + +3. Instalación y Ejecución +Instalación + 1. Clonar el repositorio: + git clone + cd JNC-Scan + 2. Instalar Dependencias del Sistema: + sudo apt update + sudo apt install python3-pip nmap tcpdump dnsmasq hostapd iw + 3. Configurar el Entorno Python: + python3 -m venv venv + source venv/bin/activate + pip install -r requirements.txt + (Si falta  + requirements.txt, instale manualmente: pip install PyQt6 python-nmap scapy psutil pyroute2) +Ejecución +Para ejecutar la aplicación, utilice el script de lanzamiento proporcionado que gestiona los permisos de root y la activación del entorno virtual: +bash JNC-Scan_Launcher.sh +Nota: Se le solicitará su contraseña de sudo. + + +4. Arquitectura Técnica +La aplicación sigue una arquitectura modular que separa la Lógica del Núcleo (Backend) de la GUI (Frontend). +Estructura de Directorios +JNC-Scan/ + + + + +├── main.py # Punto de entrada +├── JNC-Scan_Launcher.sh # Script de inicio +├── src/ +│ ├── core/ # Lógica Backend +│ │ ├── network_manager.py # Lógica de Interfaz, Bridge, DHCP, Wi-Fi +│ │ ├── scanner.py # Lógica de Escáner de Puertos/Red Nmap +│ │ ├── sniffer.py # Lógica de Sniffer Scapy +│ │ ├── vlan_scanner.py # Detección pasiva de VLAN (tcpdump) +│ │ └── diagnostics.py # Ping, Traceroute, etc. +│ ├── gui/ # Frontend (PyQt6) +│ │ ├── main_window.py # Ventana principal de la aplicación +│ │ ├── styles.py # Hojas de estilo CSS/QSS +│ │ └── widgets/ # Pestañas de funciones individuales +│ │ ├── ip_config.py +│ │ ├── vlan_bridge.py +│ │ ├── scanner_view.py +│ │ ├── port_scanner.py +│ │ ├── sniffer_view.py +│ │ └── diagnostics_view.py +│ └── utils/ +│ └── report_generator.py # Generación de Informes HTML + + + + +5. Funcionalidades Detalladas e Implementación Técnica +A. Configuración IP + • Función: Ver y configurar direcciones IP, subredes y puertas de enlace. + • Implementación: + ◦ Utiliza psutil y pyroute2 para obtener el estado de la interfaz. + ◦ Utiliza nmcli (CLI de NetworkManager) para aplicar configuraciones persistentes (IP Estática o DHCP). + ◦ Refresco: Actualizaciones en tiempo real de la lista de interfaces. +B. VLAN y Bridging + • Función: Crear puentes de red complejos. + ◦ VLAN Trunk: Puentea un ID de VLAN específico desde un puerto trunk a un puerto de acceso. + ◦ Passthrough: Puentea transparentemente dos interfaces. + ◦ Bridging Wi-Fi AP: Crea un punto de acceso Wi-Fi puenteado a una red cableada. + • Detalles Técnicos: + ◦ VLANs: Creadas usando ip link add link name type vlan id . + ◦ Bridges: Creados usando ip link add name
type bridge. + ◦ Servidor DHCP: Lanza un proceso dnsmasq vinculado a la interfaz del puente para servir direcciones IP a los clientes conectados. + ◦ Wi-Fi AP: Genera un hostapd.conf temporal y lanza hostapd. + ◦ Bridging de Cliente Wi-Fi (Corrección Error 95): Intenta automáticamente habilitar el modo 4addr (WDS) usando iw dev set 4addr on para permitir que los clientes Wi-Fi sean puenteados. Maneja los errores EOPNOTSUPP con elegancia. + ◦ Escáner Pasivo de VLAN: Utiliza tcpdump -e para capturar cabeceras y análisis regex para detectar etiquetas 802.1Q en un puerto trunk sin unirse a la VLAN. + + + +C. Escáner de Red (Descubrimiento) + • Función: Descubre dispositivos activos en un rango de red (CIDR). + • Implementación: + ◦ Motor: nmap. + ◦ Método: Escaneo ARP/Ping (lógica equivalente a -sn, pero usamos -sT con skip_discovery=False para asegurar verificación activa). + ◦ Optimización: Prioriza ARP para redes locales para mayor velocidad. + ◦ Características: Registro en tiempo real, capacidad de "Detener Escaneo", Filtros de Estado (Up/Down). +D. Escáner de Puertos + • Función: Análisis detallado de una IP objetivo específica. + • Implementación: + ◦ Motor: nmap. + ◦ Modos: TCP Connect (-sT), UDP (-sU), o Ambos. + ◦ Rendimiento: Utiliza --min-rate 1000 y -T4 para velocidad. + ◦ Rangos Grandes: Oculta automáticamente los puertos "Cerrados" si se escanean >500 puertos para evitar congelamientos de la UI. + ◦ Hilos: Se ejecuta en un QThread para mantener la GUI receptiva. +E. Sniffer de Paquetes + • Función: Análisis de tráfico en tiempo real. + • Implementación: + ◦ Motor: scapy.sniff. + ◦ Filtros: Soporta BPF (ej. tcp port 80) y Filtro IP Personalizado (post-filtro basado en GUI). + ◦ Análisis: + ▪ Decodifica capas Ethernet, IP, TCP, UDP, ICMP. + ▪ Detección de Anomalías: Resalta banderas "RST" (Reinicio de Conexión), errores ICMP Unreachable y Retransmisiones. + ▪ Vista Dividida: Separa "Todo el Tráfico" de "Anomalías" para una depuración más fácil. + + + +F. Diagnósticos + • Función: Herramientas de conectividad estándar. + • Implementación: Wrappers alrededor de comandos del sistema (ping, traceroute, nslookup) con análisis de salida para mostrar en un área de texto de la GUI. +G. Informes + • Función: Genera un informe HTML de la sesión actual. + • Implementación: Recopila datos de todos los widgets (resultados de escaneo, registros del sniffer) y los compila en un archivo HTML estilizado utilizando formato de cadenas de Python. + +6. Guía para Desarrolladores (Modificando el Código) +Añadir una Nueva Pestaña + 1. Cree un nuevo archivo de widget en src/gui/widgets/ (ej. mi_herramienta.py). + 2. Defina una clase que herede de QWidget. + 3. Impórtela en src/gui/main_window.py. + 4. Añádala a las pestañas: self.tabs.addTab(MiHerramienta(), "Mi Herramienta"). +Modificar Escaneos Nmap + • Edite src/core/scanner.py. + • El método scan() construye los argumentos del comando Nmap. Puede añadir banderas como -O (Detección de SO) o -sV (Detección de Versión) aquí. +Personalizar el Sniffer + • Edite src/core/sniffer.py. + • La función process_packet determina cómo se analizan los paquetes. Puede añadir lógica para detectar payloads específicos (ej. cabeceras HTTP, firmas de malware específicas). +Estilos + • Edite src/gui/styles.py. + • La aplicación utiliza QSS (Hojas de Estilo Qt). Puede cambiar colores, fuentes y comportamientos de los widgets aquí. + +7. Solución de Problemas + • "Operation not supported" (Error 95): Ocurre al puentear una interfaz Wi-Fi que no soporta el modo de 4 direcciones. + ◦ Solución: Use una tarjeta Wi-Fi que soporte modo WDS/Mesh, o use el modo "Wi-Fi AP" en lugar de puentear una conexión cliente. + • "iw: command not found": Falta la herramienta iw en el sistema. + ◦ Solución: sudo apt install iw. + • Sin Resultados de Escaneo: + ◦ Asegúrese de estar ejecutando como root (a través del lanzador). + ◦ Verifique si el firewall (ufw) está bloqueando las respuestas. + • Congelamiento de UI: + ◦ Un tráfico extremadamente alto en el Sniffer puede ralentizar la UI. Use el filtro BPF para reducir el volumen de captura.