Documentación de El libro de Sibuna 1.0.0-beta.3
Idioma: Español
English简体中文한국어日本語EspañolDeutschहिन्दीالعربية
En esta página

Parte IX: Operaciones y despliegue

Tratamos los dos modos de protección, todas las opciones de la línea de comandos, las recetas de forward-auth, los archivos de políticas, el almacenamiento persistente en SQLite o PostgreSQL, el clúster sobre una única base de datos compartida y el empaquetado.

Modos de protección y configuración

Elegir un modo de protección

  • Gate (--gate, alias --no-waf): admisión por prueba de trabajo, sesiones, reglas declarativas, reputación, límites GCRA y bloqueos.
  • Shield (por defecto, --shield, alias --waf): Gate más el cortafuegos semántico.
  • Despliegue distribuido (una opción para cualquiera de los dos modos): --data-dir guarda políticas, reputación y datos forenses en un archivo SQLite local; --database-url con --cluster-node conecta varios nodos a una única base de datos PostgreSQL (SID 0011).

Referencia de la línea de comandos

La tabla enumera todas las opciones de sibuna --help. Los rangos son los que impone el analizador.

Tabla 23 Opciones del daemon
Opción Valor por defecto Significado
--port, -p 8080 Puerto de escucha, de 1 a 65535
--host, -h 0.0.0.0 Dirección de escucha, un literal de dirección IP
--upstream-host 127.0.0.1 Host del origen (modo proxy inverso)
--upstream-port, -u 3000 Puerto del origen
--mode, -m reverse_proxy reverse_proxy o forward_auth (también proxy y auth), indicado una sola vez
--workers, -w uno por CPU Hilos de aceptación que comparten el socket de escucha, de 0 (uno por CPU) a 64; después, cada conexión aceptada recibe su propio hilo
--max-connections 1024 Conexiones atendidas a la vez, de 1 a 8192; las siguientes reciben 503
--max-connections-per-ip 64 Conexiones que puede mantener una dirección de par del socket, de 0 (sin límite) a 8192; un par IPv6 cuenta con su red --ipv6-prefix, y las cabeceras reenviadas no intervienen; las siguientes reciben 503
--idle-timeout 15 Silencio máximo en segundos, de 0 a 86400. El encabezado de una petición debe llegar dentro de ese plazo. Una respuesta del origen lo renueva en cada lectura, así que un flujo lento sigue vivo mientras fluyan bytes y un origen silencioso se corta en ambos sockets. Una subida a través del proxy debe entregar 16 KiB por periodo (una tasa mínima contra los ataques de cuerpo lento). El socket del cliente lleva un plazo de escritura de la misma duración, así que un cliente que no acepta ningún byte durante ese tiempo pierde la conexión
--websocket-idle-timeout 300 Plazo de inactividad de una conexión actualizada con Upgrade, en segundos, de 0 a 86400
--trust-forwarded desactivada; activada en forward-auth Acepta X-Forwarded-For / X-Real-IP del par
--no-trust-forwarded desactivada No las acepta nunca, ni siquiera en modo forward-auth
--trusted-hops 1 Si la identidad reenviada es de confianza, el cliente es la entrada de X-Forwarded-For situada a este número de posiciones desde la derecha, de 1 a 8
--ja4-header desactivada La cabecera de petición en la que un proxy de entrada de confianza envía la huella TLS JA4 del cliente, como cf-ja4; de 1 a 64 caracteres de token, que no sea X-Forwarded-*, X-Real-IP, X-Sibuna-* ni Forwarded. Solo se lee si la identidad reenviada es de confianza (véase "Huellas JA4 desde el proxy de entrada")
--ipv6-prefix 64 Longitud del prefijo IPv6, de 32 a 128, a la que se aplican los límites de tasa, los bloqueos y el límite de conexiones por cliente
--algorithm, -a posw posw o hashcash
--difficulty, -d 16 Bits de trabajo, de 1 a 64: bits a cero de Hashcash, o profundidad de PoSW más tres
--posw-challenges 16 Aperturas por prueba de trabajo secuencial, de 1 a 32
--token-scheme mac mac (BLAKE3 con clave) o ed25519
--token-ttl 86400 Duración de la sesión, en segundos (de 1 a 31.536.000)
--challenge-ttl 300 Duración del desafío, en segundos (de 1 a 86.400)
--secret-file, -s aleatorio 64 caracteres hexadecimales o 32 bytes en bruto; también se acepta SIBUNA_SECRET (64 caracteres hexadecimales)
--cookie-name __sibuna_token Nombre de la cookie de sesión, de 1 a 64 caracteres de token
--secure-cookie desactivada Añade el atributo Secure
--gate / --shield shield Selección del modo de protección
--rate-limit 100 Peticiones por ventana y por cliente (ráfaga GCRA)
--rate-window 10 Ventana en segundos, de 1 a 86400
--challenge-rate-limit 30 Emisiones y verificaciones de desafíos por ventana y por cliente, aparte del presupuesto de peticiones
--ban-seconds 3600 Duración del bloqueo del honeypot, de 0 a 31.536.000
--policy-file, -P ninguno Política JSON declarativa
--rate-table-cells 262144 Celdas por tabla del limitador de tasa, de 16 bytes cada una, de 4.096 a 16.777.216, redondeadas hacia arriba a una potencia de dos
--ban-table-slots 65536 Posiciones de la tabla de bloqueos, de 24 bytes cada una, de 1.024 a 16.777.216, redondeadas hacia arriba a una potencia de dos
--spent-tags 1048576 Desafíos resueltos que se recuerdan para impedir su reutilización, de 24 bytes cada uno, de 65.536 a 16.777.216
--data-dir, -D ninguno Un nodo: persiste en el archivo SQLite <path>/sibuna.db
--database-url ninguno Un clúster: la base de datos PostgreSQL compartida (postgres:// o postgresql://)
--database-url-file ninguno Lee la URL de la base de datos de un archivo accesible solo por su propietario
--cluster-node ninguno El id de este nodo; vincula las claves de desafío y los bits altos de los identificadores de incidentes; obligatorio con una URL de base de datos
--storage-poll-ms 500 Intervalo del ciclo de almacenamiento, de 1 a 60.000 ms
--verbose, -v desactivada Registro detallado
--help / --version Imprime la ayuda (primero las opciones de la consola, si la consola está incluida en la compilación) o la versión, y termina

--data-dir y una URL de base de datos se excluyen mutuamente, igual que --database-url y --database-url-file. Se rechaza una URL de base de datos sin --cluster-node. Las opciones de clúster de Zaxonlite --cluster-listen, --cluster-peer, --cluster-secret-file y --cluster-tls-cert, --cluster-tls-key y --cluster-tls-ca ya no existen; si se indica alguna, el arranque se detiene con RemovedOption y una pista que remite a SID 0011. Las opciones de la consola se enumeran en el capítulo siguiente.

Vista previa de la consola

La consola se compila en el daemon mediante la feature por defecto console, pero solo arranca con --console. Necesita almacenamiento: --console sin --data-dir ni --database-url se rechaza con CONSOLE001 (StorageRequired). Usa cargo build --release -p sibuna --no-default-features --features sqlite para excluirla de la compilación; una compilación solo con --no-default-features no tiene ni almacenamiento ni consola. Inicializa localmente con el daemon detenido:

sibuna init-admin admin --data-dir ./data
sibuna --data-dir ./data --console 127.0.0.1:19446

sibuna console init-admin es el mismo comando. Abre http://127.0.0.1:19446/console/ y sustituye la contraseña temporal generada, que debe cambiarse en el primer inicio de sesión y caduca al cabo de una hora. La navegación con sesión iniciada ofrece el globo animado de países, estadísticas de peticiones y desafíos, investigación de incidentes, editores de políticas y de inspección, usuarios, tokens de API con ámbito, auditoría y controles del nodo que sirve. La interfaz de autenticación no carga geometría del globo ni telemetría. La interfaz es un módulo WebAssembly compilado desde cmd/console-ui (crate sibuna-console-ui) por el script de compilación del daemon; el módulo y la hoja de estilos incluida en el repositorio se distribuyen con las compilaciones ordinarias.

Tabla 24 Opciones de la consola
Opción Significado
--console <ip:port> Inicia la consola en esta dirección de escucha (IPv6 entre corchetes, puerto distinto de cero); requiere --data-dir o --database-url
--console-key-file <path> 64 caracteres hexadecimales, permisos solo para el propietario; protege los secretos guardados del segundo factor y de los webhooks
--console-origin <https-origin> El origen HTTPS canónico detrás de un proxy
--console-behind-proxy Un proxy que termina TLS entrega todas las peticiones
--console-trusted-proxy <cidr> Una red cuyas conexiones pueden llevar campos reenviados; repetible, como máximo 16
--console-advertise <origin> El enlace que otras consolas muestran para esta
--console-location <latitude,longitude> La posición declarada de este nodo en el globo
--console-probe <node-id>=<http://ip:port> La dirección de escucha del plano de datos de un par, cuyo estado se comprueba; repetible, como máximo ocho
--console-peer <node-id>=<https://origin> Un par de gestión; repetible, como máximo ocho
--console-peer-key-file <path> La clave de los pares: solo para el propietario, 64 caracteres hexadecimales, independiente de la clave de la consola
--console-peer-ca-file <path> Anclas de confianza PEM opcionales para los pares, que sustituyen a las raíces del sistema
--console-query-steps <n> Pasos de SQLite por lectura agregada, de 100.000 a 50.000.000, por defecto 4.000.000
--console-capture-heads Guarda por incidente los encabezados enmascarados de la petición y de la respuesta del origen; desactivada por defecto
--console-capture-header <name> Conserva el valor de esta cabecera en los encabezados guardados; repetible, como máximo 16; requiere --console-capture-heads
--console-cookie-secure Da a las cookies de la consola el atributo Secure sin proxy (el analizador la acepta, pero no aparece en --help)

Una opción de consola sin --console, una opción repetida o un valor mal formado detienen el arranque con CONSOLE002 y el nombre de error de la opción. Una configuración que incumple una regla de la consola (por ejemplo, una dirección de escucha fuera de loopback sin proxy de confianza) lo detiene con CONSOLE001.

Un recorrido por la consola

Las capturas siguientes proceden de una compilación release en un único nodo en loopback con almacenamiento SQLite y una política de cuatro reglas ALLOW sobre un desafío por defecto, tras unos cuatro minutos de tráfico sintético: direcciones de rangos de documentación, sondas de inyección SQL y de cross-site scripting, tres accesos al honeypot y siete desafíos resueltos en Chromium sin interfaz gráfica. Por tanto, todas las cifras son ilustrativas. Las tomamos con cargo xtask browser console --viewport-only, que recorre la consola en Chromium a 1440 por 960 píxeles y evalúa cada página. Cada página responde a una pregunta enunciada en su título y muestra el producto, el nodo que sirve, la página y el camino de vuelta en el mismo lugar.

La página de inicio de sesión de la consola: campos de nombre de usuario, contraseña y código del autenticador con un botón Sign in y, debajo, un campo Kiosk code con un botón Open wall display.
Fig. 13 Inicio de sesión. La interfaz pública no carga geometría del globo, datos GeoIP ni telemetría; el segundo formulario canjea un código de pantalla mural por una sesión de estadísticas de solo lectura.
La página de resumen Traffic de las últimas 24 horas: recuadros de peticiones, admitidas, desafiadas, denegadas por política, bloqueadas, limitadas por tasa, otras, y 4xx y 5xx del origen, cada uno con una comparación con el día anterior y una pequeña minigráfica.
Fig. 14 Statistics, Traffic, en las últimas 24 horas. La nota bajo el control del periodo indica la cobertura: solo existen cuatro de los 1.440 registros por minuto esperados, así que cada "Yesterday" muestra "Not available". Los recuadros muestran los recuentos conservados de minutos cerrados con una minigráfica en vivo de 60 segundos; los colores de las decisiones (admitida en verde, desafiada en ámbar, denegada en rojo) son los mismos en todos los paneles. Los 4xx y 5xx del origen muestran "Not recorded" para un periodo conservado, porque los registros por minuto no guardan el modo de proxy que da sentido a un recuento del origen; los totales en vivo desde el arranque sí los muestran. Debajo de los recuadros visibles hay dos recuadros de nivel, entradas de bloqueo activas y nodos sanos, la cronología y paneles muestreados que clasifican las rutas de las peticiones y los hosts de referencia, y cuentan los sistemas operativos, los navegadores y los estados de respuesta de los clientes.
La página de resumen Security: recuadros de inspección, reputación, limitación de tasa, desafíos, bloqueos y honeypot, paneles de tendencias en vivo y un flujo de eventos en vivo con los hallazgos del WAF.
Fig. 15 Statistics, Security. Un recuadro por módulo durante el periodo seleccionado, tendencias de resultados en vivo y el flujo de eventos en vivo con sus hallazgos más recientes (aquí waf:sqli y waf:xss). Los valores que no se registran lo indican en lugar de mostrar cero: el recuadro de Reputation muestra "Not recorded". Más abajo en la página aparecen los hallazgos en sesenta intervalos iguales, las categorías de ataque y las rutas atacadas.
La página Events, con un formulario de filtros (módulo, categoría, país, dirección del cliente, ruta, nodo, intervalo de tiempo) sobre una lista de incidentes registrados con las etiquetas waf:xss y waf:sqli.
Fig. 16 Events. El formulario de filtros sobre los incidentes registrados, del más reciente al más antiguo. Cada incidente se despliega en línea con sus pruebas: la respuesta local seleccionada, las longitudes en bytes, la campaña candidata y entradas explícitas "not recorded" para la regla coincidente, los términos de la puntuación y la huella JA4. Con --console-capture-heads, el encabezado enmascarado de la petición (y, para las admisiones auditadas a través del proxy inverso, el encabezado de la respuesta del origen) se abre bajo demanda, mostrado como UTF-8 o Latin-1, con la condición de la respuesta indicada (capturada, local, no observada en forward-auth, origen no disponible) y un comando para copiarlo como cURL; solo se conservan los valores de las cabeceras enumeradas, y --console-capture-header <name> amplía esa lista. En otro caso, los encabezados figuran como no registrados. Las acciones de denegar y permitir abren el formulario de grupos IP con la dirección ya rellenada.
La página Challenges con una ventana conservada de 24 horas: siete desafíos emitidos, enviados y aceptados, ninguno rechazado, y una tabla de causas de rechazo, todas a cero.
Fig. 17 Challenges. Una ventana conservada (una hora, un día o siete días) suma registros duraderos por minuto e indica cuántos minutos se registraron y estaban completos; aquí se emitieron, enviaron y aceptaron siete desafíos, y todas las causas de rechazo están a cero. Más abajo aparecen los totales en vivo desde este arranque, los parámetros configurados y los emitidos más recientemente, el histograma de tiempos de resolución aceptados desglosado por algoritmo y por intervalo de parámetros, las transiciones de dificultad adaptativa y los registros por dirección con atajos para denegar y permitir, conservados siete días.
La página Policies: la configuración aplicada (Shield, revisión 3, cuatro reglas, PoSW con dificultad 16, límites locales del nodo) y la primera regla, public-static, con 339 coincidencias registradas hoy.
Fig. 18 Policies. El motor aplicado nombra su modo de protección, sus revisiones, su algoritmo y dificultad por defecto y sus límites locales del nodo, y después enumera las reglas en orden de evaluación con sus coincidencias de hoy y la cobertura de esos recuentos. Más abajo aparecen la matriz de modos de inspección, el probador de peticiones y los grupos IP. Managed rules abre el editor; guardar una edición muestra primero una revisión de los campos cambiados, y confirmarla valida el candidato completo y crea una nueva revisión.
La página Nodes: el nodo 1 aceptando conexiones, con las conexiones abiertas, las entradas de bloqueo locales activas, las revisiones de política 3 de 3, el tiempo en funcionamiento, la memoria residente, la CPU y el identificador de arranque, minigráficas de memoria y CPU, y los botones Drain node, Resume admission y Clear local bans.
Fig. 19 Nodes. El estado y los comandos del nodo que sirve, con la memoria residente y la CPU del último segundo y sus minigráficas de sesenta segundos; debajo, cada miembro anunciado con su revisión de política aplicada frente a la revisión confirmada, su dirección de gestión y el resultado de su sondeo (SID 0007, SID 0013).
La página GeoIP con el proveedor ip-location-db user-country, todavía sin ninguna generación cargada, y el formulario de importación.
Fig. 20 GeoIP. Proveedor, licencia, resumen criptográfico de la generación activa, hora de carga y el formulario de importación; aquí aún no se ha cargado ninguna generación. Una importación fallida nunca sustituye a la generación activa.
La página Settings con una lista vacía de destinos de notificación y el formulario para un nuevo destino webhook o syslog.
Fig. 21 Settings, todavía sin destino de notificaciones y con el formulario para crear uno. Más abajo en la página aparecen los umbrales de picos de denegaciones, la retención con una confirmación explícita por ventana, las plantillas de páginas de respuesta y About.
La página Audit con un formulario de filtros y filas de actividad registrada: session.create, session.logout, kiosk.exchange y kiosk.grant, cada una con la hora, el actor y su rol, el sujeto y un botón Open.
Fig. 22 Audit. Historial de solo adición con actor y rol, acción, sujeto y una vista de detalle con resúmenes enmascarados del antes y el después; también se registran los inicios de sesión rechazados. Cada modificación de gestión y cada fila de autenticación registran la dirección del cliente que presentó la credencial; las filas que escribe el propio sistema la muestran como no registrada. Un registro de política ofrece Revert this change, que restaura el documento registrado antes de esa revisión como una revisión nueva y auditada tras una confirmación, y se rechaza si el conjunto de reglas ha cambiado desde entonces.
Una pantalla mural titulada Node 1 Traffic, con los controles Live, una caducidad de 719 minutos, Pause, Theme y Exit kiosk, y los once recuadros de tráfico sin navegación.
Fig. 23 Una pantalla mural. Una sesión de quiosco muestra solo las vistas Traffic y Security, sin navegación, e indica cuándo caduca.

La opción --console-location <latitude,longitude> declara la posición de este nodo, por ejemplo 1.3521,103.8198 para un despliegue en Singapur. El globo se centra inicialmente allí; Center Sibuna vuelve a ese punto después de girarlo. La actividad de los países sigue arcos animados de círculo máximo hacia el nodo, con recorte del hemisferio posterior y de la línea de cambio de fecha en el mapa plano. Las posiciones de los países son centroides representativos, y las flechas representan la ventana observada de sesenta segundos, no conexiones individuales. Una posición del servidor sin configurar sigue siendo explícitamente desconocida. El marcador configurado sigue visible durante las caídas de la telemetría; el tráfico obsoleto no se anima.

Las vistas previas de políticas construyen un candidato privado que incluye las reglas configuradas en archivo. Al guardar se compara la revisión esperada y se exige confirmar una comparación de campos. Las reversiones históricas se comparan con la regla actual y crean una revisión nueva. Las revisiones confirmadas y las aplicadas localmente son distintas. Los detalles de auditoría conservan cambios de decisión acotados y el rol efectivo que actuó. Los valores de los comparadores se enmascaran, y los registros antiguos sin contexto siguen marcados explícitamente como ausentes. Drenar, reanudar y borrar los bloqueos locales requieren una vista previa del comando. Un comando que llega mientras otro se ejecuta en el nodo se rechaza con 503 CONSOLENODE en lugar de ponerse en cola. Inspecciona el recibo duradero tras una respuesta perdida antes de reintentar; una intención confirmada no demuestra por sí sola que el efecto en tiempo de ejecución haya terminado.

Para operar en remoto, usa un proxy HTTPS y configura --console-origin, --console-behind-proxy, CIDR explícitos de --console-trusted-proxy y --console-key-file. El archivo de clave contiene 64 caracteres hexadecimales, tiene permisos solo para el propietario y protege los secretos guardados del segundo factor; consérvalo entre reinicios, separado de la semilla de desafíos. El origen HTTPS configurado y la lista de proxies permitidos son obligatorios para el acceso fuera de loopback. Sibuna tampoco termina TLS entrante en el puerto de escucha de la consola; la consola usa TLS solo para sus conexiones salientes, mediante rustls (SID 0012).

La CLI nativa accede a la consola en ejecución mediante los mismos contratos de autorización y almacenamiento. Lee las credenciales de archivos privados, no de valores en la línea de comandos:

sibuna console geoip update --version 2026-09-09 \
    --origin http://127.0.0.1:19446 --username admin \
    --password-file ./admin-password

Usa un archivo de contraseña accesible solo por su propietario, completa primero la configuración de la contraseña y añade --factor-file para un código de autenticador o de recuperación cuando se exija; --token-file sustituye al nombre de usuario y la contraseña en las operaciones de cuentas y de GeoIP. El cliente habla HTTP/1.1, exige HTTPS salvo para una dirección loopback literal, nunca sigue redirecciones y limita cada petición a 20 segundos y cada respuesta a 16 KiB. geoip status lee la generación activa. Las actualizaciones descargan por HTTPS los archivos publicados del proveedor seleccionado (por defecto el conjunto de datos de dominio público user-country, o DB-IP Lite con --provider dbip --version YYYY-MM), verifican las sumas de comprobación que publica el proveedor (o la indicada con --checksum), validan rangos acotados mediante sibuna-geoip, persisten la nueva generación y la activan localmente. Las actualizaciones fallidas conservan la generación anterior. Un tiempo de espera de la CLI (--timeout, por defecto 1200 segundos) deja de esperar; no cancela el trabajo de almacenamiento enviado. DB-IP Lite exige la atribución CC BY 4.0, que se muestra solo mientras sus datos están activos. Una compilación con SIBUNA_GEOIP_DATA=<snapshot> incorpora una instantánea validada (escrita por la herramienta geoip-snapshot) hasta la primera importación duradera; una compilación sin la consola la rechaza con GEOIP001. Las direcciones desconocidas, la pérdida de muestras y los datos obsoletos siguen siendo visibles; importar datos de países no crea tráfico ni enriquece muestras ya caducadas.

Los miembros del clúster se anuncian mediante la tabla de pertenencia de la base de datos compartida (console_nodes) al arrancar, cada minuto y en los dos segundos siguientes a un cambio de la revisión de política o de control aplicada, y aparecen en la página Nodes de todas las consolas. No hay elección de líder: un nodo SQLite informa del rol single y se declara líder a sí mismo, y un nodo PostgreSQL informa del rol unknown y que no hay líder, porque la conmutación por error de PostgreSQL no es visible para Sibuna (SID 0007). Configura --console-probe <node-id>=<http://ip:port> para los pares cuyas direcciones de escucha del plano de datos debe comprobar esta consola y --console-advertise <origin> para el enlace que muestran las otras consolas. La telemetría directa en vivo usa --console-peer <node-id>=<https://origin> (repetible, como máximo ocho) y un --console-peer-key-file dedicado. Los pares requieren --console-behind-proxy. Ambos extremos deben incluirse mutuamente en su lista y usar un proxy de entrada HTTPS de confianza. La clave de los pares es un archivo accesible solo por su propietario que contiene 64 caracteres hexadecimales, aprovisionado con independencia de la clave de la consola y de la semilla de desafíos. Los pares se comunican por un WebSocket TLS autenticado, mediante rustls con el proveedor ring (SID 0012). --console-peer-ca-file aporta opcionalmente anclas de confianza PEM para una PKI de gestión privada; en otro caso, el cliente usa las raíces del sistema. La verificación del nombre de host se aplica siempre y no se puede desactivar: el host de cada origen de gestión, un nombre DNS o un literal de dirección IP, debe figurar en el certificado del par. Un certificado rechazado marca al par como rejected y escribe una fila de auditoría peer.rejected. La rotación de claves y un cambio del archivo de la CA requieren un reinicio coordinado; el certificado de un par se puede renovar sin él. La API de Nodes y su suscripción informan de la antigüedad de la recepción, el desfase de reloj, los cambios de arranque y la pérdida de muestras. Las observaciones que faltan siguen sin estar disponibles y los valores desconectados siguen marcados como obsoletos; las estadísticas recibidas nunca pasan a ser la contribución propia de otro nodo. El Live traffic scope del panel selecciona un nodo o combina los nodos configurados. Node coverage and locations identifica las fuentes ausentes, obsoletas y con desfase de reloj, las horas de observación y los destinos configurados. Las clasificaciones por país muestran la incertidumbre debida a las filas de origen omitidas. Las flechas conservan su nodo receptor, y no se inventan las ubicaciones de nodo que faltan. La tasa combinada sigue sin observarse cuando alguna fuente que contribuye carece de un intervalo consecutivo. Selecciona un nodo para inspeccionar sus segundos conservados y las clasificaciones de rutas del minuto actual. Las consultas remotas usan la conexión autenticada con el par; la respuesta a una consulta debe caber en un mensaje WebSocket de 4 KiB, así que la consola que sirve reduce a la mitad las filas de una página que no cabe. Los pares ausentes siguen sin estar disponibles y los cursores del historial no pueden cruzar un reinicio de nodo. El historial por minuto mantiene su propia selección de nodos y sus filas por nodo. La navegación y la cabecera móvil identifican el nodo de consola que sirve con independencia de la fuente de tráfico seleccionada. Los comandos locales siguen siendo por nodo.

Los recuadros de tráfico se abren sobre las últimas 24 horas de registros conservados de minutos cerrados de los nodos seleccionados. El control del periodo también ofrece una hora, siete o noventa días y los totales en vivo desde el arranque. Las desviaciones respecto a ayer requieren una cobertura completa y coincidente de todos los nodos seleccionados. El globo y las minigráficas siguen describiendo su propia ventana en vivo de 60 segundos. Un escaneo conservado se actualiza un minuto después de terminar, y mantiene visibles sus valores anteriores y su antigüedad hasta que se sustituyen; cambiar la fuente o el periodo descarta el ámbito anterior. El historial ausente nunca se convierte en cero.

Compare retained traffic muestra dos ventanas de minutos cerrados una junto a otra: la misma ventana de ayer, el periodo anterior o un segundo nodo. Los controles de duración y de desplazamiento final fijan ambos rangos UTC. Cada acción lee como máximo dieciséis páginas compactas por lado, con 96 registros guardados por página. Esto cubre una ventana de 24 horas sin reinicios solapados en un solo lote; Continue conserva los mismos límites para escaneos más largos. La cobertura completa, la cobertura incompleta y el historial ausente siguen siendo explícitos. Los porcentajes de tasa requieren intervalos completos y sin solapamiento en ventanas UTC iguales, normalizados por los milisegundos observados; una referencia cero con tráfico nuevo muestra "New". El periodo principal de Traffic sigue siendo independiente. El formato por minuto no registra el modo de proxy histórico, así que las comparaciones de respuestas del origen siguen sin estar disponibles en lugar de interpretar los ceros de forward-auth como respuestas observadas.

Compare retained path rankings selecciona dos ventanas cerradas o dos nodos. El nodo 0 incluye todos los nodos conservados, incluidos los miembros retirados. Una acción lee como máximo dieciséis archivos inmutables, comprueba sus identidades y sumas de comprobación, y combina todos los contadores antes de seleccionar las filas que se muestran. Los archivos se sellan tras la ventana de 60 segundos para muestras tardías, así que el minuto cerrado más reciente aún puede estar pendiente. Continue conserva las ventanas y el cursor originales. Los límites describen prefijos de ruta muestreados, no totales exactos de peticiones. La página muestra los escaneos parciales, el truncamiento, los límites de retención y la pérdida de cola notificada; los archivos ausentes no pueden demostrar tráfico cero ni una cobertura completa.

Security se abre sobre las últimas 24 horas y usa sesenta intervalos de tiempo iguales sobre el periodo seleccionado. Sus agregados se ejecutan en el hilo de almacenamiento bajo una cota de trabajo. En SQLite la cota es --console-query-steps pasos de la máquina virtual (de 100.000 a 50.000.000, por defecto cuatro millones). Fíjala junto con --console; los valores no válidos o repetidos se rechazan. En PostgreSQL la cota es un tiempo límite de sentencia de 2.000 ms fijado en la transacción de la lectura (SID 0013); cambiar --console-query-steps no lo modifica. Las consultas agotadas piden un periodo más estrecho. Los recuentos de pasos acotan el trabajo de la consulta, no el tiempo transcurrido. Los gráficos comparten escala; despliega los valores de Trend para ver los inicios de los intervalos UTC y los recuentos agrupados exactos. Son hallazgos conservados, así que la falta de cobertura de incidentes no puede interpretarse como ausencia de ataques.

Las pantallas murales usan sesiones de quiosco. En Account, un operador da nombre a la pantalla y selecciona Create display code. La pantalla pega el código de un solo uso en el formulario de inicio de sesión en un plazo de diez minutos; su sesión es de solo lectura, se limita a las estadísticas y caduca en un máximo de doce horas. La página de la cuenta borra el código mostrado al navegar o al ocultarse. Ocultarla no revoca una concesión sin usar; el plazo de canje sigue vigente. Los códigos nunca deben ir en las URL. Traffic y Security comparten la pantalla: Security muestra tendencias agregadas de los módulos y los resultados de las peticiones sin direcciones de incidentes ni pruebas de carga útil. La rotación automática es opcional, está desactivada al principio y se suspende con movimiento reducido, datos obsoletos o Pause.

Los destinos de notificación (webhooks firmados y syslog para picos de denegaciones, bloqueos, miembros inalcanzables y cambios de líder) están en Settings; los secretos de los webhooks necesitan --console-key-file. El tipo de cambio de líder sigue definido para que los destinos guardados conserven su significado, pero ningún nodo lo genera, porque no hay elección de líder. Cada destino tiene su propio periodo de espera y un presupuesto de tres intentos. Los registros de auditoría de entrega muestran los resultados; el historial de la cola completada se limita a siete días y 4.096 eventos. Los webhooks incluyen una Idempotency-Key estable para que los receptores puedan suprimir efectos repetidos tras una finalización de red incierta. Los webhooks se envían por HTTPS, o por HTTP sin cifrar solo a una dirección loopback literal, y el cuerpo de la respuesta se lee hasta 64 KiB. La selección UDP/TCP de syslog se aplica solo a las notificaciones salientes, con independencia del tráfico web protegido. Las pruebas manuales registran la intención y la finalización en Audit y actualizan el resultado del destino; una finalización de auditoría no confirmada se muestra explícitamente antes de que un operador reintente.

Settings también controla la retención: de uno a 90 días para el historial por minuto, de uno a siete para las clasificaciones, de uno a 30 para los incidentes y de uno a 365 para la auditoría. Los valores superiores son los valores por defecto; las clasificaciones mantienen su cuota de 512 MiB. Guardar un valor de retención requiere confirmación porque la limpieza elimina definitivamente los registros más antiguos en lotes acotados. Aumentar el valor después no restaura el historial borrado. Las ediciones obsoletas se rechazan y los cambios correctos aparecen en Audit.

Las páginas de respuesta (desafío, denegada, tasa limitada, bloqueada, sobrecargada) se pueden editar en Settings como HTML acotado con marcadores fijos; los borradores se previsualizan en una pestaña aislada y las páginas guardadas se sirven a partir de la siguiente instantánea de políticas.

Flujos de trabajo de políticas en la página Policies: reordenar reglas gestionadas, reproducir un borrador contra los hallazgos de inspección conservados, gestionar grupos IP y bloqueos de países fijados a la generación GeoIP activa, y exportar o importar de forma atómica el conjunto gestionado (también sibuna console policies export y sibuna console policies import --file <set.json>). Una importación es una petición que lleva de 1 a 128 documentos de 4 KiB como máximo cada uno y 256 KiB como máximo en total; la nota de la página indica la importación por línea de comandos para conjuntos de más de unos 96 KiB. Las reglas aplicadas muestran las coincidencias registradas hoy, minigráficas por hora y una tabla accesible. Una coincidencia es una evaluación correcta de un comparador declarativo: cuentan las reglas WEIGH que coinciden y la primera coincidencia terminal; una decisión anterior de inspección o de reputación puede impedir la evaluación. Las pruebas privadas no incrementan estos contadores. Compare rule hits fija dos periodos cerrados para un nodo registrado. El historial de revisiones ofrece Compare hits around this edit, que excluye el minuto de la edición y usa periodos disponibles iguales hasta la duración elegida. Los filtros opcionales por revisión aplicada mantienen las generaciones no relacionadas fuera de la comparación. El arranque, la conmutación, las escrituras ausentes y la retención dejan huecos de cobertura visibles; los porcentajes requieren cobertura completa en ambos lados. Las observaciones de reglas y los resúmenes por hora y por día siguen el ajuste de retención por minuto. Un cambio observado en torno a una edición es una comparación, no una prueba de que la edición causara el cambio de tráfico.

Importar una generación GeoIP posterior no actualiza automáticamente las filas de reputación existentes derivadas de países. Previsualiza la acción del país para comparar los prefijos añadidos, conservados y eliminados; recorre página a página la diferencia revisada antes de aplicarla. La sustitución elimina las filas obsoletas que pertenecen a ese país y conserva los prefijos gestionados de forma independiente. Una generación o una revisión de política cambiadas requieren una vista previa nueva, y las ediciones independientes que se solapan se rechazan. La página Events contiene los hallazgos WAF conservados y los incidentes del honeypot; no es un registro de accesos completo. Con GeoIP cargado, el hilo de almacenamiento registra el país y la generación de cada incidente en la transacción del lote de incidentes. Es una atribución en el momento de persistir, no una ubicación reconstruida en el momento de la petición. Las importaciones posteriores no modifican las asignaciones registradas. El filtro de país acepta un código de dos letras en mayúsculas, unknown para una dirección ausente de la generación cargada, o not_recorded para un incidente sin datos de asignación. Los grupos de origen indican explícitamente los países mixtos o la cobertura. La acción View events del globo mantiene el nodo seleccionado y abre los incidentes conservados del país durante la última hora. La vista Security de la página Statistics combina las tasas en vivo de límites de tasa, desafíos y bloqueos con los hallazgos conservados de inspección y del honeypot durante una hora, un día, siete días o treinta días. Los enlaces de categoría, origen y ruta abren el flujo normal de incidentes con el mismo nodo y un límite temporal fijo. Aplicar filtros de incidentes inicia un periodo nuevo. Los hallazgos incluyen registros de auditoría y son distintos de los totales de peticiones bloqueadas; la atribución ausente de reputación y de coincidencias de reglas se muestra como no registrada. Los filtros de eventos y de auditoría mantienen las etiquetas junto a sus controles, alinean la acción Apply por separado y adaptan sus columnas al ancho de contenido disponible. Un único WebSocket autenticado sobrevive a la navegación y transporta estadísticas, resúmenes de incidentes, el estado de los nodos, revisiones de políticas, desafíos y resúmenes de auditoría. Los nuevos registros de incidentes y de auditoría esperan detrás de Load latest records para que la tabla no se mueva mientras se lee. Las actualizaciones de políticas muestran las revisiones confirmadas y aplicadas actuales sin sustituir un borrador abierto. Los contadores de flujo se actualizan en vivo; actualiza explícitamente una partición de tiempos de desafío seleccionada que no sea la predeterminada. Las consultas históricas, las lecturas de detalle y las modificaciones siguen siendo peticiones HTTP.

Los fragmentos de página se pueden guardar como marcadores; Back y Forward vuelven a abrir páginas autenticadas. La barra lateral también recuerda en este navegador las preferencias de tema y de espaciado, con System como tema por defecto. SID 0007 está en estado Committed. La consola supera sus fixtures de referencia y sus flujos de trabajo en el navegador en Chromium sin interfaz gráfica (cargo xtask browser console, criterio 5 de SID 0010). Su batería de pruebas de extremo a extremo es cmd/sibuna/tests/console_*.rs, cuyos escenarios de clúster PostgreSQL se ejecutan cuando se define SIBUNA_TEST_DATABASE_URL. SID 0010 registra que, con la consola compilada y desactivada, solo con almacenamiento, o activada y en reposo, las 16 cargas de trabajo del producto se mantienen a menos de un 1% del daemon compilado sin ella, lo que está dentro del ruido. El criterio formal de aislamiento de SID 0007, con ocho paneles activos bajo carga, aún no se ha medido (parte VIII). La aplicación WebAssembly completa tiene un techo de 768 KiB sin comprimir, que el script de compilación del daemon impone haciendo fallar la compilación, y un umbral de revisión de 640 KiB. En la 1.0.0-beta.3 el módulo mide 724.330 bytes (272.568 con gzip), por encima del umbral de revisión, lo que SID 0007 registra para su revisión. Estos límites del proyecto dejan margen para los flujos de trabajo de la consola; no sustituyen a las mediciones de carga y de capacidad de respuesta en el navegador. La memoria lineal del módulo crece bajo demanda hasta un máximo declarado de 16 MiB.

Topologías de despliegue

Proxy inverso

Una petición pasa por los bloqueos locales y el límite de tasa, y después por la inspección y la política. Un DENY lleva a Denegar. Un ALLOW lleva al origen o a un éxito de autenticación. Un CHALLENGE comprueba el MAC de la sesión: una sesión válida lleva al origen, y una ausente o no válida lleva a un desafío nuevo.
Fig. 24 Enrutamiento de peticiones en el modo de protección Shield
sibuna --port 80 --upstream-host 127.0.0.1 --upstream-port 3000 \
       --secret-file /etc/sibuna/secret --difficulty 16 --algorithm posw

Las peticiones admitidas llegan al origen con las cabeceras X-Forwarded-For, X-Forwarded-Proto, X-Real-IP, X-Sibuna-Status y X-Sibuna-Rule. Se eliminan las cabeceras hop-by-hop, los campos que escribe el propio Sibuna y los campos de reenvío alternativos (Forwarded, X-Forwarded-Host, X-Forwarded-Port), también cuando un cliente escribe sus nombres con guiones bajos (X_Forwarded_For). X-Real-IP es el cliente según el cual se juzgó la petición. X-Forwarded-For es solo el par del socket, nunca una entrada escrita por el cliente; cuando la identidad reenviada es de confianza, es la cadena recibida seguida del par del socket. Por tanto, los orígenes deben leer el cliente de X-Real-IP o desde la derecha de X-Forwarded-For, nunca de su entrada más a la izquierda. La ruta que recibe el origen es la forma normal que juzgó la política (SID 0009); una ruta sin forma normal recibe 400.

Las actualizaciones a WebSocket de HTTP/1.1 pasan por las comprobaciones de admisión y de políticas antes de que se acepte el handshake del origen. La negociación de subprotocolos y extensiones sigue siendo de extremo a extremo. Dos hilos retransmiten los bytes, uno por dirección, cada uno con un búfer fijo, incluidos los bytes leídos por adelantado y los cierres parciales; por tanto, una conexión actualizada ocupa dos hilos, y el número de hilos de conexión puede llegar al doble de --max-connections cuando todas las conexiones están actualizadas. Los sockets actualizados siguen dentro de la cuota normal de conexiones y del registro de apagado, pero usan --websocket-idle-timeout (300 segundos por defecto) con independencia del plazo de inactividad HTTP. El tráfico en cualquiera de las dos direcciones renueva esa cota, pero un par que no acepta ningún byte durante todo el periodo termina la retransmisión, por muy activa que esté la otra dirección. Las tramas posteriores al handshake no son entradas de la inspección WAF. HTTPS/WSS usa un proxy de entrada que termina TLS delante del puerto de escucha HTTP/1.1 privado de Sibuna; Sibuna no termina por sí mismo el TLS del navegador.

El proxy de entrada puede negociar HTTP/2 con los navegadores y reenviar HTTP/1.1 a Sibuna. El soporte nativo de HTTP/2 en Sibuna se aplaza a una actualización posterior; este esquema no ofrece semántica HTTP/2 de extremo a extremo para aplicaciones como gRPC nativo.

Los cuerpos de petición con Content-Length fluyen a través de búferes fijos, conservando los bytes y las cabeceras MIME. Las subidas multipart conservan los delimitadores, los nombres de campo repetidos, los nombres de archivo y los tipos de las partes. El WAF examina como máximo los primeros 8 KiB del cuerpo: los metadatos multipart y los campos que no son archivos siguen siendo entradas de la inspección de texto, mientras que el contenido de los archivos es opaco. Una parte cuyo filename está vacío es un campo ordinario. Un cuerpo de un tipo MIME de nivel superior binario reconocido (imágenes salvo SVG, audio, vídeo, PDF, ZIP, gzip, 7z, protobuf y octet-stream) es opaco solo cuando su prefijo también parece binario, es decir, cuando al menos un byte de cada dieciséis es un byte de control distinto de tabulador, salto de línea, tabulador vertical, salto de página y retorno de carro; en otro caso se inspecciona como texto (SID 0004). JSON, XML, SVG, los formularios URL-encoded y los tipos desconocidos mantienen la inspección de texto. Los metadatos MIME ambiguos o mal formados recurren a la inspección de texto. El análisis multipart se limita a 32 partes y 2 KiB de cabeceras por parte dentro de ese mismo prefijo, y acepta el relleno de transporte de RFC 2046 tras un delimitador.

Esto es compatibilidad con las subidas, no validación de archivos ni análisis de malware. El backend debe imponer los tipos MIME aceptados en lugar de fiarse de la declaración Content-Type del cliente. Los campos posteriores al prefijo de inspección, incluidos los que siguen a un archivo subido grande, no se inspeccionan. Las cargas útiles comprimidas no se descomprimen para inspeccionarlas. Las subidas siguen pasando las comprobaciones de admisión, ruta, consulta y cabeceras, y siguen sujetas a los plazos de conexión. Los cuerpos de petición chunked se decodifican dentro del búfer de la conexión antes de la inspección (SID 0009). Un cuerpo que termina dentro del búfer llega al backend con Content-Length. Si es más largo, Sibuna lo vuelve a dividir en chunks, uno por lectura, así que el backend nunca ve los tamaños de chunk, las extensiones ni los trailers del cliente. Una línea de chunk con un CR o un LF sueltos, espacios en blanco alrededor del tamaño, una extensión mal formada o más de 4 KiB se rechaza con 400. Lo mismo ocurre con una sección de trailers de más de 16 KiB. Transfer-Encoding con otra codificación recibe 501. Los backends que no pueden analizar peticiones chunked siguen recibiendo Content-Length para cuerpos de menos de unos 44 KiB. Una conexión al origen que transportó un cuerpo de petición se cierra tras su intercambio y nunca vuelve al conjunto de conexiones. Los clientes que esperan 100-continue lo reciben localmente antes de enviar el cuerpo; las expectativas no admitidas reciben 417. La cabecera Expect se consume antes de reenviar al backend.

Forward-auth detrás de un proxy de entrada

En --mode forward_auth el daemon responde a la subpetición del proxy de entrada con 200 (más las cabeceras de auditoría X-Sibuna-Status, X-Sibuna-Rule y X-Sibuna-Rule-Hash), 401 para un desafío, 403 para una denegación o 429 cuando se limita la tasa. El proxy de entrada debe reenviar la dirección del cliente y la URL original; el modo forward-auth confía en ellas por defecto. Asocia este puerto de escucha a una dirección privada para que solo pueda conectarse el proxy de entrada. X-Forwarded-Uri (Caddy) o X-Original-URI (Nginx), y X-Forwarded-Method, restauran la petición de la aplicación para evaluar las políticas; la ruta original se lleva a su forma normal, igual que la ruta de una línea de petición. Los campos de URL original duplicados o contradictorios, y una URI original que no está en forma de origen, se rechazan con 400. Las rutas internas del daemon usan siempre la URI real de la petición. Forward-auth no inspecciona un cuerpo que el proxy de entrada omite.

map $http_upgrade $sibuna_connection_upgrade {
    default upgrade;
    '' close;
}
server {
    listen 443 ssl;
    location / {
        auth_request /__sibuna_auth;
        auth_request_set $sibuna_auth_status $upstream_status;
        auth_request_set $sibuna_retry_after $upstream_http_retry_after;
        auth_request_set $sibuna_status $upstream_http_x_sibuna_status;
        auth_request_set $sibuna_rule $upstream_http_x_sibuna_rule;
        auth_request_set $sibuna_rule_hash $upstream_http_x_sibuna_rule_hash;
        error_page 401 = @sibuna_challenge;
        error_page 500 = @sibuna_auth_error;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $sibuna_connection_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Sibuna-Status $sibuna_status;
        proxy_set_header X-Sibuna-Rule $sibuna_rule;
        proxy_set_header X-Sibuna-Rule-Hash $sibuna_rule_hash;
        proxy_read_timeout 300s;
        proxy_pass http://127.0.0.1:3000;
    }
    location = /__sibuna_auth {
        internal;
        proxy_pass http://127.0.0.1:8080/;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
        proxy_set_header X-Original-URI $request_uri;
        proxy_set_header X-Forwarded-Method $request_method;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Uri "";
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header User-Agent $http_user_agent;
        proxy_set_header Cookie $http_cookie;
    }
    location @sibuna_challenge {
        rewrite ^ /__sibuna/challenge break;
        proxy_pass http://127.0.0.1:8080;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
        proxy_set_header X-Original-URI $request_uri;
        proxy_set_header X-Forwarded-Method $request_method;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    location @sibuna_auth_error {
        add_header Retry-After $sibuna_retry_after always;
        if ($sibuna_auth_status = 429) { return 429; }
        return 503;
    }
    location /__sibuna/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}
example.com {
    handle /__sibuna/* {
        reverse_proxy localhost:8080
    }
    handle {
        forward_auth localhost:8080 {
            uri /
            header_up X-Forwarded-For {remote_host}
            header_up -X-Original-URI
            copy_headers X-Sibuna-Status X-Sibuna-Rule X-Sibuna-Rule-Hash
        }
        reverse_proxy localhost:3000
    }
}

El espacio de nombres /__sibuna/* (página intermedia, desafío, verificación, recursos del solucionador) debe llegar directamente al daemon en ambas recetas. La página de error de nginx transmite la URI y el método originales para que la página intermedia lleve el requisito que decidió la autorización; sin ellos la página sigue funcionando, y la emisión recurre a evaluar la URL que indica el navegador. Caddy aporta por sí mismo los metadatos de URI y método originales. Los bloques handle exclusivos garantizan que las rutas de desafío y de verificación no entren en la comprobación previa de forward-auth. Nginx requiere las cabeceras Upgrade/Connection explícitas que se muestran arriba para los WebSockets de la aplicación. El gestor de errores de Nginx sirve la ruta interna del desafío sin tomar una segunda decisión de autorización ni consumir el cuerpo de la subida. Su módulo de autenticación acepta directamente solo 2xx, 401 y 403, así que el ejemplo traduce un error de autenticación por límite de tasa de vuelta a 429 con Retry-After; los demás fallos de autorización siguen denegándose con 503. Nginx aporta su propio cuerpo 403, mientras que Caddy reenvía la página de denegación de Sibuna. Ambas recetas sustituyen las cabeceras de auditoría de Sibuna entrantes por la respuesta de autorización real. Configura en el proxy de entrada los certificados TLS normales y los límites de subida y de plazos de la aplicación; los ejemplos muestran la lógica de enrutamiento. El repositorio aún no prueba estas recetas contra proxies de entrada reales; las reglas de metadatos reenviados de las que dependen están cubiertas por pruebas unitarias en sibuna-http.

Huellas JA4 desde el proxy de entrada

Una huella JA4 resume cómo abre un cliente una conexión TLS. Se calcula a partir del primer mensaje de handshake del cliente, el ClientHello. La biblioteca TLS del cliente fija ese mensaje antes de que se envíe ningún byte HTTP, así que un cliente no puede cambiar su huella desde dentro de sus peticiones HTTP. Los navegadores, las bibliotecas y los bots difieren en ella. Esto hace de JA4 una señal más fuerte que un valor de User-Agent, que cualquier cliente puede escribir como quiera (SID 0014). JA4 lo definió FoxIO. Una huella tiene 36 caracteres en tres partes unidas por _:

t13d1516h2_8daaf6152771_02713d6af862
^^^^^^^^^^ ^^^^^^^^^^^^ ^^^^^^^^^^^^
a          b            c

a  protocolo (t TCP, q QUIC, d DTLS), versión de TLS (13 es TLS 1.3),
   d con SNI o i sin él, número de cifrados (dos dígitos),
   número de extensiones (dos dígitos), código ALPN (h2 es HTTP/2)
b  hash hexadecimal en minúsculas, de 12 dígitos, de los conjuntos
   de cifrado ordenados
c  hash hexadecimal en minúsculas, de 12 dígitos, de las extensiones
   y los algoritmos de firma ordenados

Solo el componente que termina TLS ve el ClientHello, así que solo él puede calcular JA4. Sibuna no termina TLS: sirve HTTP/1.1 sin cifrar detrás de un proxy de entrada, y el proxy de entrada habla TLS, HTTP/2 y HTTP/3 con los navegadores. Varios proxies de entrada ya calculan JA4. Por eso dejamos que el proxy de entrada calcule la huella y la envíe en una cabecera de petición, y Sibuna la lee de ahí.

--ja4-header <name> nombra esa cabecera. Está desactivada por defecto y no tiene nombre por defecto; siempre indicamos el nombre de la cabecera que usa el proxy de entrada. Sibuna guarda el nombre en minúsculas y lo compara sin distinguir mayúsculas. Rechaza los nombres de los campos que él mismo escribe o elimina (X-Forwarded-*, X-Real-IP, X-Sibuna-* y Forwarded, también con _ en lugar de -). Cuando la opción está activa, el banner de arranque imprime una línea como JA4: from cf-ja4 (trusted).

La cabecera solo se lee si los campos reenviados son de confianza. Es la misma decisión que rige X-Forwarded-For: --trust-forwarded, o el modo forward-auth sin --no-trust-forwarded. Si el par no es de confianza, la cabecera se ignora. Si es de confianza, una petición lleva una huella cuando está presente exactamente un campo con ese nombre y su valor tiene la forma de JA4. Un valor mal formado, o un campo repetido, deja la petición sin huella. Dos contadores lo reflejan: sibuna_ja4_present_total cuenta las peticiones con huella, y sibuna_ja4_invalid_total cuenta las peticiones cuya cabecera estaba mal formada o repetida. Una petición de un par que no es de confianza no incrementa ninguno de los dos contadores.

En modo proxy inverso, el origen solo ve la cabecera cuando Sibuna confía en ella. Si no confía en ella, Sibuna elimina todos los campos con ese nombre de la petición que envía al origen, también cuando un cliente escribe el nombre con _ en lugar de -. Por tanto, un cliente no puede entregar al origen una huella falsificada con ese nombre. Si confía en ella, el campo pasa sin cambios con su grafía exacta, y un alias con _ se sigue eliminando. Sin --ja4-header, un campo con ese nombre es un campo corriente.

Cloudflare. La transformación gestionada "Add bot protection headers" añade cf-ja4 a la petición enviada al origen, junto a cf-bot-score, cf-verified-bot y cf-ja3-hash. Requiere un plan Enterprise con Bot Management. Un proxy de entrada situado entre Cloudflare y Sibuna debe pasar el campo sin cambios. Arrancamos Sibuna con:

sibuna --ja4-header cf-ja4 --trust-forwarded -s /etc/sibuna/secret

El proxy de entrada situado delante de Sibuna debe aceptar conexiones solo de las direcciones de Cloudflare; de lo contrario, un cliente puede saltarse Cloudflare y enviar su propio cf-ja4.

nginx. El ja4-nginx-module de FoxIO calcula JA4 dentro de nginx y lo expone como $http_ssl_ja4. Necesita nginx 1.26 o posterior con el parche de captura del ClientHello del módulo, compilado con --with-http_ssl_module. proxy_set_header sustituye el campo del cliente con el mismo nombre, así que cada location que llega a Sibuna fija la cabecera por sí misma:

# Proxy inverso: Sibuna se ejecuta con --ja4-header x-ja4 --trust-forwarded
location / {
    proxy_set_header X-JA4 $http_ssl_ja4;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_pass http://127.0.0.1:8080;
}

# Forward-auth: Sibuna se ejecuta con --mode forward_auth --ja4-header x-ja4
location = /__sibuna_auth {
    internal;
    proxy_pass http://127.0.0.1:8080/;
    proxy_set_header X-JA4 $http_ssl_ja4;
    # ... los demás campos de la receta de forward-auth anterior
}

En la receta de forward-auth, la misma línea proxy_set_header X-JA4 $http_ssl_ja4; va también en @sibuna_challenge y en location /__sibuna/. Una location que la omita pasa a Sibuna el propio X-JA4 del cliente, y Sibuna confía en él.

Apache Traffic Server. El plugin ja4_fingerprint se activa con la línea ja4_fingerprint.so en plugin.config. No tiene opciones. Añade un campo ja4 con la huella, y un campo x-ja4-via con el nombre del proxy, a las peticiones de cada conexión TLS. Arrancamos Sibuna con --ja4-header ja4 --trust-forwarded. La documentación del plugin no dice si sustituye un campo ja4 que haya enviado el cliente. Debemos comprobarlo para nuestra versión, o eliminar el campo del cliente antes de que el plugin añada el suyo, antes de confiar en el valor.

Una regla comprueba una huella con el campo ja4 (parte X, Esquema de políticas). El valor es o bien una huella completa, que debe ser igual, o bien un prefijo seguido de *, por el que debe empezar la huella. "*" por sí solo coincide con cualquier huella. Una petición sin huella nunca coincide con una regla ja4. El cargador rechaza un patrón con el que ninguna huella podría coincidir, como T13D* en mayúsculas, con INVALID POLICY JA4. La comparación opera sobre bytes y no asigna memoria.

{ "rules": [
    { "name": "deny-known-scanner", "action": "DENY",
      "ja4": "t13i010400_0f2cb44170f4_5c4c70b73fa0" },
    { "name": "weigh-no-sni", "ja4": "t13i*", "action": "WEIGH", "weight": 15 },
    { "name": "weigh-headless", "user_agent": "Headless", "action": "WEIGH",
      "weight": 30 },
    { "name": "challenge-tls12-checkout", "path": "/checkout/*", "ja4": "t12*",
      "action": "CHALLENGE" }
] }

La primera regla deniega exactamente una huella; el valor es un ejemplo, no un escáner conocido. Las dos siguientes añaden peso a la puntuación de la petición en lugar de decidir: un cliente TLS 1.3 que no envió nombre de servidor, y un navegador sin interfaz gráfica por su User-Agent. Si ninguna regla posterior decide antes, una petición que muestra ambas señales puntúa 45 y alcanza el umbral de denegación por defecto de 40, mientras que una petición que muestra solo una recibe un desafío. La última regla desafía, por prefijo, a todo cliente que negoció TLS 1.2 sobre TCP en la ruta de pago. Desafía en lugar de denegar porque muchos clientes legítimos más antiguos siguen usando TLS 1.2. Las reglas deberían combinar JA4 con otras señales de este modo. Un valor JA4 nombra una biblioteca TLS y su configuración, no una persona ni un dispositivo. Muchos clientes comparten una biblioteca, y las bibliotecas especializadas pueden imitar el ClientHello de un navegador. JA4 eleva el coste de la automatización; no demuestra la identidad. Por el mismo motivo, Sibuna asocia los bloqueos y la reputación a la dirección y nunca a la huella.

Los incidentes (denegaciones del WAF, accesos al honeypot y hallazgos de auditoría) registran la huella de su petición cuando esta llevaba una, en la columna security_incidents.ja4. La consola la muestra en la evidencia del incidente como "JA4 fingerprint", con el valor o "Not recorded". Los filtros de Events aceptan una huella o un prefijo. El editor de reglas gestionadas tiene un campo JA4, guardado en policies.ja4_pattern, y el formulario de prueba de políticas acepta una huella.

Política declarativa

{
  "default_action": "CHALLENGE",
  "waf": true,
  "thresholds": { "challenge_at": 10, "deny_at": 40, "bits_step": 5 },
  "ip_rules": { "10.0.0.0/8": "ALLOW", "192.0.2.0/24": "DENY", "2001:db8::/32": "DENY" },
  "rules": [
    { "name": "deny-cf-workers", "headers": { "CF-Worker": ".*" }, "action": "DENY" },
    { "name": "deny-amazonbot", "user_agent": "Amazonbot", "action": "DENY" },
    { "name": "api-with-key", "path": "/api/*", "headers": { "X-Api-Key": ".*" },
    "action": "ALLOW" },
    { "name": "protect-checkout", "path": "/checkout/*", "action": "CHALLENGE",
      "challenge": { "difficulty": 20, "algorithm": "posw" } },
    { "name": "headless", "user_agent": "Headless", "action": "WEIGH", "weight": 30 },
    { "name": "internal-vpc", "remote_addresses": ["10.0.0.0/8", "fd00::/8"],
    "action": "ALLOW" }
  ]
}

El cargador falla de forma segura (fail closed): una clave desconocida, una acción mal escrita, una dirección mal formada o un número fuera de rango rechazan todo el archivo, el diagnóstico nombra la regla y el campo, y el daemon no arranca. Una línea de comandos con una opción desconocida o un valor fuera de rango se rechaza de la misma manera. rules sustituye a la tabla integrada cuando está presente; ip_rules alimenta el trie de reputación, que escala a miles de prefijos; waf: false selecciona el modo de protección Gate desde el archivo. Otras dos claves forman parte del esquema (parte X): inspection fija cada categoría del WAF en disabled, audit o enforce, y el objeto limits de una regla le da una cuota propia. El campo ja4 de una regla compara la huella JA4 que reenvió un proxy de entrada de confianza, de forma exacta o por un prefijo seguido de *; necesita --ja4-header (véase "Huellas JA4 desde el proxy de entrada"). Los patrones de ruta coinciden con la ruta de la petición en forma normal (SID 0003), así que un patrón debe escribirse en esa forma.

Almacenamiento persistente y clúster

Los hilos de peticiones introducen los incidentes en un anillo MPSC de 512 posiciones. El hilo de almacenamiento los extrae y escribe lotes mediante sqlx en el archivo SQLite o en la base de datos PostgreSQL que contiene policies, ip_reputation, security_incidents y el índice de texto completo. Cuando cambia la revisión de la política, reconstruye el motor y lo publica como un Arc, que leen los hilos de peticiones. Los demás nodos del clúster comparten la base de datos PostgreSQL y reciben NOTIFY sibuna_policy.
Fig. 25 La arquitectura de almacenamiento: los workers nunca se bloquean esperando a la base de datos

--data-dir /var/lib/sibuna abre el archivo SQLite /var/lib/sibuna/sibuna.db (modo WAL, synchronous=NORMAL, un tiempo de espera ante bloqueo (busy timeout)) e inicia el hilo de almacenamiento. --database-url (o --database-url-file) se conecta en su lugar a una base de datos PostgreSQL. El hilo de almacenamiento posee un runtime tokio de un solo hilo y un pequeño conjunto de conexiones; es el único lugar que ejecuta SQL. Al arrancar, cada vez que cambia la revisión de la política (una escritura en policies, ip_reputation o policy_inspection) y cuando caduca una entrada de reputación, el hilo reconstruye el motor a partir del archivo de políticas y de la base de datos y lo publica; las peticiones nunca esperan a SQL. Una reconstrucción lee la revisión antes y después de cargar, y descarta su candidato si entretanto un escritor confirmó una transacción.

Esquema

Tabla 25 Tablas principales
Tabla Propósito y clave
policy_revision La revisión de la política, una fila; la hacen avanzar disparadores en las tres tablas de políticas.
policies Reglas dinámicas ordenadas, con clave id. La columna ja4_pattern, que admite nulos, guarda el criterio JA4 de una regla, de 37 bytes como máximo.
policy_inspection El modo WAF guardado por categoría, una fila.
ip_reputation Puntuaciones, recuentos de coincidencias y caducidad, con clave por dirección o prefijo.
incident_receipts El recibo duradero de incidentes de cada nodo (la secuencia siguiente a su último lote confirmado), con clave por nodo.
security_incidents Un registro de evento acotado con su embedding de 64 componentes (256 bytes), con clave node_id << 40 | sequence. La columna ja4, que admite nulos, guarda la huella JA4 de la petición, de exactamente 36 bytes.
incidents_fts En SQLite: una tabla FTS5 sobre los tokens canónicos de las rutas y las cargas útiles. En PostgreSQL los mismos tokens son la columna tsvector search de security_incidents con un índice GIN.
sibuna_schema Cada migración aplicada, con clave por componente y versión.

El esquema principal es crates/storage/src/schema.rs, escrito una vez por dialecto. Con la consola, el componente console añade 33 tablas cuyos nombres empiezan por console_ (SID 0013; crates/console-storage/src/schema/). Las migraciones se numeran por componente y se compilan en el binario. La migración 2 del núcleo añade las dos columnas JA4; una base de datos creada antes de ella se migra al arrancar. Todas las migraciones pendientes se ejecutan en una sola transacción, y un nodo rechaza una base de datos cuya versión de un componente es más nueva que la que conoce. Un esquema impreso abreviado no es un script de actualización. Las tablas SQLite son STRICT, y las restricciones CHECK reflejan los tipos de Rust, así que la base de datos rechaza una fila que el daemon no podría representar. Los valores enumerados se guardan en minúsculas: una escritura directa de 'DENY' se rechaza.

Operación

Usa el shell sqlite3 sobre sibuna.db (el modo WAL le permite leer mientras el daemon se ejecuta), o psql sobre la base de datos del clúster:

-- Añade una regla dinámica; cada nodo reconstruye el motor en su siguiente ciclo.
INSERT INTO policies (id, name, priority, path_pattern, action, difficulty, algorithm,
  header_matchers, cidr_matchers, weight, enabled, created_at, updated_at)
VALUES ('p-checkout', 'protect-checkout', 10, '/checkout/*', 'challenge', 20, 'posw',
  '{"X-Api": "v2"}', '["10.0.0.0/8"]', 0, 1, unixepoch(), unixepoch());

-- Bloquea una dirección en todo el clúster durante un día.
INSERT INTO ip_reputation (ip_or_cidr, reputation_score, banned_until,
  trigger_rule, hits, last_seen)
VALUES ('198.51.100.7', -100, unixepoch() + 86400, 'analyst', 1, unixepoch());

-- Análisis forense: búsqueda de texto completo en las cargas útiles registradas.
SELECT s.id, s.client_ip, s.violation_category, s.path, s.campaign_id
FROM incidents_fts f JOIN security_incidents s ON s.id = f.rowid
WHERE incidents_fts MATCH 'union' ORDER BY rank LIMIT 20;

Las sentencias están escritas para SQLite. En PostgreSQL, enabled es TRUE, la hora es CAST(extract(epoch FROM now()) AS BIGINT) en lugar de unixepoch(), y la búsqueda lee WHERE search @@ CAST('union' AS tsquery) sobre security_incidents. path y offending_payload contienen los bytes en bruto de la petición (BLOB o BYTEA). La base de datos rechaza una escritura directa que incumple una restricción, y esa escritura nunca llega a un nodo. En PostgreSQL el disparador de revisión también emite NOTIFY sibuna_policy, así que los demás nodos ejecutan su ciclo de inmediato; el sondeo sigue siendo la garantía.

Las puntuaciones iguales o inferiores a \(-50\) se convierten en prefijos deny en el trie, las iguales o superiores a \(50\) se convierten en allow, y banned_until acota el bloqueo. Los accesos al honeypot insertan automáticamente un registro de \(-100\), así que, con una base de datos PostgreSQL compartida, una trampa activada en un nodo bloquea la dirección en todos ellos.

Un recibo de transacción hace que reintentar sea seguro

El hilo de almacenamiento reúne como máximo 32 registros pendientes y construye una transacción SQL. La transacción inserta incidentes, actualiza el índice de texto completo y aplica los cambios de reputación del honeypot. Cada emisor (nodo) tiene un recibo monótonamente creciente, su fila de incident_receipts. Cada sentencia que modifica datos está protegida por ese recibo; la transacción lo hace avanzar en último lugar, y nunca hacia atrás.

Una confirmación fallida conserva el lote pendiente en memoria e incrementa incident_write_failures. El ciclo sigue intentando el sondeo de políticas. Una cola llena de 512 registros cuenta incidents_dropped; nunca bloquea una respuesta HTTP esperando al disco. El lote pendiente añade espacio para 32 registros. Si el proceso muere antes de confirmar, pueden perderse datos en cola: es un camino forense asíncrono y acotado, no una cola de mensajes duradera en el momento de encolar.

Agrupación en campañas

La carga útil de cada incidente se representa como un vector unitario de 64 dimensiones mediante el truco del hashing sobre trigramas de bytes (con los dígitos unificados y las mayúsculas convertidas en minúsculas) y se guarda como 256 bytes en security_incidents.embedding. El hilo de almacenamiento mantiene en memoria los 16.384 embeddings más recientes de todos los nodos (4 MiB), actualizados desde la base de datos en cada ciclo. Antes de insertar, busca el más cercano de ellos, incluidos los registros anteriores del mismo lote; si la distancia coseno es como máximo \(0.35\), el nuevo incidente se une al campaign_id de ese incidente; en otro caso, inicia una campaña con el nombre de su propio identificador. Los incidentes más antiguos que la ventana no se comparan. La similitud es una heurística: los ejemplos de regresión agrupan cargas útiles SQL relacionadas, pero eso no garantiza que cada par de ataques comparta campaña. No se ejecuta ningún modelo ni se entrena nada.

Funcionamiento en clúster

Un clúster es un conjunto de nodos que comparten una única base de datos PostgreSQL. Compila con la feature postgres-tls (cargo build --release -p sibuna --features postgres-tls; implica postgres) e inicia cada miembro con la base de datos y un id de nodo propio:

sibuna --database-url-file /etc/sibuna/database-url --cluster-node 1 \
       --secret-file /etc/sibuna/secret

Todos los miembros deben usar el mismo secreto maestro y un --cluster-node único de 1 a 8.388.607. El archivo de la URL contiene una URL postgres:// y solo debe poder leerlo su propietario; el banner nunca imprime la URL. Las escrituras van al primario de PostgreSQL. El hilo de almacenamiento de cada nodo ve el cambio de la revisión confirmada (mediante NOTIFY o por sondeo) y reconstruye su motor.

Los nodos acceden a la base de datos compartida a través de la red, así que ciframos y verificamos esa conexión. Damos al servidor un certificado firmado por nuestra propia autoridad de certificación, y nombramos esa autoridad en la URL: postgres://sibuna:...@db.internal:5432/sibuna?sslmode=verify-full&sslrootcert=/etc/sibuna/db-ca.pem. En el servidor aceptamos TCP solo mediante líneas hostssl en pg_hba.conf.

Al arrancar, el daemon imprime una línea sobre la conexión a la base de datos. Con verify-full indica que el certificado y el nombre de host están verificados. Con cualquier modo más débil imprime una advertencia y una pista. Sin sslmode el modo es prefer: la conexión solo se cifra si el servidor ofrece TLS, y el servidor no se verifica. Un daemon compilado sin postgres-tls rechaza require, verify-ca y verify-full y nombra la feature que falta; nunca recurre a una conexión sin cifrar. Un certificado rechazado detiene el arranque de inmediato; la pista nos pide comprobar sslrootcert y que el host de la URL sea un nombre del certificado del servidor. sslrootcert añade nuestra autoridad al almacén de confianza del sistema; no elimina las autoridades del sistema (SID 0011, SID 0012).

Sibuna no replica una base de datos propia y no elige líder. La replicación, la conmutación por error y las copias de seguridad corresponden a PostgreSQL (replicación en streaming, Patroni o un servicio gestionado). La vista de nodos de la consola no tiene líder: muestra el rol single para un nodo SQLite y unknown para un nodo PostgreSQL, y quorum significa solo que el último viaje de ida y vuelta del nodo a la base de datos tuvo éxito. Si la base de datos es inalcanzable, el último motor publicado sigue sirviendo, los incidentes se encolan en el anillo acotado y se descartan con un contador cuando este se llena, y el hilo de almacenamiento reintenta con espera exponencial; un nodo conserva su última política hasta que se vuelve a conectar. No se lee un directorio de datos de Zaxonlite (SID 0005); las políticas se trasladan con sibuna console policies export y sibuna console policies import, y el historial forense no se migra.

Enrutamiento de desafíos en el clúster

Las claves de desafío están vinculadas a --cluster-node; mantén la emisión y la verificación de un desafío en el mismo miembro. Los tokens usan la semilla compartida y funcionan en los demás miembros. Las cuotas de tasa locales no se convierten en cuotas globales, y los reinicios del proceso vacían los conjuntos de desafíos gastados. Con tres nodos sobre un PostgreSQL local, una fila de política escrita directamente llega a los tres en un ciclo, un bloqueo del honeypot en un nodo llega a los demás y los identificadores de incidentes nunca colisionan (crates/storage/tests/multi_node.rs, criterio 2 de SID 0011; se ejecuta cuando se define SIBUNA_TEST_DATABASE_URL).

Empaquetado

Cada versión publicada en GitHub incluye el mismo ejecutable para cada plataforma, compilado desde la etiqueta de la versión con las features por defecto: almacenamiento SQLite y la consola. Los clústeres PostgreSQL necesitan una compilación propia (más abajo).

Plataforma Archivos de la versión
Linux x86-64, ARM64 sibuna-linux-amd64.tar.gz y sibuna-linux-arm64.tar.gz contienen un ejecutable musl estático que funciona en cualquier distribución. sibuna_<version>-1_amd64.deb, sibuna_<version>-1_arm64.deb, sibuna-<version>-1.x86_64.rpm y sibuna-<version>-1.aarch64.rpm lo instalan con un servicio systemd; sibuna-bin-<version>-1-x86_64.pkg.tar.zst hace lo mismo en Arch Linux.
macOS arm64, x86-64 sibuna-macos-arm64.tar.gz, sibuna-macos-amd64.tar.gz, para macOS 12 o posterior.
Windows x86-64 sibuna-windows-amd64.zip contiene sibuna.exe, para Windows 10 o Server 2016 o posterior.
FreeBSD 15.1, OpenBSD 7.9 (amd64) sibuna-<version>-freebsd-15.1-amd64.pkg y sibuna-<version>.tgz.
Homebrew, Kubernetes, contenedores sibuna.rb, helm-sibuna-<version>.tgz y la imagen ghcr.io/insanai/sibuna:<version> para amd64 y arm64, cuyo digest está en IMAGE-DIGEST.txt.
Fuentes sibuna-<version>-source.tar.gz.

Cada archivo comprimido y cada paquete incluyen LICENSE, NOTICE, LICENSES/ (con THIRD-PARTY-RUST.txt, los crates del ejecutable), README.md, SECURITY.md y sibuna.build.json. El manifiesto registra la versión, el commit, el target de Rust, la versión del compilador, las features y el SHA-256 del ejecutable y de sus dos módulos WebAssembly. El flujo de trabajo de publicación arranca cada ejecutable en su propia plataforma antes de publicar nada, e instala, reinstala y elimina los paquetes en Debian, Fedora, Arch Linux, FreeBSD y OpenBSD.

Los archivos no están firmados. Comprobamos cada descarga contra SHA256SUMS de la misma versión antes de instalarla:

sha256sum --ignore-missing -c SHA256SUMS          # Linux
shasum -a 256 --ignore-missing -c SHA256SUMS      # macOS, FreeBSD
sha256 -C SHA256SUMS sibuna-1.0.0-beta.3.tgz      # OpenBSD

En macOS, una descarga hecha con el navegador lleva un atributo de cuarentena que bloquea un ejecutable sin firmar; xattr -d com.apple.quarantine sibuna lo elimina después de la comprobación.

El servicio systemd

Los paquetes Debian, RPM y Arch instalan /usr/bin/sibuna, la unidad sibuna.service, la cuenta sibuna (mediante systemd-sysusers), el script auxiliar /usr/lib/sibuna/seed.sh y el archivo de ajustes /etc/sibuna/service.env. La instalación no arranca nada. Fijamos el origen, un literal IP, en el archivo de ajustes y arrancamos el servicio:

sudoedit /etc/sibuna/service.env      # SIBUNA_UPSTREAM_HOST, SIBUNA_UPSTREAM_PORT
sudo systemctl enable --now sibuna
curl -s http://127.0.0.1:8080/__sibuna/health

El servicio escucha en 127.0.0.1:8080 mientras SIBUNA_HOST y SIBUNA_PORT no indiquen otra cosa. SIBUNA_OPTIONS pasa más opciones, separadas por espacios, por ejemplo --mode forward_auth o --console 127.0.0.1:19446. Antes de cada arranque, seed.sh crea la semilla de admisión /var/lib/sibuna/admission.seed (64 dígitos hexadecimales, modo 0600, propiedad de sibuna) si no existe; nunca sustituye una existente, porque una semilla nueva terminaría todas las sesiones. El daemon guarda su base de datos SQLite en /var/lib/sibuna, un directorio con modo 0700. La unidad se ejecuta sin capabilities, con un sistema de solo lectura (ProtectSystem=strict), /tmp y dispositivos privados, y sin nuevos privilegios.

Una actualización conserva el archivo de ajustes, la semilla y el estado, y no reinicia el servicio; lo reiniciamos después de hacer una copia de seguridad. La desinstalación detiene y desactiva el servicio, pero conserva la cuenta, la semilla, los ajustes y el estado, que borramos nosotros mismos cuando retiramos el host.

Los paquetes de FreeBSD y OpenBSD solo instalan /usr/local/bin/sibuna y sus documentos (pkg add, o pkg_add -D unsigned para un paquete que no procede de los servidores espejo de OpenBSD). No crean servicio, cuenta ni estado: ejecutamos el daemon como un usuario sin privilegios, con una semilla y un directorio de datos privados.

Homebrew

sibuna.rb instala el archivo de la versión adecuado para la máquina: macOS o Linux, arm64 o x86-64. No compila desde las fuentes, porque el Rust de Homebrew no tiene biblioteca estándar para wasm32-unknown-unknown, que necesita la compilación de los dos módulos WebAssembly integrados; los archivos contienen los ejecutables que el flujo de trabajo de publicación ya comprobó. Homebrew solo instala fórmulas desde taps, así que ponemos la fórmula en un tap local:

brew tap-new "$USER/local"
cp sibuna.rb "$(brew --repository)/Library/Taps/$USER/homebrew-local/Formula/"
brew install "$USER/local/sibuna"

La fórmula no arranca ningún servicio. Sus advertencias (caveats) muestran cómo crear una semilla; su prueba arranca el daemon dos veces sobre el mismo directorio de datos.

Contenedores y Kubernetes

La imagen ghcr.io/insanai/sibuna:<version> contiene el ejecutable estático sobre una base distroless: certificados de CA, usuario 65532, sin shell y sin gestor de paquetes. El punto de entrada es sibuna, así que los argumentos son opciones del daemon. El flujo de trabajo de publicación la ejecuta en solo lectura, sin capabilities, con una semilla montada en solo lectura y un volumen para el estado, y la reinicia una vez:

docker run -d --read-only --cap-drop=ALL --security-opt=no-new-privileges \
  -v "$PWD/admission.seed:/run/admission.seed:ro" -v sibuna-state:/var/lib/sibuna \
  -p 8080:8080 ghcr.io/insanai/sibuna:1.0.0-beta.3 \
  --host 0.0.0.0 --secret-file /run/admission.seed --data-dir /var/lib/sibuna/data \
  --upstream-host 10.0.0.5 --upstream-port 3000

El chart de Helm helm-sibuna-<version>.tgz ejecuta un Pod de esa imagen. Requiere un Secret que creamos nosotros (secret.existingSecret, clave admission.seed), de modo que ninguna semilla aparece nunca en los valores ni en las plantillas. El Pod se ejecuta como UID 65532 con un sistema de archivos raíz de solo lectura bajo el estándar de seguridad de pods Restricted. Una sola réplica con actualizaciones Recreate mantiene un único escritor en el volumen ReadWriteOnce, donde Sibuna guarda su estado SQLite en data/; la reclamación de volumen se conserva al desinstalar. Las sondas llaman a /__sibuna/health. El Service es ClusterIP, el chart no crea ingress ni consola, y su NetworkPolicy deniega todo el tráfico hasta que networkPolicy.ingressFrom y networkPolicy.egressTo permitan los clientes y el origen. upstream.host debe ser un literal IP, y extraArgs pasa más opciones al daemon. El flujo de trabajo instala, actualiza y desinstala el chart en un clúster kind que aplica el estándar Restricted.

kubectl -n sibuna create secret generic sibuna-admission --from-file=admission.seed
helm install gateway ./helm-sibuna-1.0.0-beta.3.tgz --namespace sibuna \
  --set secret.existingSecret=sibuna-admission \
  --set upstream.host=10.0.0.5 --set upstream.port=3000

Compilar desde las fuentes

Compilamos y probamos con Rust 1.100; Rust 1.94 sigue siendo la versión mínima compatible.

Instalamos la cadena de herramientas de la versión con rustup toolchain install 1.100.0 --profile minimal --target wasm32-unknown-unknown y la seleccionamos con cargo +1.100.0 en los comandos siguientes.

  • cargo build --release -p sibuna produce target/release/sibuna con las features por defecto: almacenamiento SQLite y la consola. sqlx incluye SQLite, y ring (rustls) necesita un compilador de C en tiempo de compilación; el binario enlaza dinámicamente el runtime de C del sistema. El script de compilación también compila el solucionador WebAssembly y la interfaz de la consola, lo que necesita rustup target add wasm32-unknown-unknown; SIBUNA_POW_WASM=<path> y SIBUNA_CONSOLE_WASM=<path> incorporan en su lugar módulos precompilados.
  • cargo build --release -p sibuna --no-default-features produce el cortafuegos en memoria sin ningún crate externo; --data-dir y --database-url se rechazan entonces al arrancar con StorageDisabled, y sibuna console con CONSOLEBUILD.
  • cargo build --release -p sibuna --features postgres-tls añade los clústeres PostgreSQL con TLS verificado hacia la base de datos. No necesita OpenSSL.
  • Los ejecutables Linux estáticos de las versiones publicadas proceden de cargo build --release --locked -p sibuna --target x86_64-unknown-linux-musl (o aarch64-unknown-linux-musl) con musl-gcc como compilador de C (CC_x86_64_unknown_linux_musl=musl-gcc).

El perfil de release usa LTO completo (fat) y una unidad de generación de código. El flujo de trabajo compila los dos módulos WebAssembly una sola vez y los pasa a todas las plataformas, de modo que todos los ejecutables de una versión incorporan módulos idénticos byte a byte. cargo xtask licenses regenera LICENSES/THIRD-PARTY-RUST.txt cuando cambia una dependencia.

En Windows, el daemon se detiene con Ctrl+C, Ctrl+Break y los eventos de cierre de la consola; no se ejecuta como servicio de Windows. Los archivos de Windows no tienen bits de modo, así que Sibuna no puede rechazar un archivo de clave, de credenciales o de URL de base de datos que otros puedan leer: restringimos esos archivos con ACL. Los indicadores de memoria y CPU de la consola se leen de /proc y no están disponibles en otros sistemas.