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

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.