Create README.md
This commit is contained in:
juakoknife
@@ -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.
|
||||||
Reference in New Issue
Block a user