mini-waf: agregá un WAF a tu API Node.js en 5 minutos

En pocas palabras: mini-waf es un paquete npm que agrega un Web Application Firewall a una API Node.js con Express, Fastify o NestJS en una sola línea. Sin dependencias en runtime, bloquea SQLi, XSS, RCE y path traversal con reglas OWASP Core Rule Set, devolviendo 403 Forbidden.

mini-waf es un paquete npm que agrega un Web Application Firewall a una API Node.js en Express, Fastify o NestJS con una sola línea de código. Según el artículo original de su creador, corre como middleware sin dependencias en runtime y bloquea inyecciones SQL, XSS y path traversal devolviendo 403 Forbidden.

Un WAF para Node.js es una capa de software que inspecciona cada request HTTP antes de que llegue a las rutas de la aplicación, buscando patrones de ataque conocidos como inyección SQL o scripts maliciosos en el body. mini-waf, publicado en npm por su creador, implementa ese concepto como middleware nativo para Express, Fastify y NestJS, con reglas derivadas del OWASP Core Rule Set.

¿Por qué faltaba un WAF para Node.js bien mantenido?

Porque la mayoría de los paquetes WAF que existían en npm estaban abandonados o pegados a versiones viejas de sus frameworks. El propio autor lo cuenta así en su publicación en dev.to: al buscar un WAF para sus propios proyectos Node.js se topó con librerías sin commits en años. Las alternativas pesadas tipo ModSecurity existen, pero viven delante de la app, no dentro, y no están pensadas para el desarrollador Node.js promedio.

¿Y entonces? Armó el suyo.

La validación de inputs (esa que probablemente ya tenés con Zod o Joi) atrapa datos mal formados, pero no está diseñada para detectar una inyección SQL escondida en un campo de búsqueda, un intento de leer /etc/passwd vía path traversal, o un scanner automatizado probando cada ruta de tu API. Ese es exactamente el hueco que mini-waf viene a tapar: una capa liviana, con tipos, que corre en el mismo proceso que tu aplicación.

¿Cómo funciona mini-waf por dentro?

Cada request entrante se convierte en un contexto agnóstico de framework y se evalúa contra una lista ordenada de reglas. Cada regla tiene una condición y una acción, y eso es todo el motor.

• block: corta el request con un 403 Forbidden.
• allow: salta todas las reglas restantes (útil para health checks).
• log: registra el match y sigue evaluando.

Rara vez escribís reglas desde cero. En vez de eso elegís presets (sqli, xss, rce, rfi, path-traversal, scanners, protocol o default para todos juntos) y un nivel de protección. Ojo con esto: cada nivel agrega más reglas, y cada regla nueva suma probabilidad de falso positivo. Ya cubrimos antes cómo desplegar tu web en Vercel.

• low (19 reglas): scanners obvios, SQLi clásico, path traversal plano y LFI. Pensado para APIs sensibles a falsos positivos.
• balanced (51 reglas, nivel por defecto): suma XSS, tautologías SQL, operadores NoSQL, SSTI y rate limiting básico. Es el punto de partida recomendado para producción general.
• high (81 reglas): agrega prototype pollution, XXE, LDAP injection y detección de CL+TE. Pensado para escenarios bajo ataque activo.
• paranoid (94 reglas): cobertura máxima, con más ruido: User-Agents genéricos, headers sobredimensionados, introspección GraphQL.

Una regla manda por sobre todas las demás según la documentación: el body parser tiene que correr antes que el WAF. Si no, el body llega vacío cuando mini-waf lo mira, y las reglas que dependen del payload (como las de XSS en JSON) directamente no disparan.

¿Cómo instalar mini-waf en Express, Fastify y NestJS?

Se instala con npm install mini-waf más el framework que uses como peer dependency, y el orden de tres pasos (parser, WAF, rutas) es el mismo en todos los casos. Cambia solo el entrypoint de importación según el framework.

En Express, primero registrás express.json() y express.urlencoded(), después app.use(expressWaf({ presets: ['default'], level: 'balanced' })), y recién ahí tus rutas. Si invertís el orden, el WAF queda ciego.

