第XI部:早見表¶
ターミナルのそばに置いてください。ビルド、実行、設定、ルーティング、観測、診断を扱います。完全な表は第X部にあります。この早見表には、運用者が入力するものをまとめています。
ビルド¶
cargo build --release -p sibuna # デーモン+SQLite+コンソール
cargo build --release -p sibuna --no-default-features # インメモリ、外部クレートなし
cargo build --release -p sibuna --features postgres-tls # 共有PostgreSQLのクラスター
rustup target add wasm32-unknown-unknown # またはSIBUNA_POW_WASM / SIBUNA_CONSOLE_WASM
cargo test # 単体、稼働中のデーモン、ストレージ、コンソールのテスト
cargo clippy --all-targets && cargo fmt --check
cargo xtask check # 70行 / 1,408行 / 99桁の検査
cargo xtask browser # ヘッドレスChromiumでの検査
cargo xtask bench product # wrkによる製品全体の測定 -> benchmarks/results/
guidedog build # 本書(guidedog dsc:SIDの記録)
実行¶
# Shield(標準):PoW + WAF、:3000へプロキシ
sibuna -p 8080 -u 3000 -s /etc/sibuna/secret
# Gate:PoWのみ
sibuna --gate -p 8080 -u 3000 -s /etc/sibuna/secret
# Nginx/Caddyの後ろでforward auth(X-Forwarded-Forを信頼する)
sibuna -m forward_auth --host 127.0.0.1 -p 8080 -s /etc/sibuna/secret
# Edge:<dir>/sibuna.dbに永続的なポリシー、レピュテーション、フォレンジック
sibuna -D /var/lib/sibuna -s /etc/sibuna/secret
# 信頼できるイングレスからのJA4(Cloudflareのヘッダー。nginxモジュール:x-ja4、ATS:ja4)
sibuna --ja4-header cf-ja4 --trust-forwarded -p 8080 -u 3000 -s /etc/sibuna/secret
# クラスターのメンバー:共有PostgreSQL、一意なノード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
コンソール(オプトインのプレビュー)¶
# デーモンを停止した状態で初期化し、その後コンソールを起動する
sibuna init-admin admin --data-dir ./data
sibuna --data-dir ./data --console 127.0.0.1:19446
http://127.0.0.1:19446/console/を開き、一時パスワードを変更します。--console-location 1.3521,103.8198を加えると、ノードを地球儀上に配置します。リモートからのアクセスには、HTTPSプロキシ、明示的なオリジン、信頼するプロキシのCIDRが必要です。第IX部に従ってください。SID 0007はCommittedです。コンソールはヘッドレスChromiumでのブラウザーのワークフローに合格しています(SID 0010、基準5)。正式な性能分離の判定はまだ完了していません(第VIII部)。
まず押さえるべきフラグ¶
| フラグ | 既定値 | 意味 |
|---|---|---|
-d, --difficulty |
16 | 作業ビット(PoSWの深さ = ビット - 3) |
-a, --algorithm |
posw | poswまたはhashcash |
--posw-challenges |
16 | 証明あたりの開示数 |
--token-ttl |
86400 | セッションの秒数 |
--challenge-ttl |
300 | チャレンジの秒数 |
--token-scheme |
mac | macまたはed25519 |
--rate-limit / --rate-window |
100 / 10 | 窓あたりのGCRAのバースト |
--ban-seconds |
3600 | ハニーポットによる禁止 |
-w, --workers |
CPU数 | 受付スレッド |
--max-connections |
1024 | 超えると503 |
--max-connections-per-ip |
64 | 相手アドレスごと(IPv6では--ipv6-prefixごと)、超えると503 |
--trusted-hops |
1 | クライアント = 右からn番目のX-Forwarded-Forの項目 |
--ja4-header |
無効 | イングレスのJA4フィンガープリントを持つヘッダー。信頼する場合にだけ読む |
--idle-timeout |
15 | 回収の秒数 |
-P, --policy-file |
なし | JSONのポリシー |
--trust-forwarded |
無効 | forward authでは有効 |
--secure-cookie |
無効 | Secureを付加 |
/__sibuna/配下のエンドポイント¶
| ルート | 応答 |
|---|---|
challenge |
中間ページのHTML |
challenge.json?need=&path= |
{id, algorithm, difficulty, challenges, expires_at} |
verify(POST) |
{challenge_id, nonce | proof} -> 200 + Set-Cookie、それ以外は400 |
wasm/sibuna-pow.wasm |
15,181バイトのソルバー |
worker.js |
WASMとJSの証明器を持つワーカー |
honeypot |
呼び出し元を禁止して403。サブリソースやクロスサイトの取得には404 |
health |
{"status":"ok",...} |
metrics |
Prometheusのテキスト |
これらはすべてオリジンではなく、デーモンにルーティングしてください。
ステータスコード¶
| コード | 発生条件 |
|---|---|
| 200 | 許可(forward auth)、中間ページ、内部ルート |
| 400 | 不正な形式のリクエストや対象、拒否された解答(診断のボディー) |
| 401 | チャレンジが必要:HTML以外のクライアント、またはforward auth |
| 403 | ポリシーまたはWAFによる拒否、禁止、ハニーポット |
| 404 | 不明な/__sibuna/のルート、拒否されたハニーポットへのアクセス |
| 413 | 64 KBのバッファーを超える解答のボディー |
| 414 | 8 KiBを超える、報告されたチャレンジのURL |
| 417 | サポートしないリクエストのexpectation |
| 429 | GCRAの制限、Retry-After秒 |
| 431 | 16 KBを超えるヘッダー部 |
| 501 | chunked以外の転送コーディング |
| 502 | オリジンに到達できない、または不正な形式 |
| 503 | 接続数の上限に到達、またはノードがドレイン中 |
ヘッダー¶
- 上流(プロキシ):
X-Forwarded-For(ソケットの相手。信頼する場合は受信した連鎖の後ろに追加)、X-Forwarded-Proto、X-Real-IP(判定したクライアント)、X-Sibuna-Status: PASS、X-Sibuna-Rule: <rule>。ホップごとのフィールドと別形式の転送フィールドは、アンダースコアの綴りも含めて取り除きます。 - forward-authの応答:
X-Sibuna-Status、X-Sibuna-Rule、X-Sibuna-Rule-Hash。 - チャレンジの応答:
X-Sibuna-Status: CHALLENGE。 - Cookie:
__sibuna_token=<75 chars, 139 with ed25519>; Path=/; Max-Age=<ttl>; HttpOnly; SameSite=Lax[; Secure]
ポリシーファイルの骨組み¶
{ "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:フィンガープリント全体、または接頭辞と*。フィンガープリントがなければ一致しない。パターン:*または.*は任意、^...$は完全一致、末尾の*は接頭辞、先頭の/はパスの完全一致、それ以外は大文字小文字を区別しない部分文字列です。パスは正規形で照合します。順序:WAF -> トライのdeny/allow -> ルール -> スコア -> バイパス -> トライのchallenge -> bots -> 既定。
SQLで見るストレージ(Edge)¶
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)。動作名は小文字です。スコア\(\le -50\)-> 拒否の接頭辞、\(\ge 50\)-> 許可。クラスター:全ノードで同じ秘密、一つのPostgreSQLデータベース、--features postgres-tls、1から8,388,607の一意なNを指定した--database-url-file <file> --cluster-node N。メンバーリスト、リーダー、クラスター内のTLSはありません(SID 0011)。
診断¶
| タイトル | 意味 |
|---|---|
MALFORMED CHALLENGE |
IDが編集されたか切り詰められた。新しいものを取得する |
INVALID CHALLENGE TAG |
このシードまたはノードが発行したものではない |
CHALLENGE EXPIRED |
TTLより古い、または時計のずれが60秒超 |
CLIENT FINGERPRINT MISMATCH |
アドレスまたはUser-Agentが変わった |
DIFFICULTY NOT MET |
nonceのゼロビットが足りない |
INVALID PROOF OF SEQUENTIAL WORK |
開示が根に到達しない |
WRONG SOLUTION TYPE |
PoSWにnonce、またはHashcashに証明 |
DOUBLE SPEND PREVENTED |
チャレンジはすでに使用済み |
STORE FULL |
使用済み集合が飽和。TTLを下げるか--spent-tagsを上げる |
NETWORK BINDING MISMATCH |
Cookieが別のクライアントにコピーされた |
INVALID COMMAND LINE |
不明なオプション、不正な値、または削除されたZaxonliteのオプション |
アラートを設定すべきメトリクス:denied、rate_limited、overloaded、upstream_errors、incidents_dropped、incident_write_failures、bans_refused、forwarded_invalid(すべてsibuna_*_total)。
覚えておく数値¶
チャレンジIDは70文字(36バイトのペイロード + 16バイトのタグ)。トークンは75文字(40 + 16)、Ed25519では139文字。証明のバイト数は\(32(1 + t(n+1))\)。PoSWの深さ = ビット - 3、範囲は4から24。リクエストバッファーは64 KB。ヘッダー部の上限は16 KB。検査するボディーは8 KB。使用済み集合は1,048,576タグ(--spent-tags)。レートのセルは表あたり262,144(--rate-table-cells)。禁止は65,536スロット(--ban-table-slots)。クライアントアドレスあたり64接続。インシデントリングは512。バッチは32。キャンペーンの距離は最新16,384個の埋め込みベクトルに対して0.35。keep-aliveは接続あたり4,096リクエスト。オリジンのプールは256ソケット。ストレージのジョブキューは32。
イングレスのルーティング¶
第IX部「イングレスの背後でのforward auth」のNginxまたはCaddyのレシピを使ってください。/__sibuna/*は直接ルーティングします。アプリケーションのリクエストは、元のURI、メソッド、信頼できるクライアントアドレスで認可します。受信したSibunaの監査用ヘッダーは、認可の結果で置き換えます。Nginxでは、チャレンジ、429、認可が利用できない場合を明示的に扱う必要があります。
reverse_proxyは、許可したHTTP/1.1のボディーとWebSocketを運びます。forward_authは許可を与え、それらはイングレスが運びます。認可で省かれたボディーとオリジンの応答は、Sibunaが検査することも数えることもできません。TLSはイングレスで終端します。ネイティブのHTTP/2は先送りしています。アップロードはContent-Lengthかchunkedコーディングを使います。検査が見るのは最大8 KiBの先頭部分で、ファイルのバイトは中身を見ません。