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¶
| 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:
| 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¶
| 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).
| 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).
| 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¶
| 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).