Monitor ISP

Aplicación web en Go que ejecuta periódicamente MTR (My Traceroute) contra targets configurados para detectar cambios de upstream del ISP.

Características

• Detección automática de upstream: Ejecuta MTR periódicamente y detecta el primer hop con ASN válido para identificar el upstream de salida
• Comparación con upstreams conocidos: Compara el ASN detectado contra una lista de upstreams conocidos (configurables vía web UI)
• Detección de cambios: Compara cada resultado con el anterior y detecta cuando el upstream cambia
• Interfaz web responsive: CRUD completo de targets y upstreams conocidos, visualización de resultados y cambios, eliminación de resultados
• Ejecución manual de MTR: Botón en la web para ejecutar MTR inmediato sobre un target (se ejecuta en background)
• Scheduler configurable: Intervalo configurable para ejecución automática de MTR
• Configuración por-target: Count e intervalo de MTR personalizables por cada target
• Protección CSRF: Middleware de protección CSRF en todos los formularios
• Validación de hosts: Rechaza IPs privadas/loopback como targets
• Retención de datos: Purga automática de resultados mayores a 30 días (configurable)
• Ejecución paralela: Los MTRs se ejecutan en paralelo cuando hay múltiples targets
• SSE (Server-Sent Events): Notificaciones en tiempo real cuando se completa un MTR o se detecta un cambio de upstream
• Flash messages: Retroalimentación visual al crear/editar/eliminar recursos
• Dashboard mejorado: Estado del scheduler, estadísticas por target, indicadores visuales de estado
• Healthcheck: Endpoint /health para monitoreo externo
• Configuración por variables de entorno: Soporte para Docker y despliegue con contenedores
• Logging a archivo: Opción de loggear a archivo además de stdout

Requisitos

• Go 1.26+
• mtr instalado en el sistema (paquete mtr-tiny o mtr)
• SQLite3 (manejado por el driver, no requiere instalación separada)

Instalación

# Clonar el repositorio
git clone <repo-url>
cd monitor_isp

# Compilar
make build

# Inicializar base de datos
make migrate-up

# Ejecutar
make run

Docker

Docker Compose - Producción (recomendado)

Usa la imagen pre-construida del registro de Forgejo:

# docker-compose.yml
services:
  app:
    image: git.jesusmarin.dev/angel/monitor_isp:latest
    container_name: monitor_isp
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - app-data:/app/data
    environment:
      MONITOR_SERVER_HOST: "0.0.0.0"
      MONITOR_SERVER_PORT: "8080"
      MONITOR_DB_PATH: "/app/data/monitor.db"
      MONITOR_MTR_INTERVAL: "30m"
      MONITOR_MTR_COUNT: "10"
      MONITOR_LOG_LEVEL: "info"

volumes:
  app-data:

# Levantar el servicio
docker compose up -d

# Ver logs
docker compose logs -f

# Detener el servicio
docker compose down

La configuración se realiza mediante variables de entorno (MONITOR_*). No se requiere montar un archivo de configuración.

Docker Compose - Desarrollo

Para construir la imagen localmente durante el desarrollo:

# Construir y levantar
make docker-up

# Ver logs
make docker-logs

# Detener
make docker-down

Docker manual

# Construir imagen
make docker-build

# Ejecutar con docker
docker run -d \
  -p 8080:8080 \
  -v monitor-data:/app/data \
  -e MONITOR_MTR_INTERVAL=1h \
  -e MONITOR_LOG_LEVEL=info \
  monitor_isp

La imagen Docker ejecuta automáticamente las migraciones de base de datos al iniciar mediante un entrypoint.sh que invoca migrate antes de arrancar la aplicación.

La imagen se publica en el registro de Forgejo (git.jesusmarin.dev/angel/monitor_isp) mediante Forgejo Actions: en cada push a master (tags latest + sha-<commit>) y en cada tag v* (tag de versión + latest).

Variables de entorno soportadas:

Variable	Descripción
MONITOR_SERVER_HOST	Host del servidor (default: 0.0.0.0)
MONITOR_SERVER_PORT	Puerto del servidor (default: 8080)
MONITOR_DB_PATH	Ruta a la base de datos SQLite (default: ./data/monitor.db)
MONITOR_MTR_INTERVAL	Intervalo entre ejecuciones MTR (default: 30m)
MONITOR_MTR_COUNT	Número de paquetes por ejecución MTR (default: 10)
MONITOR_MTR_TIMEOUT	Timeout por ejecución MTR (default: 60s)
MONITOR_LOG_LEVEL	Nivel de log (default: info)
MONITOR_LOG_FILE	Ruta a archivo de log (opcional)
MONITOR_RETENTION_DAYS	Días de retención de datos (default: 30)

