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¶
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¶
# 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 <dir>/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)¶
# 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¶
| 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/¶
| 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¶
| 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: <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=<ttl>; HttpOnly; SameSite=Lax[; Secure]
Policy File Skeleton¶
{ "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¶
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); actions are lowercase. Score \(\le -50\) -> deny prefix; \(\ge 50\) -> allow. Cluster: same secret on every node, one PostgreSQL database, --features postgres-tls, --database-url-file <file> --cluster-node N with a unique N from 1 to 8,388,607; no member list, leader or cluster TLS (SID 0011).
Diagnostics¶
| 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 \(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.