Part XI: Quick Reference Card ============================= Keep beside a terminal: build, run, configure, route, observe, and diagnose. Part X holds the full tables; this card holds what an operator types. Build ----- .. code-block:: sh cargo build --release -p sibuna # daemon + SQLite + console cargo build --release -p sibuna --no-default-features # in-memory, no external crate cargo build --release -p sibuna --features postgres-tls # shared PostgreSQL clusters rustup target add wasm32-unknown-unknown # or set SIBUNA_POW_WASM / SIBUNA_CONSOLE_WASM cargo test # unit, live daemon, storage and console tests cargo clippy --all-targets && cargo fmt --check cargo xtask check # 70-line / 1,408-line / 99-column gate cargo xtask browser # headless Chromium checks cargo xtask bench product # whole products under wrk -> benchmarks/results/ guidedog build # this book (guidedog dsc: the SID records) Run --- .. code-block:: sh # Shield (default): PoW + WAF, proxy to :3000 sibuna -p 8080 -u 3000 -s /etc/sibuna/secret # Gate: PoW only sibuna --gate -p 8080 -u 3000 -s /etc/sibuna/secret # Forward auth behind Nginx/Caddy (trusts X-Forwarded-For) sibuna -m forward_auth --host 127.0.0.1 -p 8080 -s /etc/sibuna/secret # Edge: persistent policies, reputation, forensics in /sibuna.db sibuna -D /var/lib/sibuna -s /etc/sibuna/secret # JA4 from a trusted ingress (Cloudflare's header; nginx module: x-ja4; ATS: ja4) sibuna --ja4-header cf-ja4 --trust-forwarded -p 8080 -u 3000 -s /etc/sibuna/secret # Cluster member: shared PostgreSQL, unique node id 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 Console (opt-in preview) ------------------------ .. code-block:: sh # Initialize while the daemon is stopped, then start the console sibuna init-admin admin --data-dir ./data sibuna --data-dir ./data --console 127.0.0.1:19446 Open ``http://127.0.0.1:19446/console/`` and replace the temporary password. Add ``--console-location 1.3521,103.8198`` to place the node on the globe. Remote access requires an HTTPS proxy, an explicit origin and trusted-proxy CIDRs; follow Part IX. SID 0007 is Committed. The console passes its browser workflows in headless Chromium (SID 0010, criterion 5); its formal performance isolation gate remains open (Part VIII). Flags That Matter First ----------------------- .. list-table:: :header-rows: 1 :widths: 38 16 46 * - Flag - Default - Meaning * - ``-d, --difficulty`` - 16 - work bits (PoSW depth = bits - 3) * - ``-a, --algorithm`` - posw - ``posw`` or ``hashcash`` * - ``--posw-challenges`` - 16 - openings per proof * - ``--token-ttl`` - 86400 - session seconds * - ``--challenge-ttl`` - 300 - challenge seconds * - ``--token-scheme`` - mac - ``mac`` or ``ed25519`` * - ``--rate-limit / --rate-window`` - 100 / 10 - GCRA burst per window * - ``--ban-seconds`` - 3600 - honeypot ban * - ``-w, --workers`` - CPUs - accept threads * - ``--max-connections`` - 1024 - then ``503`` * - ``--max-connections-per-ip`` - 64 - per peer address (IPv6: per ``--ipv6-prefix``), then ``503`` * - ``--trusted-hops`` - 1 - client = n-th ``X-Forwarded-For`` entry from the right * - ``--ja4-header`` - off - header with the ingress's JA4 fingerprint; read only when trusted * - ``--idle-timeout`` - 15 - reaper seconds * - ``-P, --policy-file`` - none - JSON policy * - ``--trust-forwarded`` - off - on in forward auth * - ``--secure-cookie`` - off - add ``Secure`` Endpoints Under ``/__sibuna/`` ------------------------------ .. list-table:: :header-rows: 1 :widths: 40 60 * - Route - Answer * - ``challenge`` - interstitial HTML * - ``challenge.json?need=&path=`` - ``{id, algorithm, difficulty, challenges, expires_at}`` * - ``verify`` (POST) - ``{challenge_id, nonce | proof}`` -> ``200`` + ``Set-Cookie``, else ``400`` * - ``wasm/sibuna-pow.wasm`` - 15,181-byte solver * - ``worker.js`` - worker with WASM and JS provers * - ``honeypot`` - bans caller, ``403``; ``404`` for a subresource or cross-site fetch * - ``health`` - ``{"status":"ok",...}`` * - ``metrics`` - Prometheus text Route all of them to the daemon, never to the origin. Status Codes ------------ .. list-table:: :header-rows: 1 :widths: 12 88 * - Code - When * - 200 - admitted (forward auth), interstitial, internal routes * - 400 - malformed request or target, rejected solution (diagnostic body) * - 401 - challenge required: non-HTML client or forward auth * - 403 - policy or WAF denial, ban, honeypot * - 404 - unknown ``/__sibuna/`` route, refused honeypot hit * - 413 - solution body over the 64 KB buffer * - 414 - reported challenge URL over 8 KiB * - 417 - unsupported request expectation * - 429 - GCRA limit, ``Retry-After`` seconds * - 431 - head over 16 KB * - 501 - transfer coding other than chunked * - 502 - origin unreachable or malformed * - 503 - connection limits reached, or node draining Headers ------- - *Upstream (proxy)*: ``X-Forwarded-For`` (socket peer, after the received chain when trusted), ``X-Forwarded-Proto``, ``X-Real-IP`` (the judged client), ``X-Sibuna-Status: PASS``, ``X-Sibuna-Rule: ``; hop-by-hop and alternative forwarding fields dropped, underscore spellings too. - *Forward-auth reply*: ``X-Sibuna-Status``, ``X-Sibuna-Rule``, ``X-Sibuna-Rule-Hash``. - *Challenge reply*: ``X-Sibuna-Status: CHALLENGE``. - *Cookie*: ``__sibuna_token=<75 chars, 139 with ed25519>; Path=/; Max-Age=; HttpOnly; SameSite=Lax[; Secure]`` Policy File Skeleton -------------------- .. code-block:: json { "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: a whole fingerprint, or a prefix and ``*``; no fingerprint, no match. Patterns: ``*`` or ``.*`` any; ``^...$`` exact; trailing ``*`` prefix; leading ``/`` exact path; else case-insensitive substring. Paths are matched in normal form. Order: WAF -> trie deny/allow -> rules -> score -> bypass -> trie challenge -> bots -> default. Storage (Edge) in SQL --------------------- .. code-block:: 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 /sibuna.db``); actions are lowercase. Score :math:`\le -50` -> deny prefix; :math:`\ge 50` -> allow. Cluster: same secret on every node, one PostgreSQL database, ``--features postgres-tls``, ``--database-url-file --cluster-node N`` with a unique N from 1 to 8,388,607; no member list, leader or cluster TLS (SID 0011). Diagnostics ----------- .. list-table:: :header-rows: 1 :widths: 44 56 * - Title - Meaning * - ``MALFORMED CHALLENGE`` - id edited or truncated; fetch a new one * - ``INVALID CHALLENGE TAG`` - not minted by this seed or node * - ``CHALLENGE EXPIRED`` - older than TTL or clock skew > 60 s * - ``CLIENT FINGERPRINT MISMATCH`` - address or User-Agent changed * - ``DIFFICULTY NOT MET`` - nonce lacks zero bits * - ``INVALID PROOF OF SEQUENTIAL WORK`` - openings do not reach the root * - ``WRONG SOLUTION TYPE`` - nonce for PoSW or proof for Hashcash * - ``DOUBLE SPEND PREVENTED`` - challenge already used * - ``STORE FULL`` - spent set saturated; lower TTL or raise ``--spent-tags`` * - ``NETWORK BINDING MISMATCH`` - cookie copied to another client * - ``INVALID COMMAND LINE`` - unknown option, bad value, or a removed Zaxonlite option Metrics to alert on: ``denied``, ``rate_limited``, ``overloaded``, ``upstream_errors``, ``incidents_dropped``, ``incident_write_failures``, ``bans_refused``, ``forwarded_invalid`` (all ``sibuna_*_total``). Numbers to Remember ------------------- Challenge id 70 chars (36-byte payload + 16-byte tag); token 75 chars (40 + 16), 139 with Ed25519; proof bytes :math:`32(1 + t(n+1))`; PoSW depth = bits - 3, range 4 to 24; request buffer 64 KB; head limit 16 KB; body inspected 8 KB; spent set 1,048,576 tags (``--spent-tags``); rate cells 262,144 per table (``--rate-table-cells``); bans 65,536 slots (``--ban-table-slots``); 64 connections per client address; incident ring 512; batch 32; campaign distance 0.35 over the 16,384 most recent embeddings; keep-alive 4,096 requests per connection; origin pool 256 sockets; storage job queue 32. Ingress Routing --------------- Use the Nginx or Caddy recipe in Part IX, Forward Auth Behind an Ingress. Route ``/__sibuna/*`` directly; authorize application requests with the original URI, method and trusted client address. Replace incoming Sibuna audit headers with the authorization result. Nginx needs explicit challenge, 429 and unavailable-auth handling. ``reverse_proxy`` carries admitted HTTP/1.1 bodies and WebSockets; ``forward_auth`` grants admission and the ingress carries them. Omitted auth bodies and origin responses cannot be inspected or counted by Sibuna. TLS terminates at the ingress; native HTTP/2 is deferred. Uploads use Content-Length or chunked coding; inspection sees at most an 8 KiB prefix, with file bytes opaque.