Configuración

1. Copiar el archivo de configuración de ejemplo:

cp configs/config.example.yaml configs/config.yaml

2. Editar configs/config.yaml con los valores deseados:

app:
  name: "monitor-isp"
  environment: "production"

server:
  host: "0.0.0.0"
  port: 8080
  read_timeout: 15s
  write_timeout: 30s
  idle_timeout: 60s

database:
  path: "./data/monitor.db"

mtr:
  interval: 30m
  count: 10
  timeout: 60s

logging:
  level: "info"
  file: ""

retention:
  days: 30

Migraciones de Base de Datos

Las migraciones se ejecutan manualmente (no por la aplicación):

# Aplicar migraciones pendientes (crea data/ si no existe)
make migrate-up

# Revertir última migración
make migrate-down

# Crear nueva migración
make migrate-create

Nota: Se requiere migrate CLI instalado. Ver golang-migrate

Uso

Iniciar la aplicación

# Con configuración por defecto
make run

# Con archivo de configuración personalizado
./bin/monitor_isp -config /path/to/config.yaml

Interfaz Web

Acceder a http://localhost:8080:

• Dashboard: Resumen del estado actual, scheduler, últimos upstreams detectados y cambios recientes
• Targets: CRUD de targets (IPs/dominios a monitorear), ejecución manual de MTR, configuración por-target
• Upstreams Conocidos: CRUD de upstreams conocidos con nombre, ASN e IP típica (todos obligatorios)
• Resultados: Historial de resultados MTR con detalle de hops, opción de eliminar resultados incorrectos
• Cambios: Historial de cambios de upstream detectados

Endpoint de Salud

GET /health → {"status":"ok"}

Eventos en tiempo real

GET /events → SSE stream con eventos de cambios de upstream y resultados MTR

Cómo Funciona la Detección de Upstream

1. Se ejecuta mtr -zrn -c <count> <target> via os/exec
2. Se parsea cada línea del output para extraer hop_number, ASN, host y métricas
3. Se detecta el upstream: primer hop con ASN válido (no AS???)
4. Se identifica si es un upstream conocido: se compara el ASN contra la tabla de upstreams conocidos
5. Se compara con el resultado anterior del mismo target
6. Si el upstream cambió → se registra el cambio en la base de datos y se publica un evento SSE

Nota: Solo se permiten IPs públicas como targets. Las IPs privadas (10.x, 172.16-31.x, 192.168.x, 127.x, etc.) son rechazadas.

Nota: La ejecución manual de MTR desde la interfaz web se realiza en segundo plano (goroutine). Una notificación SSE aparece cuando el resultado está disponible.

Arquitectura

Monolito modular siguiendo Standard Go Project Layout:

cmd/server/          - Punto de entrada
internal/
  platform/          - Cross-cutting concerns (config, db, logger, etc.)
  app/
    bootstrap/       - Composición de dependencias, scheduler, purger
    shared/          - Bus de eventos interno
  modules/
    monitor/         - MTR, detección de upstream, detección de cambios
      domain/        - Entidades, interfaces de repositorio, servicios, validadores
      application/   - Command/Query handlers, DTOs
      adapters/
        http/        - Handlers HTTP, templates, SSE broker
        persistence/ - Repositorios SQLite
        mtr/         - Ejecutor y parser de MTR
migrations/          - SQL migrations
web/
  templates/         - Plantillas HTML
  static/css/        - Estilos CSS
configs/             - Archivos de configuración

Comandos del Makefile

Comando	Descripción
make build	Compilar binario
make run	Compilar y ejecutar
make test	Ejecutar tests
make lint	Ejecutar go vet
make fmt	Formatear código
make race-test	Tests con race detector
make migrate-up	Aplicar migraciones (crea data/ si no existe)
make migrate-down	Revertir última migración
make migrate-create	Crear nueva migración
make docker-build	Construir imagen Docker
make docker-up	Levantar contenedor con docker compose
make docker-down	Detener contenedor
make docker-logs	Ver logs del contenedor
make clean	Limpiar binarios y datos

Dependencias

Librería	Propósito
modernc.org/sqlite	Driver SQLite puro Go (sin CGO)
github.com/golang-migrate/migrate	Migraciones de base de datos
gopkg.in/yaml.v3	Parseo de configuración YAML
github.com/justinas/nosurf	Protección CSRF
github.com/justinas/alice	Middleware chaining
html/template, net/http, os/exec, log/slog	Stdlib

Licencia

Ver archivo LICENSE.