NSGateway

Qué es NSGateway

nsgateway es el concentrador de conexiones de Nacarsoft: un único binario que reúne terminal web, SSH, proxy inverso, sites públicos por Host y portales públicos. Sustituye el acceso directo por SSH, los bastiones y los túneles: el usuario entra por HTTPS con su identidad y su rol, el administrador decide qué aplicaciones y destinos se publican, y cada sesión queda registrada.

• Cuatro formas de acceso: aplicación de terminal (comando del servidor), aplicación SSH (host/puerto), aplicación proxy (URL interna) y portal público o privado (catálogo con login opcional y límites).
• Sin clientes en el puesto: ni cliente SSH, ni claves, ni túneles. Solo HTTPS y WebSocket.
• Identidad central: JWT, usuarios y grupos, RBAC por aplicación, cupos de sesiones y LDAP/Active Directory opcional.
• Consolas internas: se publican por proxy inverso con allowlist, bloqueo de IP privadas/metadatos y reescritura de enlaces.
• Portales públicos y privados: para proveedores, guardia, soporte externo o usuarios internos; los públicos son anónimos y los privados exigen login, ambos con límites y auditoría.
• Sites públicos por Host (estilo Caddy): sitios independientes en SQLite, enrutados por Host y path, con rutas proxy o redirect, strip_prefix, reglas de cabeceras, gzip/zstd, logs JSONL por sitio y vista previa del Caddyfile en solo lectura. El TLS termina delante; los sites son públicos por diseño.
• Sesiones y auditoría: app, usuario, PID, portal de origen, IP, país, navegador, hijos, CPU/memoria, timeout y motivo de cierre; búsqueda y filtros por usuario, app y portal, y orden por cualquier columna; la reconciliación al arrancar y periódica cierra filas muertas y mata grupos de procesos huérfanos verificados sin tocar PIDs reciclados.
• Experiencia web: plantillas con cabecera/paneles/barra de estado, horarios de disponibilidad, teclas PF de Natural, temas e idiomas.
• Un solo binario con SQLite embebido; API REST para automatizar.

Los comandos, aplicaciones, hosts y usuarios de los ejemplos son ficticios.

Casos de uso

1. Concentrar el acceso a servidores y SSH

Publicar una shell y un servidor SSH sin instalar clientes ni repartir claves.

nsgateway init /tmp/nsgateway-demo
# → imprime la contraseña aleatoria de admin; guárdala
nsgateway start --config /tmp/nsgateway-demo
nsgateway status --config /tmp/nsgateway-demo
# → NSGateway v26.1 ... Listening: http://0.0.0.0:11030

Flujo web: Administración → Aplicaciones → crear una app de tipo terminal (shell, comando /bin/bash) y otra de tipo SSH (host, puerto 22, autenticación password o system) → asignarlas a los grupos → Panel → Abrir.

2. Publicar consolas internas por proxy

Exponer una aplicación web interna sin abrir su URL a la red de usuarios.

