Guía de inicio

Requiere Node.js 20 o superior. Vantor se instala en el servidor. En un proyecto con frontend separado (React con Vite, por ejemplo), instalalo en el backend.

1. Licencia e instalación

Requiere una licencia gratuita. Creá una cuenta, creá una licencia en el panel y copiala.

npm install vantor-shield
npx vantor license TU_LICENCIA
npx vantor init

vantor license la guarda en .vantor-license y la agrega a .gitignore. En un servidor, usá la variable de entorno VANTOR_LICENSE o agregala a tu .env. Vantor la lee aunque dotenv no se haya cargado.

Para ver los cambios sin escribir archivos: npx vantor init --dry-run. Para ver la licencia en uso: npx vantor status.

Estados de la licencia

La licencia se verifica en tu servidor con Ed25519, sin conexión.

Un problema de licencia no detiene la aplicación. Las licencias duran un año. Para renovar, copiá una nueva desde el panel.

2. Orden de carga

Vantor debe cargarse antes que el resto de la aplicación. Si un módulo guarda una referencia a fs, http o child_process antes de que Vantor inicie, esa referencia queda sin protección.

init agrega la línea al inicio del servidor. Si la agregás a mano, va primera, antes de dotenv.

3. Por framework

Express, Fastify u otro servidor Node.js

// ESM o TypeScript
import 'vantor-shield/auto';
import express from 'express';

// CommonJS
require('vantor-shield/auto');
const express = require('express');

Next.js

init crea instrumentation.ts:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('vantor-shield/auto');
  }
}

Agregá también esto a next.config:

serverExternalPackages: ['vantor-shield']

El runtime Edge y el middleware que corre en Edge no quedan cubiertos.

Configurar desde código

onEvent no se puede expresar en JSON. Para usarlo, llamá a protect() en un archivo que se importe primero:

// vantor.setup.mjs
import { protect } from 'vantor-shield';

protect({
  mode: 'block',
  onEvent: (event) => miSistemaDeAlertas.enviar(event),
});

// server.mjs
import './vantor.setup.mjs';
import express from 'express';

4. Modo monitor

El modo monitor no bloquea, no agrega cabeceras y no aplica límites. Escribe en stderr una línea JSON por hallazgo:

{"vantor":1,"rule":"sql","action":"monitored","sink":"pg.query","source":"query","inputLength":28,"inputPreview":"x' UNION SELECT version() --","request":{"method":"GET","path":"/user","ip":"203.0.113.9"}}

Dejalo activo con tráfico real y revisá cada hallazgo:

• Ataque real: tu código tiene una vulnerabilidad que hay que corregir.
• Falso positivo: resolvelo antes de pasar a bloqueo.

5. Modo bloqueo

En vantor.config.json:

{ "mode": "block" }

También podés activar regla por regla:

{ "mode": "monitor", "rules": { "sql": "block", "command": "block" } }

Al bloquear, la operación falla con un VantorBlockedError (status 403). El error llega a tu código como cualquier otro, por rechazo de la promesa, por el callback o por el evento error del stream. Si no hay un manejador de errores, Vantor responde 403.

6. Desactivar Vantor

Para desactivar Vantor sin cambiar el código, definí esta variable de entorno:

VANTOR_MODE=off

VANTOR_MODE tiene prioridad sobre la configuración.

7. Detrás de un proxy

Si tu aplicación está detrás de Nginx, un balanceador o CloudFront, indicá cuántos proxies hay. De lo contrario, todos los usuarios figuran con la misma IP y comparten el mismo límite de peticiones:

{ "mode": "block", "trustProxy": 1, "rateLimit": { "max": 300 } }

Usá el número exacto. Con un número mayor, un cliente puede falsificar su IP con X-Forwarded-For.

8. Instalar desde un archivo

Para no depender de un registry en el despliegue, guardá el paquete en tu repositorio:

mkdir vendor
npm pack vantor-shield --pack-destination vendor
npm install ./vendor/vantor-shield-1.0.0-beta.1.tgz

Si compilás con Docker, copiá la carpeta y la configuración en el Dockerfile:

COPY package*.json ./
COPY vendor ./vendor
RUN npm ci --omit=dev
COPY vantor.config.json ./