第X部:手元リファレンスと診断¶
エンドポイント、メトリクス、エラーの一覧、ポリシーのスキーマ、ストレージの表を一か所にまとめます。
エンドポイント¶
| エンドポイント | メソッド | 機能 |
|---|---|---|
/__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として、次の順に公開するカウンターです。
| カウンター | 増加する条件 |
|---|---|
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を増やすことがあります。一定の間隔での増加を監視してください。合計だけではキューの深さは分かりません。
ステータスコード¶
| コード | 発生条件 |
|---|---|
| 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)を示します。
| エラー | 原因 | ヒント |
|---|---|---|
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)。
| コード | ステータス | 意味 |
|---|---|---|
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です。
ビルドターゲット¶
| コマンド | 結果 |
|---|---|
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)。