Flujo web: Administración → Aplicaciones → tipo Proxy URL (targetUrl https://intranet.ejemplo.local:8443/app, WebSocket activado si la app lo usa, reescritura de enlaces) → asignar a grupos. Solo el administrador define la URL; el usuario la abre con su sesión, su RBAC y su auditoría.

3. Publicar un sitio completo por Host (estilo Caddy)

Da a erp.ejemplo.local sus propias rutas sin escribir un Caddyfile.

Flujo web: Administración → Sites → crear el sitio (host, compresión y fichero de log) → añadir /api/* como ruta proxy a la aplicación erp-api con strip_prefix, y /old como redirect a /new con estado 301. El TLS termina delante (nginx, Caddy o un balanceador); NSGateway recibe HTTP, enruta por Host y path, comprime, reescribe cabeceras, escribe logs de acceso JSONL en logs/sites/ y muestra el Caddyfile equivalente en solo lectura. Los sites son públicos: el WAF, los rate limits, la blocklist de IP y la protección SSRF siguen aplicando, pero no el login/RBAC.

4. Abrir un portal público para proveedores o guardia

Dar acceso anónimo y acotado a un catálogo de aplicaciones.

Flujo web: Administración → Portales → crear (slug, nombre, descripción, plantilla y sessionTimeout) → añadir aplicaciones públicas → compartir https://gateway.ejemplo.local/pub/<slug>. El portal no pide login, aplica límites por IP y tiempo, y las sesiones se marcan con la insignia public.

5. Dar a un equipo acceso limitado con cupo

El grupo operadores puede usar consola-prod con un máximo de 2 sesiones simultáneas por usuario.

Flujo web: Usuarios → crear usuario → asignarle el grupo → Grupos → asignar la aplicación con su max por usuario → el usuario solo ve sus aplicaciones; al superar el cupo recibe el aviso y no se abre una sesión nueva.

6. Supervisar y terminar sesiones

Ver quién ejecuta qué, desde dónde y con qué consume.

Flujo web: Sesiones (app, usuario, PID, inicio, duración, timeout, CPU, memoria, IP, país, navegador, hijos; filtros por activas/cerradas/todas, origen, tipo, usuario, app, portal e IP; orden por columnas) → terminar una sesión pidiendo motivo, o cierre masivo por selección/IP/portal/app. Con rol admin se añaden las conexiones HTTP/HTTPS y la gráfica RX/TX.

7. Dar aspecto web y horario a una aplicación

Convertir una aplicación de terminal en una consola con cabecera corporativa, menú lateral, barra de estado y teclas PF.

Flujo web: Administración → Plantillas → asignar a la aplicación; Horarios → plantilla de disponibilidad (mañana, tarde, noche, fin de semana o laboral); la app aparece Cerrada fuera de su franja y el servidor rechaza la apertura. Los administradores también quedan sujetos salvo excepción explícita.

8. Integrar LDAP/AD y altas por invitación

Usar el directorio corporativo sin perder los usuarios locales.

Flujo web: Configuración → Autenticación → LDAP (URLs, base DN, bind, filtros y atributos) → probar conexión. Para altas: Autorizaciones → activar alta automática, grupo por defecto, modo de activación y lista de correos autorizados (o importar CSV) → enviar invitación individual o masiva.

9. Automatizar y auditar con la API

Consultar aplicaciones y sesiones desde un script con la cookie de sesión.

# Tras iniciar sesión en la web, reutilizar la cookie de sesión
curl -b cookie.txt http://localhost:11030/api/apps
curl -b cookie.txt "http://localhost:11030/api/sessions?status=active"

Flujo web: Auditoría → filtrar por hora, usuario, acción, detalle, IP y país; las altas, cambios de grupo, accesos y terminaciones quedan registradas.

Interfaz

Idiomas: ES y EN. Temas: oscuro, claro y alto contraste, con ajuste de fuente.

Referencia

Requisitos

Comandos CLI

El alias El binario y la documentación actuales son nsgateway.

Configuración principal (config.yaml)

NSGateway se niega a arrancar con un jwtSecret vacío o de ejemplo. Use openssl rand -hex 32.

La licencia se busca en $NS_HOME/licenses/nsgateway.key (identificador de licencia de NSGateway). NS_HOME por defecto es /opt/ns.

Tipos de aplicación

Notas:

• SSH: con autenticación password se usa un cliente SSH integrado en el binario (sin sshpass); con system se usa OpenSSH con sus claves y agente. El visitante introduce usuario y contraseña en el formulario; la contraseña viaja por el WebSocket cifrado, se usa solo en memoria y no se guarda. El cliente se ejecuta con el usuario del servicio (no usa run_as ni sudo); la primera conexión guarda la clave del servidor en known_hosts (accept-new). El campo sshCommand permite ejecutar un comando remoto tras el login (por ejemplo cd /opt/app && ./start.sh); si está vacío se abre la shell.
• Proxy: el usuario nunca escribe la URL; solo el administrador la define. allowedHosts restringe destinos y blockPrivateIPs / blockMetadataIP añaden protección SSRF.
• Cupos: el maxUserSessions por grupo y aplicación manda sobre el valor por defecto de la aplicación; el grupo es la autoridad para sus miembros y un 0 explícito significa sin límite. /api/apps/usage informa de max y limitSource (group o app). Al superar el cupo no se abre una sesión nueva.

Plano de datos y operación del proxy inverso

El proxy viene ajustado por defecto: pool keep-alive de 200 sockets por backend, gzip para HTML/CSS/JS/JSON/SVG, circuit breaker por app (5 fallos, enfriamiento de 15 s), CA privada / mTLS / override de SNI para backends HTTPS, tope de subida y timeout de respuesta. Se editan en Administración → Configuración → Proxy.

/metrics y /debug/pprof solo responden desde loopback o las direcciones de server.trustedProxies; nunca son públicos. SIGTERM hace un apagado ordenado: deja de aceptar conexiones, drena las peticiones en curso hasta 25 segundos y cierra SQLite después (permite TimeoutStopSec=40 y LimitNOFILE=1048576 en el gestor de servicios). SQLite va en WAL con synchronous=NORMAL, pool de 25 conexiones y busy timeout de 10 s; los heartbeats del proxy se agrupan en una escritura por sesión cada 30 s.

Sites públicos por Host (estilo Caddy)

Además de las apps proxy integradas, NSGateway publica sitios independientes por Host, con semántica cercana a bloques de Caddyfile pero guardada en SQLite. El TLS termina delante (nginx, Caddy, un balanceador): NSGateway escucha HTTP y enruta por Host y path. Administración → Sites.

Campos del sitio: name y description (etiquetas), host (exacto o *.ejemplo.local; vacío = solo fallback sin Host), encode (gzip, zstd, gzip,zstd o vacío), log_file, enabled.

Ejemplo equivalente a un bloque de Caddy:

erp.ejemplo.local {
    encode gzip zstd
    log { output file erp.log }
    handle_path /api/* { reverse_proxy app:erp-api }
    redir /old /new permanent
}

En la práctica: crea el site erp.ejemplo.local, una ruta /api/* proxy a la app erp-api con strip_prefix, y una ruta /old de tipo redirect a /new con estado 301. La pestaña Caddyfile muestra el equivalente en solo lectura.

Orden de resolución: site de Host exacto → site de Host comodín → rutas sin Host (solo desde NoRoute, para que /api, /login, /static y las páginas de administración sigan siendo de NSGateway) → rutas normales de NSGateway. Si un Host pertenece a un site pero ninguna ruta coincide, se devuelve el 404 de ese site. No crees un site para el Host de administración de NSGateway.

Logs: logs/sites/<fichero> en JSON Lines (ts, site, route, app, remote_ip, host, method, uri, proto, status, bytes, duration_ms, user_agent, referer, upstream, error) con la rotación habitual. Se rechazan rutas absolutas y ...

Seguridad: los sites son públicos y saltan login/RBAC; la UI lo avisa. El WAF, los rate limits, la blocklist de IP, la allowlist de Host y la protección SSRF siguen aplicando porque el enrutado va después del security guard. Si server.allowedHosts está definido, incluye los Hosts de los sites públicos. Una app deshabilitada devuelve 503; una app usada por un site no se puede borrar (409). Esta versión no tiene TLS/ACME propio, ficheros estáticos, basic_auth ni balanceo.

API: GET/POST /api/admin/sites, GET/PUT/DELETE /api/admin/sites/:id (las rutas van anidadas en el payload del site).

Portales públicos y privados

Un portal publica un catálogo de aplicaciones para proveedores, guardia, soporte externo o usuarios internos:

• Se crea en Administración → Portales con slug, nombre, descripción, plantilla, visibilidad y sessionTimeout.
• Público: la URL /pub/<slug> no requiere cuenta y muestra las aplicaciones activas del portal.
• Privado: exige autenticación; el visitante anónimo va al login y vuelve al portal. Solo se muestran las aplicaciones que el usuario puede abrir según sus grupos.
• Solo los portales públicos conceden acceso anónimo: una aplicación que únicamente está en un portal privado no responde en /public/<appId>.
• Cada tarjeta muestra los límites; en modo anónimo el cupo por usuario se aplica por dirección IP.
• Las sesiones anónimas quedan marcadas como public y se auditan igual que las de usuario.

Plantillas, horarios y teclas PF

• Plantillas: cabecera, contenedor izquierdo/derecho y barra de estado con HTML/CSS; el CSS se aplica aislado en un shadow root. Marcadores como {{app.name}}, {{user.name}}, {{company.name}}, {{company.logo}}, {{pf.buttons}} y valores vivos ({{now.time}}, {{session.uptime}}, {{session.remaining}}). Se pueden exportar e importar como JSON (con vista previa y modo omitir/sobrescribir). En un portal, los valores de sesión se actualizan según la pestaña SSH o de terminal seleccionada.
• Horarios: plantillas de mañana, tarde, noche, fin de semana y horario laboral; zona horaria propia, varias ventanas y cruce de medianoche. El servidor es la autoridad: fuera de la franja la app aparece Cerrada y no se puede abrir.
• Teclas PF: la aplicación declara PF1..PF12 y la plantilla dibuja los botones; al pulsarlos se envía la secuencia a la sesión (códigos Natural o xterm según la app).
• Branding: nombre y logo corporativo en las plantillas y, opcionalmente, en la pantalla de login.

Sesiones y auditoría

Cada sesión registra aplicación, usuario, PID, inicio, duración, timeout, CPU, memoria, IP, país, navegador e hijos. El listado se actualiza en vivo por WebSocket y permite:

• Filtrar por activas/cerradas/todas, origen (público/usuario), tipo (terminal/ssh/proxy), portal, aplicación o IP.
• Terminar una sesión (con motivo) o hacer cierre masivo por selección, IP, portal o aplicación.
• Ajustar el timeout de una sesión concreta.
• Ver, con rol admin, conexiones HTTP/HTTPS y tráfico RX/TX.
• Las sesiones de proxy muestran una capa de «Sesión finalizada»; las de terminal/SSH muestran el motivo.
• Reconciliación: al arrancar y cada 15 s NSGateway cierra las filas cuyo proceso ya no existe, ignora PIDs reciclados (nunca señaliza un proceso ajeno) y mata los grupos de procesos huérfanos verificados que dejó un fallo; las filas proxy siguen heartbeats y al sweeper del proxy. Estas acciones se auditan (session_reconcile_*).

Seguridad perimetral y notificaciones

NSGateway puede exponerse directamente a Internet con:

• WAF en modo monitor o block, rate limiting global y por IP, concurrencia y límites de WebSocket.
• Blocklist persistente de IPv4/IPv6/CIDR, manual y automática, con allowlist.
• Validación de Host, límites de cabeceras, timeouts y conexiones.
• Eventos y métricas en memoria y logs/security/*.jsonl; SQLite solo guarda configuración, RBAC, sesiones y la blocklist.
• Página Administración → Seguridad (/security) con eventos en vivo, incidentes, IPs bloqueadas y configuración de avisos por email.

security:
  waf:
    enabled: true
    mode: monitor          # monitor | block
  ipBlock:
    enabled: true
    auto: true
    threshold: 30
    allowlist: []
  limits:
    globalPerSecond: 20000
    perIPPerSecond: 300
    perIPBurst: 600
    perIPConcurrent: 2000
    proxyPerIPPerSecond: 600
    userPerSecond: 60
    userBurst: 240
    userConcurrent: 120
  notifications:
    enabled: false
    recipients: []
    minSeverity: high
    cooldownMinutes: 15
    maxPerHour: 30
    digestMinutes: 0

Las notificaciones incluyen umbral de severidad, categorías, cooldown, límite por hora, digest y horas de silencio. Se envía un correo por incidente agrupado, no uno por petición. Las peticiones autenticadas saltan el bucket por IP y usan el presupuesto user*, así una NAT corporativa o VPN con cientos de usuarios no se limita como si fuera un único infractor; las inundaciones anónimas siguen acotadas por dirección.

API

# Con la cookie de sesión de la web
curl -b cookie.txt http://localhost:11030/api/apps
curl -b cookie.txt "http://localhost:11030/api/sessions?status=active"

# Comprobación previa de una app de terminal
curl -b cookie.txt http://localhost:11030/api/terminal/shell/check

Seguridad y licencia

• Login con JWT HS256 en cookie HttpOnly y caducidad configurable.
• Contraseñas con Argon2id (los hashes legacy bcrypt se actualizan al siguiente login), política de longitud, caducidad, aviso e historial.
• LDAP/Active Directory opcional, conviviendo con usuarios locales.
• Protección SSRF en el proxy: allowlist, bloqueo de IP privadas y metadatos cloud, límite de cuerpo y timeout.
• Los sites públicos por Host saltan login/RBAC por diseño; el WAF, los rate limits, la blocklist, la allowlist de Host y la protección SSRF se ejecutan antes de sus rutas.
• Auditoría de accesos, altas, cambios de grupo, terminaciones, cambios de site y acciones administrativas.
• Licencia firmada por máquina en $NS_HOME/licenses/nsgateway.key. Sin licencia válida el servicio no arranca; license muestra el fingerprint para solicitarla.

Ejemplos comentados

# 1. Entorno nuevo y arranque
nsgateway init /opt/nsgateway
# guardar la contraseña de admin que imprime init
nsgateway start --config /opt/nsgateway
nsgateway status --config /opt/nsgateway

# 2. Reinicio tras cambiar config.yaml
nsgateway restart --config /opt/nsgateway

# 3. Licencia y versión
nsgateway license --config /opt/nsgateway
nsgateway version

# 4. Primer plano para systemd
nsgateway run --config /opt/nsgateway

Proxy inverso con nginx (WebSocket incluido):

server {
    listen 443 ssl;
    server_name gateway.ejemplo.local;

    ssl_certificate     /etc/pki/tls/certs/gateway.crt;
    ssl_certificate_key /etc/pki/tls/private/gateway.key;

    location / {
        proxy_pass         http://127.0.0.1:11030;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection "upgrade";
        proxy_set_header   Host $host;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }
}

Preguntas frecuentes

¿Qué diferencia hay entre NSGateway y un terminal web? NSGateway es el concentrador: además del terminal web, publica aplicaciones SSH, aplicaciones internas por proxy y portales públicos, todo con la misma identidad, RBAC y auditoría.

¿Sustituye a SSH? Sí para el usuario: no instala cliente ni gestiona claves. También puede publicar aplicaciones SSH contra servidores existentes; el cliente OpenSSH se ejecuta en el servidor de NSGateway.

¿Hay que abrir el puerto 22? No para el acceso del usuario. Solo se necesita HTTPS (y WebSocket) en 11030; si se publican apps SSH, NSGateway inicia la conexión saliente al host/puerto indicado.

¿Cuál es la contraseña inicial de admin? La genera init y la imprime una sola vez; no hay contraseña fija. Cámbiela en el primer acceso.

¿Cómo funciona un portal público? Es un catálogo anónimo en /pub/<slug>: el administrador elige las apps, la plantilla y el tiempo de sesión; se aplican límites por IP y todo queda auditado.

¿La sesión sigue si cierro el navegador? Sí. El proceso vive en el servidor; al volver, la pestaña se reconecta a la misma sesión con su PID.

¿Se puede integrar con Active Directory? Sí: LDAP/AD es opcional y convive con los usuarios locales. El usuario se mapea a su cuenta Linux para las apps que lo necesiten.

¿Puedo publicar varios sites en Hosts distintos? Sí. Sites guarda bloques estilo Caddy en SQLite: Hosts exactos o comodín, rutas por path a apps proxy o redirects, compresión, cabeceras y logs de acceso JSONL. El TLS termina delante; los sites son públicos, así que WAF, rate-limit, blocklist y SSRF siguen aplicando, pero no el login/RBAC.

¿Sustituye a Caddy/nginx? Para enrutar apps internas por Host/path, sí. Esta versión no termina TLS para los sites (usa nginx/Caddy/un balanceador delante), no sirve ficheros estáticos, no hace basic_auth ni balanceo.

¿Dónde va la licencia? En $NS_HOME/licenses/nsgateway.key; si NS_HOME no está definido, en /opt/ns/licenses/nsgateway.key. El identificador de licencia es nsgateway.

¿Qué idiomas y temas hay? ES y EN; temas oscuro, claro y alto contraste, con tamaño de fuente ajustable.