Teil X: Nachschlagewerk und Diagnose¶
Endpunkte, Metriken, Fehlerkatalog, Richtlinienschema und Speichertabellen an einem Ort.
Endpunkte¶
| Endpunkt | Methode | Funktion |
|---|---|---|
/__sibuna/challenge |
GET | Die Zwischenseite |
/__sibuna/challenge.json?need=&path= |
GET | Stellt eine zustandslose Challenge aus: Das Anforderungsticket aus der Challenge-Antwort bestimmt sie, andernfalls wird die gemeldete URL in Normalform ausgewertet (414 über 8 KiB, 400 für einen Pfad ohne Normalform). Gibt {id, algorithm, difficulty, challenges, expires_at} zurück |
/__sibuna/verify |
POST | Nimmt {"challenge_id", "nonce"} oder {"challenge_id", "proof"} an; 200 mit Set-Cookie, 400 mit einer Diagnose oder 413 für einen Body, der größer als der Verbindungspuffer ist |
/__sibuna/wasm/sibuna-pow.wasm |
GET | Das Löser-Modul, 14.744 Bytes (wasm_bytes in benchmarks/results/primitives-latest.json), eine Stunde lang cachebar |
/__sibuna/worker.js |
GET | Der Web Worker mit WASM- und JavaScript-Beweisern, eine Stunde lang cachebar |
/__sibuna/honeypot |
GET | Sperrt den Aufrufer für --ban-seconds und zeichnet einen Vorfall auf; 403. Nur eine Anfrage auf oberster Ebene sperrt (kein Sec-Fetch-Dest oder document und kein websiteübergreifendes Sec-Fetch-Site); jede andere wird mit 404 beantwortet und gezählt |
/__sibuna/health |
GET | JSON-Lebenszeichen mit Engine-Name, Version, Proxy-Modus und Nachweisalgorithmus |
/__sibuna/metrics |
GET | Prometheus-Textformat (Version 0.0.4) |
Jeder andere Pfad unter /__sibuna/ wird mit 404 beantwortet. Ausstellung und Verifikation verbrauchen das getrennte Budget --challenge-rate-limit, und eine gesperrte Adresse wird auf jeder Route mit 403 abgewiesen. Challenge-Antworten tragen X-Sibuna-Status: CHALLENGE; zugelassene Anfragen tragen zum Ursprungsserver X-Sibuna-Status: PASS und X-Sibuna-Rule (und in Forward-Auth-Antworten X-Sibuna-Rule-Hash in hexadezimaler Form). Ein Client, der kein HTML akzeptiert, erhält 401 mit {"error":"challenge_required","challenge":"/__sibuna/challenge.json?need=<ticket>"}.
Der getrennte, optional aktivierte Verwaltungs-Listener bedient /console/. Sein Administrator wird lokal mit sibuna init-admin eingerichtet; danach wird das temporäre Passwort bei der ersten Anmeldung ersetzt. /console/api/stats und /console/ws erfordern eine authentifizierte Sitzung (eine Kiosk-Sitzung eingeschlossen). Der WebSocket bündelt Statistiken, Ereignisse, Knoten, Richtlinien, Challenges und Audit mit begrenzten Schnappschüssen, Deltas und Lückenwiederherstellung. Verwaltungs-Peers verbinden sich mit /console/peer, und jede API-Route liegt unter /console/api/. Fehlerzähler des Ursprungsservers werden im Forward-Auth-Modus nicht beobachtet. Teil IX dokumentiert die Workflows der Konsole, den Einsatz mit HTTPS und die aktuellen Grenzen von SID 0007.
Metriken¶
Zähler, die als sibuna_<name>_total im Prometheus-Textformat bereitgestellt werden, in dieser Reihenfolge:
| Zähler | Erhöht, wenn |
|---|---|
incidents_persisted, incident_batches |
Datensätze und Transaktionen, deren Commit der Speicherthread bestätigt hat |
incidents_dropped, incident_write_failures |
Abgewiesene Einreihungen, weil der Ring voll war, und fehlgeschlagene Commit-Versuche |
requests |
Eine geparste Anfrage hat die Verteilung (Dispatch) erreicht (reservierte Routen eingeschlossen) |
allowed, denied, challenged |
Eine Richtlinienentscheidung wurde getroffen (zugelassen, abgewiesen, Challenge ausgestellt oder erneut ausgestellt) |
challenges_issued |
/__sibuna/challenge.json hat einen Challenge-Datensatz ausgestellt |
solutions_accepted, solutions_rejected |
/__sibuna/verify hat einen Nachweis angenommen oder abgewiesen |
rate_limited |
GCRA hat eine Anfrage abgewiesen (429): das Anfragelimit, das Challenge-Budget oder das Kontingent einer Regel |
banned |
Eine gesperrte Adresse wurde abgewiesen, oder der Honeypot hat eine gesperrt |
bans_issued |
Eine Sperre wurde verzeichnet (Honeypot oder die Sperre aus dem Kontingent einer Regel) |
proxied, upstream_errors |
Eine Anfrage wurde an den Ursprungsserver weitergereicht, oder der Ursprungsserver ist gescheitert (502) |
parse_errors |
Ein fehlerhafter Kopf, ein wiederholter Host, ein Ziel ohne Normalform (400) oder eine nicht unterstützte Transfer-Kodierung (501) wurde abgewiesen |
overloaded |
Eine Verbindung über --max-connections oder --max-connections-per-ip hinaus wurde mit 503 beantwortet |
bans_refused |
Eine Sperre wurde nicht verzeichnet, weil jeder Slot, den ihr Schlüssel belegen darf, eine wirksame Sperre hielt |
forwarded_invalid |
Eine vertrauenswürdige weitergeleitete Clientadresse ließ sich nicht parsen; die Anfrage wurde nach dem Socket-Peer beurteilt |
honeypot_refused |
Ein Honeypot-Treffer hat niemanden gesperrt, weil eine Seite und keine Person ihn angefordert hat |
rate_evictions |
Eine Ankunft im Begrenzer hat die Zelle eines anderen aktiven Clients verdrängt |
ja4_present |
Mit --ja4-header und vertrauenswürdiger Weiterleitung trug die Anfrage genau einen Header dieses Namens mit einem JA4-Fingerabdruck |
ja4_invalid |
Mit --ja4-header und vertrauenswürdiger Weiterleitung war der Header fehlerhaft oder wiederholt; die Anfrage wurde ohne Fingerabdruck beurteilt |
Eine Wiederholung kann incident_write_failures erhöhen, ohne Datensätze zu verlieren, weil der ausstehende Batch behalten wird. Die Zuwächse über ein Intervall überwachen; Summen allein sind keine Warteschlangentiefe.
Statuscodes¶
| Code | Wann |
|---|---|
| 200 | Zugelassen (Forward-Auth), Zwischenseite (HTML-Navigation, die eine Challenge braucht), interne Routen |
| 302 | Im aktuellen Protokoll nicht verwendet; die Verifikation antwortet mit 200, und die Seite lädt neu |
| 400 | Fehlerhafte Anfrage, ein wiederholtes Host-Feld, ein Ziel ohne Normalform, ungültige Weiterleitungsmetadaten, ein fehlerhafter Body oder eine abgewiesene Lösung mit einer Diagnose im Elm-Stil |
| 401 | Challenge erforderlich für einen Client, der kein HTML akzeptiert, oder im Forward-Auth-Modus |
| 403 | Ablehnung durch Richtlinie oder WAF, gesperrte Adresse, Honeypot |
| 404 | Ein unbekannter Pfad unter /__sibuna/ oder ein Honeypot-Treffer, der keine Anfrage auf oberster Ebene ist |
| 413 | Lösungs-Body größer als der 64-KB-Verbindungspuffer |
| 414 | Eine gemeldete Challenge-URL über 8 KiB |
| 417 | Nicht unterstützte Anfrageerwartung; 100-continue wird lokal behandelt |
| 429 | GCRA-Limit überschritten; Retry-After in Sekunden |
| 431 | Anfragekopf über 16 KB |
| 501 | Transfer-Encoding mit einer anderen Kodierung als chunked |
| 502 | Ursprungsserver nicht erreichbar, oder sein Antwortkopf war fehlerhaft oder größer als 16 KB |
| 503 | Verbindungslimit (--max-connections oder --max-connections-per-ip) erreicht, oder der Knoten ist im Drain-Zustand; der Socket wird nach der Antwort geschlossen |
Fehlerkatalog¶
INVALID COMMAND LINE bricht den Start ab bei jeder Option, die der Daemon nicht kennt, bei jedem Wert außerhalb seines dokumentierten Bereichs und bei einer ungültigen, fehlenden oder doppelten Modusauswahl. Der Block nennt die Option, den angegebenen Wert, den erwarteten Bereich und den Fehler (UnknownOption, MissingValue, InvalidValue, InvalidMode, MissingMode, DuplicateMode, RemovedOption für eine Zaxonlite-Cluster-Option, ConflictingOptions für zwei Speicheroptionen, die einander ausschließen, MissingOption für eine Datenbank-URL ohne --cluster-node) und endet mit einem Hinweis. Eine Datenbank-URL wird als [redacted] angezeigt. --mode reverse_proxy oder --mode forward_auth genau einmal angeben; -m ist die gleichwertige Kurzoption. Eine abgewiesene Richtliniendatei gibt einen Block aus, dessen Titel ihren Fehler nennt (zum Beispiel INVALID POLICY ACTION), mit Datei, Fehlername, Regel, Feld und Wert. Ein ja4-Muster, auf das kein Fingerabdruck passen könnte, gibt INVALID POLICY JA4 (InvalidJa4) aus; ein Verwaltungsdokument der Konsole mit einem solchen Muster wird mit demselben Fehlernamen abgewiesen. Konsolenoptionen werden getrennt geprüft: CONSOLE002 bezeichnet eine fehlerhafte oder wiederholte Konsolenoption und CONSOLE001 eine Konsolenkonfiguration, die eine Regel verletzt (StorageRequired ohne Speicher).
| Fehler | Ursache | Hinweis |
|---|---|---|
MalformedChallenge |
Die Kennung ist kein wohlgeformter Challenge-Datensatz | Eine frische Challenge abrufen und sie unverändert einreichen |
InvalidChallengeTag |
Das Tag authentifiziert nicht; nicht von diesem Cluster ausgestellt oder bearbeitet | Challenges lassen sich nicht fälschen; eine neue anfordern |
ChallengeExpired |
Älter als die Challenge-TTL oder in der Zukunft ausgestellt | Eine neue Challenge anfordern |
FingerprintMismatch |
Von einer anderen Adresse oder einem anderen User-Agent eingereicht | Vom Client einreichen, der sie abgerufen hat |
DifficultyNotMet |
Der Hashcash-Nonce fehlen die geforderten Nullbits | Weiter nach Nonces suchen |
InvalidProof |
Der Nachweis sequenzieller Arbeit öffnet die festgelegten Labels nicht | Den Beweiser für die ausgestellte Tiefe und die Öffnungen vollständig laufen lassen |
WrongSolutionType |
Eine Nonce für eine PoSW-Challenge oder ein Nachweis für Hashcash | Das Lösungsfeld an den Algorithmus anpassen |
DoubleSpendAttempt |
Die Challenge wurde bereits verbraucht | Challenges sind nur einmal verwendbar |
StoreFull |
Die Verbrauchsmenge ist voll | Die Challenge-TTL senken oder --spent-tags erhöhen |
InvalidTokenSignature |
Tag oder Signatur des Cookies ungültig | Über die Zwischenseite erneut authentifizieren |
TokenExpired |
Cookie nach seinem Ablauf | Erneut authentifizieren |
TokenBoundAddressMismatch |
Cookie von einer anderen Clientidentität vorgelegt | Cookies lassen sich nicht weitergeben |
Die API der Konsole beantwortet einen Fehlschlag mit {"error":"<CODE>","hint":"<sentence>"}; der Hinweis ist der Text, den die Oberfläche anzeigt (crates/console/src/http/reply.rs).
| Code | Status | Bedeutung |
|---|---|---|
CONSOLE002 |
400 | Die Anfrage ist fehlerhaft, zu groß oder in dieser Form nicht erlaubt |
CONSOLE003 |
503 / 429 | Die Speicher-Job-Warteschlange ist voll (32 Jobs), oder der Passwortverifizierer ist ausgelastet |
CONSOLEQUORUM |
503 | Die Datenbank hat nicht innerhalb der Wartezeit der Anfrage von 10 Sekunden geantwortet; das Ergebnis ist unbekannt, und die Datenebene arbeitet mit der zuletzt angewendeten Richtlinie weiter |
CONSOLE004 |
503 | Der Dienst kann nicht antworten: in diesem Build nicht verfügbar, im Herunterfahren oder ein interner Fehler |
CONSOLENODE |
400 / 409 / 503 | Ein Knotenbefehl wurde abgewiesen: Er nennt einen anderen Knoten (400), eine veraltete Boot- oder Steuerrevision (409), oder er traf ein, während ein anderer Befehl lief oder ein Abschluss nicht verzeichnet werden konnte (503); vor einer Wiederholung den Vorgangsbeleg prüfen |
CONSOLEMUTATION |
429 | Mehr als sechzig Verwaltungsänderungen in einer Minute aus einer Sitzung |
Richtlinienschema¶
{
"default_action": "ALLOW" | "DENY" | "CHALLENGE",
"waf": true | false,
"inspection": { "path_traversal" | "sqli" | "xss" | "rce": "disabled" | "audit" | "enforce" },
"thresholds": { "challenge_at": int, "deny_at": int, "bits_step": int },
"ip_rules": { "<cidr>": "ALLOW" | "DENY" | "CHALLENGE", ... },
"rules": [ // bis zu 128
{
"name": "<kebab-case>", // 1 bis 128 druckbare Bytes
"path" | "path_regex": "<pattern>", // bis zu 512 Bytes
"user_agent" | "user_agent_regex": "<pattern>",
"headers" | "headers_regex": { "<Header>": "<pattern>" }, // bis zu 4
"remote_addresses" | "cidrs": ["<cidr>", ...], // bis zu 8, IPv4 oder IPv6
"action": "ALLOW" | "DENY" | "CHALLENGE" | "WEIGH",
"weight": int, // nur WEIGH, -1000..1000
"challenge": { "difficulty": <work bits>, "algorithm": "hashcash" | "posw" },
"limits": { "rate": int, "window_seconds": int, "ban_seconds": int },
"ja4": "<fingerprint>" | "<prefix>*" // 36 Bytes oder Präfix und *
}
]
}
challenge_at und deny_at liegen zwischen -1000 und 1000, mit deny_at mindestens gleich challenge_at, und bits_step zwischen 1 und 1000. Ein challenge-Block gehört nur zu CHALLENGE-Regeln, mit 1 bis 64 Arbeitsbits. limits gibt einer Regel ein eigenes Kontingent: rate 1 bis 1.000.000 und window_seconds 1 bis 86.400 sind Pflicht, ban_seconds (höchstens 86.400) ist optional, und WEIGH-Regeln können keine Limits tragen. ja4 ist ein ganzer JA4-Fingerabdruck, der gleich sein muss, oder ein Präfix gefolgt von *, mit dem der Fingerabdruck beginnen muss; * allein passt auf jeden Fingerabdruck, und eine Anfrage ohne Fingerabdruck passt auf keine ja4-Regel. Ein Muster, auf das kein Fingerabdruck passen könnte, wird mit InvalidJa4 abgewiesen (Teil IX, „JA4-Fingerabdrücke vom Eingangsproxy“). Der Reputations-Trie von ip_rules fasst höchstens 8.192 Knoten. Jede Regel darf von jedem Kriterium eine Schreibweise verwenden.
Mustergrammatik: .* oder * passen auf alles; ^...$ verankert einen exakten Pfad; ein abschließendes *, /* oder .* ist ein Präfix; ein Muster, das mit / beginnt, ist ein exakter Pfad; alles andere ist eine Teilzeichenkette ohne Beachtung der Groß-/Kleinschreibung. Pfadmuster werden mit dem Pfad in Normalform verglichen (ein Schrägstrich zwischen Segmenten, keine Punktsegmente, nicht reservierte Zeichen unmaskiert, andere Escapes mit großgeschriebenen Hexadezimalziffern), sodass ein Muster mit ;, %2F, %5C oder \ auf nichts passt, und der Pfadvergleich beachtet Groß-/Kleinschreibung (SID 0003).
Speichertabellen¶
policy_revision, policies (mit dem nullbaren Kriterium ja4_pattern von höchstens 37 Bytes), policy_inspection, ip_reputation, incident_receipts, security_incidents (mit dem 256-Byte-Embedding und dem nullbaren 36-Byte-Fingerabdruck ja4), der Volltextindex (incidents_fts, FTS5 über kanonische Tokens, unter SQLite; die tsvector-Spalte search mit einem GIN-Index unter PostgreSQL) und sibuna_schema; die Konsole fügt 33 console_*-Tabellen hinzu. Gespeicherte Namen von Aktionen, Algorithmen und Modi sind kleingeschrieben. Vorfalls-IDs sind node_id << 40 | sequence, im ganzen Cluster ohne Koordination eindeutig; Knoten-IDs reichen von 1 bis 8.388.607.
Build-Ziele¶
| Befehl | Ergebnis |
|---|---|
cargo build --release -p sibuna |
Daemon mit SQLite-Speicher und Konsole (die Standard-Features) |
cargo build --release -p sibuna --no-default-features |
Daemon im Arbeitsspeicher ohne Speicherung oder Konsole und ohne externes Crate |
cargo build --release -p sibuna --features postgres-tls |
Daemon, der sich zusätzlich mit einer gemeinsamen PostgreSQL-Datenbank verbindet, mit verifiziertem TLS (das Feature postgres allein verbindet sich ohne TLS) |
cargo test |
Unit-Tests, Integrationstests gegen einen laufenden Daemon, Speicher- und Konsolentests (die PostgreSQL-Tests, wenn SIBUNA_TEST_DATABASE_URL gesetzt ist) |
cargo clippy --all-targets, cargo fmt --check |
Lints und Formatierung (max_width = 99) |
cargo xtask check |
Die Grenzen von 70 Zeilen pro Funktion, 1.408 Zeilen pro Datei und 99/108 Spalten pro Zeile; keine Tabulatoren |
cargo xtask browser |
Prüfungen in Headless Chromium (sibuna-browser) |
cargo xtask bench <primitives|product|latency> |
Benchmarks im Release-Modus; Ergebnisse in benchmarks/results/<command>-latest.json |
cargo build -p sibuna-pow-wasm --target wasm32-unknown-unknown --profile wasm |
Nur das Browsermodul (-p sibuna-console-ui für die Konsolenoberfläche) |
cargo run -p sibuna-geoip --bin geoip-snapshot -- ... |
Länderdaten validieren und einen einbettbaren GeoIP-Schnappschuss schreiben |
guidedog build / guidedog dsc |
Dieses Buch / die SID-Dokumente |
Das Build-Skript des Daemons (cmd/sibuna/build.rs) baut beide WebAssembly-Module mit dem Profil wasm in das Zielverzeichnis des Workspace und lässt den Build scheitern, wenn die Konsolenoberfläche 768 KiB überschreitet. SIBUNA_POW_WASM und SIBUNA_CONSOLE_WASM benennen stattdessen vorgebaute Module, für Builds ohne das Ziel wasm32-unknown-unknown. SIBUNA_GEOIP_DATA benennt einen einzubettenden GeoIP-Schnappschuss; er wird zur Build-Zeit dekodiert, und ein Build ohne Konsole weist ihn ab (GEOIP001).