VeilGate

VeilGate es un proxy de engaño de código abierto para equipos que quieren aumentar el coste del escaneo de seguridad automatizado sin poner reglas de bloqueo frágiles delante de los usuarios reales.

Se sitúa delante de una aplicación web, puntúa cada solicitud y elige uno de tres resultados:

• Real: reenviar el tráfico limpio a la aplicación upstream.
• Challenge: pedir a clientes sospechosos pero ambiguos que resuelvan una prueba de trabajo del navegador.
• Tarpit: desviar el tráfico de agentes de alta confianza hacia una aplicación falsa determinista.

El objetivo no es una invulnerabilidad mágica. El objetivo es una mejor relación coste-beneficio: mantener a los humanos y a la automatización normal en movimiento, mientras se hace que los escáneres asistidos por IA gasten tiempo, tokens y atención en callejones sin salida creíbles.

Qué hace

• Proxy inverso con modos observe, challenge, tarpit y auto controlado por umbrales.
• Señales de detección para agentes de usuario sospechosos, cabeceras de navegador escasas, rutas honeypot, regularidad temporal, rutas de escáner, marcadores SQLi/XSS/OOB, rotación de IP/UA, comportamiento de cookies, forma del grafo de solicitudes, huellas TLS JA3/JA4, huellas de HTTP/2, reproducción canary y puntuación ML en línea.
• Desafío de prueba de trabajo del navegador con transporte tanto por cookie como por cabecera X-Veilgate-Token, para que las SPA de origen cruzado puedan resolver y reincorporar el token en llamadas API posteriores. La respuesta de desafío 401 tiene en cuenta a las SPA: devuelve HTML para las navegaciones de nivel superior y JSON (con los metadatos PoW para resolver en línea) para los contextos fetch / XHR.
• Cadena de verificadores HMAC emitida por el operador para clientes servidor a servidor que no pueden resolver el PoW (ver docs/how-to/server-to-server-hmac.md).
• Respuestas de aplicación en sombra con perfiles falsos estables por cliente.
• Inyección de prompts y de payloads señuelo para las respuestas tarpit.
• Persistencia SQLite para eventos, resúmenes de características, registros de auditoría y canaries.
• Métricas Prometheus y un panel ligero en el listener de métricas.
• Archivos de reglas YAML recargables en caliente, alimentados por el repositorio comunitario independiente veilgate-rules.

Inicio rápido

Opción 1 — Script de instalación (recomendado)

Descarga el binario, instala un servicio systemd, instala las reglas comunitarias y escribe una configuración inicial en modo observe.

# One-liner
curl -sSL https://veilgate.dev/install.sh | sudo bash -s -- --upstream http://localhost:3000

# Or download first, then run
curl -sSL https://veilgate.dev/install.sh -o install.sh
sudo ./install.sh --upstream http://localhost:3000

Opciones:

La configuración incluida usa rules_dir: "~/.veilgate/rules". Bajo systemd, VeilGate se ejecuta como el usuario veilgate, cuyo directorio personal es /var/lib/veilgate, por lo que esto se resuelve a /var/lib/veilgate/.veilgate/rules.

Si se omite --secret en una instalación nueva, el instalador lo solicita en terminales interactivas y, en caso contrario, genera un secreto aleatorio. Si el usuario del servicio no existe, el instalador pregunta antes de crearlo en terminales interactivas y, en instalaciones no interactivas, lo crea por defecto.

Después de la instalación:

systemctl status veilgate
journalctl -u veilgate -f

Opción 2 — Docker

docker run -d --name veilgate \
  --network host \
  -v /etc/veilgate/veilgate.yaml:/etc/veilgate/veilgate.yaml:ro \
  -v ~/.veilgate/rules:/home/nonroot/.veilgate/rules \
  -e VEILGATE_SECRET=$(openssl rand -hex 32) \
  ghcr.io/c0oki3s/veilgate:latest -config /etc/veilgate/veilgate.yaml

Opción 3 — Compilar desde el código fuente

