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

Parte X: Referencia de consulta y diagnóstico

Endpoints, métricas, catálogo de errores, esquema de políticas y tablas de almacenamiento en un solo lugar.

Endpoints

Tabla 27 Rutas reservadas
Endpoint Método Función
/__sibuna/challenge GET La página intermedia
/__sibuna/challenge.json?need=&path= GET Emite un desafío sin estado: lo decide el ticket de requisito de la respuesta que exigió el desafío; si no lo hay, se evalúa en forma normal la URL que indica el cliente (414 por encima de 8 KiB, 400 para una ruta sin forma normal). Devuelve {id, algorithm, difficulty, challenges, expires_at}
/__sibuna/verify POST Acepta {"challenge_id", "nonce"} o {"challenge_id", "proof"}; responde 200 con Set-Cookie, 400 con un diagnóstico o 413 si el cuerpo es mayor que el búfer de la conexión
/__sibuna/wasm/sibuna-pow.wasm GET El módulo del solucionador, de 14.744 bytes (wasm_bytes en benchmarks/results/primitives-latest.json), que se puede almacenar en caché durante una hora
/__sibuna/worker.js GET El Web Worker con los probadores WASM y JavaScript, que se puede almacenar en caché durante una hora
/__sibuna/honeypot GET Bloquea a quien llama durante --ban-seconds y registra un incidente; 403. Solo bloquea una petición de nivel superior (sin Sec-Fetch-Dest o con document, y sin Sec-Fetch-Site entre sitios); cualquier otra recibe 404 y se contabiliza
/__sibuna/health GET Estado de disponibilidad en JSON con el nombre del motor, la versión, el modo de proxy y el algoritmo de prueba
/__sibuna/metrics GET Formato de texto de Prometheus (versión 0.0.4)

Cualquier otra ruta bajo /__sibuna/ recibe 404. La emisión y la verificación consumen el presupuesto independiente --challenge-rate-limit, y una dirección bloqueada se rechaza con 403 en todas las rutas. Las respuestas de desafío llevan X-Sibuna-Status: CHALLENGE; las peticiones admitidas llevan X-Sibuna-Status: PASS y X-Sibuna-Rule hacia el origen (y X-Sibuna-Rule-Hash, en hexadecimal, en las respuestas de forward-auth). Un cliente que no acepta HTML recibe 401 con {"error":"challenge_required","challenge":"/__sibuna/challenge.json?need=<ticket>"}.

El puerto de escucha de gestión, independiente y opcional, sirve /console/. Inicializa su administrador localmente con sibuna init-admin y sustituye la contraseña temporal en el primer inicio de sesión. /console/api/stats y /console/ws requieren una sesión autenticada (incluida una sesión de quiosco). El WebSocket multiplexa estadísticas, eventos, nodos, políticas, desafíos y auditoría con instantáneas acotadas, deltas y recuperación de huecos. Los pares de gestión se conectan a /console/peer, y todas las rutas de la API están bajo /console/api/. En el modo forward-auth no se observan los contadores de errores del origen. La parte IX documenta los flujos de trabajo de la consola, su despliegue con HTTPS y los límites actuales de SID 0007.

Métricas

Contadores expuestos como sibuna_<name>_total en formato de texto de Prometheus, en este orden:

