Teil IX: Betrieb und Einsatz¶
Wir behandeln die beiden Betriebsformen, jede Kommandozeilenoption, Rezepte für Forward-Auth, Richtliniendateien, persistente Speicherung in SQLite oder PostgreSQL, Cluster über eine gemeinsame Datenbank und die Paketierung.
Betriebsformen und Konfiguration¶
Eine Betriebsform wählen¶
- Gate (
--gate, Alias--no-waf): Proof-of-Work-Zulassung, Sitzungen, deklarative Regeln, Reputation, GCRA-Limits, Sperren. - Shield (Standard,
--shield, Alias--waf): Gate plus die semantische Firewall. - Verteilter Einsatz (eine Option für beide Betriebsformen):
--data-dirhält Richtlinien, Reputation und Forensik in einer lokalen SQLite-Datei;--database-urlmit--cluster-nodeverbindet mehrere Knoten mit einer PostgreSQL-Datenbank (SID 0011).
Kommandozeilenreferenz¶
Die Tabelle listet jede Option von sibuna --help. Die Wertebereiche sind diejenigen, die der Parser durchsetzt.
| Option | Standard | Bedeutung |
|---|---|---|
--port, -p |
8080 |
Port, auf dem gelauscht wird, 1 bis 65535 |
--host, -h |
0.0.0.0 |
Adresse, auf der gelauscht wird, ein IP-Adressliteral |
--upstream-host |
127.0.0.1 |
Host des Ursprungsservers (Reverse-Proxy-Modus) |
--upstream-port, -u |
3000 |
Port des Ursprungsservers |
--mode, -m |
reverse_proxy |
reverse_proxy oder forward_auth (auch proxy und auth), genau einmal angegeben |
--workers, -w |
eine pro CPU | Accept-Threads, die sich den lauschenden Socket teilen, 0 (eine pro CPU) bis 64; jede angenommene Verbindung erhält danach einen eigenen Thread |
--max-connections |
1024 |
Gleichzeitig bediente Verbindungen, 1 bis 8192; weitere werden mit 503 beantwortet |
--max-connections-per-ip |
64 |
Verbindungen, die eine Peer-Adresse eines Sockets halten darf, 0 (keine Grenze) bis 8192; ein IPv6-Peer zählt mit seinem --ipv6-prefix-Netz, und weitergeleitete Header spielen keine Rolle; weitere werden mit 503 beantwortet |
--idle-timeout |
15 |
Längste Stille in Sekunden, 0 bis 86400. Ein Anfragekopf muss innerhalb dieser Zeit eintreffen. Eine Antwort des Ursprungsservers erneuert die Frist bei jedem Lesen, sodass ein langsamer Stream lebt, solange Bytes fließen, und ein stummer Ursprungsserver auf beiden Sockets getrennt wird. Ein weitergeleiteter Upload muss pro Periode 16 KiB liefern (eine Mindestrate gegen Slow-Body-Angriffe). Der Client-Socket trägt ein Schreib-Timeout derselben Länge, sodass ein Client, der so lange kein Byte annimmt, die Verbindung verliert |
--websocket-idle-timeout |
300 |
Leerlauffrist einer per Upgrade umgestellten Verbindung in Sekunden, 0 bis 86400 |
--trust-forwarded |
aus; an im Forward-Auth-Modus | X-Forwarded-For / X-Real-IP vom Peer berücksichtigen |
--no-trust-forwarded |
aus | Sie nie berücksichtigen, auch nicht im Forward-Auth-Modus |
--trusted-hops |
1 |
Bei vertrauenswürdiger weitergeleiteter Identität ist der Client der Eintrag von X-Forwarded-For, der so viele Positionen von rechts steht, 1 bis 8 |
--ja4-header |
aus | Der Anfrage-Header, in dem ein vertrauenswürdiger Eingangsproxy den JA4-TLS-Fingerabdruck des Clients sendet, etwa cf-ja4; 1 bis 64 Token-Zeichen, nicht X-Forwarded-*, X-Real-IP, X-Sibuna-* oder Forwarded. Er wird nur gelesen, wenn der weitergeleiteten Identität vertraut wird (siehe „JA4-Fingerabdrücke vom Eingangsproxy“) |
--ipv6-prefix |
64 |
IPv6-Präfixlänge, 32 bis 128, für die Ratenlimits, Sperren und die Verbindungsgrenze pro Client gelten |
--algorithm, -a |
posw |
posw oder hashcash |
--difficulty, -d |
16 |
Arbeitsbits, 1 bis 64: Nullbits bei Hashcash oder PoSW-Tiefe plus drei |
--posw-challenges |
16 |
Öffnungen pro Nachweis sequenzieller Arbeit, 1 bis 32 |
--token-scheme |
mac |
mac (BLAKE3 mit Schlüssel) oder ed25519 |
--token-ttl |
86400 |
Lebensdauer der Sitzung, Sekunden (1 bis 31.536.000) |
--challenge-ttl |
300 |
Lebensdauer der Challenge, Sekunden (1 bis 86.400) |
--secret-file, -s |
zufällig | 64 Hex-Zeichen oder 32 Rohbytes; SIBUNA_SECRET (64 Hex-Zeichen) wird ebenfalls akzeptiert |
--cookie-name |
__sibuna_token |
Name des Sitzungscookies, 1 bis 64 Token-Zeichen |
--secure-cookie |
aus | Das Attribut Secure hinzufügen |
--gate / --shield |
shield | Auswahl der Betriebsform |
--rate-limit |
100 |
Anfragen pro Fenster und Client (GCRA-Burst) |
--rate-window |
10 |
Fenster in Sekunden, 1 bis 86400 |
--challenge-rate-limit |
30 |
Ausgaben und Prüfungen von Challenges pro Fenster und Client, getrennt vom Anfragebudget |
--ban-seconds |
3600 |
Sperrdauer durch den Honeypot, 0 bis 31.536.000 |
--policy-file, -P |
keine | Deklarative JSON-Richtlinie |
--rate-table-cells |
262144 |
Zellen pro Tabelle des Ratenbegrenzers, je 16 Bytes, 4.096 bis 16.777.216, aufgerundet auf eine Zweierpotenz |
--ban-table-slots |
65536 |
Slots der Sperrtabelle, je 24 Bytes, 1.024 bis 16.777.216, aufgerundet auf eine Zweierpotenz |
--spent-tags |
1048576 |
Gelöste Challenges, die gegen Wiedereinspielung gespeichert werden, je 24 Bytes, 65.536 bis 16.777.216 |
--data-dir, -D |
keine | Ein Knoten: dauerhaft in der SQLite-Datei <path>/sibuna.db speichern |
--database-url |
keine | Ein Cluster: die gemeinsame PostgreSQL-Datenbank (postgres:// oder postgresql://) |
--database-url-file |
keine | Die Datenbank-URL aus einer Datei lesen, die nur der Eigentümer lesen darf |
--cluster-node |
keine | Die Kennung dieses Knotens; bindet Challenge-Schlüssel und die oberen Bits der Vorfallskennungen; mit einer Datenbank-URL erforderlich |
--storage-poll-ms |
500 |
Taktintervall des Speicherthreads, 1 bis 60.000 ms |
--verbose, -v |
aus | Ausführliche Protokollierung |
--help / --version |
Die Hilfe (zuerst die Konsolenoptionen, wenn die Konsole einkompiliert ist) oder die Version ausgeben und beenden |
--data-dir und eine Datenbank-URL schließen einander aus, ebenso --database-url und --database-url-file. Eine Datenbank-URL ohne --cluster-node wird abgewiesen. Die Zaxonlite-Clusteroptionen --cluster-listen, --cluster-peer, --cluster-secret-file sowie --cluster-tls-cert, --cluster-tls-key und --cluster-tls-ca gibt es nicht mehr; wird eine davon angegeben, bricht der Start mit RemovedOption und einem Hinweis auf SID 0011 ab. Die Optionen der Konsole stehen im nächsten Kapitel.
Vorschau der Konsole¶
Die Konsole wird über das Standard-Feature console in den Daemon einkompiliert, startet aber nur mit --console. Sie braucht eine Speicherung: --console ohne --data-dir oder --database-url wird mit CONSOLE001 (StorageRequired) abgewiesen. Mit cargo build --release -p sibuna --no-default-features --features sqlite lässt sie sich herauskompilieren; ein Build mit --no-default-features allein hat weder Speicherung noch Konsole. Die lokale Ersteinrichtung erfolgt bei angehaltenem Daemon:
sibuna init-admin admin --data-dir ./data
sibuna --data-dir ./data --console 127.0.0.1:19446
sibuna console init-admin ist derselbe Befehl. http://127.0.0.1:19446/console/ öffnen und das erzeugte temporäre Passwort ersetzen, das bei der ersten Anmeldung geändert werden muss und nach einer Stunde abläuft. Die Navigation nach der Anmeldung bietet den animierten Länderglobus, Anfrage- und Challenge-Statistiken, die Untersuchung von Vorfällen, Editoren für Richtlinien und Prüfung, Benutzer, API-Tokens mit begrenztem Geltungsbereich, Audit sowie Steuerelemente für den bedienenden Knoten. Die Authentifizierungsoberfläche lädt weder Globusgeometrie noch Telemetrie. Die Oberfläche ist ein WebAssembly-Modul, das das Build-Skript des Daemons aus cmd/console-ui (Crate sibuna-console-ui) baut; es wird zusammen mit dem eingecheckten Stylesheet in gewöhnlichen Builds ausgeliefert.
| Option | Bedeutung |
|---|---|
--console <ip:port> |
Die Konsole auf diesem Listener starten (IPv6 in eckigen Klammern, Port ungleich null); erfordert --data-dir oder --database-url |
--console-key-file <path> |
64 Hex-Zeichen, Rechte nur für den Eigentümer; schützt gespeicherte Geheimnisse für den zweiten Faktor und für Webhooks |
--console-origin <https-origin> |
Der kanonische HTTPS-Origin hinter einem Proxy |
--console-behind-proxy |
Ein TLS-terminierender Proxy liefert jede Anfrage |
--console-trusted-proxy <cidr> |
Ein Netz, dessen Verbindungen weitergeleitete Felder tragen dürfen; wiederholbar, höchstens 16 |
--console-advertise <origin> |
Der Link, den andere Konsolen für diese anzeigen |
--console-location <latitude,longitude> |
Die angegebene Position dieses Knotens auf dem Globus |
--console-probe <node-id>=<http://ip:port> |
Ein Data-Plane-Listener eines Peers, dessen Zustand geprüft wird; wiederholbar, höchstens acht |
--console-peer <node-id>=<https://origin> |
Ein Management-Peer; wiederholbar, höchstens acht |
--console-peer-key-file <path> |
Der Peer-Schlüssel: nur für den Eigentümer, 64 Hex-Zeichen, unabhängig vom Konsolenschlüssel |
--console-peer-ca-file <path> |
Optionale PEM-Vertrauensanker für Peers, die die Systemwurzeln ersetzen |
--console-query-steps <n> |
SQLite-Schritte pro Aggregatabfrage, 100.000 bis 50.000.000, Standard 4.000.000 |
--console-capture-heads |
Geschwärzte Köpfe von Anfrage und Ursprungsantwort pro Vorfall speichern; standardmäßig aus |
--console-capture-header <name> |
Den Wert dieses Headers in gespeicherten Köpfen behalten; wiederholbar, höchstens 16; erfordert --console-capture-heads |
--console-cookie-secure |
Konsolen-Cookies ohne Proxy das Attribut Secure geben (vom Parser akzeptiert, nicht in --help aufgeführt) |
Eine Konsolenoption ohne --console, eine wiederholte Option oder ein fehlerhafter Wert bricht den Start mit CONSOLE002 und dem Fehlernamen der Option ab. Eine Konfiguration, die eine Regel der Konsole verletzt (zum Beispiel ein Listener außerhalb des Loopbacks ohne vertrauenswürdigen Proxy), bricht ihn mit CONSOLE001 ab.
Ein Rundgang durch die Konsole¶
Die folgenden Bildschirmfotos stammen von einem Release-Build auf einem Loopback-Knoten mit SQLite-Speicher und einer Richtlinie aus vier ALLOW-Regeln über einer Standard-Challenge, nach etwa vier Minuten synthetischen Datenverkehrs: Adressen aus Dokumentationsbereichen, Sondierungen auf SQL-Injection und Cross-Site-Scripting, drei Honeypot-Treffer und sieben in Headless Chromium gelöste Challenges. Jede Zahl ist daher nur ein Beispiel. Wir haben sie mit cargo xtask browser console --viewport-only aufgenommen; der Befehl durchläuft die Konsole in Chromium mit 1440 mal 960 Pixeln und bewertet jede Seite. Jede Seite beantwortet eine Frage, die in ihrem Titel steht, und zeigt an derselben Stelle das Produkt, den bedienenden Knoten, die Seite und den Weg zurück.
waf:sqli und waf:xss). Nicht erfasste Werte sagen das, statt null zu zeigen: Die Kachel Reputation zeigt „Not recorded“. Weiter unten auf der Seite stehen Befunde über sechzig gleiche Intervalle, Angriffskategorien und angegriffene Pfade.¶
--console-capture-heads öffnet sich auf Anforderung der geschwärzte Anfragekopf (und bei auditierten Zulassungen über den Reverse Proxy der Kopf der Ursprungsantwort), dargestellt als UTF-8 oder Latin-1, mit Angabe des Antwortzustands (erfasst, lokal, bei Forward-Auth nicht beobachtet, Ursprungsserver nicht verfügbar) und einem Befehl zum Kopieren als cURL; nur aufgelistete Header-Werte werden behalten, und --console-capture-header <name> erweitert diese Liste. Andernfalls gelten Köpfe als nicht erfasst. Die Aktionen Deny und Allow öffnen das Formular für IP-Gruppen mit der Adresse als Entwurf.¶
Die optionale Angabe --console-location <latitude,longitude> legt die Position dieses Knotens fest, zum Beispiel 1.3521,103.8198 für einen Einsatz in Singapur. Der Globus ist zunächst dort zentriert; Center Sibuna kehrt nach einer Drehung zu diesem Punkt zurück. Die Aktivität der Länder folgt animierten Großkreisbögen zum Knoten, mit Abschneiden an der Rückseite der Halbkugel und an der Datumsgrenze der flachen Karte. Länderpositionen sind repräsentative Schwerpunkte, und Pfeile stellen das beobachtete Fenster von sechzig Sekunden dar, nicht einzelne Verbindungen. Eine nicht gesetzte Serverposition bleibt ausdrücklich unbekannt. Die konfigurierte Markierung bleibt bei Telemetrieausfällen sichtbar; veralteter Datenverkehr wird nicht animiert.
Richtlinienvorschauen bauen einen privaten Kandidaten einschließlich der konfigurierten Dateiregeln. Beim Speichern wird die erwartete Revision verglichen, und ein Feldvergleich muss bestätigt werden. Historische Rücknahmen vergleichen mit der aktuellen Regel und erzeugen eine neue Revision. Festgeschriebene und lokal angewandte Revisionen sind verschieden. Audit-Details behalten begrenzte Entscheidungsänderungen und die tatsächlich handelnde Rolle. Werte von Matchern werden geschwärzt, und bei alten Datensätzen bleibt fehlender Kontext ausdrücklich als fehlend gekennzeichnet. Drain, Resume und das Löschen lokaler Sperren erfordern eine Befehlsvorschau. Ein Befehl, der eintrifft, während auf dem Knoten ein anderer läuft, wird mit 503 CONSOLENODE abgewiesen, statt in eine Warteschlange zu kommen. Nach einer verlorenen Antwort vor einem neuen Versuch die dauerhafte Quittung prüfen; eine festgeschriebene Absicht allein belegt nicht, dass die Wirkung zur Laufzeit abgeschlossen ist.
Für den Fernbetrieb einen HTTPS-Proxy verwenden und --console-origin, --console-behind-proxy, ausdrückliche CIDRs für --console-trusted-proxy und --console-key-file konfigurieren. Die Schlüsseldatei enthält 64 hexadezimale Zeichen, hat Rechte nur für den Eigentümer und schützt gespeicherte Geheimnisse für den zweiten Faktor; sie ist über Neustarts hinweg getrennt vom Challenge-Seed aufzubewahren. Der konfigurierte HTTPS-Ursprung und die Allowlist der Proxys sind für Zugriffe außerhalb des Loopbacks Pflicht. Auch auf dem Konsolen-Listener terminiert Sibuna kein eingehendes TLS; die Konsole nutzt TLS nur für ihre ausgehenden Verbindungen, über rustls (SID 0012).
Die native CLI greift über dieselben Autorisierungs- und Speicherverträge auf die laufende Konsole zu. Sie liest Anmeldedaten aus privaten Dateien, nicht aus Werten der Kommandozeile:
sibuna console geoip update --version 2026-09-09 \
--origin http://127.0.0.1:19446 --username admin \
--password-file ./admin-password
Eine Passwortdatei nur für den Eigentümer verwenden, zuerst die Passworteinrichtung abschließen und bei Bedarf --factor-file für einen Authenticator- oder Wiederherstellungscode hinzufügen; --token-file ersetzt Benutzername und Passwort bei Konto- und GeoIP-Operationen. Der Client spricht HTTP/1.1, verlangt HTTPS außer bei einer literalen Loopback-Adresse, folgt nie Weiterleitungen und begrenzt jede Anfrage auf 20 Sekunden und jede Antwort auf 16 KiB. geoip status liest die aktive Generation. Aktualisierungen laden die veröffentlichten Dateien des gewählten Anbieters über HTTPS herunter (standardmäßig den gemeinfreien Datensatz user-country oder DB-IP Lite mit --provider dbip --version YYYY-MM), prüfen die Prüfsummen des Herausgebers (oder die mit --checksum angegebene), validieren begrenzte Bereiche über sibuna-geoip, speichern die neue Generation dauerhaft und aktivieren sie lokal. Fehlgeschlagene Aktualisierungen erhalten die vorherige Generation. Ein CLI-Timeout (--timeout, Standard 1200 Sekunden) beendet das Warten; es bricht bereits übergebene Speicherarbeit nicht ab. DB-IP Lite verlangt eine Namensnennung nach CC BY 4.0, die nur angezeigt wird, solange seine Daten aktiv sind. Ein Build mit SIBUNA_GEOIP_DATA=<snapshot> bettet einen validierten Snapshot ein (geschrieben vom Werkzeug geoip-snapshot), der bis zum ersten dauerhaften Import gilt; ein Build ohne Konsole weist ihn mit GEOIP001 ab. Unbekannte Adressen, Stichprobenverluste und veraltete Daten bleiben sichtbar; der Import von Länderdaten erzeugt keinen Datenverkehr und reichert keine bereits abgelaufenen Stichproben an.
Cluster-Mitglieder kündigen sich über die Mitgliedertabelle der gemeinsamen Datenbank (console_nodes) an: beim Start, jede Minute und innerhalb von zwei Sekunden nach einer Änderung der angewandten Richtlinien- oder Steuerrevision; sie erscheinen auf der Seite Nodes jeder Konsole. Es gibt keine Leader-Wahl: Ein SQLite-Knoten meldet die Rolle single und sich selbst als Leader, und ein PostgreSQL-Knoten meldet die Rolle unknown und keinen Leader, weil das Failover von PostgreSQL für Sibuna nicht sichtbar ist (SID 0007). --console-probe <node-id>=<http://ip:port> für die Peers konfigurieren, deren Data-Plane-Listener diese Konsole auf ihren Zustand prüfen soll, und --console-advertise <origin> für den Link, den andere Konsolen anzeigen. Direkte Live-Telemetrie verwendet --console-peer <node-id>=<https://origin> (wiederholbar, höchstens acht) und eine eigene --console-peer-key-file. Peers erfordern --console-behind-proxy. Beide Endpunkte müssen einander aufführen und einen vertrauenswürdigen HTTPS-Eingangsproxy nutzen. Der Peer-Schlüssel ist eine Datei nur für den Eigentümer mit 64 Hex-Zeichen, die unabhängig vom Konsolenschlüssel und vom Challenge-Seed bereitgestellt wird. Peers kommunizieren über einen authentifizierten TLS-WebSocket, über rustls mit dem Provider ring (SID 0012). --console-peer-ca-file liefert optional PEM-Vertrauensanker für eine private Management-PKI; andernfalls nutzt der Client die Systemwurzeln. Die Prüfung des Hostnamens gilt immer und lässt sich nicht abschalten: Der Host jedes Management-Ursprungs, ein DNS-Name oder ein IP-Adressliteral, muss im Zertifikat des Peers genannt sein. Ein abgewiesenes Zertifikat markiert den Peer als rejected und schreibt eine Audit-Zeile peer.rejected. Schlüsselrotation und ein Wechsel der CA-Datei erfordern einen koordinierten Neustart; das Zertifikat eines Peers lässt sich ohne Neustart erneuern. Die Knoten-API und ihr Abonnement melden das Alter der Quittung, die Uhrenabweichung, Neustarts und Stichprobenverluste. Fehlende Beobachtungen bleiben nicht verfügbar, und getrennte Werte bleiben veraltet; empfangene Statistiken werden nie zum eigenen Beitrag eines anderen Knotens. Der Live traffic scope des Dashboards wählt einen Knoten oder kombiniert die konfigurierten Knoten. Node coverage and locations zeigt fehlende, veraltete und zeitlich abweichende Quellen, Beobachtungszeiten und konfigurierte Ziele. Länderranglisten zeigen die Unsicherheit durch ausgelassene Quellzeilen. Pfeile behalten ihren empfangenden Knoten, und fehlende Knotenpositionen werden nicht erfunden. Die kombinierte Rate bleibt unbeobachtet, wenn einer beitragenden Quelle ein lückenloses Intervall fehlt. Einen Knoten wählen, um seine aufbewahrten Sekunden und die Pfadranglisten der laufenden Minute zu untersuchen. Entfernte Abfragen nutzen die authentifizierte Peer-Verbindung; eine Antwort muss in eine WebSocket-Nachricht von 4 KiB passen, daher halbiert die bedienende Konsole die Zeilen einer Seite, die nicht passt. Fehlende Peers bleiben nicht verfügbar, und Verlaufscursor können keinen Neustart eines Knotens überqueren. Der Minutenverlauf behält seine eigene Knotenauswahl und Zeilen pro Knoten. Navigation und mobiler Kopfbereich nennen den bedienenden Konsolenknoten unabhängig von der gewählten Quelle des Datenverkehrs. Lokale Befehle bleiben pro Knoten.
Die Traffic-Kacheln öffnen mit den letzten 24 Stunden aufbewahrter Datensätze abgeschlossener Minuten für die gewählten Knoten. Die Zeitraumauswahl bietet außerdem eine Stunde, sieben oder neunzig Tage und die Live-Summen seit dem Start. Abweichungen gegenüber gestern erfordern vollständige passende Abdeckung von jedem gewählten Knoten. Globus und Sparklines beschreiben weiterhin ihr eigenes Live-Fenster von 60 Sekunden. Eine aufbewahrte Auswertung wird eine Minute nach ihrem Abschluss aufgefrischt und hält ihre vorigen Werte und deren Alter bis zur Ersetzung sichtbar; ein Wechsel der Quelle oder des Zeitraums verwirft den alten Umfang. Fehlender Verlauf wird nie zu null.
Compare retained traffic zeigt zwei abgeschlossene Minutenfenster nebeneinander: dasselbe Fenster gestern, den vorhergehenden Zeitraum oder einen zweiten Knoten. Steuerelemente für Dauer und Endversatz frieren beide UTC-Bereiche ein. Jede Aktion liest höchstens sechzehn kompakte Seiten pro Seite des Vergleichs, mit 96 gespeicherten Datensätzen pro Seite. Das deckt ein Fenster von 24 Stunden ohne überlappende Neustarts in einem Durchgang ab; Continue behält für längere Auswertungen dieselben Grenzen bei. Vollständige Abdeckung, unvollständige Abdeckung und fehlender Verlauf bleiben ausdrücklich sichtbar. Prozentuale Raten erfordern vollständige, nicht überlappende Intervalle in gleichen UTC-Fenstern, normiert auf beobachtete Millisekunden; eine Referenz von null mit neuem Datenverkehr zeigt „New“. Der Hauptzeitraum der Seite Traffic bleibt unabhängig. Das Minutenformat erfasst den historischen Proxy-Modus nicht, daher bleiben Vergleiche von Ursprungsantworten nicht verfügbar, statt Nullen aus dem Forward-Auth-Modus als beobachtete Antworten zu deuten.
Compare retained path rankings wählt zwei abgeschlossene Fenster oder Knoten. Knoten 0 umfasst alle aufbewahrten Knoten, auch ausgeschiedene Mitglieder. Eine Aktion liest höchstens sechzehn unveränderliche Archive, prüft ihre Identitäten und Prüfsummen und führt jeden Zähler zusammen, bevor sie Anzeigezeilen auswählt. Archive werden nach dem Fenster von 60 Sekunden für verspätete Stichproben versiegelt, sodass die neueste abgeschlossene Minute noch ausstehen kann. Continue bewahrt die ursprünglichen Fenster und den Cursor. Die Grenzen beschreiben stichprobenartig erfasste Pfadpräfixe, keine exakten Anfragesummen. Die Seite zeigt unvollständige Auswertungen, Abschneidungen, Aufbewahrungsgrenzen und gemeldete Verluste in der Warteschlange; fehlende Archive können weder ausbleibenden Datenverkehr noch vollständige Abdeckung belegen.
Die Seite Security öffnet mit den letzten 24 Stunden und verwendet sechzig gleiche Zeitintervalle über den gewählten Zeitraum. Ihre Aggregate laufen auf dem Speicherthread unter einer Arbeitsgrenze. Unter SQLite ist die Grenze --console-query-steps Schritte der virtuellen Maschine (100.000 bis 50.000.000, Standard vier Millionen). Sie wird zusammen mit --console gesetzt; ungültige oder wiederholte Werte werden abgewiesen. Unter PostgreSQL ist die Grenze ein Statement-Timeout von 2.000 ms, das in der Transaktion der Leseoperation gesetzt wird (SID 0013); eine Änderung von --console-query-steps ändert es nicht. Erschöpfte Abfragen bitten um einen engeren Zeitraum. Schrittzahlen begrenzen die Arbeit einer Abfrage, nicht die verstrichene Zeit. Diagramme teilen sich eine Skala; die Trend-Werte aufklappen, um die UTC-Intervallanfänge und die exakten gruppierten Zählungen zu sehen. Dies sind aufbewahrte Befunde, daher darf fehlende Vorfallsabdeckung nicht als Abwesenheit von Angriffen gedeutet werden.
Wandanzeigen verwenden Kiosk-Sitzungen. Unter Account benennt ein Betreiber die Anzeige und wählt Create display code. Die Anzeige fügt den Einmalcode innerhalb von zehn Minuten in das Anmeldeformular ein; ihre Sitzung ist schreibgeschützt, auf Statistiken beschränkt und läuft innerhalb von zwölf Stunden ab. Die Kontoseite löscht den angezeigten Code beim Navigieren oder wenn sie verborgen wird. Das Verbergen widerruft eine unbenutzte Berechtigung nicht; die Frist für den Austausch gilt weiterhin. Codes gehören nie in URLs. Traffic und Security teilen sich die Anzeige: Security zeigt aggregierte Modultrends und Anfrageergebnisse ohne Vorfallsadressen oder Nutzlastbelege. Automatisches Durchschalten ist optional, anfangs aus und wird bei reduzierter Bewegung, veralteten Daten oder Pause ausgesetzt.
Benachrichtigungsziele (signierte Webhooks und Syslog für Ablehnungsspitzen, Sperren, unerreichbare Mitglieder und Leader-Wechsel) liegen unter Settings; Webhook-Geheimnisse brauchen --console-key-file. Die Art Leader-Wechsel bleibt definiert, damit gespeicherte Ziele ihre Bedeutung behalten, aber kein Knoten löst sie aus, weil es keine Leader-Wahl gibt. Jedes Ziel hat seine eigene Abklingzeit und ein Budget von drei Zustellversuchen. Audit-Datensätze der Zustellung zeigen die Ergebnisse; der Verlauf abgeschlossener Warteschlangeneinträge ist auf sieben Tage und 4.096 Ereignisse begrenzt. Webhooks enthalten einen stabilen Idempotency-Key, damit Empfänger wiederholte Wirkungen nach unsicherem Netzwerkabschluss unterdrücken können. Webhooks werden über HTTPS gesendet, oder über reines HTTP nur an eine literale Loopback-Adresse, und der Antwortbody wird bis zu 64 KiB gelesen. Die Wahl zwischen UDP und TCP für Syslog gilt nur für ausgehende Benachrichtigungen, unabhängig vom geschützten Web-Datenverkehr. Manuelle Tests erfassen Absicht und Abschluss im Audit und frischen das Ergebnis des Ziels auf; ein unbestätigter Audit-Abschluss wird ausdrücklich angezeigt, bevor ein Betreiber es erneut versucht.
Settings steuert auch die Aufbewahrung: ein bis 90 Tage für den Minutenverlauf, ein bis sieben für Ranglisten, ein bis 30 für Vorfälle und ein bis 365 für das Audit. Die oberen Werte sind die Standardwerte; Ranglisten behalten ihr Kontingent von 512 MiB. Das Speichern eines Aufbewahrungswerts erfordert eine Bestätigung, weil die Bereinigung ältere Datensätze in begrenzten Durchgängen endgültig entfernt. Ein späteres Erhöhen des Werts stellt gelöschten Verlauf nicht wieder her. Veraltete Änderungen werden abgewiesen, und erfolgreiche Änderungen erscheinen im Audit.
Antwortseiten (Challenge, abgelehnt, Ratenlimit erreicht, gesperrt, überlastet) lassen sich unter Settings als begrenztes HTML mit festen Platzhaltern bearbeiten; Entwürfe werden in einem Tab mit Sandbox als Vorschau gezeigt, und gespeicherte Seiten werden ab dem nächsten Richtlinienschnappschuss ausgeliefert.
Richtlinien-Workflows auf der Seite Policies: verwaltete Regeln neu ordnen, einen Entwurf gegen aufbewahrte Prüfbefunde abspielen, IP-Gruppen und Ländersperren verwalten, die an die aktive GeoIP-Generation gebunden sind, und den verwalteten Satz exportieren oder atomar importieren (auch sibuna console policies export und sibuna console policies import --file <set.json>). Ein Import ist eine Anfrage mit 1 bis 128 Dokumenten von je höchstens 4 KiB und insgesamt höchstens 256 KiB; der Hinweis der Seite nennt den Import über die Kommandozeile für Sätze über etwa 96 KiB. Angewandte Regeln zeigen die heute erfassten Treffer, stündliche Sparklines und eine barrierefreie Tabelle. Ein Treffer ist eine erfolgreiche Auswertung eines deklarativen Matchers: Passende WEIGH-Regeln und der erste terminale Treffer zählen; eine frühere Prüf- oder Reputationsentscheidung kann die Auswertung verhindern. Private Tests erhöhen diese Zähler nicht. Compare rule hits friert zwei abgeschlossene Zeiträume für einen erfassten Knoten ein. Der Revisionsverlauf bietet Compare hits around this edit; dabei wird die Minute der Änderung ausgeschlossen, und es werden gleiche verfügbare Zeiträume bis zur gewählten Dauer verwendet. Optionale Filter nach angewandter Revision halten fremde Generationen aus dem Vergleich heraus. Start, Umstellung, fehlende Schreibvorgänge und Aufbewahrung hinterlassen sichtbare Abdeckungslücken; Prozentangaben erfordern vollständige Abdeckung auf beiden Seiten. Regelbeobachtungen und stündliche/tägliche Zusammenfassungen folgen der Einstellung für die Minutenaufbewahrung. Eine beobachtete Änderung rund um eine Bearbeitung ist ein Vergleich, kein Beleg dafür, dass die Bearbeitung die Änderung des Datenverkehrs verursacht hat.
Der Import einer späteren GeoIP-Generation frischt vorhandene, aus Ländern abgeleitete Reputationszeilen nicht automatisch auf. Die Vorschau der Länderaktion ansehen, um hinzugefügte, behaltene und entfernte Präfixe zu vergleichen, und vor dem Anwenden durch den geprüften Diff blättern. Die Ersetzung entfernt veraltete Zeilen, die diesem Land gehören, und bewahrt unabhängig verwaltete Präfixe. Eine geänderte Generation oder Richtlinienrevision erfordert eine neue Vorschau, und überlappende unabhängige Änderungen werden abgewiesen. Die Seite Events enthält aufbewahrte WAF-Befunde und Honeypot-Vorfälle; sie ist kein vollständiges Zugriffsprotokoll. Mit geladenem GeoIP erfasst der Speicherthread Land und Generation jedes Vorfalls in der Transaktion des Vorfallsstapels. Das ist eine Zuordnung zum Zeitpunkt der Speicherung, keine rekonstruierte Position zum Zeitpunkt der Anfrage. Spätere Importe lassen erfasste Zuordnungen unverändert. Der Länderfilter akzeptiert einen großgeschriebenen Code aus zwei Buchstaben, unknown für eine Adresse, die in der geladenen Generation fehlt, oder not_recorded für einen Vorfall ohne Zuordnungsdaten. Quellgruppen melden gemischte Länder oder Abdeckung ausdrücklich. Die Aktion View events des Globus behält den gewählten Knoten bei und öffnet die aufbewahrten Vorfälle des Landes für die letzte Stunde. Die Ansicht Security der Seite Statistics kombiniert Live-Raten von Ratenlimits, Challenges und Sperren mit aufbewahrten Prüf- und Honeypot-Befunden über eine Stunde, einen Tag, sieben Tage oder dreißig Tage. Links zu Kategorie, Quelle und Pfad öffnen den normalen Vorfalls-Workflow mit demselben Knoten und einer festen Zeitgrenze. Das Anwenden von Vorfallsfiltern beginnt einen neuen Zeitraum. Befunde schließen Audit-Datensätze ein und sind von den Summen blockierter Anfragen verschieden; fehlende Zuordnungen zu Reputation und Regeltreffern werden als nicht erfasst angezeigt. Ereignis- und Audit-Filter halten Beschriftungen bei ihren Steuerelementen, richten die Aktion Apply getrennt aus und passen ihre Spalten an die verfügbare Inhaltsbreite an. Ein authentifizierter WebSocket überdauert die Navigation und überträgt Statistiken, Vorfallszusammenfassungen, Knotenstatus, Richtlinienrevisionen, Challenges und Audit-Zusammenfassungen. Neue Vorfalls- und Audit-Datensätze warten hinter Load latest records, damit die Tabelle beim Lesen an ihrem Platz bleibt. Richtlinienaktualisierungen zeigen die aktuellen festgeschriebenen und angewandten Revisionen, ohne einen offenen Entwurf zu ersetzen. Flusszähler werden live aktualisiert; eine gewählte, vom Standard abweichende Partition der Challenge-Zeiten ausdrücklich auffrischen. Historische Abfragen, Detailabrufe und Änderungen bleiben HTTP-Anfragen.
Seitenfragmente lassen sich als Lesezeichen speichern; Zurück und Vorwärts öffnen authentifizierte Seiten erneut. Die Seitenleiste merkt sich in diesem Browser außerdem die gewählten Einstellungen für Theme und Abstände; Standard-Theme ist System. SID 0007 hat den Status Committed. Die Konsole besteht ihre Golden Fixtures und ihre Browser-Workflows in Headless Chromium (cargo xtask browser console, SID 0010, Kriterium 5). Ihre End-to-End-Testsuite ist cmd/sibuna/tests/console_*.rs; deren PostgreSQL-Clusterszenarien laufen, wenn SIBUNA_TEST_DATABASE_URL gesetzt ist. SID 0010 hält fest, dass die 16 Produkt-Arbeitslasten mit einkompilierter Konsole, ob deaktiviert, nur mit Speicherung oder aktiviert und im Leerlauf, innerhalb von etwa 1 % des ohne Konsole gebauten Daemons bleiben, also im Rauschen. Das formale Isolationskriterium von SID 0007, mit acht aktiven Dashboards unter Last, ist noch nicht gemessen (Teil VIII). Die vollständige WebAssembly-Anwendung hat eine unkomprimierte Obergrenze von 768 KiB, die das Build-Skript des Daemons durchsetzt, indem es den Build scheitern lässt, und eine Prüfschwelle von 640 KiB. In 1.0.0-beta.3 misst das Modul 724.330 Bytes (272.568 mit gzip) und liegt damit über der Prüfschwelle, was SID 0007 zur Überprüfung festhält. Diese Projektgrenzen lassen Raum für die Workflows der Konsole; sie ersetzen keine Messungen von Ladezeit und Reaktionsfähigkeit im Browser. Der lineare Speicher des Moduls wächst bei Bedarf bis zu einem deklarierten Maximum von 16 MiB.
Einsatztopologien¶
Reverse Proxy¶
sibuna --port 80 --upstream-host 127.0.0.1 --upstream-port 3000 \
--secret-file /etc/sibuna/secret --difficulty 16 --algorithm posw
Zugelassene Anfragen erreichen den Ursprungsserver mit den Headern X-Forwarded-For, X-Forwarded-Proto, X-Real-IP, X-Sibuna-Status und X-Sibuna-Rule. Hop-by-Hop-Header, die Felder, die Sibuna selbst schreibt, und die alternativen Weiterleitungsfelder (Forwarded, X-Forwarded-Host, X-Forwarded-Port) werden entfernt, auch wenn ein Client ihre Namen mit Unterstrichen schreibt (X_Forwarded_For). X-Real-IP ist der Client, nach dem die Anfrage beurteilt wurde. X-Forwarded-For ist allein der Socket-Peer, nie ein vom Client geschriebener Eintrag; wenn der weitergeleiteten Identität vertraut wird, ist es die empfangene Kette, gefolgt vom Socket-Peer. Ursprungsserver müssen den Client daher aus X-Real-IP oder von rechts aus X-Forwarded-For lesen, nie aus dessen linkestem Eintrag. Der Pfad, den der Ursprungsserver erhält, ist die Normalform, die die Richtlinie beurteilt hat (SID 0009); ein Pfad ohne Normalform wird mit 400 beantwortet.
WebSocket-Upgrades unter HTTP/1.1 durchlaufen Zulassung und Richtlinienprüfung, bevor der Handshake des Ursprungsservers angenommen wird. Die Aushandlung von Subprotokollen und Erweiterungen bleibt Ende-zu-Ende. Zwei Threads leiten Bytes weiter, einer pro Richtung, jeder mit einem festen Puffer, einschließlich vorab gelesener Bytes und halbseitiger Schließungen; eine per Upgrade umgestellte Verbindung hält daher zwei Threads, und die Zahl der Verbindungsthreads kann das Doppelte von --max-connections erreichen, wenn jede Verbindung umgestellt ist. Umgestellte Sockets bleiben im normalen Verbindungskontingent und im Shutdown-Register, verwenden aber --websocket-idle-timeout (standardmäßig 300 Sekunden) unabhängig von der HTTP-Leerlauffrist. Datenverkehr in einer der beiden Richtungen erneuert diese Grenze, aber ein Peer, der während der ganzen Periode kein Byte annimmt, beendet die Weiterleitung, wie beschäftigt die andere Richtung auch ist. Frames nach dem Handshake sind keine Eingaben der WAF-Prüfung. HTTPS/WSS nutzt einen TLS-terminierenden Eingangsproxy vor dem privaten HTTP/1.1-Listener von Sibuna; Sibuna terminiert Browser-TLS nicht selbst.
Der Eingangsproxy kann mit Browsern HTTP/2 aushandeln und HTTP/1.1 an Sibuna weiterleiten. Native HTTP/2-Unterstützung in Sibuna ist auf ein späteres Update verschoben; diese Anordnung bietet keine Ende-zu-Ende-Semantik von HTTP/2 für Anwendungen wie natives gRPC.
Anfragebodys mit Content-Length fließen durch feste Puffer, wobei Bytes und MIME-Header erhalten bleiben. Multipart-Uploads behalten Grenzen, wiederholte Feldnamen, Dateinamen und Teiltypen. Die WAF untersucht höchstens die ersten 8 KiB des Bodys: Multipart-Metadaten und Felder, die keine Dateien sind, bleiben Eingaben der Textprüfung, während Dateinutzlasten undurchsichtig sind. Ein Teil, dessen filename leer ist, ist ein gewöhnliches Feld. Ein Body eines erkannten binären MIME-Haupttyps (Bilder außer SVG, Audio, Video, PDF, ZIP, gzip, 7z, protobuf und octet-stream) ist nur dann undurchsichtig, wenn auch sein Präfix binär aussieht, das heißt, wenn mindestens eines von sechzehn Bytes ein Steuerbyte außer Tabulator, Zeilenvorschub, vertikalem Tabulator, Seitenvorschub und Wagenrücklauf ist; andernfalls wird er als Text geprüft (SID 0004). JSON, XML, SVG, URL-codierte Formulare und unbekannte Typen behalten die Textprüfung. Mehrdeutige oder fehlerhafte MIME-Metadaten fallen auf die Textprüfung zurück. Das Multipart-Parsing ist innerhalb desselben Präfixes auf 32 Teile und 2 KiB Header pro Teil begrenzt und akzeptiert das Transport-Padding nach RFC 2046 nach einem Trennzeichen.
Das ist Upload-Kompatibilität, keine Dateivalidierung und keine Malware-Prüfung. Das Backend muss akzeptierte Medientypen selbst durchsetzen, statt der Content-Type-Angabe eines Clients zu vertrauen. Felder nach dem Prüfpräfix, auch solche nach einer großen hochgeladenen Datei, werden nicht geprüft. Komprimierte Nutzlasten werden für die Prüfung nicht dekomprimiert. Uploads durchlaufen dennoch Zulassung sowie Pfad-, Query- und Header-Prüfungen und unterliegen weiterhin den Verbindungsfristen. Chunked-Anfragebodys werden vor der Prüfung im Verbindungspuffer dekodiert (SID 0009). Ein Body, der innerhalb des Puffers endet, erreicht das Backend mit Content-Length. Ein längerer wird von Sibuna neu in Chunks zerlegt, ein Chunk pro Leseoperation, sodass das Backend nie die Chunk-Größen, Erweiterungen oder Trailer des Clients sieht. Eine Chunk-Zeile mit einem einzelnen CR oder LF, Leerraum um die Größe, einer fehlerhaften Erweiterung oder mehr als 4 KiB wird mit 400 abgewiesen. Ebenso ein Trailer-Abschnitt über 16 KiB. Transfer-Encoding mit einer anderen Kodierung erhält 501. Backends, die keine Chunked-Anfragen parsen können, erhalten für Bodys unter etwa 44 KiB weiterhin Content-Length. Eine Verbindung zum Ursprungsserver, die einen Anfragebody übertragen hat, wird nach ihrem Austausch geschlossen und kehrt nie in den Pool zurück. Clients, die auf 100-continue warten, erhalten es lokal, bevor sie den Body senden; nicht unterstützte Erwartungen erhalten 417. Der Expect-Header wird vor der Weiterleitung an das Backend verbraucht.
Forward-Auth hinter einem Eingangsproxy¶
Mit --mode forward_auth beantwortet der Daemon die Unteranfrage des Eingangsproxys mit 200 (plus den Audit-Headern X-Sibuna-Status, X-Sibuna-Rule und X-Sibuna-Rule-Hash), 401 für eine Challenge, 403 für eine Ablehnung oder 429 bei erreichtem Ratenlimit. Der Eingangsproxy muss die Client-Adresse und die ursprüngliche URL weiterleiten; der Forward-Auth-Modus vertraut ihnen standardmäßig. Dieser Listener wird privat gebunden, damit sich nur der Eingangsproxy verbinden kann. X-Forwarded-Uri (Caddy) oder X-Original-URI (Nginx) und X-Forwarded-Method stellen die Anwendungsanfrage für die Richtlinienauswertung wieder her; der ursprüngliche Pfad wird in Normalform gebracht, so wie der Pfad einer Anfragezeile. Doppelte oder widersprüchliche Felder für die ursprüngliche URL und eine ursprüngliche URI, die nicht in Origin-Form vorliegt, werden mit 400 abgewiesen. Interne Routen des Daemons verwenden immer die tatsächliche Anfrage-URI. Forward-Auth prüft keinen Body, den der Eingangsproxy weglässt.
map $http_upgrade $sibuna_connection_upgrade {
default upgrade;
'' close;
}
server {
listen 443 ssl;
location / {
auth_request /__sibuna_auth;
auth_request_set $sibuna_auth_status $upstream_status;
auth_request_set $sibuna_retry_after $upstream_http_retry_after;
auth_request_set $sibuna_status $upstream_http_x_sibuna_status;
auth_request_set $sibuna_rule $upstream_http_x_sibuna_rule;
auth_request_set $sibuna_rule_hash $upstream_http_x_sibuna_rule_hash;
error_page 401 = @sibuna_challenge;
error_page 500 = @sibuna_auth_error;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $sibuna_connection_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Sibuna-Status $sibuna_status;
proxy_set_header X-Sibuna-Rule $sibuna_rule;
proxy_set_header X-Sibuna-Rule-Hash $sibuna_rule_hash;
proxy_read_timeout 300s;
proxy_pass http://127.0.0.1:3000;
}
location = /__sibuna_auth {
internal;
proxy_pass http://127.0.0.1:8080/;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
proxy_set_header X-Forwarded-Method $request_method;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Uri "";
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header User-Agent $http_user_agent;
proxy_set_header Cookie $http_cookie;
}
location @sibuna_challenge {
rewrite ^ /__sibuna/challenge break;
proxy_pass http://127.0.0.1:8080;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
proxy_set_header X-Forwarded-Method $request_method;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
}
location @sibuna_auth_error {
add_header Retry-After $sibuna_retry_after always;
if ($sibuna_auth_status = 429) { return 429; }
return 503;
}
location /__sibuna/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header X-Forwarded-For $remote_addr;
}
}
example.com {
handle /__sibuna/* {
reverse_proxy localhost:8080
}
handle {
forward_auth localhost:8080 {
uri /
header_up X-Forwarded-For {remote_host}
header_up -X-Original-URI
copy_headers X-Sibuna-Status X-Sibuna-Rule X-Sibuna-Rule-Hash
}
reverse_proxy localhost:3000
}
}
Der Namensraum /__sibuna/* (Zwischenseite, Challenge, Verifikation, Assets des Lösers) muss in beiden Rezepten den Daemon direkt erreichen. Die Fehlerseite von nginx übergibt die ursprüngliche URI und Methode, damit die Zwischenseite die Anforderung trägt, die die Autorisierung entschieden hat; ohne sie funktioniert die Seite trotzdem, und die Ausgabe fällt darauf zurück, die vom Browser gemeldete URL auszuwerten. Caddy liefert die Metadaten zu ursprünglicher URI und Methode selbst. Die exklusiven handle-Blöcke stellen sicher, dass Challenge- und Verifikationsrouten nicht in die Forward-Auth-Vorprüfung gelangen. Nginx benötigt für WebSockets der Anwendung die oben gezeigten ausdrücklichen Upgrade/Connection-Header. Der Fehlerhandler von Nginx stellt die interne Challenge-Route dar, ohne eine zweite Autorisierungsentscheidung zu treffen oder den Upload-Body zu verbrauchen. Sein Auth-Modul akzeptiert direkt nur 2xx, 401 und 403, daher übersetzt das Beispiel einen Auth-Fehler wegen Ratenlimit zurück in 429 mit Retry-After; andere Autorisierungsfehler bleiben mit 503 geschlossen. Nginx liefert seinen eigenen 403-Body, während Caddy die Ablehnungsseite von Sibuna weiterleitet. Beide Rezepte ersetzen eingehende Audit-Header von Sibuna durch die tatsächliche Autorisierungsantwort. Normale TLS-Zertifikate und die Upload- und Fristgrenzen der Anwendung werden am Eingangsproxy konfiguriert; die Beispiele zeigen die Routing-Logik. Das Repository testet diese Rezepte noch nicht gegen laufende Eingangsproxys; die Regeln für weitergeleitete Metadaten, auf die sie sich stützen, sind durch Unit-Tests in sibuna-http abgedeckt.
JA4-Fingerabdrücke vom Eingangsproxy¶
Ein JA4-Fingerabdruck fasst zusammen, wie ein Client eine TLS-Verbindung öffnet. Er wird aus der ersten Handshake-Nachricht des Clients berechnet, dem ClientHello. Die TLS-Bibliothek des Clients legt diese Nachricht fest, bevor ein einziges HTTP-Byte gesendet wird, daher kann ein Client seinen Fingerabdruck nicht aus seinen HTTP-Anfragen heraus ändern. Browser, Bibliotheken und Bots unterscheiden sich darin. Das macht JA4 zu einem stärkeren Signal als ein User-Agent-Wert, den jeder Client nach Belieben schreiben kann (SID 0014). JA4 wurde von FoxIO definiert. Ein Fingerabdruck hat 36 Zeichen in drei Teilen, die durch _ verbunden sind:
t13d1516h2_8daaf6152771_02713d6af862
^^^^^^^^^^ ^^^^^^^^^^^^ ^^^^^^^^^^^^
a b c
a Protokoll (t TCP, q QUIC, d DTLS), TLS-Version (13 ist TLS 1.3),
d mit SNI oder i ohne, Anzahl der Cipher Suites (zweistellig),
Anzahl der Erweiterungen (zweistellig), ALPN-Code (h2 ist HTTP/2)
b 12-stelliger Hexadezimal-Hash (Kleinbuchstaben) der sortierten Cipher Suites
c 12-stelliger Hexadezimal-Hash (Kleinbuchstaben) der sortierten Erweiterungen
und Signaturalgorithmen
Nur die Komponente, die TLS terminiert, sieht das ClientHello, daher kann nur sie JA4 berechnen. Sibuna terminiert kein TLS: Es bedient einfaches HTTP/1.1 hinter einem Eingangsproxy, und der Eingangsproxy spricht TLS, HTTP/2 und HTTP/3 mit den Browsern. Mehrere Eingangsproxys berechnen JA4 bereits. Wir lassen daher den Eingangsproxy den Fingerabdruck berechnen und in einem Anfrage-Header senden, und Sibuna liest ihn von dort.
--ja4-header <name> benennt diesen Header. Die Option ist standardmäßig aus und hat keinen Standardnamen; wir nennen stets den Header, den der Eingangsproxy verwendet. Sibuna speichert den Namen in Kleinbuchstaben und vergleicht ihn ohne Beachtung der Groß-/Kleinschreibung. Es weist die Namen von Feldern ab, die es selbst schreibt oder entfernt (X-Forwarded-*, X-Real-IP, X-Sibuna-* und Forwarded, auch mit _ statt -). Ist die Option gesetzt, gibt das Start-Banner eine Zeile wie JA4: from cf-ja4 (trusted) aus.
Der Header wird nur gelesen, wenn weitergeleiteten Feldern vertraut wird. Das ist dieselbe Entscheidung, die für X-Forwarded-For gilt: --trust-forwarded oder der Forward-Auth-Modus ohne --no-trust-forwarded. Von einem nicht vertrauenswürdigen Peer wird der Header ignoriert. Mit Vertrauen trägt eine Anfrage einen Fingerabdruck, wenn genau ein Feld dieses Namens vorhanden ist und sein Wert die JA4-Form hat. Ein fehlerhafter Wert oder ein wiederholtes Feld lässt die Anfrage ohne Fingerabdruck. Zwei Zähler beobachten dies: sibuna_ja4_present_total zählt Anfragen mit einem Fingerabdruck, und sibuna_ja4_invalid_total zählt Anfragen, deren Header fehlerhaft oder wiederholt war. Eine Anfrage von einem nicht vertrauenswürdigen Peer erhöht keinen der beiden Zähler.
Im Reverse-Proxy-Modus sieht der Ursprungsserver den Header nur, wenn Sibuna ihm vertraut. Ohne Vertrauen entfernt Sibuna jedes Feld dieses Namens aus der Anfrage, die es an den Ursprungsserver sendet, auch wenn ein Client den Namen mit _ statt - schreibt. Ein Client kann dem Ursprungsserver daher unter diesem Namen keinen gefälschten Fingerabdruck unterschieben. Mit Vertrauen wird das Feld unverändert in seiner genauen Schreibweise weitergereicht, und ein Alias mit _ wird dennoch entfernt. Ohne --ja4-header ist ein Feld dieses Namens ein gewöhnliches Feld.
Cloudflare. Die verwaltete Transformation „Add bot protection headers“ fügt der an den Ursprungsserver gesendeten Anfrage cf-ja4 hinzu, neben cf-bot-score, cf-verified-bot und cf-ja3-hash. Sie erfordert einen Enterprise-Tarif mit Bot Management. Ein Eingangsproxy zwischen Cloudflare und Sibuna muss das Feld unverändert weiterreichen. Wir starten Sibuna mit:
sibuna --ja4-header cf-ja4 --trust-forwarded -s /etc/sibuna/secret
Der Eingangsproxy vor Sibuna darf Verbindungen nur von den Adressen von Cloudflare annehmen; andernfalls kann ein Client Cloudflare umgehen und sein eigenes cf-ja4 senden.
nginx. FoxIOs ja4-nginx-module berechnet JA4 innerhalb von nginx und stellt es als $http_ssl_ja4 bereit. Es braucht nginx 1.26 oder neuer mit dem Patch des Moduls zum Erfassen des ClientHello, gebaut mit --with-http_ssl_module. proxy_set_header ersetzt ein Feld des Clients mit demselben Namen, daher setzt jede Location, die Sibuna erreicht, den Header selbst:
# Reverse Proxy: Sibuna läuft mit --ja4-header x-ja4 --trust-forwarded
location / {
proxy_set_header X-JA4 $http_ssl_ja4;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_pass http://127.0.0.1:8080;
}
# Forward-Auth: Sibuna läuft mit --mode forward_auth --ja4-header x-ja4
location = /__sibuna_auth {
internal;
proxy_pass http://127.0.0.1:8080/;
proxy_set_header X-JA4 $http_ssl_ja4;
# ... die übrigen Felder des Forward-Auth-Rezepts oben
}
Im Forward-Auth-Rezept gehört dieselbe Zeile proxy_set_header X-JA4 $http_ssl_ja4; auch in @sibuna_challenge und in location /__sibuna/. Eine Location, die sie weglässt, reicht das eigene X-JA4 des Clients an Sibuna weiter, das ihm vertraut.
Apache Traffic Server. Das Plugin ja4_fingerprint wird durch die Zeile ja4_fingerprint.so in plugin.config aktiviert. Es hat keine Optionen. Es fügt den Anfragen jeder TLS-Verbindung ein Feld ja4 mit dem Fingerabdruck und ein Feld x-ja4-via mit dem Namen des Proxys hinzu. Wir starten Sibuna mit --ja4-header ja4 --trust-forwarded. Die Dokumentation des Plugins sagt nicht, ob es ein vom Client gesendetes Feld ja4 ersetzt. Wir müssen dies für unsere Version feststellen oder das Feld des Clients entfernen, bevor das Plugin sein eigenes hinzufügt, bevor wir dem Wert vertrauen.
Eine Regel gleicht einen Fingerabdruck mit dem Feld ja4 ab (Teil X, Richtlinienschema). Der Wert ist entweder ein ganzer Fingerabdruck, der gleich sein muss, oder ein Präfix gefolgt von *, mit dem der Fingerabdruck beginnen muss. "*" allein passt auf jeden Fingerabdruck. Eine Anfrage ohne Fingerabdruck passt nie auf eine ja4-Regel. Der Lader weist ein Muster, auf das kein Fingerabdruck passen könnte, etwa T13D* in Großbuchstaben, mit INVALID POLICY JA4 ab. Der Abgleich vergleicht Bytes und allokiert nichts.
{ "rules": [
{ "name": "deny-known-scanner", "action": "DENY",
"ja4": "t13i010400_0f2cb44170f4_5c4c70b73fa0" },
{ "name": "weigh-no-sni", "ja4": "t13i*", "action": "WEIGH", "weight": 15 },
{ "name": "weigh-headless", "user_agent": "Headless", "action": "WEIGH",
"weight": 30 },
{ "name": "challenge-tls12-checkout", "path": "/checkout/*", "ja4": "t12*",
"action": "CHALLENGE" }
] }
Die erste Regel lehnt genau einen Fingerabdruck ab; der Wert ist ein Beispiel, kein bekannter Scanner. Die nächsten beiden fügen der Bewertung der Anfrage Gewicht hinzu, statt zu entscheiden: ein Client mit TLS 1.3, der keinen Servernamen gesendet hat, und ein Headless-Browser, erkennbar an seinem User-Agent. Wenn keine spätere Regel zuerst entscheidet, erreicht eine Anfrage, die beide Signale zeigt, die Bewertung 45 und damit die Standardschwelle für Ablehnung von 40, während eine Anfrage, die eines zeigt, eine Challenge erhält. Die letzte Regel stellt per Präfix jedem Client eine Challenge, der auf dem Checkout-Pfad TLS 1.2 über TCP ausgehandelt hat. Sie stellt eine Challenge, statt abzulehnen, weil viele legitime ältere Clients noch TLS 1.2 verwenden. Regeln sollten JA4 auf diese Weise mit anderen Signalen kombinieren. Ein JA4-Wert benennt eine TLS-Bibliothek und ihre Konfiguration, keine Person und kein Gerät. Viele Clients teilen sich eine Bibliothek, und spezialisierte Bibliotheken können das ClientHello eines Browsers nachahmen. JA4 erhöht die Kosten der Automatisierung; es beweist keine Identität. Aus demselben Grund führt Sibuna Sperren und Reputation nach Adresse und nie nach Fingerabdruck.
Vorfälle (WAF-Ablehnungen, Honeypot-Treffer und Audit-Befunde) zeichnen den Fingerabdruck ihrer Anfrage auf, wenn sie einen trug, in der Spalte security_incidents.ja4. Die Konsole zeigt ihn in den Belegen des Vorfalls als „JA4 fingerprint“, mit dem Wert oder „Not recorded“. Die Filter der Seite Events akzeptieren einen Fingerabdruck oder ein Präfix. Der Editor für verwaltete Regeln hat ein JA4-Feld, gespeichert in policies.ja4_pattern, und das Testformular für Richtlinien nimmt einen Fingerabdruck an.
Deklarative Richtlinie¶
{
"default_action": "CHALLENGE",
"waf": true,
"thresholds": { "challenge_at": 10, "deny_at": 40, "bits_step": 5 },
"ip_rules": { "10.0.0.0/8": "ALLOW", "192.0.2.0/24": "DENY", "2001:db8::/32": "DENY" },
"rules": [
{ "name": "deny-cf-workers", "headers": { "CF-Worker": ".*" }, "action": "DENY" },
{ "name": "deny-amazonbot", "user_agent": "Amazonbot", "action": "DENY" },
{ "name": "api-with-key", "path": "/api/*", "headers": { "X-Api-Key": ".*" },
"action": "ALLOW" },
{ "name": "protect-checkout", "path": "/checkout/*", "action": "CHALLENGE",
"challenge": { "difficulty": 20, "algorithm": "posw" } },
{ "name": "headless", "user_agent": "Headless", "action": "WEIGH", "weight": 30 },
{ "name": "internal-vpc", "remote_addresses": ["10.0.0.0/8", "fd00::/8"],
"action": "ALLOW" }
]
}
Der Lader schlägt geschlossen fehl: Ein unbekannter Schlüssel, eine falsch geschriebene Aktion, eine fehlerhafte Adresse oder eine Zahl außerhalb des Bereichs weist die ganze Datei ab, die Diagnose nennt Regel und Feld, und der Daemon startet nicht. Eine Kommandozeile mit einer unbekannten Option oder einem Wert außerhalb des Bereichs wird auf dieselbe Weise abgewiesen. rules ersetzt, wenn vorhanden, die eingebaute Tabelle; ip_rules speist den Reputations-Trie, der auf Tausende von Präfixen skaliert; waf: false wählt die Betriebsform Gate aus der Datei. Zwei weitere Schlüssel gehören zum Schema (Teil X): inspection setzt jede WAF-Kategorie auf disabled, audit oder enforce, und das Objekt limits einer Regel gibt ihr ein eigenes Kontingent. Das Feld ja4 einer Regel gleicht den JA4-Fingerabdruck ab, den ein vertrauenswürdiger Eingangsproxy weitergeleitet hat, exakt oder per Präfix gefolgt von *; es braucht --ja4-header (siehe „JA4-Fingerabdrücke vom Eingangsproxy“). Pfadmuster passen auf den Anfragepfad in Normalform (SID 0003), daher muss ein Muster in dieser Form geschrieben sein.
Persistente Speicherung und Cluster¶
--data-dir /var/lib/sibuna öffnet die SQLite-Datei /var/lib/sibuna/sibuna.db (WAL-Modus, synchronous=NORMAL, ein Busy-Timeout) und startet den Speicherthread. --database-url (oder --database-url-file) verbindet stattdessen mit einer PostgreSQL-Datenbank. Der Speicherthread besitzt eine einfädige tokio-Laufzeit und einen kleinen Verbindungspool; er ist die einzige Stelle, die SQL ausführt. Beim Start, bei jeder Änderung der Richtlinienrevision (ein Schreibvorgang auf policies, ip_reputation oder policy_inspection) und wenn ein Reputationseintrag abläuft, baut der Thread die Engine aus der Richtliniendatei und der Datenbank neu auf und veröffentlicht sie; Anfragen warten nie auf SQL. Ein Neuaufbau liest die Revision vor und nach dem Laden und verwirft seinen Kandidaten, wenn ein Schreiber dazwischen festgeschrieben hat.
Schema¶
| Tabelle | Zweck und Schlüssel |
|---|---|
policy_revision |
Die Richtlinienrevision, eine Zeile; Trigger auf den drei Richtlinientabellen erhöhen sie. |
policies |
Geordnete dynamische Regeln, mit Schlüssel id. Das nullbare ja4_pattern enthält das JA4-Kriterium einer Regel, höchstens 37 Bytes. |
policy_inspection |
Der gespeicherte WAF-Modus pro Kategorie, eine Zeile. |
ip_reputation |
Bewertungen, Trefferzahlen und Ablauf, mit Adresse oder Präfix als Schlüssel. |
incident_receipts |
Die dauerhafte Vorfallsquittung jedes Knotens (die nächste Sequenznummer nach seinem letzten festgeschriebenen Stapel), mit dem Knoten als Schlüssel. |
security_incidents |
Ein begrenzter Ereignisdatensatz mit seinem Embedding aus 64 Komponenten (256 Bytes), mit Schlüssel node_id << 40 | sequence. Das nullbare ja4 enthält den JA4-Fingerabdruck der Anfrage, genau 36 Bytes. |
incidents_fts |
Unter SQLite: eine FTS5-Tabelle über die kanonischen Tokens von Pfaden und Nutzlasten. Unter PostgreSQL sind dieselben Tokens die tsvector-Spalte search von security_incidents mit einem GIN-Index. |
sibuna_schema |
Jede angewandte Migration, mit Komponente und Version als Schlüssel. |
Das Kernschema ist crates/storage/src/schema.rs, einmal pro Dialekt geschrieben. Mit der Konsole fügt die Komponente console 33 Tabellen hinzu, deren Namen mit console_ beginnen (SID 0013; crates/console-storage/src/schema/). Migrationen sind pro Komponente nummeriert und in die Binärdatei einkompiliert. Die Kernmigration 2 fügt die beiden JA4-Spalten hinzu; eine vor ihr angelegte Datenbank wird beim Start migriert. Alle ausstehenden Migrationen laufen in einer Transaktion, und ein Knoten weist eine Datenbank ab, deren Version einer Komponente neuer ist, als er kennt. Ein gekürzt abgedrucktes Schema ist kein Upgrade-Skript. SQLite-Tabellen sind STRICT, und CHECK-Constraints spiegeln die Rust-Typen, sodass die Datenbank eine Zeile abweist, die der Daemon nicht darstellen könnte. Aufzählungswerte werden in Kleinbuchstaben gespeichert: Ein direkter Schreibvorgang von 'DENY' wird abgewiesen.
Der Betrieb¶
Die sqlite3-Shell auf sibuna.db verwenden (der WAL-Modus erlaubt ihr das Lesen, während der Daemon läuft) oder psql auf der Cluster-Datenbank:
-- Eine dynamische Regel hinzufügen; jeder Knoten baut beim nächsten Takt neu.
INSERT INTO policies (id, name, priority, path_pattern, action, difficulty, algorithm,
header_matchers, cidr_matchers, weight, enabled, created_at, updated_at)
VALUES ('p-checkout', 'protect-checkout', 10, '/checkout/*', 'challenge', 20, 'posw',
'{"X-Api": "v2"}', '["10.0.0.0/8"]', 0, 1, unixepoch(), unixepoch());
-- Eine Adresse clusterweit für einen Tag sperren.
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());
-- Forensik: Volltextsuche über aufgezeichnete Nutzlasten.
SELECT s.id, 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;
Die Anweisungen sind für SQLite geschrieben. Unter PostgreSQL ist enabled gleich TRUE, die Zeit ist CAST(extract(epoch FROM now()) AS BIGINT) statt unixepoch(), und die Suche lautet WHERE search @@ CAST('union' AS tsquery) auf security_incidents. path und offending_payload halten die rohen Anfragebytes (BLOB oder BYTEA). Ein direkter Schreibvorgang, der einen Constraint verletzt, wird von der Datenbank abgewiesen und erreicht nie einen Knoten. Unter PostgreSQL sendet der Revisionstrigger außerdem NOTIFY sibuna_policy, sodass die anderen Knoten sofort einen Takt ausführen; das Polling bleibt die Garantie.
Bewertungen bei oder unter \(-50\) werden zu deny-Präfixen im Trie, Bewertungen bei oder über \(50\) zu allow, und banned_until begrenzt die Sperre. Honeypot-Treffer fügen automatisch einen Datensatz mit \(-100\) ein, sodass mit einer gemeinsamen PostgreSQL-Datenbank eine auf einem Knoten ausgelöste Falle die Adresse auf allen Knoten sperrt.
Eine Transaktionsquittung macht Wiederholungen sicher¶
Der Speicherthread sammelt höchstens 32 ausstehende Datensätze und baut daraus eine SQL-Transaktion. Die Transaktion fügt Vorfälle ein, aktualisiert den Volltextindex und wendet Reputationsänderungen durch den Honeypot an. Jeder Aussteller (Knoten) hat eine monoton wachsende Quittung, seine Zeile in incident_receipts. Jede datenverändernde Anweisung ist durch diese Quittung geschützt; die Transaktion erhöht sie zuletzt, und nie rückwärts.
Ein fehlgeschlagenes Festschreiben behält den ausstehenden Stapel im Speicher und erhöht incident_write_failures. Der Takt versucht dennoch das Polling der Richtlinie. Eine volle Warteschlange mit 512 Datensätzen zählt incidents_dropped; sie blockiert nie eine HTTP-Antwort, die auf die Festplatte wartet. Der ausstehende Stapel bietet Platz für weitere 32 Datensätze. Stirbt der Prozess vor dem Festschreiben, können eingereihte Daten verloren gehen: Dies ist ein begrenzter asynchroner Forensikpfad, keine Nachrichtenwarteschlange, die schon beim Einreihen dauerhaft ist.
Kampagnenbildung¶
Jede Vorfallsnutzlast wird mit dem Hashing-Trick über Byte-Trigramme (Ziffern zusammengefasst, Groß- und Kleinschreibung zusammengefasst) als 64-dimensionaler Einheitsvektor eingebettet und als 256 Bytes in security_incidents.embedding gespeichert. Der Speicherthread hält die 16.384 neuesten Embeddings aller Knoten im Speicher (4 MiB) und frischt sie bei jedem Takt aus der Datenbank auf. Vor dem Einfügen sucht er die nächstgelegene davon, einschließlich früherer Datensätze desselben Stapels; ist der Cosinus-Abstand höchstens \(0.35\), schließt sich der neue Vorfall der campaign_id dieses Vorfalls an, andernfalls beginnt er eine Kampagne, die nach seiner eigenen Kennung benannt ist. Vorfälle, die älter als das Fenster sind, werden nicht verglichen. Ähnlichkeit ist eine Heuristik: Die Regressionsbeispiele gruppieren verwandte SQL-Nutzlasten, aber das garantiert nicht, dass jedes Paar von Angriffen eine Kampagne teilt. Es läuft kein Modell, und nichts wird trainiert.
Clusterbetrieb¶
Ein Cluster ist eine Menge von Knoten, die sich eine PostgreSQL-Datenbank teilen. Mit dem Feature postgres-tls bauen (cargo build --release -p sibuna --features postgres-tls; es schließt postgres ein) und jedes Mitglied mit der Datenbank und einer eigenen Knotenkennung starten:
sibuna --database-url-file /etc/sibuna/database-url --cluster-node 1 \
--secret-file /etc/sibuna/secret
Jedes Mitglied muss dasselbe Master-Geheimnis und ein eindeutiges --cluster-node von 1 bis 8.388.607 verwenden. Die URL-Datei enthält eine postgres://-URL und darf nur für ihren Eigentümer lesbar sein; das Banner gibt die URL nie aus. Schreibvorgänge gehen an den PostgreSQL-Primary. Der Speicherthread jedes Knotens sieht die Änderung der festgeschriebenen Revision (per NOTIFY oder per Polling) und baut seine Engine neu auf.
Knoten erreichen die gemeinsame Datenbank über das Netz, daher verschlüsseln und verifizieren wir diese Verbindung. Wir geben dem Server ein Zertifikat, das von unserer eigenen Zertifizierungsstelle signiert ist, und nennen diese Stelle in der URL: postgres://sibuna:...@db.internal:5432/sibuna?sslmode=verify-full&sslrootcert=/etc/sibuna/db-ca.pem. Auf dem Server akzeptieren wir TCP nur über hostssl-Zeilen in pg_hba.conf.
Beim Start gibt der Daemon eine Zeile über die Datenbankverbindung aus. Mit verify-full meldet er, dass Zertifikat und Hostname verifiziert sind. Mit jedem schwächeren Modus gibt er eine Warnung und einen Hinweis aus. Ohne sslmode ist der Modus prefer: Die Verbindung ist nur verschlüsselt, wenn der Server TLS anbietet, und der Server wird nicht verifiziert. Ein ohne postgres-tls gebauter Daemon weist require, verify-ca und verify-full ab und nennt das fehlende Feature; er fällt nie auf Klartext zurück. Ein abgewiesenes Zertifikat bricht den Start sofort ab; der Hinweis bittet uns, sslrootcert zu prüfen und ob der Host der URL ein Name im Zertifikat des Servers ist. sslrootcert fügt unsere Zertifizierungsstelle zum Vertrauensspeicher des Systems hinzu; es entfernt nicht die Zertifizierungsstellen des Systems (SID 0011, SID 0012).
Sibuna repliziert keine eigene Datenbank und wählt keinen Leader. Replikation, Failover und Backups sind Sache von PostgreSQL (Streaming-Replikation, Patroni oder ein verwalteter Dienst). Die Knotenansicht der Konsole hat keinen Leader: Sie zeigt die Rolle single für einen SQLite-Knoten und unknown für einen PostgreSQL-Knoten, und quorum bedeutet nur, dass der letzte Datenbank-Roundtrip des Knotens gelungen ist. Ist die Datenbank nicht erreichbar, bedient die zuletzt veröffentlichte Engine weiter, Vorfälle werden im begrenzten Ring eingereiht und mit einem Zähler verworfen, sobald er voll ist, und der Speicherthread versucht es mit Backoff erneut; ein Knoten behält seine letzte Richtlinie, bis er sich wieder verbindet. Ein Zaxonlite-Datenverzeichnis (SID 0005) wird nicht gelesen; Richtlinien werden mit sibuna console policies export und sibuna console policies import übertragen, und der Forensikverlauf wird nicht migriert.
Challenge-Routing im Cluster¶
Challenge-Schlüssel sind an --cluster-node gebunden; Ausgabe und Verifikation einer Challenge bleiben daher auf demselben Mitglied. Tokens verwenden den gemeinsamen Seed und funktionieren auf anderen Mitgliedern. Lokale Ratenkontingente werden nicht zu globalen Kontingenten, und Prozessneustarts leeren die Verbrauchsmengen. Mit drei Knoten auf einer lokalen PostgreSQL-Datenbank erreicht eine direkt geschriebene Richtlinienzeile alle drei innerhalb eines Takts, eine Honeypot-Sperre auf einem Knoten erreicht die anderen, und Vorfallskennungen kollidieren nie (crates/storage/tests/multi_node.rs, SID 0011, Kriterium 2; der Test läuft, wenn SIBUNA_TEST_DATABASE_URL gesetzt ist).
Paketierung¶
Jedes Release auf GitHub enthält für jede Plattform dieselbe ausführbare Datei, gebaut aus dem Release-Tag mit den Standard-Features: SQLite-Speicher und Konsole. PostgreSQL-Cluster brauchen einen eigenen Build (siehe unten).
| Plattform | Release-Dateien |
|---|---|
| Linux x86-64, ARM64 | sibuna-linux-amd64.tar.gz und sibuna-linux-arm64.tar.gz enthalten eine statische ausführbare musl-Datei, die auf jeder Distribution läuft. sibuna_<version>-1_amd64.deb, sibuna_<version>-1_arm64.deb, sibuna-<version>-1.x86_64.rpm und sibuna-<version>-1.aarch64.rpm installieren sie mit einem systemd-Dienst; sibuna-bin-<version>-1-x86_64.pkg.tar.zst tut dasselbe unter Arch Linux. |
| macOS arm64, x86-64 | sibuna-macos-arm64.tar.gz, sibuna-macos-amd64.tar.gz, für macOS 12 oder neuer. |
| Windows x86-64 | sibuna-windows-amd64.zip enthält sibuna.exe, für Windows 10 oder Server 2016 oder neuer. |
| FreeBSD 15.1, OpenBSD 7.9 (amd64) | sibuna-<version>-freebsd-15.1-amd64.pkg und sibuna-<version>.tgz. |
| Homebrew, Kubernetes, Container | sibuna.rb, helm-sibuna-<version>.tgz und das Image ghcr.io/insanai/sibuna:<version> für amd64 und arm64, dessen Digest in IMAGE-DIGEST.txt steht. |
| Quellcode | sibuna-<version>-source.tar.gz. |
Jedes Archiv und jedes Paket enthält LICENSE, NOTICE, LICENSES/ (mit THIRD-PARTY-RUST.txt, den Crates in der ausführbaren Datei), README.md, SECURITY.md und sibuna.build.json. Das Manifest verzeichnet die Version, den Commit, das Rust-Target, die Compilerversion, die Features und den SHA-256 der ausführbaren Datei und ihrer beiden WebAssembly-Module. Der Release-Workflow startet jede ausführbare Datei auf ihrer eigenen Plattform, bevor er etwas veröffentlicht, und er installiert, reinstalliert und entfernt die Pakete unter Debian, Fedora, Arch Linux, FreeBSD und OpenBSD.
Die Dateien sind nicht signiert. Wir prüfen einen Download gegen SHA256SUMS aus demselben Release, bevor wir ihn installieren:
sha256sum --ignore-missing -c SHA256SUMS # Linux
shasum -a 256 --ignore-missing -c SHA256SUMS # macOS, FreeBSD
sha256 -C SHA256SUMS sibuna-1.0.0-beta.3.tgz # OpenBSD
Unter macOS trägt ein Download aus dem Browser ein Quarantäne-Attribut, das eine unsignierte ausführbare Datei blockiert; xattr -d com.apple.quarantine sibuna entfernt es nach der Prüfung.
Der systemd-Dienst¶
Die Debian-, RPM- und Arch-Pakete installieren /usr/bin/sibuna, die Unit sibuna.service, das Konto sibuna (über systemd-sysusers), das Hilfsskript /usr/lib/sibuna/seed.sh und die Einstellungsdatei /etc/sibuna/service.env. Die Installation startet nichts. Wir tragen den Ursprungsserver, ein IP-Literal, in die Einstellungsdatei ein und starten den Dienst:
sudoedit /etc/sibuna/service.env # SIBUNA_UPSTREAM_HOST, SIBUNA_UPSTREAM_PORT
sudo systemctl enable --now sibuna
curl -s http://127.0.0.1:8080/__sibuna/health
Der Dienst lauscht auf 127.0.0.1:8080, solange SIBUNA_HOST und SIBUNA_PORT nichts anderes festlegen. SIBUNA_OPTIONS übergibt weitere Optionen, an Leerzeichen getrennt, zum Beispiel --mode forward_auth oder --console 127.0.0.1:19446. Vor jedem Start erzeugt seed.sh den Admission-Seed /var/lib/sibuna/admission.seed (64 Hexadezimalziffern, Modus 0600, Eigentümer sibuna), falls er nicht existiert; einen vorhandenen ersetzt es nie, denn ein neuer Seed würde jede Sitzung beenden. Der Daemon hält seine SQLite-Datenbank in /var/lib/sibuna, einem Verzeichnis mit Modus 0700. Die Unit läuft ohne Capabilities, mit schreibgeschütztem System (ProtectSystem=strict), privatem /tmp und privaten Geräten und ohne neue Privilegien.
Ein Upgrade behält die Einstellungsdatei, den Seed und den Zustand und startet den Dienst nicht neu; wir starten ihn nach einer Sicherung neu. Die Deinstallation stoppt und deaktiviert den Dienst, behält aber das Konto, den Seed, die Einstellungen und den Zustand, die wir selbst löschen, wenn wir den Host außer Betrieb nehmen.
Die FreeBSD- und OpenBSD-Pakete installieren nur /usr/local/bin/sibuna und seine Dokumente (pkg add, oder pkg_add -D unsigned für ein Paket, das nicht von den OpenBSD-Mirrors stammt). Sie legen weder Dienst noch Konto noch Zustand an: Wir betreiben den Daemon als unprivilegierten Benutzer mit eigenem Seed und eigenem Datenverzeichnis.
Homebrew¶
sibuna.rb installiert das Release-Archiv für die Maschine: macOS oder Linux, arm64 oder x86-64. Es baut nicht aus dem Quellcode, weil das Rust von Homebrew keine Standardbibliothek für wasm32-unknown-unknown hat, die der Build der beiden eingebetteten WebAssembly-Module braucht; die Archive enthalten die ausführbaren Dateien, die der Release-Workflow bereits geprüft hat. Homebrew installiert Formeln nur aus Taps, daher legen wir die Formel in einen lokalen Tap:
brew tap-new "$USER/local"
cp sibuna.rb "$(brew --repository)/Library/Taps/$USER/homebrew-local/Formula/"
brew install "$USER/local/sibuna"
Die Formel startet keinen Dienst. Ihre Caveats zeigen, wie man einen Seed erzeugt; ihr Test startet den Daemon zweimal auf demselben Datenverzeichnis.
Container und Kubernetes¶
Das Image ghcr.io/insanai/sibuna:<version> enthält die statische ausführbare Datei auf einer Distroless-Basis: CA-Zertifikate, Benutzer 65532, keine Shell und kein Paketmanager. Der Einstiegspunkt ist sibuna, die Argumente sind also Daemon-Optionen. Der Release-Workflow betreibt es schreibgeschützt, ohne Capabilities, mit einem schreibgeschützt eingehängten Seed und einem Volume für den Zustand, und startet es einmal neu:
docker run -d --read-only --cap-drop=ALL --security-opt=no-new-privileges \
-v "$PWD/admission.seed:/run/admission.seed:ro" -v sibuna-state:/var/lib/sibuna \
-p 8080:8080 ghcr.io/insanai/sibuna:1.0.0-beta.3 \
--host 0.0.0.0 --secret-file /run/admission.seed --data-dir /var/lib/sibuna/data \
--upstream-host 10.0.0.5 --upstream-port 3000
Das Helm-Chart helm-sibuna-<version>.tgz betreibt einen Pod dieses Images. Es verlangt ein Secret, das wir selbst anlegen (secret.existingSecret, Schlüssel admission.seed), sodass nie ein Seed in Values oder Templates erscheint. Der Pod läuft als UID 65532 mit schreibgeschütztem Root-Dateisystem unter dem Pod-Security-Standard Restricted. Ein einziges Replikat mit Recreate-Upgrades hält genau einen Schreiber auf dem ReadWriteOnce-Volume, auf dem Sibuna seinen SQLite-Zustand in data/ hält; der Claim bleibt bei der Deinstallation erhalten. Die Probes rufen /__sibuna/health auf. Der Service ist vom Typ ClusterIP, das Chart legt weder Ingress noch Konsole an, und seine NetworkPolicy verweigert jeden Datenverkehr, bis networkPolicy.ingressFrom und networkPolicy.egressTo die Clients und den Ursprungsserver erlauben. upstream.host muss ein IP-Literal sein, und extraArgs übergibt weitere Daemon-Optionen. Der Workflow installiert, aktualisiert und deinstalliert das Chart in einem kind-Cluster, der den Standard Restricted durchsetzt.
kubectl -n sibuna create secret generic sibuna-admission --from-file=admission.seed
helm install gateway ./helm-sibuna-1.0.0-beta.3.tgz --namespace sibuna \
--set secret.existingSecret=sibuna-admission \
--set upstream.host=10.0.0.5 --set upstream.port=3000
Bauen aus dem Quellcode¶
Wir bauen und testen mit Rust 1.100; Rust 1.94 bleibt die niedrigste unterstützte Version.
Wir installieren die Release-Werkzeugkette mit rustup toolchain install 1.100.0 --profile minimal --target wasm32-unknown-unknown und wählen sie in den folgenden Befehlen mit cargo +1.100.0 aus.
cargo build --release -p sibunaerzeugttarget/release/sibunamit den Standard-Features: SQLite-Speicher und Konsole. sqlx bündelt SQLite, undring(rustls) braucht zur Build-Zeit einen C-Compiler; die Binärdatei bindet die C-Laufzeit des Systems dynamisch. Das Build-Skript baut außerdem den WebAssembly-Löser und die Konsolenoberfläche, wofürrustup target add wasm32-unknown-unknownnötig ist;SIBUNA_POW_WASM=<path>undSIBUNA_CONSOLE_WASM=<path>betten stattdessen vorgebaute Module ein.cargo build --release -p sibuna --no-default-featureserzeugt die Firewall im Arbeitsspeicher ganz ohne externe Crates;--data-dirund--database-urlwerden dann beim Start mitStorageDisabledabgewiesen undsibuna consolemitCONSOLEBUILD.cargo build --release -p sibuna --features postgres-tlsfügt PostgreSQL-Cluster mit verifiziertem TLS zur Datenbank hinzu. Es braucht kein OpenSSL.- Die statischen ausführbaren Linux-Dateien der Releases entstehen mit
cargo build --release --locked -p sibuna --target x86_64-unknown-linux-musl(oderaarch64-unknown-linux-musl) undmusl-gccals C-Compiler (CC_x86_64_unknown_linux_musl=musl-gcc).
Das Release-Profil verwendet fettes LTO und eine Codegen-Einheit. Der Workflow baut die beiden WebAssembly-Module einmal und reicht sie an jede Plattform weiter, sodass alle ausführbaren Dateien eines Releases byteidentische Module einbetten. cargo xtask licenses erzeugt LICENSES/THIRD-PARTY-RUST.txt neu, nachdem sich eine Abhängigkeit geändert hat.
Unter Windows stoppt der Daemon bei Ctrl+C, Ctrl+Break und beim Schließen der Konsole; er läuft nicht als Windows-Dienst. Windows-Dateien haben keine Modusbits, daher kann Sibuna eine Schlüssel-, Zugangsdaten- oder Datenbank-URL-Datei, die andere lesen dürfen, nicht abweisen: Wir beschränken diese Dateien mit ACLs. Die Speicher- und CPU-Anzeigen der Konsole werden aus /proc gelesen und sind auf anderen Systemen nicht verfügbar.