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

第X部:手元リファレンスと診断

エンドポイント、メトリクス、エラーの一覧、ポリシーのスキーマ、ストレージの表を一か所にまとめます。

エンドポイント

表 27 予約されたルート
エンドポイント メソッド 機能
/__sibuna/challenge GET 中間ページ
/__sibuna/challenge.json?need=&path= GET 状態を持たないチャレンジを発行します。チャレンジを求めた応答の要件チケットがあればそれで決め、なければ報告されたURLを正規形で評価します(8 KiBを超えると414、正規形を持たないパスは400)。{id, algorithm, difficulty, challenges, expires_at}を返します
/__sibuna/verify POST {"challenge_id", "nonce"}または{"challenge_id", "proof"}を受け付けます。Set-Cookie付きの200、診断付きの400、または接続バッファーより大きいボディーには413を返します
/__sibuna/wasm/sibuna-pow.wasm GET ソルバーのモジュール、14,744バイト(benchmarks/results/primitives-latest.jsonのwasm_bytes)。1時間キャッシュ可能
/__sibuna/worker.js GET WASMとJavaScriptの証明器を持つWeb Worker。1時間キャッシュ可能
/__sibuna/honeypot GET 呼び出し元を--ban-secondsの間禁止し、インシデントを記録します。403を返します。禁止するのはトップレベルのリクエスト(Sec-Fetch-Destがないかdocumentで、クロスサイトのSec-Fetch-Siteがないもの)だけです。それ以外には404で応答し、数えます
/__sibuna/health GET エンジン名、バージョン、プロキシのモード、証明のアルゴリズムを含むJSONの生存状態
/__sibuna/metrics GET Prometheusのテキスト形式(バージョン0.0.4)

/__sibuna/配下のそれ以外のパスには404で応答します。発行と検証は別の--challenge-rate-limitの予算を消費し、禁止されたアドレスはどのルートでも403で拒否されます。チャレンジの応答はX-Sibuna-Status: CHALLENGEを運びます。許可されたリクエストは上流にX-Sibuna-Status: PASSとX-Sibuna-Ruleを運びます(forward-authの応答では、16進数のX-Sibuna-Rule-Hashも運びます)。HTMLを受け付けないクライアントは、{"error":"challenge_required","challenge":"/__sibuna/challenge.json?need=<ticket>"}付きの401を受け取ります。

別のオプトインの管理用リスナーが/console/を配信します。管理者はsibuna init-adminでローカルに初期設定し、最初のサインインで一時パスワードを変更します。/console/api/statsと/console/wsには認証済みのセッション(キオスクのセッションを含む)が必要です。WebSocketは、統計、イベント、ノード、ポリシー、チャレンジ、監査を、上限のあるスナップショット、差分、欠落の回復とともに多重化します。管理用のピアは/console/peerに接続し、APIのルートはすべて/console/api/配下にあります。forward-authモードでは、オリジンのエラーカウンターは観測されません。コンソールのワークフロー、HTTPSでのデプロイ、SID 0007の現在の制限は第IX部に記載しています。

メトリクス

Prometheusのテキスト形式でsibuna_<name>_totalとして、次の順に公開するカウンターです。