Tabla 28 Contadores
Contador Se incrementa cuando
incidents_persisted, incident_batches Registros y transacciones cuya confirmación ha verificado el hilo de almacenamiento
incidents_dropped, incident_write_failures Inserciones en la cola rechazadas porque el anillo estaba lleno, e intentos de confirmación fallidos
requests Una petición analizada llegó al despacho (incluidas las rutas reservadas)
allowed, denied, challenged Se tomó una decisión de política (admitida, rechazada, desafío emitido o reemitido)
challenges_issued /__sibuna/challenge.json emitió un registro de desafío
solutions_accepted, solutions_rejected /__sibuna/verify aceptó o rechazó una prueba
rate_limited GCRA rechazó una petición (429): el límite de peticiones, el presupuesto de desafíos o la cuota de una regla
banned Se rechazó una dirección bloqueada, o el honeypot bloqueó una
bans_issued Se registró un bloqueo (del honeypot o de la cuota de una regla)
proxied, upstream_errors Se retransmitió una petición al origen, o el origen falló (502)
parse_errors Se rechazó un encabezado de petición mal formado, un Host repetido, un destino sin forma normal (400) o una codificación de transferencia no admitida (501)
overloaded Una conexión por encima de --max-connections o --max-connections-per-ip recibió 503
bans_refused No se registró un bloqueo porque todas las posiciones que puede ocupar su clave tenían un bloqueo vigente
forwarded_invalid No se pudo analizar una dirección de cliente reenviada de confianza; la petición se evaluó según el extremo remoto del socket
honeypot_refused Un acceso al honeypot no bloqueó a nadie porque lo solicitó una página, no una persona
rate_evictions Una llegada al limitador desalojó la celda de otro cliente activo
ja4_present Con --ja4-header y el reenvío de confianza, la petición llevaba exactamente una cabecera de ese nombre, con una huella JA4
ja4_invalid Con --ja4-header y el reenvío de confianza, la cabecera estaba mal formada o repetida; la petición se evaluó sin huella

Un reintento puede incrementar incident_write_failures sin perder registros, porque el lote pendiente se conserva. Vigila los incrementos durante un intervalo; los totales por sí solos no indican la profundidad de la cola.

Códigos de estado

Tabla 29 Códigos de estado del plano de datos
Código Cuándo
200 Admitida (forward-auth), página intermedia (navegación HTML que necesita un desafío), rutas internas
302 No lo usa el protocolo actual; la verificación responde 200 y la página se recarga
400 Petición mal formada, un campo Host repetido, un destino sin forma normal, metadatos de reenvío no válidos, un cuerpo mal formado o una solución rechazada con un diagnóstico al estilo de Elm
401 Se requiere un desafío para un cliente que no acepta HTML, o en el modo forward-auth
403 Denegación por política o por el WAF, dirección bloqueada, honeypot
404 Una ruta desconocida bajo /__sibuna/, o un acceso al honeypot que no es una petición de nivel superior
413 Cuerpo de la solución mayor que el búfer de conexión de 64 KB
414 La URL indicada para el desafío supera 8 KiB
417 Expectativa de la petición no admitida; 100-continue se gestiona localmente
429 Límite GCRA superado; Retry-After en segundos
431 Encabezado de la petición de más de 16 KB
501 Transfer-Encoding con una codificación distinta de chunked
502 Origen inalcanzable, o el encabezado de su respuesta estaba mal formado o superaba 16 KB
503 Se alcanzó el límite de conexiones (--max-connections o --max-connections-per-ip), o el nodo se está drenando; el socket se cierra tras la respuesta

Catálogo de errores

INVALID COMMAND LINE detiene el arranque ante cualquier opción que el daemon no reconoce, cualquier valor fuera de su rango documentado y una selección de modo no válida, ausente o duplicada. El bloque nombra la opción, el valor dado, el rango esperado y el error (UnknownOption, MissingValue, InvalidValue, InvalidMode, MissingMode, DuplicateMode, RemovedOption para una opción de clúster de Zaxonlite, ConflictingOptions para dos opciones de almacenamiento que se excluyen entre sí, MissingOption para una URL de base de datos sin --cluster-node), y termina con una pista. Una URL de base de datos se muestra como [redacted]. Indica --mode reverse_proxy o --mode forward_auth una sola vez; -m es la opción corta equivalente. Un archivo de políticas rechazado imprime un bloque titulado con su error (por ejemplo INVALID POLICY ACTION) con el archivo, el nombre del error, la regla, el campo y el valor. Un patrón ja4 con el que ninguna huella podría coincidir imprime INVALID POLICY JA4 (InvalidJa4); un documento de gestión de la consola con un patrón así se rechaza con el mismo nombre de error. Las opciones de la consola se comprueban por separado: CONSOLE002 señala una opción de consola mal formada o repetida, y CONSOLE001 una configuración de consola que incumple una regla (StorageRequired sin almacenamiento).

