Escáner de Red - Node.js + Express + MySQL

Aplicacion de escaner de red desarrollada en Node.js con Express para detectar dispositivos activos, identificar puertos abiertos y almacenar la información en una base datos.

Requisitos

Node.js 16+ - Descargar Node.js
MySQL 5.7+ o MariaDB 10.3+
Windows/Linux/macOS

Instalacion

1. Instalar Node.js

Si no tienes Node.js instalado:

Descarga desde: https://nodejs.org/
Instala la versión LTS recomendada
Verifica la instalación:

node --version
npm --version

2. Instalar dependencias del proyecto

npm install

3. Configurar la base de datos

Ejecutar el script SQL para crear la base de datos:

mysql -u root -p < database.sql

O importar manualmente el archivo database.sql usando MySQL Workbench, phpMyAdmin, etc.

4. Configurar variables de entorno

Copiar el archivo de ejemplo y editarlo:

copy .env.example .env

Editar .env con tus configuraciones:

# Base de datos MySQL
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=tu_contraseña
DB_NAME=escaner_red

# Servidor API
PORT=3000

# Configuración del escáner
SCAN_NETWORK=192.168.1.0/24
SCAN_TIMEOUT=2000
SCAN_CONCURRENCY=50

Uso

Opción 1: Ejecutar el escáner de red (CLI)

npm run scan

Este comando:

Escanea la red configurada en SCAN_NETWORK
Detecta hosts activos mediante ping
Obtiene Sistema Operativo (por TTL)
Identifica Fabricante del dispositivo (por MAC)
Detecta Hostname del equipo
Escanea puertos comunes en cada host
Valida conflictos de IP/MAC
Aplica regla de 10 minutos para puertos
Guarda toda la información en MySQL
Muestra los resultados en consola

Salida esperada:

============================================================
ESCANER DE RED
============================================================
Red a escanear: 192.168.1.0/24
Timeout: 2000ms
Concurrencia: 50
============================================================

Escaneando 254 direcciones IP...
Progreso: 254/254 IPs escaneadas (100%)...

Escaneo completado. 5 hosts activos encontrados.

──────────────────────────────────────────────────
IP: 192.168.1.10
🏷Hostname: DESKTOP-ABC123
MAC Address: 00-1A-2B-3C-4D-5E
Fabricante: Intel Corporate
Sistema Operativo: Windows
Tipo de dispositivo: PC
Fecha de escaneo: 2025-11-25T10:30:00.000Z

Puertos abiertos en 192.168.1.10:
   ├─ Puerto 80 (open)
   │  └─ Servicio: HTTP
   │     └─ Tiempo respuesta: 15ms
   ├─ Puerto 443 (open)
   │  └─ Servicio: HTTPS
   │     └─ Tiempo respuesta: 18ms

============================================================
RESUMEN DEL ESCANEO
============================================================
Hosts detectados:       5
Equipos guardados:      5
Equipos con conflicto: 0
Puertos registrados:    12
Puertos omitidos (10m): 3
============================================================

Opción 2: Ejecutar el servidor API

npm start

O para desarrollo con auto-reload:

npm run dev

El servidor estará disponible en: http://localhost:3000

API REST

Endpoints disponibles

1. GET / - Información de la API

curl http://localhost:3000/

2. GET /api/hosts - Obtener todos los equipos

curl http://localhost:3000/api/hosts

Respuesta:

{
  "success": true,
  "count": 3,
  "equipos": [
    {
      "id": 1,
      "hostname": "DESKTOP-ABC123",
      "direccion_ip": "192.168.1.10",
      "mac_address": "00-1A-2B-3C-4D-5E",
      "fabricante": "Intel Corporate",
      "sistema_operativo": "Windows",
      "tipo_dispositivo": "PC",
      "estado": "activo",
      "primera_deteccion": "2025-09-30T15:00:00.000Z",
      "ultima_deteccion": "2025-09-30T15:30:00.000Z",
      "puertos": [...]
    }
  ]
}

3. GET /api/hosts/:ip - Obtener equipo por IP

curl http://localhost:3000/api/hosts/192.168.1.10

4. GET /api/hosts/mac/:mac - Obtener equipo por MAC

curl http://localhost:3000/api/hosts/mac/00-1A-2B-3C-4D-5E

5. GET /api/hosts/stats/all - Obtener estadísticas

curl http://localhost:3000/api/hosts/stats/all

Respuesta:

{
  "success": true,
  "stats": {
    "total_equipos": 15,
    "equipos_activos": 12,
    "total_registros_puertos": 147,
    "registros_hoy": 45,
    "fabricantes_top": [...],
    "sistemas_operativos": [...]
  }
}

6. GET /api/hosts/conflictos/all - Ver conflictos de IP/MAC

curl http://localhost:3000/api/hosts/conflictos/all

7. GET /api/hosts/actividad/reciente - Actividad reciente

curl "http://localhost:3000/api/hosts/actividad/reciente?horas=24"