表 28 カウンター
カウンター 増加する条件
incidents_persisted, incident_batches ストレージスレッドがコミットを確認したレコードとトランザクション
incidents_dropped, incident_write_failures リングが満杯で拒否されたキューへの追加と、失敗したコミットの試行
requests パースしたリクエストがディスパッチに達した(予約されたルートを含む)
allowed, denied, challenged ポリシーの判断が下された(許可、拒否、チャレンジの発行または再発行)
challenges_issued /__sibuna/challenge.jsonがチャレンジレコードを発行した
solutions_accepted, solutions_rejected /__sibuna/verifyが証明を受理または拒否した
rate_limited GCRAがリクエストを拒否した(429):リクエストの上限、チャレンジの予算、ルールのクォータ
banned 禁止されたアドレスを拒否した、またはハニーポットがアドレスを禁止した
bans_issued 禁止を記録した(ハニーポット、またはルールのクォータによる禁止)
proxied, upstream_errors リクエストをオリジンに中継した、またはオリジンが失敗した(502)
parse_errors 不正な形式のヘッダー部、繰り返されたHost、正規形を持たない対象(400)、サポートしない転送コーディング(501)を拒否した
overloaded --max-connectionsまたは--max-connections-per-ipを超えた接続に503で応答した
bans_refused キーが入り得るすべてのスロットに有効な禁止があったため、禁止を記録しなかった
forwarded_invalid 信頼する転送されたクライアントアドレスをパースできなかった。リクエストはソケットの相手で判定した
honeypot_refused 人ではなくページが要求したため、ハニーポットへのアクセスで誰も禁止しなかった
rate_evictions リミッターへの到着が、別の有効なクライアントのセルを追い出した
ja4_present --ja4-headerを指定し、転送を信頼する場合に、リクエストがJA4フィンガープリントを持つその名前のヘッダーをちょうど一つ運んだ
ja4_invalid --ja4-headerを指定し、転送を信頼する場合に、ヘッダーが不正な形式であるか繰り返されていた。リクエストはフィンガープリントなしで判定した

保留中のバッチは保持されるので、再試行はレコードを失わずにincident_write_failuresを増やすことがあります。一定の間隔での増加を監視してください。合計だけではキューの深さは分かりません。

ステータスコード

表 29 データプレーンのステータスコード
コード 発生条件
200 許可(forward-auth)、中間ページ(チャレンジが必要なHTMLのページ遷移)、内部ルート
302 現在のプロトコルでは使いません。検証は200で応答し、ページが再読み込みします
400 不正な形式のリクエスト、繰り返されたHostフィールド、正規形を持たない対象、無効な転送メタデータ、不正な形式のボディー、またはElm形式の診断付きで拒否された解答
401 HTMLを受け付けないクライアント、またはforward-authモードでチャレンジが必要
403 ポリシーまたはWAFによる拒否、禁止されたアドレス、ハニーポット
404 /__sibuna/配下の不明なパス、またはトップレベルのリクエストでないハニーポットへのアクセス
413 64 KBの接続バッファーより大きい解答のボディー
414 8 KiBを超える、報告されたチャレンジのURL
417 サポートしないリクエストのexpectation。100-continueはローカルで処理します
429 GCRAの制限を超過。Retry-Afterは秒単位
431 16 KBを超えるリクエストのヘッダー部
501 chunked以外のコーディングを指定したTransfer-Encoding
502 オリジンに到達できない、またはその応答のヘッダー部が不正な形式か16 KBより大きい
503 接続数の上限(--max-connectionsまたは--max-connections-per-ip)に到達、またはノードがドレイン中。応答の後でソケットを閉じます

エラーの一覧

INVALID COMMAND LINEは、デーモンが認識しないオプション、文書化した範囲外の値、無効、欠落、重複したモードの選択のいずれかがあると起動を停止します。このブロックは、オプション、与えられた値、期待される範囲、エラー(UnknownOption、MissingValue、InvalidValue、InvalidMode、MissingMode、DuplicateMode、ZaxonliteのクラスターオプションにはRemovedOption、互いに排他的な二つのストレージオプションにはConflictingOptions、--cluster-nodeのないデータベースURLにはMissingOption)を示し、ヒントで終わります。データベースのURLは[redacted]と表示されます。--mode reverse_proxyまたは--mode forward_authを一度だけ指定してください。-mは同等の短いオプションです。拒否されたポリシーファイルは、そのエラーを題にしたブロック(たとえばINVALID POLICY ACTION)を、ファイル、エラー名、ルール、フィールド、値とともに表示します。どのフィンガープリントも一致し得ないja4のパターンはINVALID POLICY JA4(InvalidJa4)を表示します。そのようなパターンを含むコンソールの管理文書も、同じエラー名で拒否されます。コンソールのオプションは別に確認します。CONSOLE002は不正な形式または繰り返されたコンソールのオプションを、CONSOLE001は規則に反するコンソールの設定(ストレージなしでのStorageRequired)を示します。

表 30 チャレンジとセッションのエラー
エラー 原因 ヒント
MalformedChallenge 識別子が正しい形式のチャレンジレコードではない 新しいチャレンジを取得し、変更せずに提出する
InvalidChallengeTag タグが認証できない。このクラスターが発行したものでないか、編集されている チャレンジは偽造できない。新しいものを要求する
ChallengeExpired チャレンジのTTLより古い、または未来の時刻で発行されている 新しいチャレンジを要求する
FingerprintMismatch 別のアドレスまたはUser-Agentから提出された 取得したクライアントから提出する
DifficultyNotMet Hashcashのnonceに必要なゼロビットがない nonceの探索を続ける
InvalidProof 逐次作業の証明が、コミットしたラベルを開示しない 発行された深さと開示数で、証明器を最後まで実行する
WrongSolutionType PoSWのチャレンジにnonce、またはHashcashに証明 解答のフィールドをアルゴリズムに合わせる
DoubleSpendAttempt チャレンジはすでに使用済み チャレンジは一回限り
StoreFull 使用済み集合が満杯 チャレンジのTTLを下げるか、--spent-tagsを上げる
InvalidTokenSignature Cookieのタグまたは署名が一致しない 中間ページで認証し直す
TokenExpired Cookieの期限切れ 認証し直す
TokenBoundAddressMismatch 別のクライアントの識別情報から提示されたCookie Cookieは共有できない

コンソールのAPIは失敗を{"error":"<CODE>","hint":"<sentence>"}で返します。hintはインターフェースが表示する文です(crates/console/src/http/reply.rs)。

表 31 運用者に関係するコンソールの失敗コード
コード ステータス 意味
CONSOLE002 400 リクエストが不正な形式、大きすぎる、またはその形式では許可されない
CONSOLE003 503 / 429 ストレージのジョブキューが満杯(32ジョブ)、またはパスワードの検証器が使用中
CONSOLEQUORUM 503 データベースがリクエストの待ち時間10秒以内に応答しなかった。結果は不明で、データプレーンは最後に適用したポリシーで動作を続ける
CONSOLE004 503 サービスが応答できない。このビルドでは利用できない、停止中、または内部の失敗
CONSOLENODE 400 / 409 / 503 ノードへのコマンドが拒否された。別のノードを指している(400)、起動または制御のリビジョンが古い(409)、または別のコマンドの実行中に届いたか完了を記録できなかった(503)。再試行する前に操作の受領記録を確認する
CONSOLEMUTATION 429 一つのセッションから1分間に60件を超える管理上の変更

ポリシーのスキーマ

{
  "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": [                                                    // 最大128個
    {
      "name": "<kebab-case>",                                   // 表示可能な1から128バイト
      "path" | "path_regex": "<pattern>",                       // 最大512バイト
      "user_agent" | "user_agent_regex": "<pattern>",
      "headers" | "headers_regex": { "<Header>": "<pattern>" }, // 最大4個
      "remote_addresses" | "cidrs": ["<cidr>", ...],            // 最大8個、IPv4またはIPv6
      "action": "ALLOW" | "DENY" | "CHALLENGE" | "WEIGH",
      "weight": int,                                            // WEIGHのみ、-1000..1000
      "challenge": { "difficulty": <work bits>, "algorithm": "hashcash" | "posw" },
      "limits": { "rate": int, "window_seconds": int, "ban_seconds": int },
      "ja4": "<fingerprint>" | "<prefix>*"                      // 36バイト、または接頭辞と*
    }
  ]
}

challenge_atとdeny_atは-1000から1000の範囲で、deny_atはchallenge_at以上です。bits_stepは1から1000です。challengeブロックはCHALLENGEルールにだけ置け、作業ビットは1から64です。limitsはルールに専用のクォータを与えます。rate(1から1,000,000)とwindow_seconds(1から86,400)は必須で、ban_seconds(最大86,400)は任意です。WEIGHルールは制限を持てません。ja4は、JA4フィンガープリント全体(等しくなければならない)か、*が続く接頭辞(フィンガープリントがそれで始まらなければならない)です。*だけなら任意のフィンガープリントに一致し、フィンガープリントのないリクエストはどのja4ルールにも一致しません。どのフィンガープリントも一致し得ないパターンはInvalidJa4で拒否されます(第IX部「イングレスから受け取るJA4フィンガープリント」)。ip_rulesのレピュテーショントライは最大8,192ノードを保持します。各ルールでは、各条件について一つの綴りだけを使えます。

パターンの文法:.*または*は何にでも一致します。^...$はパスの完全一致を固定します。末尾の*、/*、.*は接頭辞です。/で始まるパターンはパスの完全一致です。それ以外は大文字小文字を区別しない部分文字列です。パスのパターンは正規形のパス(セグメント間のスラッシュは一つ、ドットセグメントなし、予約されていない文字はエスケープを解除、その他のエスケープは大文字の16進数字)と照合します。そのため;、%2F、%5C、\を含むパターンは何にも一致せず、パスの照合は大文字小文字を区別します(SID 0003)。

ストレージのテーブル

policy_revision、policies(最大37バイトでNULLを許すja4_pattern条件付き)、policy_inspection、ip_reputation、incident_receipts、security_incidents(256バイトの埋め込みベクトルと、36バイトでNULLを許すja4フィンガープリント付き)、全文索引(SQLiteでは正規化したトークンに対するFTS5のincidents_fts、PostgreSQLではGIN索引付きのtsvector列search)、sibuna_schemaです。コンソールは33個のconsole_*表を加えます。保存する動作、アルゴリズム、モードの名前は小文字です。インシデントのIDはnode_id << 40 | sequenceで、調整なしにクラスター全体で一意です。ノードIDは1から8,388,607です。

ビルドターゲット

表 32 ビルドとリポジトリのコマンド
コマンド 結果
cargo build --release -p sibuna SQLiteストレージとコンソールを持つデーモン(既定のフィーチャー)
cargo build --release -p sibuna --no-default-features ストレージもコンソールも外部クレートも持たない、メモリ上のデーモン
cargo build --release -p sibuna --features postgres-tls 共有のPostgreSQLデータベースにも検証付きのTLSで接続するデーモン(postgresフィーチャーだけではTLSなしで接続します)
cargo test 単体テスト、稼働中のデーモンに対する結合テスト、ストレージとコンソールのテスト(SIBUNA_TEST_DATABASE_URLを設定するとPostgreSQLのテストも)
cargo clippy --all-targets, cargo fmt --check lintと整形(max_width = 99)
cargo xtask check 関数70行、ファイル1,408行、行99/108桁の上限。タブ禁止
cargo xtask browser ヘッドレスChromiumでの確認(sibuna-browser)
cargo xtask bench <primitives|product|latency> リリースモードのベンチマーク。結果はbenchmarks/results/<command>-latest.json
cargo build -p sibuna-pow-wasm --target wasm32-unknown-unknown --profile wasm ブラウザー用モジュールのみ(コンソールのインターフェースには-p sibuna-console-ui)
cargo run -p sibuna-geoip --bin geoip-snapshot -- ... 国のデータを検証し、埋め込み可能なGeoIPのスナップショットを書き出す
guidedog build / guidedog dsc 本書 / SIDの記録

デーモンのビルドスクリプト(cmd/sibuna/build.rs)は、二つのWebAssemblyモジュールをwasmプロファイルでワークスペースのターゲットディレクトリにビルドし、コンソールのインターフェースが768 KiBを超えるとビルドを失敗させます。wasm32-unknown-unknownターゲットのないビルドでは、SIBUNA_POW_WASMとSIBUNA_CONSOLE_WASMで代わりにビルド済みのモジュールを指定します。SIBUNA_GEOIP_DATAは埋め込むGeoIPのスナップショットを指定します。これはビルド時にデコードされ、コンソールなしのビルドはこれを拒否します(GEOIP001)。