Tabla 30 Errores de desafío y de sesión
Error Causa Pista
MalformedChallenge El identificador no es un registro de desafío bien formado Obtén un desafío nuevo y envíalo sin cambios
InvalidChallengeTag La etiqueta no se verifica: el desafío no lo emitió este clúster o se modificó Los desafíos no se pueden falsificar; solicita uno nuevo
ChallengeExpired Supera el TTL del desafío, o se emitió en el futuro Solicita un desafío nuevo
FingerprintMismatch Enviado desde otra dirección u otro User-Agent Envíalo desde el cliente que lo obtuvo
DifficultyNotMet Al nonce de Hashcash le faltan los bits a cero requeridos Sigue buscando nonces
InvalidProof La prueba de trabajo secuencial no abre las etiquetas del compromiso Ejecuta el probador hasta el final con la profundidad y las aperturas emitidas
WrongSolutionType Un nonce para un desafío PoSW o una prueba para Hashcash Haz coincidir el campo de la solución con el algoritmo
DoubleSpendAttempt El desafío ya se había gastado Los desafíos son de un solo uso
StoreFull El conjunto de desafíos gastados está lleno Reduce el TTL de los desafíos o aumenta --spent-tags
InvalidTokenSignature Falla la etiqueta o la firma de la cookie Vuelve a autenticarte mediante la página intermedia
TokenExpired Cookie caducada Vuelve a autenticarte
TokenBoundAddressMismatch Cookie presentada desde otra identidad de cliente Las cookies no se pueden compartir

La API de la consola responde a un fallo con {"error":"<CODE>","hint":"<sentence>"}; la pista es el texto que muestra la interfaz (crates/console/src/http/reply.rs).

Tabla 31 Códigos de fallo de la consola que interesan a los operadores
Código Estado Significado
CONSOLE002 400 La petición está mal formada, es demasiado grande o no se permite en esa forma
CONSOLE003 503 / 429 La cola de tareas de almacenamiento está llena (32 tareas), o el verificador de contraseñas está ocupado
CONSOLEQUORUM 503 La base de datos no respondió en los 10 segundos que espera la petición; el resultado se desconoce, y el plano de datos continúa con la última política aplicada
CONSOLE004 503 El servicio no puede responder: no está disponible en esta compilación, se está deteniendo o tuvo un fallo interno
CONSOLENODE 400 / 409 / 503 Se rechazó un comando dirigido a un nodo: nombra otro nodo (400), una revisión de arranque o de control obsoleta (409), o llegó mientras se ejecutaba otro comando o no se pudo registrar una finalización (503); inspecciona el recibo de la operación antes de reintentar
CONSOLEMUTATION 429 Más de sesenta modificaciones de gestión en un minuto desde una misma sesión

Esquema de políticas

{
  "default_action": "ALLOW" | "DENY" | "CHALLENGE",
  "waf": true | false,
  "inspection": { "path_traversal" | "sqli" | "xss" | "rce": "disabled" | "audit" | "enforce" },
  "thresholds": { "challenge_at": int, "deny_at": int, "bits_step": int },
  "ip_rules": { "<cidr>": "ALLOW" | "DENY" | "CHALLENGE", ... },
  "rules": [                                                    // hasta 128
    {
      "name": "<kebab-case>",                                   // de 1 a 128 bytes imprimibles
      "path" | "path_regex": "<pattern>",                       // hasta 512 bytes
      "user_agent" | "user_agent_regex": "<pattern>",
      "headers" | "headers_regex": { "<Header>": "<pattern>" }, // hasta 4
      "remote_addresses" | "cidrs": ["<cidr>", ...],            // hasta 8, IPv4 o IPv6
      "action": "ALLOW" | "DENY" | "CHALLENGE" | "WEIGH",
      "weight": int,                                            // solo WEIGH, -1000..1000
      "challenge": { "difficulty": <work bits>, "algorithm": "hashcash" | "posw" },
      "limits": { "rate": int, "window_seconds": int, "ban_seconds": int },
      "ja4": "<fingerprint>" | "<prefix>*"                      // 36 bytes, o un prefijo y *
    }
  ]
}

