← Volver a proyectos
Proyecto personal
Port Scanner — escáner TCP asíncrono y laboratorio de detección
Escáner de puertos asyncio sin dependencias, seguro por defecto, que explica el riesgo de cada servicio abierto — y la parte Blue Team: cómo detectar ese mismo escaneo con Wireshark, Suricata y Sigma
Contexto
Reconstruí este proyecto desde cero con mentalidad defensiva. Un escáner de puertos suele presentarse desde el lado del atacante; yo quería lo contrario: una herramienta segura en una red doméstica o empresarial, que explique por qué importa un puerto abierto y qué hacer al respecto, y que luego enseñe cómo un SOC detecta el escaneo que acaba de realizar (MITRE ATT&CK T1046 — Network Service Discovery).
Lo que construí
- Un escáner TCP «connect» asíncrono (asyncio, solo biblioteca estándar): estados abierto / cerrado / filtrado, latencia, concurrencia y memoria acotadas
- El análisis de objetivos y puertos (IP, CIDR, nombres de host; 22, 20-25, top100, all) con validación estricta
- Unas cincuenta fichas de servicios: nivel de riesgo de «info» a «crítico» y recomendación defensiva para cada puerto abierto
- Lectura de banners opcional y pasiva, con escape de todo carácter no imprimible
- Salidas en texto, JSON y CSV, códigos de salida estables y --fail-on high para la integración continua
- Una interfaz web local bilingüe (port-scanner-web) que usa el mismo motor
Decisiones de seguridad
- Seguro por defecto: solo redes privadas (RFC 1918, IPv6 ULA) y loopback; se comprueban las IPv6 mapeadas, cada respuesta DNS y las IP abreviadas ambiguas (127.1, 0x7f.1)
- Límites comprobados antes de cualquier envío: 1024 direcciones, 262 144 intentos, 500 conexiones simultáneas, 30 s de espera
- Banners tratados como datos hostiles: secuencias de escape de terminal y caracteres bidireccionales invisibles (Trojan Source) neutralizados
- Inyección de fórmulas CSV evitada (OWASP); ningún informe existente se sobrescribe sin --force
- Servidor web local protegido como un servicio expuesto: solo loopback, token aleatorio de 256 bits en el fragmento de la URL, control de Host contra DNS rebinding, control de Origin contra CSRF, CSP estricta, renderizado solo con textContent
- Repositorio reforzado: rama main protegida, detección de secretos con bloqueo en el push, Dependabot, Ruff con reglas Bandit, notificación privada de vulnerabilidades
Detección (Blue Team)
- Capturas de laboratorio de un escaneo real, de tráfico normal y de un cliente legítimo muy activo
- Guía paso a paso de Wireshark y tshark: los filtros que revelan un escaneo
- Dos reglas Suricata (ráfaga de SYN, ráfaga de RST) y una correlación Sigma value_count (puertos distintos por origen)
- Un job de CI reproduce las capturas en Suricata y verifica las alertas esperadas — incluida la ausencia de alertas en tráfico normal y un falso positivo documentado
Calidad de ingeniería
250+
Pruebas automatizadas
sockets reales en loopback, red simulada en el resto
6
Jobs de CI
Windows + Linux, Python 3.11/3.14, Ruff, Suricata + Sigma
0
Dependencias de ejecución
v1.0.0 → v1.1.0
Versiones
Cómo funciona
- 1ValidarObjetivos y puertos se analizan y se contrastan con la protección de redes privadas y los límites antes de enviar nada.
- 2EscanearUn grupo fijo de trabajadores asyncio abre y cierra de inmediato una conexión TCP por cada par (dirección, puerto).
- 3ExplicarCada puerto abierto recibe su servicio probable, un nivel de riesgo y una recomendación; los banners se leen y se limpian bajo demanda.
- 4DetectarEl mismo escaneo se captura y lo detectan las reglas Suricata y Sigma, verificadas automáticamente en la CI.
Capturas de pantalla