Gatekeeper

Middleware ASGI de seguridad para FastAPI/Starlette. Una capa extra delante de tu app: rate limiting, cabeceras seguras, detección de patrones de ataque en query y body, reglas propias por YAML y auditoría en JSON.

pip install gatekeeper-asgi             # núcleo
pip install "gatekeeper-asgi[yaml]"     # + configuración por YAML
pip install "gatekeeper-asgi[redis]"    # + rate limit compartido entre workers

from fastapi import FastAPI
from gatekeeper import Config, GatekeeperMiddleware

app = FastAPI()
app.add_middleware(GatekeeperMiddleware, config=Config(rate_limit=100, rate_window=60))
# o con Redis para que todos los workers cuenten lo mismo:
# Config(rate_backend="redis", redis_url="redis://localhost:6379/0")
# o: Config.from_yaml("gatekeeper.yaml")   (ver examples/gatekeeper.yaml)

Qué cubre

Qué mide (no qué promete)

Se miden tres corpus. El primero es nuestro, redactado y con procedencia documentada (corpus/):

Once familias de detección: SQLi, XSS, path traversal, ficheros sensibles, NoSQL, comandos del sistema, SSRF, SSTI, CRLF, Log4Shell y proto-pollución. El desglose con la frontera de falsos positivos de cada una está en docs/amenazas.md.

El segundo es el retenido: un corpus escrito una vez, sin mirar las firmas de las reglas, y desde entonces solo medido. Es el que dice si las reglas generalizan o solo se acuerdan de los casos con los que se escribieron:

Que dé 94,5% y no 100% es lo esperado: el corpus propio se puede usar para ajustar las reglas y el retenido no. La metodología, y los fallos que este corpus encontró en las reglas, están en corpus/HELDOUT.md.

El tercero es ajeno: los tests de regresión de OWASP Core Rule Set (Apache-2.0, commit 30cb436, importado con tools/import_crs.py), que escribió otra gente para otro WAF, con sus propios negativos:

Ese 41.0% no es una meta: es la línea base de un corpus diseñado para un WAF de 500+ reglas y payloads mucho más ofuscados, y el workflow la vigila para que no baje. Publicarlo entero es el punto: un 100% propio y un 41.0% ajeno, los dos medidos y los dos con guarda en CI. Estas cifras miden los escaneos individuales; no incluyen inspect_cross_carrier=True.

El detalle, incluidos los payloads que se escapan y por qué, está en corpus/REPORT.md. El workflow falla si una regla nueva empeora esas cifras (python tools/evaluate.py --check).

Demo

Una sesión real contra demo/app.py (uvicorn + curl, sin trucos): tráfico normal pasa, los payloads reciben 403 y la auditoría registra la regla, el campo y el patrón que saltó — nunca el contenido.

La app de la demo incluye un playground con botones y configs de despliegue para Vercel (vercel --prod) y Docker: demo/.

Latencia

python benchmarks/latency.py mide el coste por petición en tu máquina, invocando ASGI directamente y sin red:

Una corrida local de Python 3.14.8 en Windows, con 1000 iteraciones × 5 rondas, produjo esos percentiles; la columna de overhead usa 3 repeticiones. Los resultados dependen del entorno y no son una promesa de latencia de producción. Los escenarios de body y cruce entregan el body real al middleware; los tests verifican que el caso benigno responde 200 y el cruce de ataque 403.

El pre filtro de familias. Antes de ejecutar las regex, comprueba si el texto contiene un literal obligatorio de cada familia y omite las que no pueden coincidir. Para textos de menos de 128 caracteres no lo aplica. Esta optimización no debe cambiar detecciones. tests/test_prefilter.py compara el escaneo con y sin pre filtro sobre los 1787 valores de ambos corpus (payloads propios, solicitudes CRS y valores de cabecera) y exige el mismo resultado.

El benchmark publica p50, p95 y p99 por petición para que la cola no quede oculta por un promedio. En esta corrida el escenario completo tuvo p50 de 193.40 µs, p95 de 394.10 µs y p99 de 677.90 µs; son medidas locales con ruido, no latencia de extremo a extremo ni un SLA.

python benchmarks/latency.py --save base.json y, tras cambiar el código, python benchmarks/latency.py --baseline base.json comparan dos versiones en tu máquina y dicen si algún escenario empeoró más de un margen (25 % por defecto). Sirven para comparar cambios bajo condiciones locales similares antes de abrir un PR que toca el camino caliente.

Comparar rendimiento

No hay un umbral fijo de latencia en CI: los runners compartidos no son una base estable. El benchmark es un informe local; para comparar cambios, guarda una línea base y ejecuta ambas versiones en la misma máquina:

Documentación

Guía completa con MkDocs Material en docs/: uso, detección y medición, modelo de amenazas, seguridad, referencia de API y desarrollo. En local: mkdocs serve. Se publica en https://eche-dev.github.io/Gatekeeper/ en cada push a main (build --strict en CI: un enlace roto rompe el workflow).

¿Acabas de llegar? Empieza por la guía de inicio rápido: dos comandos curl verifican que una petición normal da 200 y un ataque da 403. Y si decides dónde desplegarlo, la guía de despliegue dice qué valor cambia en cada topología (un proceso, varios workers, Docker, proxy inverso).