Requisito previo: Go 1.25.10 o superior.

git clone https://github.com/C0oki3s/veilgate.git
cd veilgate
make build
./veilgate -config configs/veilgate.yaml

Por defecto, VeilGate escucha en :8080, hace de proxy hacia http://localhost:3000 y expone métricas en :9090.

La configuración por defecto arranca en modo observe: establece una línea base del tráfico normal antes de habilitar challenge o tarpit.

Modos de funcionamiento

Despliegue recomendado:

1. Ejecuta observe durante al menos varios días.
2. Revisa las métricas y las muestras de eventos para detectar falsos positivos.
3. Habilita challenge para el tráfico ambiguo.
4. Habilita tarpit cuando tus umbrales se ajusten a tu entorno.

Configuración

Empieza con configs/veilgate.yaml:

listen: ":8080"
upstream: "http://localhost:3000"
mode: "observe"
rules_dir: "~/.veilgate/rules"

detector:
  score_challenge_threshold: 40
  score_tarpit_threshold: 70
  trusted_ips: []
  trusted_proxies: []

metrics:
  listen: ":9090"

Referencia completa: Referencia de configuración.

Reglas

VeilGate no incluye ninguna regla integrada. El binario lee rules_dir al arrancar y recarga los cambios en caliente; si el directorio está vacío, arranca sin señales de detección. Las reglas provienen de un único lugar:

• veilgate-rules — el paquete de reglas mantenido por la comunidad. El script install.sh lo clona automáticamente en la primera instalación. También puedes actualizarlo manualmente con el subcomando integrado update-rules — sin recompilar ni reiniciar:

# Install the latest pack into ~/.veilgate/rules (the default location)
veilgate update-rules

# Or pin to a release tag
veilgate update-rules --dir ~/.veilgate/rules --version v1.2.0

# List available releases
veilgate update-rules --list

Tras la instalación, el observador fsnotify de VeilGate detecta los nuevos archivos en unos ~500 ms. Cada archivo existente se respalda como <name>.bak antes de sobrescribirse (pasa --no-backup para omitirlo). La versión instalada se registra en <rules_dir>/.rules-version.json para que la CI y los operadores puedan comprobar qué versión está en ejecución sin consultar los metadatos de git.

Trata ambos directorios como política de seguridad: revisa los cambios antes de desplegar en producción, especialmente detector.yaml e ip_reputation.yaml. Guía completa y procedimiento de reversión: docs/how-to/install-community-rules.md.

Documentación

• Primeros pasos: ejecución local y primeras comprobaciones.
• Referencia de configuración: veilgate.yaml y archivos de reglas.
• Despliegue: instalación en Linux/systemd.
• Arquitectura: flujo de solicitudes y diseño de subsistemas.
• Operaciones: métricas, paneles, alertas y comprobaciones rutinarias.
• Ficha del modelo: comportamiento y limitaciones de las señales ML.
• Índice de referencia: páginas de referencia completas orientadas a la consulta.
• Reglas comunitarias: instala y actualiza conjuntos de reglas mantenidos por la comunidad mediante veilgate update-rules.
• Modelo de amenazas: qué protege y qué no protege VeilGate.

Notas de seguridad

• Despliega VeilGate únicamente delante de sistemas que poseas u operes.
• No expongas el listener de métricas directamente a Internet público.
• Establece VEILGATE_SECRET o challenge.secret antes de usar el modo challenge o tarpit. VeilGate se niega a arrancar fuera del modo observe con el secreto de desafío por defecto.
• Trata los archivos bajo rules/ como política de seguridad. Revísalos y controla sus versiones.
• Empieza con umbrales conservadores y ajusta según el tráfico observado.

Desarrollo

make test
make fmt
make build

La carpeta de nivel superior tests contiene pruebas de integración de caja negra. Las pruebas unitarias privadas de paquete viven junto a sus paquetes porque verifican los helpers no exportados del detector, de huellas TLS, de tarpit y de ML.

Licencia

Apache-2.0. Ver LICENSE.