Das Sibuna-Handbuch 1.0.0-beta.3 Dokumentation
Sprache: Deutsch
English简体中文한국어日本語EspañolDeutschहिन्दीالعربية
Auf dieser Seite

Teil XI: Kurzreferenzkarte

Neben dem Terminal bereithalten: bauen, ausführen, konfigurieren, routen, beobachten und diagnostizieren. Teil X enthält die vollständigen Tabellen; diese Karte enthält, was ein Betreiber eintippt.

Bauen

cargo build --release -p sibuna                          # Daemon + SQLite + Konsole
cargo build --release -p sibuna --no-default-features    # im RAM, ohne externe Crates
cargo build --release -p sibuna --features postgres-tls  # Cluster mit PostgreSQL
rustup target add wasm32-unknown-unknown   # oder SIBUNA_POW_WASM / SIBUNA_CONSOLE_WASM
cargo test            # Unit-, Live-Daemon-, Speicher- und Konsolentests
cargo clippy --all-targets && cargo fmt --check
cargo xtask check     # Grenzen: 70 Zeilen / 1408 Zeilen / 99 Spalten
cargo xtask browser   # Prüfungen in Headless Chromium
cargo xtask bench product   # Gesamtprodukte unter wrk -> benchmarks/results/
guidedog build        # dieses Buch (guidedog dsc: die SID-Dokumente)

Ausführen

# Shield (Standard): PoW + WAF, Proxy zu :3000
sibuna -p 8080 -u 3000 -s /etc/sibuna/secret
# Gate: nur PoW
sibuna --gate -p 8080 -u 3000 -s /etc/sibuna/secret
# Forward-Auth hinter Nginx/Caddy (vertraut X-Forwarded-For)
sibuna -m forward_auth --host 127.0.0.1 -p 8080 -s /etc/sibuna/secret
# Edge: persistente Richtlinien, Reputation, Forensik in <dir>/sibuna.db
sibuna -D /var/lib/sibuna -s /etc/sibuna/secret
# JA4 vom vertrauenswürdigen Proxy (Header von Cloudflare; nginx-Modul: x-ja4; ATS: ja4)
sibuna --ja4-header cf-ja4 --trust-forwarded -p 8080 -u 3000 -s /etc/sibuna/secret
# Cluster-Mitglied: gemeinsames PostgreSQL, eindeutige Knotenkennung
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

Konsole (optionale Vorschau)

# Bei gestopptem Daemon initialisieren, dann die Konsole starten
sibuna init-admin admin --data-dir ./data
sibuna --data-dir ./data --console 127.0.0.1:19446

http://127.0.0.1:19446/console/ öffnen und das temporäre Passwort ersetzen. Mit --console-location 1.3521,103.8198 wird der Knoten auf dem Globus platziert. Fernzugriff erfordert einen HTTPS-Proxy, einen ausdrücklichen Origin und CIDRs vertrauenswürdiger Proxys; dazu Teil IX folgen. SID 0007 hat den Status Committed. Die Konsole besteht ihre Browser-Workflows in Headless Chromium (SID 0010, Kriterium 5); ihr formales Isolationskriterium für die Leistung ist noch offen (Teil VIII).

Die wichtigsten Optionen

Option Standard Bedeutung
-d, --difficulty 16 Arbeitsbits (PoSW-Tiefe = Bits - 3)
-a, --algorithm posw posw oder hashcash
--posw-challenges 16 Öffnungen pro Nachweis
--token-ttl 86400 Sitzungsdauer in Sekunden
--challenge-ttl 300 Challenge-Dauer in Sekunden
--token-scheme mac mac oder ed25519
--rate-limit / --rate-window 100 / 10 GCRA-Burst pro Fenster
--ban-seconds 3600 Honeypot-Sperre
-w, --workers CPUs Accept-Threads
--max-connections 1024 danach 503
--max-connections-per-ip 64 pro Peer-Adresse (IPv6: pro --ipv6-prefix), danach 503
--trusted-hops 1 Client = n-ter Eintrag von X-Forwarded-For von rechts
--ja4-header aus Header mit dem JA4-Fingerabdruck des Eingangsproxys; nur bei vertrauenswürdiger Weiterleitung gelesen
--idle-timeout 15 Reaper-Sekunden
-P, --policy-file keine JSON-Richtlinie
--trust-forwarded aus an im Forward-Auth-Modus
--secure-cookie aus fügt Secure hinzu

Endpunkte unter /__sibuna/

Route Antwort
challenge HTML der Zwischenseite
challenge.json?need=&path= {id, algorithm, difficulty, challenges, expires_at}
verify (POST) {challenge_id, nonce | proof} -> 200 + Set-Cookie, sonst 400
wasm/sibuna-pow.wasm Löser mit 15.181 Bytes
worker.js Worker mit WASM- und JS-Beweisern
honeypot sperrt den Aufrufer, 403; 404 bei einem Abruf einer Unterressource oder websiteübergreifend
health {"status":"ok",...}
metrics Prometheus-Text

Alle an den Daemon routen, nie an den Ursprungsserver.

Statuscodes

Code Wann
200 zugelassen (Forward-Auth), Zwischenseite, interne Routen
400 fehlerhafte Anfrage oder fehlerhaftes Ziel, abgewiesene Lösung (Body mit Diagnose)
401 Challenge erforderlich: Nicht-HTML-Client oder Forward-Auth
403 Ablehnung durch Richtlinie oder WAF, Sperre, Honeypot
404 unbekannte /__sibuna/-Route, abgewiesener Honeypot-Treffer
413 Lösungs-Body über dem 64-KB-Puffer
414 gemeldete Challenge-URL über 8 KiB
417 nicht unterstützte Anfrageerwartung
429 GCRA-Limit, Retry-After in Sekunden
431 Kopf über 16 KB
501 Transfer-Kodierung außer chunked
502 Ursprungsserver nicht erreichbar oder fehlerhaft
503 Verbindungslimits erreicht oder Knoten im Drain-Zustand

