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.