Create README.md

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 <url_del_repositorio>
+       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 <dev> name <dev.id> type vlan id <id>.
+        ◦ Bridges: Creados usando ip link add name <br> 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 <iface> 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.