Header

  • Upstream (Proxy): X-Forwarded-For (Socket-Peer, bei Vertrauen nach der empfangenen Kette), X-Forwarded-Proto, X-Real-IP (der beurteilte Client), X-Sibuna-Status: PASS, X-Sibuna-Rule: <rule>; Hop-by-Hop-Felder und alternative Weiterleitungsfelder werden verworfen, auch Schreibweisen mit Unterstrich.
  • Forward-Auth-Antwort: X-Sibuna-Status, X-Sibuna-Rule, X-Sibuna-Rule-Hash.
  • Challenge-Antwort: X-Sibuna-Status: CHALLENGE.
  • Cookie: __sibuna_token=<75 chars, 139 with ed25519>; Path=/; Max-Age=<ttl>; HttpOnly; SameSite=Lax[; Secure]

Gerüst der Richtliniendatei

{ "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: ein ganzer Fingerabdruck oder ein Präfix und *; ohne Fingerabdruck kein Treffer. Muster: * oder .* beliebig; ^...$ exakt; abschließendes * Präfix; führendes / exakter Pfad; sonst Teilzeichenkette ohne Beachtung der Groß-/Kleinschreibung. Pfade werden in Normalform verglichen. Reihenfolge: WAF -> Trie deny/allow -> Regeln -> Bewertung -> Bypass -> Trie challenge -> Bots -> Standard.

Speicherung (Edge) in 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); Aktionen werden kleingeschrieben. Bewertung \(\le -50\) -> deny-Präfix; \(\ge 50\) -> allow. Cluster: dasselbe Geheimnis auf jedem Knoten, eine PostgreSQL-Datenbank, --features postgres-tls, --database-url-file <file> --cluster-node N mit einem eindeutigen N von 1 bis 8.388.607; keine Mitgliederliste, kein Leader und kein Cluster-TLS (SID 0011).

Diagnosen

Titel Bedeutung
MALFORMED CHALLENGE Kennung bearbeitet oder gekürzt; eine neue abrufen
INVALID CHALLENGE TAG nicht von diesem Seed oder Knoten ausgestellt
CHALLENGE EXPIRED älter als die TTL oder Uhrenabweichung > 60 s
CLIENT FINGERPRINT MISMATCH Adresse oder User-Agent geändert
DIFFICULTY NOT MET Nonce fehlen Nullbits
INVALID PROOF OF SEQUENTIAL WORK Öffnungen erreichen die Wurzel nicht
WRONG SOLUTION TYPE Nonce für PoSW oder Nachweis für Hashcash
DOUBLE SPEND PREVENTED Challenge bereits verwendet
STORE FULL Verbrauchsmenge gesättigt; TTL senken oder --spent-tags erhöhen
NETWORK BINDING MISMATCH Cookie auf einen anderen Client kopiert
INVALID COMMAND LINE unbekannte Option, ungültiger Wert oder eine entfernte Zaxonlite-Option

Metriken für Alarme: denied, rate_limited, overloaded, upstream_errors, incidents_dropped, incident_write_failures, bans_refused, forwarded_invalid (alle sibuna_*_total).

Zahlen zum Merken

Challenge-Kennung 70 Zeichen (36-Byte-Nutzlast + 16-Byte-Tag); Token 75 Zeichen (40 + 16), 139 mit Ed25519; Nachweisbytes \(32(1 + t(n+1))\); PoSW-Tiefe = Bits - 3, Bereich 4 bis 24; Anfragepuffer 64 KB; Kopflimit 16 KB; geprüfter Body 8 KB; Verbrauchsmenge 1.048.576 Tags (--spent-tags); Ratenzellen 262.144 pro Tabelle (--rate-table-cells); Sperren 65.536 Slots (--ban-table-slots); 64 Verbindungen pro Clientadresse; Vorfallsring 512; Batch 32; Kampagnenabstand 0,35 über die 16.384 jüngsten Embeddings; Keep-Alive 4.096 Anfragen pro Verbindung; Pool zum Ursprungsserver 256 Sockets; Speicher-Job-Warteschlange 32.

Routing am Eingangsproxy

Das Rezept für Nginx oder Caddy aus Teil IX, „Forward-Auth hinter einem Eingangsproxy“, verwenden. /__sibuna/* direkt routen; Anwendungsanfragen mit der ursprünglichen URI, der Methode und der vertrauenswürdigen Clientadresse autorisieren. Eingehende Sibuna-Audit-Header durch das Autorisierungsergebnis ersetzen. Nginx braucht eine ausdrückliche Behandlung von Challenge, 429 und nicht verfügbarer Autorisierung.

reverse_proxy trägt zugelassene HTTP/1.1-Bodies und WebSockets; forward_auth erteilt die Zulassung, und der Eingangsproxy trägt sie. Ausgelassene Auth-Bodies und Antworten des Ursprungsservers kann Sibuna weder prüfen noch zählen. TLS terminiert am Eingangsproxy; natives HTTP/2 ist zurückgestellt. Uploads verwenden Content-Length oder Chunked-Kodierung; die Prüfung sieht höchstens ein Präfix von 8 KiB, die Dateibytes bleiben undurchsichtig.