Contribuir: CONTRIBUTING.md · Código de conducta · Plantillas de issues y PR en la raíz del repo.

Qué NO cubre

• La detección por regex tiene falsos positivos y falsos negativos: no sustituye a consultas parametrizadas, a validación de entradas ni a un WAF.
• El contenido de los ficheros adjuntos no se inspecciona (las subidas pasan intactas; sí se inspeccionan los nombres de campo y de fichero).
• Los frames de un WebSocket no se inspeccionan: sí el handshake (ruta, query y cabeceras), que además tiene rate limit.
• Los binarios que no son JSON (imagen, PDF, zip…) no se leen.
• Por defecto, cada valor del body se analiza por separado. Con inspect_cross_carrier=True, los valores textuales no excluidos se combinan con ruta/query; las claves JSON y las cabeceras no participan.
• inspect_cross_carrier=True combina ruta/query con los valores textuales no excluidos del body cuando los escaneos individuales no detectan nada. Las claves se inspeccionan individualmente, pero no se combinan. Es opt-in; su resultado no está incluido en las métricas publicadas del corpus.
• Los operadores $gt/$lt/$in de Mongo quedan fuera de la firma NoSQL a propósito (los usan los filtros legítimos); localhost y 127.0.0.1 no cuentan como SSRF (OAuth de desarrollo).
• Con rate_backend="memory" y varios workers, el límite efectivo se multiplica: usa Redis.
• Si Redis no responde, rate_fail_open=True (por defecto) sigue admitiendo peticiones; ponlo a False si prefieres 503.
• trust_proxy=False por defecto; actívalo solo detrás de un proxy de confianza. Con trust_proxy=True el XFF se lee de derecha a izquierda (ips[-trusted_proxies]); añade trusted_proxy_cidrs si la app es alcanzable por otro camino.
• Un body JSON/form mayor que max_body_size se rechaza: súbelo o usa inspect_body=False.
• allow_paths exime de inspección, no de rate limit ni de bloqueo de IP.

Configuración

Config falla al arrancar, no en producción: claves desconocidas (un typo como rate_limt), regex inválidas o vacías, nombres duplicados, disabled_rules inexistentes y packs desconocidos lanzan ValueError. Las reglas propias se evalúan sobre texto decodificado, sin comentarios /**/ y en minúsculas; evita patrones con backtracking catastrófico, los patrones propios no están acotados por Gatekeeper.

Packs de reglas

Las once familias se evalúan por defecto. Si tu app expone menos superficie de la que asumes, puedes activar un subconjunto (los packs son opt-in: sin rule_packs no cambia nada respecto a lo que ya hacía Gatekeeper).

from gatekeeper import Config

Config(rule_packs=["api"], disabled_rules=["cmdi"])   # API sin XSS ni SSTI, sin cmdi

Un pack desconocido es ValueError al arrancar: una app no puede quedarse sin protección porque alguien escribiera rule_packs=["we"].

Excluir campos (y no campos)

Cuando tu app acepta por diseño un valor que una firma bloquea (un buscador que indexa documentación de seguridad, un parámetro template con Jinja, un webhook), exímeno ese campo, no la familia entera:

Config(exclude_fields=["template", "bio", "doc_*"])

Funciona en los tres transportes: parámetro de query, cabecera (user-agent) y puntero JSON (/user/bio o solo bio). La detección que cruza varios campos se conserva: si excluyes a pero el payload está repartido entre a y b, Gatekeeper quita a del objetivo y sigue vigilando b. La alternativa es disabled_rules, que apaga la familia para toda la app.

gatekeeper report: mide antes de bloquear

Poner el middleware delante en monitor_only=True, dejar correr el tráfico real y mirar qué salta:

monitor_only: true      # en tu configuración, mientras tanto
gatekeeper report gatekeeper.log          # ranking de reglas, rutas y campos
gatekeeper report gatekeeper.log --json   # salida legible por máquina

El informe agrupa por (regla, campo) —lo que se repite es ruido— y propone un exclude_fields o un disabled_rules listo para copiar. Acepta el JSON que emite el logger de Gatekeeper o un log de acceso genérico (GET /ruta?q=... 200). Los eventos de auditoría no incluyen el contenido del payload, así que este informe tampoco puede filtrar lo que el log no trae.

Desarrollo

pip install -e ".[dev]"
ruff check .            # estilo
mypy                    # tipos estrictos (src/gatekeeper)
bandit -r src -q        # análisis estático de seguridad
pytest --cov=gatekeeper   # incluye fuzzing con hypothesis (tests/test_fuzz.py)
python tools/evaluate.py --check     # tasas de detección y FP (propio + CRS)
python tools/import_crs.py --check   # procedencia del corpus externo
python benchmarks/latency.py         # coste por petición
python -m build && twine check dist/*   # el paquete se puede publicar

Proyecto

• CHANGELOG.md — qué cambia en cada versión.
• SECURITY.md — modelo de amenazas, límites y cómo reportar fallos.
• corpus/REPORT.md — informe de detección generado.

Licencia MIT.