Parte XI: Tarjeta de referencia rápida¶
Para tener junto al terminal: compilar, ejecutar, configurar, enrutar, observar y diagnosticar. La parte X contiene las tablas completas; esta tarjeta contiene lo que teclea un operador.
Compilar¶
cargo build --release -p sibuna # daemon + SQLite + consola
cargo build --release -p sibuna --no-default-features # en memoria, sin crates externos
cargo build --release -p sibuna --features postgres-tls # clúster con PostgreSQL común
rustup target add wasm32-unknown-unknown # o define SIBUNA_POW_WASM / SIBUNA_CONSOLE_WASM
cargo test # unitarias, daemon en ejecución, almacenamiento y consola
cargo clippy --all-targets && cargo fmt --check
cargo xtask check # límites de 70 líneas / 1.408 líneas / 99 columnas
cargo xtask browser # comprobaciones en Chromium sin interfaz gráfica
cargo xtask bench product # productos completos bajo wrk -> benchmarks/results/
guidedog build # este libro (guidedog dsc: los registros SID)
Ejecutar¶
# Shield (por defecto): PoW + WAF, proxy hacia :3000
sibuna -p 8080 -u 3000 -s /etc/sibuna/secret
# Gate: solo PoW
sibuna --gate -p 8080 -u 3000 -s /etc/sibuna/secret
# Forward-auth detrás de Nginx/Caddy (confía en X-Forwarded-For)
sibuna -m forward_auth --host 127.0.0.1 -p 8080 -s /etc/sibuna/secret
# Edge: políticas, reputación e incidentes persistentes en <dir>/sibuna.db
sibuna -D /var/lib/sibuna -s /etc/sibuna/secret
# JA4 del proxy de entrada fiable (Cloudflare; módulo nginx: x-ja4; ATS: ja4)
sibuna --ja4-header cf-ja4 --trust-forwarded -p 8080 -u 3000 -s /etc/sibuna/secret
# Miembro de un clúster: PostgreSQL compartido, id de nodo único
sibuna --database-url-file /etc/sibuna/database-url --cluster-node 1 -s /etc/sibuna/secret
head -c 32 /dev/urandom | xxd -p -c 64 > /etc/sibuna/secret
Consola (versión preliminar opcional)¶
# Inicializa con el daemon detenido y después arranca la consola
sibuna init-admin admin --data-dir ./data
sibuna --data-dir ./data --console 127.0.0.1:19446
Abre http://127.0.0.1:19446/console/ y sustituye la contraseña temporal. Añade --console-location 1.3521,103.8198 para situar el nodo en el globo. El acceso remoto requiere un proxy HTTPS, un origen explícito y los CIDR de los proxies de confianza; sigue la parte IX. SID 0007 está en estado Committed. La consola supera sus flujos de trabajo de navegador en Chromium sin interfaz gráfica (SID 0010, criterio 5); su criterio formal de aislamiento del rendimiento sigue abierto (parte VIII).
Las opciones más importantes¶
| Opción | Por defecto | Significado |
|---|---|---|
-d, --difficulty |
16 | bits de trabajo (profundidad PoSW = bits - 3) |
-a, --algorithm |
posw | posw o hashcash |
--posw-challenges |
16 | aperturas por prueba |
--token-ttl |
86400 | segundos de sesión |
--challenge-ttl |
300 | segundos de desafío |
--token-scheme |
mac | mac o ed25519 |
--rate-limit / --rate-window |
100 / 10 | ráfaga GCRA por ventana |
--ban-seconds |
3600 | bloqueo del honeypot |
-w, --workers |
núm. de CPU | hilos de aceptación |
--max-connections |
1024 | después 503 |
--max-connections-per-ip |
64 | por dirección remota (IPv6: por --ipv6-prefix), después 503 |
--trusted-hops |
1 | cliente = n-ésima entrada de X-Forwarded-For empezando por la derecha |
--ja4-header |
desactivado | cabecera con la huella JA4 del proxy de entrada; solo se lee si es de confianza |
--idle-timeout |
15 | segundos del recolector |
-P, --policy-file |
ninguno | política JSON |
--trust-forwarded |
desactivado | activado en forward-auth |
--secure-cookie |
desactivado | añade Secure |
Endpoints bajo /__sibuna/¶
| Ruta | Respuesta |
|---|---|
challenge |
HTML de la página intermedia |
challenge.json?need=&path= |
{id, algorithm, difficulty, challenges, expires_at} |
verify (POST) |
{challenge_id, nonce | proof} -> 200 + Set-Cookie; si no, 400 |
wasm/sibuna-pow.wasm |
solucionador de 15.181 bytes |
worker.js |
worker con probadores WASM y JS |
honeypot |
bloquea a quien llama, 403; 404 para un subrecurso o una petición entre sitios |
health |
{"status":"ok",...} |
metrics |
texto de Prometheus |
Enruta todos ellos al daemon, nunca al origen.
Códigos de estado¶
| Código | Cuándo |
|---|---|
| 200 | admitida (forward-auth), página intermedia, rutas internas |
| 400 | petición o destino mal formados, solución rechazada (cuerpo con diagnóstico) |
| 401 | se requiere un desafío: cliente sin HTML o forward-auth |
| 403 | denegación por política o por el WAF, bloqueo, honeypot |
| 404 | ruta /__sibuna/ desconocida, acceso al honeypot rechazado |
| 413 | cuerpo de la solución mayor que el búfer de 64 KB |
| 414 | URL indicada para el desafío de más de 8 KiB |
| 417 | expectativa de la petición no admitida |
| 429 | límite GCRA, segundos en Retry-After |
| 431 | encabezado de más de 16 KB |
| 501 | codificación de transferencia distinta de chunked |
| 502 | origen inalcanzable o con respuesta mal formada |
| 503 | límites de conexiones alcanzados, o el nodo se está drenando |
Cabeceras¶
- Hacia el origen (proxy):
X-Forwarded-For(el extremo remoto del socket, tras la cadena recibida si es de confianza),X-Forwarded-Proto,X-Real-IP(el cliente evaluado),X-Sibuna-Status: PASS,X-Sibuna-Rule: <rule>; se eliminan los campos hop-by-hop y los campos de reenvío alternativos, también sus variantes con guion bajo. - Respuesta de forward-auth:
X-Sibuna-Status,X-Sibuna-Rule,X-Sibuna-Rule-Hash. - Respuesta de desafío:
X-Sibuna-Status: CHALLENGE. - Cookie:
__sibuna_token=<75 chars, 139 with ed25519>; Path=/; Max-Age=<ttl>; HttpOnly; SameSite=Lax[; Secure]
Esqueleto del archivo de políticas¶
{ "default_action": "CHALLENGE", "waf": true,
"thresholds": {"challenge_at": 10, "deny_at": 40, "bits_step": 5},
"ip_rules": {"10.0.0.0/8": "ALLOW", "2001:db8::/32": "DENY"},
"rules": [
{"name": "api", "path": "/api/*", "headers": {"X-Api-Key": ".*"}, "action": "ALLOW"},
{"name": "checkout", "path": "/checkout/*", "action": "CHALLENGE",
"challenge": {"difficulty": 20, "algorithm": "posw"}},
{"name": "login", "path": "^/login$", "action": "CHALLENGE",
"limits": {"rate": 10, "window_seconds": 60, "ban_seconds": 600}},
{"name": "old-tls", "ja4": "t12*", "action": "CHALLENGE"},
{"name": "headless", "user_agent": "Headless", "action": "WEIGH", "weight": 30} ] }
JA4: una huella completa, o un prefijo y *; sin huella, no hay coincidencia. Patrones: * o .*, cualquiera; ^...$, exacto; * final, prefijo; / inicial, ruta exacta; en otro caso, subcadena sin distinguir mayúsculas. Las rutas se comparan en forma normal. Orden: WAF -> trie deny/allow -> reglas -> puntuación -> exención -> trie challenge -> bots -> por defecto.
Almacenamiento (Edge) en SQL¶
INSERT INTO policies (id, name, priority, path_pattern, action, difficulty, algorithm,
header_matchers, cidr_matchers, weight, enabled, created_at, updated_at)
VALUES ('p1', 'protect', 10, '/checkout/*', 'challenge', 20, 'posw', '{}', '[]', 0, 1,
unixepoch(), unixepoch());
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());
SELECT 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;
SQLite (sqlite3 <dir>/sibuna.db); las acciones van en minúsculas. Puntuación \(\le -50\) -> prefijo deny; \(\ge 50\) -> allow. Clúster: el mismo secreto en cada nodo, una base de datos PostgreSQL, --features postgres-tls, --database-url-file <file> --cluster-node N con un N único de 1 a 8.388.607; sin lista de miembros, líder ni TLS de clúster (SID 0011).
Diagnósticos¶
| Título | Significado |
|---|---|
MALFORMED CHALLENGE |
id editado o truncado; obtén uno nuevo |
INVALID CHALLENGE TAG |
no emitido con esta semilla ni por este nodo |
CHALLENGE EXPIRED |
supera el TTL o desfase de reloj > 60 s |
CLIENT FINGERPRINT MISMATCH |
cambió la dirección o el User-Agent |
DIFFICULTY NOT MET |
al nonce le faltan bits a cero |
INVALID PROOF OF SEQUENTIAL WORK |
las aperturas no llegan a la raíz |
WRONG SOLUTION TYPE |
nonce para PoSW o prueba para Hashcash |
DOUBLE SPEND PREVENTED |
desafío ya usado |
STORE FULL |
conjunto de desafíos gastados saturado; reduce el TTL o aumenta --spent-tags |
NETWORK BINDING MISMATCH |
cookie copiada a otro cliente |
INVALID COMMAND LINE |
opción desconocida, valor incorrecto u opción de Zaxonlite eliminada |
Métricas para alertas: denied, rate_limited, overloaded, upstream_errors, incidents_dropped, incident_write_failures, bans_refused, forwarded_invalid (todas sibuna_*_total).
Cifras que recordar¶
Id de desafío de 70 caracteres (carga útil de 36 bytes + etiqueta de 16 bytes); token de 75 caracteres (40 + 16), 139 con Ed25519; bytes de la prueba \(32(1 + t(n+1))\); profundidad PoSW = bits - 3, de 4 a 24; búfer de petición de 64 KB; límite de encabezado de 16 KB; 8 KB de cuerpo inspeccionados; conjunto de desafíos gastados de 1.048.576 etiquetas (--spent-tags); 262.144 celdas de tasa por tabla (--rate-table-cells); 65.536 posiciones de bloqueo (--ban-table-slots); 64 conexiones por dirección de cliente; anillo de incidentes de 512; lote de 32; distancia de campaña de 0,35 sobre los 16.384 embeddings más recientes; keep-alive de 4.096 peticiones por conexión; pool de 256 sockets hacia el origen; cola de tareas de almacenamiento de 32.
Enrutamiento en el proxy de entrada¶
Usa la receta de Nginx o Caddy de la parte IX, "Forward-auth detrás de un proxy de entrada". Enruta /__sibuna/* directamente; autoriza las peticiones de la aplicación con la URI original, el método y la dirección de cliente de confianza. Sustituye las cabeceras de auditoría de Sibuna entrantes por el resultado de la autorización. Nginx necesita un tratamiento explícito del desafío, del 429 y de la autorización no disponible.
reverse_proxy transporta los cuerpos HTTP/1.1 admitidos y los WebSockets; forward_auth concede la admisión y el proxy de entrada los transporta. Sibuna no puede inspeccionar ni contar los cuerpos que se omiten en la autorización ni las respuestas del origen. TLS termina en el proxy de entrada; el HTTP/2 nativo queda aplazado. Las subidas usan Content-Length o codificación chunked; la inspección ve como máximo un prefijo de 8 KiB, y los bytes de los archivos son opacos.