8. GET /api/hosts/puertos/top - Puertos más usados

curl "http://localhost:3000/api/hosts/puertos/top?limite=10"

9. POST /api/hosts/validar - Validar equipo antes de guardar

curl -X POST http://localhost:3000/api/hosts/validar \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "MI-PC",
    "direccion_ip": "192.168.1.100",
    "mac_address": "00-1A-2B-3C-4D-5E"
  }'

10. POST /api/scan - Iniciar escaneo manual

curl -X POST http://localhost:3000/api/scan \
  -H "Content-Type: application/json" \
  -d '{
    "network": "192.168.1.0/24",
    "timeout": 2000,
    "concurrency": 50
  }'

11. POST /api/scan/ip/:ip - Escanear una IP específica

curl -X POST http://localhost:3000/api/scan/ip/192.168.1.100

12. GET /api/scan/status - Estado del último escaneo

curl http://localhost:3000/api/scan/status

13. DELETE /api/scan/cleanup - Limpiar registros antiguos

curl -X DELETE "http://localhost:3000/api/scan/cleanup?dias=30"

🗄️ Base de Datos

Estructura de tablas

Tabla `fabricante`

Campo	Tipo	Descripción
id	INT	ID único (auto-increment)
codigo_oui	VARCHAR(8)	Primeros 3 bytes de MAC (OUI)
nombre	VARCHAR(255)	Nombre del fabricante
descripcion	TEXT	Descripción adicional

Tabla `protocolo`

Campo	Tipo	Descripción
id	INT	ID único (auto-increment)
nombre	VARCHAR(50)	Nombre del protocolo (TCP, UDP, etc.)
descripcion	VARCHAR(255)	Descripción del protocolo
puerto_por_defecto	INT	Puerto por defecto si aplica

Tabla `equipo`

Campo	Tipo	Descripción
id	INT	ID único (auto-increment)
hostname	VARCHAR(255)	Nombre del equipo
direccion_ip	VARCHAR(45)	Dirección IP
mac_address	VARCHAR(17)	Dirección MAC
fabricante_id	INT	FK a fabricante
sistema_operativo	VARCHAR(100)	SO detectado
version_so	VARCHAR(100)	Versión del SO
tipo_dispositivo	VARCHAR(50)	Tipo: PC, Router, etc.
estado	ENUM	activo/inactivo/desconocido
primera_deteccion	TIMESTAMP	Primera vez detectado
ultima_deteccion	TIMESTAMP	Última vez detectado

Tabla `protocolo_usado`

Campo	Tipo	Descripción
id	INT	ID único (auto-increment)
equipo_id	INT	FK a equipo
protocolo_id	INT	FK a protocolo
numero_puerto	INT	Número de puerto
nombre_servicio	VARCHAR(100)	Nombre del servicio
estado	ENUM	abierto/cerrado/filtrado
fecha_deteccion	TIMESTAMP	Fecha y hora de detección
tiempo_respuesta_ms	INT	Tiempo de respuesta
banner	TEXT	Banner del servicio

Puertos Escaneados

Por defecto se escanean estos puertos comunes:

Puerto	Servicio
21	FTP
22	SSH
23	Telnet
25	SMTP
53	DNS
80	HTTP
110	POP3
143	IMAP
443	HTTPS
445	SMB
3306	MySQL
3389	RDP
5432	PostgreSQL
8080	HTTP-Alt
8443	HTTPS-Alt

Puedes modificar la lista en src/utils/networkScanner.js

Estructura del Proyecto

Escaner red/
├── database.sql              # Script SQL con estructura completa
├── example.env              # Variables de entorno ejemplo
├── package.json             # Dependencias y scripts
├── README.md                # Esta documentación
└── src/
    ├── config/
    │   └── database.js      # Configuración MySQL
    ├── models/
    │   ├── equipoModel.js       # Modelo de equipos
    │   ├── fabricanteModel.js   # Modelo de fabricantes
    │   ├── protocoloModel.js    # Modelo de protocolos
    │   └── protocoloUsadoModel.js # Modelo de puertos usados
    ├── routes/
    │   ├── hostRoutes.js    # Rutas de equipos
    │   └── scanRoutes.js    # Rutas de escaneo
    ├── utils/
    │   └── networkScanner.js # Scanner de red con detección de SO/fabricante
    ├── scanner.js           # CLI de escaneo
    └── server.js            # Servidor Express

Scripts NPM

# Iniciar servidor en producción
npm start

# Iniciar servidor en modo desarrollo (con nodemon)
npm run dev

# Ejecutar escáner de red
npm run scan

📄 Licencia

Este proyecto es de código abierto y está disponible bajo la licencia MIT.

Autor REDUARDO

Desarrollado por Reduardo con ❤️ para escaneo y monitoreo de redes locales.

Name		Name	Last commit message	Last commit date
scripts		scripts
src		src
.gitignore		.gitignore
README.md		README.md
database.sql		database.sql
database_usuarios.sql		database_usuarios.sql
example.env		example.env
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation