Sibuna技術ガイド 1.0.0-beta.3 ドキュメント
言語: 日本語
English简体中文한국어日本語EspañolDeutschहिन्दीالعربية
このページの内容

第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の先頭部分で、ファイルのバイトは中身を見ません。