PingWAF WAF
Español
English EN 简体中文 ZH Español ES Français FR 日本語 JA
GitHub
Resumen Funciones Inicio rápido Documentación GitHub ↗

Inicio rápido

En marcha en cinco minutos, protegido en diez

Dos caminos oficiales: la pila compose incluida para evaluar, o una compilación propia para producción.

Ruta A Docker Compose Ruta B Compilar Tiempo ~5 minutos Almacén PostgreSQL 14+

Antes de empezar

La ruta compose solo necesita Docker. Compilar requiere Rust, Node y protoc.

Docker

Engine 24+ con Compose v2

Arranca el plano de control, un agente y PostgreSQL.

PostgreSQL

14+ (16 recomendado)

El plano de control guarda sitios, reglas y versiones.

Puertos

9080 · 9090 · 80 · 443

9080 sirve la API y la consola; 9090 el plano gRPC.

TLS

Autofirmado en el primer arranque

Sustitúyelo o confíalo antes de exponer la consola.

Inicio rápido

Docker Compose

El compose arranca PingWAF en modo all-in-one junto a PostgreSQL con la imagen publicada.

  1. Clona el repositorio

    El compose y el TOML de ejemplo están en la raíz del repositorio.

    bash 
    git clone https://github.com/shuaiZend/PingWAF.git
cd PingWAF

  2. Arranca la pila

    Define JWT_SECRET y ADMIN_PASSWORD si el host es accesible desde fuera.

    bash 
    export JWT_SECRET="$(openssl rand -hex 32)"
export ADMIN_PASSWORD="$(openssl rand -hex 16)"
docker compose up -d

  3. Abre la consola

    La consola usa HTTPS con un certificado autofirmado del primer arranque; el navegador avisará hasta que lo confíes o subas el tuyo en Ajustes.

    bash 
    curl --connect-timeout 2 --max-time 3 http://localhost:9080/healthz
# {"status":"ok","database":"up"}

  4. Añade tu primer sitio

    Crea un sitio con el dominio que apuntarás al agente y habilita solo las protecciones que necesites.

Los binarios publicados son para Linux amd64/arm64; la imagen Docker cubre ambas arquitecturas.
localhost:9080/sites
Lista de sitios en la consola con tráfico y estado de protección
La lista de sitios es donde empieza la aplicación: una fila por dominio.

Inicio rápido

Compilar desde el código

Usa esta ruta cuando necesites una compilación propia o un binario auditable.

  1. Instala el toolchain

    protoc es obligatorio: sin él el crate proto cae en marcadores de posición y los crates posteriores fallan.

    bash 
    # macOS
brew install protobuf

# Debian / Ubuntu
sudo apt install protobuf-compiler cmake

  2. Compila la consola

    La consola se embebe en el binario, así que debe compilarse primero.

    bash 
    cd web && npm ci && npm run build && cd ..

  3. Compila el binario

    El conjunto full incluye motor WAF, desafíos y automatización de certificados.

    bash 
    cargo build --release --bin pingwaf --features full

  4. Ejecuta all-in-one

    Apunta a una instancia PostgreSQL; el esquema se crea en el primer arranque.

    bash 
    ./target/release/pingwaf all-in-one \
  --db-url "postgres://pingwaf:pingwaf@localhost:5432/pingwaf"
En Linux puedes omitir la compilación con install.sh (--mode all-in-one).
localhost:9080/agents
Página de agentes con los nodos edge enrolados y su heartbeat
Una compilación propia puede actuar como plano de control y luego enrolar agentes.

Primer acceso

El plano de control crea un administrador en el primer arranque y la consola exige cambiar la contraseña.

defaults.env

Consola https://localhost:9080
Correo admin@pingwaf.local
Contraseña pingwaf123
Secreto JWT ≥ 16 caracteres

Cambia los valores por defecto antes de exponer nada

PINGWAF_JWT_SECRET y PINGWAF_ADMIN_PASSWORD tienen valores funcionales. Define ambos, pon PINGWAF_ALLOW_REGISTRATION=false y mantén 9080 en una red privada o VPN.
bash 
export PINGWAF_JWT_SECRET="$(openssl rand -hex 32)"
export PINGWAF_ADMIN_PASSWORD="$(openssl rand -hex 16)"
export PINGWAF_ALLOW_REGISTRATION=false
localhost:9080/login
Página de acceso de PingWAF con campos de correo y contraseña
Accede con la cuenta de administrador inicial; luego puedes vincular passkeys.

Siguientes pasos

Cuando el plano de control responde, el resto es configuración.

Crea un sitio

Un sitio une un dominio con grupos de origen, rutas y las protecciones que actives.

Modelo de sitio

Conecta agentes

Ejecuta pingwaf server en el nodo de control y pingwaf agent en cada nodo edge; se registran por gRPC :9090.

Despliegue distribuido

Activa protecciones

Habilita el motor WAF, el escudo CC o la política de bots por sitio: nada se aplica hasta que lo hagas.

Capacidades

Envía los logs

Manda los logs a Elasticsearch y conserva las capturas en PostgreSQL para reproducir.

Observabilidad

Si algo no arranca

La compilación falla en pingwaf-proto

Falta protoc. Instala protobuf-compiler (o brew install protobuf) y recompila: sin él el crate usa marcadores de posición.

El navegador rechaza el certificado

La consola usa HTTPS con certificado autofirmado. Confía en el certificado descargado o sube el tuyo en Ajustes → HTTPS del plano de control; define PINGWAF_TLS_SANS con el hostname real.

Un agente nunca aparece

Comprueba que alcanza el plano gRPC en :9090 (PINGWAF_SERVER_URL) y que no hay firewall ni proxy TLS por medio.

El puerto 443 no abre

443 solo se abre tras emitir o subir un certificado; hasta entonces el agente sirve HTTP en el puerto 80.

¿Necesitas la versión larga?

Los documentos de despliegue y arquitectura cubren systemd, topologías distribuidas, precedencia de configuración y todas las variables de entorno.

Guía de despliegue GitHub