En Fastify no tenés que preocuparte por el orden manual: el framework parsea el JSON antes del hook preHandler donde corre mini-waf, así que registrar fastifyWaf como plugin antes de las rutas alcanza. En NestJS, la integración es un módulo más un middleware: MiniWafModule.forRoot({ config: {...}, platform: 'auto' }) detecta si tu app corre sobre Express o Fastify por debajo. Un detalle que suele romper cosas: la ruta comodín para aplicar el middleware a todo cambió entre versiones, en Nest 11 es {*path} y en Nest 10 sigue siendo '*'. Te puede servir nuestra cobertura de cómo instalar un WAF con Docker.

¿Y si usás Koa u otro framework sin integración nativa? Ahí entra el adaptador custom: createAdapter más createMiniWaf te dejan definir cómo mini-waf lee el método, la IP, los headers y el body de tu contexto particular, y el propio repositorio trae un ejemplo funcional para Koa en su carpeta integration/. El mismo patrón sirve para node:http puro.

Si tu API corre en un VPS propio en vez de una plataforma serverless, tener un hosting con control total del entorno ayuda a la hora de instalar este tipo de middleware sin restricciones raras de runtime. Para infraestructura en Argentina, donweb.com es una opción a evaluar si necesitás ese nivel de control sobre el servidor donde vive tu Node.js.

¿Qué ataques bloquea mini-waf en la práctica?

Bloquea con 403 Forbidden las cuatro familias de ataque que el propio autor probó con curl contra un servidor de ejemplo: SQLi, path traversal, scanners automatizados y XSS en el body. El tráfico normal, mientras tanto, pasa sin fricción.

• Inyección SQL clásica en query string: un request tipo ?q=%27%20OR%201%3D1-- dispara la regla preset-sqli-classic-query.
• Path traversal: ?q=../../etc/passwd activa preset-path-traversal y corta el intento de leer archivos del sistema.
• Scanners automatizados: un request con User-Agent sqlmap/1.8 trip ea la regla preset-scanners-ua antes de que el scanner mapee nada.
• Script tags en JSON: un body como {"text":"<script>alert(1)</script>"} activa preset-xss-body.

Una búsqueda legítima como ?q=shoes no toca ninguna regla y sigue de largo. Eso es lo que en teoría diferencia un WAF bien calibrado de uno que rompe tu producto a cada rato.

¿Qué límites tiene mini-waf y qué no reemplaza?

mini-waf es una capa dentro de tu proceso Node.js, no un firewall de red ni protección DDoS de borde. Tampoco reemplaza las queries parametrizadas ni el escapado de output al renderizar HTML: según el propio repositorio, esas defensas siguen siendo tu responsabilidad en el código de la app. Tema relacionado: combinar esto con circuit breakers y timeouts.

El rollout sugerido en la documentación es simple: arrancar en balanced con logging: true, mirar los logs durante unos días para detectar falsos positivos, desactivar las reglas ruidosas puntuales con disabledRuleIds (en vez de tirar abajo todo un preset), y recién después subir a high en los endpoints más sensibles.

Subís el WAF a producción en balanced, todo funciona bien la primera semana, después alguien reporta que su búsqueda con comillas simples legítimas empieza a devolver 403, revisás el log, identificás la regla exacta que matchea de más y la apagás por id sin tocar el resto del preset: ese es el ciclo real de tuning con cualquier WAF, no solo con este.

¿Qué está confirmado sobre mini-waf y qué falta comprobar?

Confirmado, según la documentación oficial y el repositorio en GitHub: soporte nativo para Express, Fastify y NestJS, cero dependencias en runtime, empaquetado dual CommonJS y ESM, y el conteo exacto de reglas por nivel (19 en low, 51 en balanced, 81 en high, 94 en paranoid).

