Update README.md
This commit is contained in:
juakoknife
@@ -1,77 +1,99 @@
|
|||||||
JNC-NetTools // Versión ADA - Documentación Técnica
|
# 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
|
## 1. Introducción
|
||||||
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
|
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.
|
||||||
Instalación
|
|
||||||
1. Clonar el repositorio:
|
### Capacidades Clave
|
||||||
git clone <url_del_repositorio>
|
- Gestión de Interfaces de Red (IP, Subred, Puerta de Enlace)
|
||||||
cd JNC-Scan
|
- Bridging Avanzado (Trunks VLAN, Passthrough, Wi-Fi a Ethernet)
|
||||||
2. Instalar Dependencias del Sistema:
|
- Escaneo de Redes y Puertos (Integración con Nmap)
|
||||||
sudo apt update
|
- Análisis de Tráfico y Sniffing de Paquetes (Integración con Scapy)
|
||||||
sudo apt install python3-pip nmap tcpdump dnsmasq hostapd iw
|
- Diagnóstico de Red (Ping, Traceroute, DNS)
|
||||||
3. Configurar el Entorno Python:
|
- Generación Automatizada de Informes (HTML)
|
||||||
python3 -m venv venv
|
|
||||||
source venv/bin/activate
|
## 2. Requisitos del Sistema
|
||||||
pip install -r requirements.txt
|
|
||||||
(Si falta
|
### Sistema Operativo
|
||||||
requirements.txt, instale manualmente: pip install PyQt6 python-nmap scapy psutil pyroute2)
|
- Linux (Probado en Linux Mint / Ubuntu / Debian)
|
||||||
Ejecución
|
- Privilegios de Root: Requeridos para la mayoría de las operaciones (manipulación de interfaces, escaneo de sockets raw, sniffing)
|
||||||
Para ejecutar la aplicación, utilice el script de lanzamiento proporcionado que gestiona los permisos de root y la activación del entorno virtual:
|
|
||||||
|
### Dependencias de Software
|
||||||
|
|
||||||
|
#### Herramientas del Sistema
|
||||||
|
| Herramienta | Descripción | Obligatoria |
|
||||||
|
|---------------|------------------------------------------|-------------|
|
||||||
|
| iproute2 | Comando `ip` | Sí |
|
||||||
|
| nmap | Mapeador de redes | Sí |
|
||||||
|
| tcpdump | Captura de paquetes | Sí |
|
||||||
|
| dnsmasq | Servidor DHCP | Sí |
|
||||||
|
| hostapd | Punto de acceso Wi-Fi | Sí |
|
||||||
|
| iw | Configuración inalámbrica | Sí |
|
||||||
|
| ethtool | Estadísticas de interfaz | Opcional |
|
||||||
|
|
||||||
|
#### Bibliotecas de Python
|
||||||
|
| Biblioteca | Uso Principal |
|
||||||
|
|----------------|----------------------------------------|
|
||||||
|
| PyQt6 | Framework GUI |
|
||||||
|
| python-nmap | Wrapper de Nmap |
|
||||||
|
| scapy | Manipulación y sniffing de paquetes |
|
||||||
|
| psutil | Monitoreo del sistema |
|
||||||
|
| pyroute2 | Redes avanzadas en Linux (Netlink) |
|
||||||
|
|
||||||
|
- Python: 3.8 o superior
|
||||||
|
|
||||||
|
## 3. Instalación y Ejecución
|
||||||
|
|
||||||
|
### Instalación
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Clonar el repositorio
|
||||||
|
git clone https://github.com/inlutec/JNC-NetTools.git
|
||||||
|
cd JNC-Scan
|
||||||
|
|
||||||
|
# 2. Instalar dependencias del sistema
|
||||||
|
sudo apt update
|
||||||
|
sudo apt install python3-pip nmap tcpdump dnsmasq hostapd iw
|
||||||
|
|
||||||
|
# 3. Configurar entorno virtual
|
||||||
|
python3 -m venv venv
|
||||||
|
source venv/bin/activate
|
||||||
|
pip install -r requirements.txt
|
||||||
|
|
||||||
|
# Si no existe requirements.txt, instalar manualmente:
|
||||||
|
# pip install PyQt6 python-nmap scapy psutil pyroute2
|
||||||
|
```
|
||||||
|
|
||||||
|
### Ejecución
|
||||||
|
|
||||||
|
```bash
|
||||||
bash JNC-Scan_Launcher.sh
|
bash JNC-Scan_Launcher.sh
|
||||||
Nota: Se le solicitará su contraseña de sudo.
|
```
|
||||||
|
|
||||||
|
> Nota: El launcher gestiona automáticamente la activación del entorno virtual y los privilegios de root (se solicitará la contraseña sudo).
|
||||||
|
|
||||||
|
## 4. Arquitectura Técnica
|
||||||
|
|
||||||
|
La aplicación sigue una arquitectura modular que separa claramente la lógica del núcleo (backend) de la interfaz gráfica (frontend).
|
||||||
|
|
||||||
|
### Estructura de Directorios
|
||||||
|
|
||||||
|
```
|
||||||
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/
|
JNC-Scan/
|
||||||
├── main.py # Punto de entrada
|
├── main.py # Punto de entrada principal
|
||||||
├── JNC-Scan_Launcher.sh # Script de inicio
|
├── JNC-Scan_Launcher.sh # Script de lanzamiento con sudo
|
||||||
|
├── requirements.txt # Dependencias Python (si existe)
|
||||||
├── src/
|
├── src/
|
||||||
│ ├── core/ # Lógica Backend
|
│ ├── core/ # Lógica Backend
|
||||||
│ │ ├── network_manager.py # Lógica de Interfaz, Bridge, DHCP, Wi-Fi
|
│ │ ├── network_manager.py # Gestión de interfaces, bridges, DHCP, Wi-Fi AP
|
||||||
│ │ ├── scanner.py # Lógica de Escáner de Puertos/Red Nmap
|
│ │ ├── scanner.py # Escáner de red y puertos (Nmap)
|
||||||
│ │ ├── sniffer.py # Lógica de Sniffer Scapy
|
│ │ ├── sniffer.py # Sniffer con Scapy
|
||||||
│ │ ├── vlan_scanner.py # Detección pasiva de VLAN (tcpdump)
|
│ │ ├── vlan_scanner.py # Detección pasiva de VLANs (tcpdump)
|
||||||
│ │ └── diagnostics.py # Ping, Traceroute, etc.
|
│ │ └── diagnostics.py # Ping, traceroute, DNS lookup
|
||||||
│ ├── gui/ # Frontend (PyQt6)
|
│ ├── gui/ # Frontend PyQt6
|
||||||
│ │ ├── main_window.py # Ventana principal de la aplicación
|
│ │ ├── main_window.py # Ventana principal y pestañas
|
||||||
│ │ ├── styles.py # Hojas de estilo CSS/QSS
|
│ │ ├── styles.py # Hojas de estilo QSS
|
||||||
│ │ └── widgets/ # Pestañas de funciones individuales
|
│ │ └── widgets/ # Widgets por funcionalidad
|
||||||
│ │ ├── ip_config.py
|
│ │ ├── ip_config.py
|
||||||
│ │ ├── vlan_bridge.py
|
│ │ ├── vlan_bridge.py
|
||||||
│ │ ├── scanner_view.py
|
│ │ ├── scanner_view.py
|
||||||
@@ -79,90 +101,77 @@ JNC-Scan/
|
|||||||
│ │ ├── sniffer_view.py
|
│ │ ├── sniffer_view.py
|
||||||
│ │ └── diagnostics_view.py
|
│ │ └── diagnostics_view.py
|
||||||
│ └── utils/
|
│ └── utils/
|
||||||
│ └── report_generator.py # Generación de Informes HTML
|
│ └── report_generator.py # Generación de informes HTML
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. Funcionalidades Detalladas e Implementación Técnica
|
||||||
|
|
||||||
|
### A. Configuración IP
|
||||||
|
- Uso de `psutil` + `pyroute2` para lectura
|
||||||
|
- Aplicación persistente mediante `nmcli` (NetworkManager)
|
||||||
|
- Refresco en tiempo real de interfaces
|
||||||
|
|
||||||
|
### B. VLAN y Bridging Avanzado
|
||||||
|
- Creación de VLANs: `ip link add link <dev> name <dev.id> type vlan id <id>`
|
||||||
|
- Bridges: `ip link add name <br> type bridge`
|
||||||
|
- Servidor DHCP integrado con `dnsmasq`
|
||||||
|
- AP Wi-Fi con `hostapd` + configuración dinámica
|
||||||
|
- Soporte automático para modo 4addr (WDS) en interfaces Wi-Fi cliente
|
||||||
|
- Escáner pasivo de VLANs mediante `tcpdump -e` + regex 802.1Q
|
||||||
|
|
||||||
5. Funcionalidades Detalladas e Implementación Técnica
|
### C. Escáner de Red (Host Discovery)
|
||||||
A. Configuración IP
|
- Motor: Nmap
|
||||||
• Función: Ver y configurar direcciones IP, subredes y puertas de enlace.
|
- Prioriza escaneo ARP en redes locales
|
||||||
• Implementación:
|
- Soporte completo para detener escaneo en ejecución
|
||||||
◦ Utiliza psutil y pyroute2 para obtener el estado de la interfaz.
|
- Filtros en tiempo real (Up/Down)
|
||||||
◦ 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.
|
|
||||||
|
|
||||||
|
### D. Escáner de Puertos
|
||||||
|
- Modos: TCP Connect (`-sT`), UDP (`-sU`), o ambos
|
||||||
|
- Optimizado con `--min-rate 1000 -T4`
|
||||||
|
- Oculta automáticamente puertos cerrados en rangos grandes (>500)
|
||||||
|
- Ejecutado en `QThread` para mantener GUI receptiva
|
||||||
|
|
||||||
|
### E. Sniffer de Paquetes
|
||||||
|
- Motor: `scapy.sniff`
|
||||||
|
- Soporte completo para filtros BPF
|
||||||
|
- Decodificación de capas Ethernet/IP/TCP/UDP/ICMP
|
||||||
|
- Detección automática de anomalías (RST, ICMP Unreachable, retransmisiones)
|
||||||
|
- Vista separada de "Todo el tráfico" vs "Solo anomalías"
|
||||||
|
|
||||||
C. Escáner de Red (Descubrimiento)
|
### F. Diagnósticos
|
||||||
• Función: Descubre dispositivos activos en un rango de red (CIDR).
|
- Wrappers con análisis de salida para: `ping`, `traceroute`, `nslookup`
|
||||||
• 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.
|
|
||||||
|
|
||||||
|
### G. Generación de Informes
|
||||||
|
- Informe HTML completo con todos los resultados de la sesión
|
||||||
|
- Estilizado y con timestamps
|
||||||
|
|
||||||
|
## 6. Guía para Desarrolladores
|
||||||
|
|
||||||
F. Diagnósticos
|
### Añadir una nueva pestaña
|
||||||
• Función: Herramientas de conectividad estándar.
|
1. Crear widget en `src/gui/widgets/nueva_herramienta.py`
|
||||||
• 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.
|
2. Heredar de `QWidget`
|
||||||
G. Informes
|
3. Importar en `src/gui/main_window.py`
|
||||||
• Función: Genera un informe HTML de la sesión actual.
|
4. Añadir: `self.tabs.addTab(NuevaHerramienta(), "Nueva Herramienta")`
|
||||||
• 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)
|
### Modificar escaneos Nmap
|
||||||
Añadir una Nueva Pestaña
|
- Editar `src/core/scanner.py` → método `scan()`
|
||||||
1. Cree un nuevo archivo de widget en src/gui/widgets/ (ej. mi_herramienta.py).
|
- Añadir flags como `-O` (detección SO) o `-sV` (versiones)
|
||||||
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
|
### Personalizar el sniffer
|
||||||
• "Operation not supported" (Error 95): Ocurre al puentear una interfaz Wi-Fi que no soporta el modo de 4 direcciones.
|
- Editar `src/core/sniffer.py` → función `process_packet`
|
||||||
◦ 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.
|
- Añadir detección de payloads específicos (HTTP, malware, etc.)
|
||||||
• "iw: command not found": Falta la herramienta iw en el sistema.
|
|
||||||
◦ Solución: sudo apt install iw.
|
### Cambiar estilos
|
||||||
• Sin Resultados de Escaneo:
|
- Editar `src/gui/styles.py` (QSS)
|
||||||
◦ Asegúrese de estar ejecutando como root (a través del lanzador).
|
|
||||||
◦ Verifique si el firewall (ufw) está bloqueando las respuestas.
|
## 7. Solución de Problemas Comunes
|
||||||
• 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.
|
| Problema | Causa más común | Solución |
|
||||||
|
|---------------------------------------|----------------------------------------------|--------------------------------------------------------------------------|
|
||||||
|
| "Operation not supported" (Error 95) | Wi-Fi no soporta modo 4addr/WDS | Usar tarjeta compatible o modo "Wi-Fi AP" en lugar de puente cliente |
|
||||||
|
| `iw: command not found` | Herramienta `iw` no instalada | `sudo apt install iw` |
|
||||||
|
| Sin resultados en escaneos | No ejecutado como root o firewall bloqueando | Usar el launcher oficial / desactivar temporalmente ufw |
|
||||||
|
| UI se congela en sniffer | Volumen de tráfico muy alto | Aplicar filtro BPF estricto (ej. `tcp port 80`) |
|
||||||
|
|
||||||
|
¡Listo para copiar y pegar directamente en tu `README.md` de GitHub!
|
||||||
|
Mantendrá perfectamente el formato con tablas, código y estructura de carpetas.
|
||||||
|
|||||||
Reference in New Issue
Block a user