challenge_at y deny_at están entre -1000 y 1000, con deny_at mayor o igual que challenge_at, y bits_step entre 1 y 1000. Un bloque challenge solo pertenece a las reglas CHALLENGE, con 1 a 64 bits de trabajo. limits da a una regla su propia cuota: rate de 1 a 1.000.000 y window_seconds de 1 a 86.400 son obligatorios, ban_seconds (como máximo 86.400) es opcional, y las reglas WEIGH no pueden llevar límites. ja4 es una huella JA4 completa, a la que la huella debe ser igual, o un prefijo seguido de *, por el que debe empezar la huella; * por sí solo coincide con cualquier huella, y una petición sin huella no coincide con ninguna regla ja4. Un patrón con el que ninguna huella podría coincidir se rechaza con InvalidJa4 (parte IX, "Huellas JA4 desde el proxy de entrada"). El trie de reputación de ip_rules contiene como máximo 8.192 nodos. Cada regla puede usar una sola variante de cada criterio.

Gramática de patrones: .* o * coinciden con cualquier cosa; ^...$ ancla una ruta exacta; un *, /* o .* final indica un prefijo; un patrón que empieza por / es una ruta exacta; cualquier otra cosa es una subcadena que no distingue mayúsculas de minúsculas. Los patrones de ruta se comparan con la ruta en forma normal (una barra entre segmentos, sin segmentos de punto, caracteres no reservados sin escapar y el resto de escapes con dígitos hexadecimales en mayúsculas), así que un patrón que contiene ;, %2F, %5C o \ no coincide con nada, y la comparación de rutas distingue mayúsculas de minúsculas (SID 0003).

Tablas de almacenamiento

policy_revision, policies (con el criterio ja4_pattern, que admite nulos, de 37 bytes como máximo), policy_inspection, ip_reputation, incident_receipts, security_incidents (con el embedding de 256 bytes y la huella ja4 de 36 bytes, que admite nulos), el índice de texto completo (incidents_fts, FTS5 sobre tokens canónicos, en SQLite; la columna tsvector search con un índice GIN en PostgreSQL) y sibuna_schema; la consola añade 33 tablas console_*. Los nombres de acción, algoritmo y modo se guardan en minúsculas. Los ids de incidente son node_id << 40 | sequence, únicos en todo un clúster sin coordinación; los ids de nodo van de 1 a 8.388.607.

Objetivos de compilación

Tabla 32 Comandos de compilación y del repositorio
Comando Resultado
cargo build --release -p sibuna Daemon con almacenamiento SQLite y la consola (las features por defecto)
cargo build --release -p sibuna --no-default-features Daemon en memoria sin almacenamiento ni consola y sin ningún crate externo
cargo build --release -p sibuna --features postgres-tls Daemon que además se conecta a una base de datos PostgreSQL compartida, con TLS verificado (la feature postgres por sí sola se conecta sin TLS)
cargo test Pruebas unitarias, pruebas de integración contra un daemon en ejecución, pruebas de almacenamiento y de consola (las de PostgreSQL cuando se define SIBUNA_TEST_DATABASE_URL)
cargo clippy --all-targets, cargo fmt --check Lints y formato (max_width = 99)
cargo xtask check Los límites de 70 líneas por función, 1.408 líneas por archivo y 99/108 columnas por línea; sin tabuladores
cargo xtask browser Comprobaciones en Chromium sin interfaz gráfica (sibuna-browser)
cargo xtask bench <primitives|product|latency> Pruebas de rendimiento en modo release; resultados en benchmarks/results/<command>-latest.json
cargo build -p sibuna-pow-wasm --target wasm32-unknown-unknown --profile wasm Solo el módulo del navegador (-p sibuna-console-ui para la interfaz de la consola)
cargo run -p sibuna-geoip --bin geoip-snapshot -- ... Valida los datos de países y escribe una instantánea GeoIP que se puede integrar
guidedog build / guidedog dsc Este libro / los registros SID

El script de compilación del daemon (cmd/sibuna/build.rs) compila ambos módulos WebAssembly con el perfil wasm en el directorio de destino del workspace y hace fallar la compilación cuando la interfaz de la consola supera 768 KiB. SIBUNA_POW_WASM y SIBUNA_CONSOLE_WASM indican en su lugar módulos precompilados, para compilaciones sin el objetivo wasm32-unknown-unknown. SIBUNA_GEOIP_DATA indica una instantánea GeoIP que integrar; se decodifica en tiempo de compilación, y una compilación sin la consola la rechaza (GEOIP001).