Lo que no está confirmado con datos públicos independientes: no hay benchmarks de performance de terceros que midan el overhead real de mini-waf bajo carga, ni una auditoría de seguridad externa publicada. Tampoco hay cifras de adopción (descargas semanales, empresas usándolo en producción) más allá de lo que muestra el propio paquete en npm. Si vas a meterlo en un sistema crítico, correr tu propio benchmark de latencia antes y después de agregarlo es un paso razonable que la fuente no cubre pero que cualquier equipo serio debería hacer. Lo explicamos a fondo en evitar errores 500 en tu API de Vercel.

Errores comunes al implementar un WAF para Node.js

• Registrar el WAF antes del body parser: si expressWaf corre antes de express.json(), el body llega vacío y las reglas de XSS o SQLi en payload JSON nunca disparan. El request pasa como si nada.
• Saltar directo a paranoid sin pasar por balanced: paranoid suma 94 reglas pensadas para máxima cobertura, no para tráfico normal. Arrancar ahí sin logging previo suele tirar abajo funcionalidad legítima el primer día.
• Escribir reglas custom sobre campos genéricos (bag fields): usar query o headers completo en vez de apuntar a query.id o headers.user-agent hace que el matcher evalúe cada valor del objeto, con más costo de regex y más chance de falso positivo.
• Asumir que el wildcard de NestJS es siempre '*': en Nest 11 el patrón cambió a {*path}. Copiar un ejemplo viejo de Nest 10 rompe el middleware silenciosamente.

Preguntas Frecuentes

¿Qué es un WAF y para qué sirve en una API Node.js?

Un WAF (Web Application Firewall) es una capa que inspecciona cada request HTTP buscando patrones de ataque conocidos antes de que lleguen a tu lógica de negocio. En una API Node.js sirve para bloquear inyección SQL, XSS, path traversal y scanners automatizados sin tener que escribir esa lógica de detección a mano.

¿Cómo instalo mini-waf en Express o Fastify?

Corré npm install mini-waf express (o fastify según tu caso) y registrá el middleware después del body parser y antes de tus rutas. En Express es app.use(expressWaf({ presets: ['default'], level: 'balanced' })); en Fastify es app.register(fastifyWaf, { config: {...} }).

¿mini-waf reemplaza la validación de inputs?

No. mini-waf detecta patrones de ataque conocidos en el request completo, pero no valida la forma ni el tipo de dato que espera tu endpoint. Seguís necesitando Zod, Joi o el validador que uses para chequear que un campo sea el email o el número que tu API espera recibir.

¿Qué ataques bloquea mini-waf por defecto?

Con el preset default y nivel balanced, bloquea SQLi, XSS, path traversal, RCE, RFI, scanners y ataques a nivel protocolo HTTP, sumando 51 reglas activas según el repositorio oficial. Cada ataque devuelve un 403 Forbidden con el id de la regla que matcheó.

¿mini-waf sirve para NestJS o solo para Express?

Sirve para NestJS de forma nativa, vía MiniWafModule.forRoot() con la opción platform: 'auto', que detecta si tu app Nest corre sobre Express o Fastify por debajo. También soporta Express y Fastify directamente, y cualquier otro framework mediante un adaptador custom.

Conclusión

mini-waf llena un hueco real: paquetes WAF vivos y mantenidos para Node.js eran, hasta esta publicación, prácticamente inexistentes en npm. La propuesta de su creador no es reinventar la detección de ataques (usa el OWASP Core Rule Set como base), sino empaquetarla como middleware liviano que un desarrollador Node.js instala en minutos sin sumar un proceso externo.

Si tenés una API en producción sin ninguna capa de filtrado de requests, mini-waf es un punto de partida barato de probar: arrancá en balanced con logging activado, mirá qué reglas te generan ruido durante unos días y recién después decidí si subir el nivel. Lo que no conviene es tratarlo como reemplazo de queries parametrizadas o de un firewall de red, porque ni la fuente ni el propio autor lo venden así.

Fuentes

• Add a Web Application Firewall to Your Node.js API in Five Minutes – publicación original del creador de mini-waf en dev.to
• Mini-WAF en GitHub – repositorio oficial con documentación de presets, niveles y adaptadores
• mini-waf en npm – página oficial del paquete e instrucciones de instalación
• Documentación oficial de mini-waf – guía completa de configuración y reglas