第IX部:運用とデプロイ¶
二つの運用構成、すべてのコマンドラインフラグ、forward-authのレシピ、ポリシーファイル、SQLiteまたはPostgreSQLによる永続ストレージ、一つの共有データベースによるクラスタリング、パッケージングを扱います。
運用構成と設定¶
運用構成の選び方¶
- Gate(
--gate、別名--no-waf):作業証明による許可、セッション、宣言的なルール、レピュテーション、GCRAによる制限、禁止。 - Shield(既定、
--shield、別名--waf):Gateに意味解析ファイアウォールを加えたもの。 - 分散デプロイ(どちらの運用構成でも選択可能):
--data-dirは、ポリシー、レピュテーション、フォレンジックをローカルのSQLiteファイルに保持します。--database-urlと--cluster-nodeは、複数のノードを一つのPostgreSQLデータベースに接続します(SID 0011)。
コマンドラインのリファレンス¶
この表はsibuna --helpのすべてのオプションを示します。範囲はパーサーが強制するものです。
| フラグ | 既定値 | 意味 |
|---|---|---|
--port, -p |
8080 |
待ち受けポート、1から65535 |
--host, -h |
0.0.0.0 |
待ち受けアドレス、IPアドレスのリテラル |
--upstream-host |
127.0.0.1 |
オリジンのホスト(リバースプロキシモード) |
--upstream-port, -u |
3000 |
オリジンのポート |
--mode, -m |
reverse_proxy |
reverse_proxyまたはforward_auth(proxyとauthも可)、一度だけ指定 |
--workers, -w |
CPUごとに一つ | 待ち受けソケットを共有する受付スレッド、0(CPUごとに一つ)から64。受け付けた各接続にはその後、専用のスレッドが割り当てられます |
--max-connections |
1024 |
同時に処理する接続、1から8192。それを超える接続には503で応答します |
--max-connections-per-ip |
64 |
一つのソケットの相手アドレスが保持できる接続、0(上限なし)から8192。IPv6の相手は--ipv6-prefixのネットワーク単位で数え、転送ヘッダーは関与しません。それを超える接続には503で応答します |
--idle-timeout |
15 |
最長の無通信時間(秒)、0から86400。リクエストのヘッダー部はこの時間内に届かなければなりません。オリジンの応答は読み込みのたびにこれを更新するので、遅いストリームもバイトが流れている間は生き続け、無通信のオリジンは両方のソケットで切断されます。プロキシするアップロードは、期間ごとに16 KiBを届けなければなりません(遅いボディーの攻撃に対する最低速度)。クライアントのソケットには同じ長さの書き込みタイムアウトがあるので、その間1バイトも受け取らないクライアントは接続を失います |
--websocket-idle-timeout |
300 |
アップグレードした接続のアイドル期限(秒)、0から86400 |
--trust-forwarded |
無効。forward-authでは有効 | 相手からのX-Forwarded-For/X-Real-IPを受け入れる |
--no-trust-forwarded |
無効 | forward-authモードでも、決して受け入れない |
--trusted-hops |
1 |
転送された識別情報を信頼する場合、クライアントは右からこの位置にあるX-Forwarded-Forの項目、1から8 |
--ja4-header |
無効 | 信頼するイングレスがクライアントのJA4 TLSフィンガープリントを送るリクエストヘッダー(たとえばcf-ja4)。トークン文字で1から64文字、X-Forwarded-*、X-Real-IP、X-Sibuna-*、Forwarded以外。転送された識別情報を信頼する場合にだけ読む(「イングレスから受け取るJA4フィンガープリント」を参照) |
--ipv6-prefix |
64 |
レート制限、禁止、クライアントごとの接続数の上限を適用するIPv6の接頭辞長、32から128 |
--algorithm, -a |
posw |
poswまたはhashcash |
--difficulty, -d |
16 |
作業ビット、1から64。Hashcashのゼロビット数、またはPoSWの深さに3を足した値 |
--posw-challenges |
16 |
逐次作業の証明あたりの開示数、1から32 |
--token-scheme |
mac |
mac(鍵付きBLAKE3)またはed25519 |
--token-ttl |
86400 |
セッションの有効期間、秒(1から31,536,000) |
--challenge-ttl |
300 |
チャレンジの有効期間、秒(1から86,400) |
--secret-file, -s |
ランダム | 16進数64文字または生の32バイト。SIBUNA_SECRET(16進数64文字)も受け付けます |
--cookie-name |
__sibuna_token |
セッションCookieの名前、トークン文字で1から64文字 |
--secure-cookie |
無効 | Secure属性を付加 |
--gate / --shield |
shield | 運用構成の選択 |
--rate-limit |
100 |
クライアントごとの窓あたりのリクエスト数(GCRAのバースト) |
--rate-window |
10 |
窓の秒数、1から86400 |
--challenge-rate-limit |
30 |
クライアントごとの窓あたりのチャレンジの発行と検証の回数。リクエストの予算とは別 |
--ban-seconds |
3600 |
ハニーポットによる禁止の期間、0から31,536,000 |
--policy-file, -P |
なし | 宣言的なJSONのポリシー |
--rate-table-cells |
262144 |
レートリミッターの表あたりのセル数、各16バイト、4,096から16,777,216、2の累乗に切り上げ |
--ban-table-slots |
65536 |
禁止テーブルのスロット数、各24バイト、1,024から16,777,216、2の累乗に切り上げ |
--spent-tags |
1048576 |
リプレイ対策として記憶する解かれたチャレンジ、各24バイト、65,536から16,777,216 |
--data-dir, -D |
なし | 一つのノード:SQLiteファイル<path>/sibuna.dbに永続化 |
--database-url |
なし | クラスター:共有のPostgreSQLデータベース(postgres://またはpostgresql://) |
--database-url-file |
なし | 所有者だけが読めるファイルからデータベースのURLを読む |
--cluster-node |
なし | このノードのID。チャレンジ鍵とインシデントの識別子の上位ビットに結び付きます。データベースのURLとともに必須 |
--storage-poll-ms |
500 |
ストレージのティック間隔、1から60,000 ms |
--verbose, -v |
無効 | 詳細なログ出力 |
--help / --version |
ヘルプ(コンソールを組み込んでいる場合はコンソールのオプションが先)またはバージョンを表示して終了 |
--data-dirとデータベースのURLは互いに排他的で、--database-urlと--database-url-fileも互いに排他的です。--cluster-nodeのないデータベースのURLは拒否されます。Zaxonliteのクラスターオプション--cluster-listen、--cluster-peer、--cluster-secret-file、--cluster-tls-cert、--cluster-tls-key、--cluster-tls-caは廃止されました。どれかを指定すると、起動はRemovedOptionとSID 0011を示すヒントで停止します。コンソールのオプションは次の章に挙げます。
コンソールのプレビュー¶
コンソールは既定のconsoleフィーチャーでデーモンに組み込まれますが、起動するのは--consoleを指定したときだけです。コンソールにはストレージが必要です。--data-dirも--database-urlもない--consoleはCONSOLE001(StorageRequired)で拒否されます。コンソールを除いてコンパイルするにはcargo build --release -p sibuna --no-default-features --features sqliteを使います。--no-default-featuresだけのビルドには、ストレージもコンソールもありません。デーモンを停止した状態で、ローカルで初期設定します。
sibuna init-admin admin --data-dir ./data
sibuna --data-dir ./data --console 127.0.0.1:19446
sibuna console init-adminも同じコマンドです。http://127.0.0.1:19446/console/を開き、生成された一時パスワードを変更します。一時パスワードは最初のサインインで変更しなければならず、1時間で失効します。サインイン後のナビゲーションでは、アニメーションする国の地球儀、リクエストとチャレンジの統計、インシデントの調査、ポリシーと検査のエディター、ユーザー、スコープ付きAPIトークン、監査、配信ノードの制御を利用できます。認証画面は地球儀の形状もテレメトリーも読み込みません。インターフェースは、デーモンのビルドスクリプトがcmd/console-ui(クレートsibuna-console-ui)からビルドするWebAssemblyモジュールです。これとコミット済みのスタイルシートは、通常のビルドに含まれます。
| フラグ | 意味 |
|---|---|
--console <ip:port> |
このリスナーでコンソールを起動(IPv6は角括弧で囲み、ポートは0以外)。--data-dirまたは--database-urlが必要 |
--console-key-file <path> |
16進数64文字、所有者のみの権限。保存した二要素認証とWebhookの秘密を保護 |
--console-origin <https-origin> |
プロキシの背後での正規のHTTPSオリジン |
--console-behind-proxy |
TLSを終端するプロキシがすべてのリクエストを届ける |
--console-trusted-proxy <cidr> |
接続が転送フィールドを運んでよいネットワーク。繰り返し指定可、最大16 |
--console-advertise <origin> |
他のコンソールがこのコンソールのために表示するリンク |
--console-location <latitude,longitude> |
このノードの地球儀上の宣言位置 |
--console-probe <node-id>=<http://ip:port> |
ヘルスチェックするピアのデータプレーンのリスナー。繰り返し指定可、最大8 |
--console-peer <node-id>=<https://origin> |
管理用のピア。繰り返し指定可、最大8 |
--console-peer-key-file <path> |
ピア鍵:所有者のみ、16進数64文字、コンソール鍵とは独立 |
--console-peer-ca-file <path> |
ピア用の任意のPEMのトラストアンカー。システムのルートを置き換える |
--console-query-steps <n> |
集計の読み込みあたりのSQLiteのステップ数、100,000から50,000,000、既定4,000,000 |
--console-capture-heads |
インシデントごとに、伏せ字にしたリクエストとオリジンの応答のヘッダー部を保存。既定では無効 |
--console-capture-header <name> |
保存するヘッダー部にこのヘッダーの値を残す。繰り返し指定可、最大16。--console-capture-headsが必要 |
--console-cookie-secure |
プロキシなしでコンソールのCookieにSecure属性を付ける(パーサーは受け付けるが、--helpには載らない) |
--consoleなしのコンソールのオプション、繰り返したオプション、不正な形式の値は、CONSOLE002とオプションのエラー名で起動を停止します。コンソールの規則に反する設定(たとえば信頼するプロキシのない、ループバック以外のリスナー)は、CONSOLE001で起動を停止します。
コンソールの各画面¶
以下のスクリーンショットは、SQLiteストレージを持つループバック上の一つのノードで動くリリースビルドから撮ったものです。ポリシーは既定のチャレンジの上に四つのALLOWルールを置いたもので、約4分間の合成トラフィックの後に撮りました。トラフィックは、文書用のアドレス範囲からのアドレス、SQLインジェクションとクロスサイトスクリプティングの試行、三回のハニーポットへのアクセス、ヘッドレスChromiumで解いた七つのチャレンジです。したがって、どの数値も説明のためのものです。撮影にはcargo xtask browser console --viewport-onlyを使いました。これはChromiumで1440×960ピクセルの画面でコンソールを巡回し、すべてのページを判定します。各ページはタイトルに書いた一つの問いに答え、製品、配信ノード、ページ、戻る手段を同じ場所に置いています。
waf:sqliとwaf:xss)を示すライブのイベントフィードです。記録されていない値は、ゼロを表示する代わりにそのことを示します。Reputationのタイルは"Not recorded"と表示されています。ページのさらに下には、60個の等しい区間ごとの検出、攻撃のカテゴリー、攻撃されたパスがあります。¶
--console-capture-headsを指定すると、伏せ字にしたリクエストのヘッダー部(リバースプロキシを通して監査付きで許可されたものでは、オリジンの応答のヘッダー部も)を要求に応じて開けます。UTF-8またはLatin-1として表示し、応答の状態(取得済み、ローカル、forward-authで未観測、オリジン利用不可)を示し、cURLコマンドとしてコピーできます。保存するのは列挙したヘッダーの値だけで、--console-capture-header <name>でその一覧に加えます。それ以外の場合、ヘッダー部は記録なしと表示されます。拒否と許可の操作は、アドレスを入力済みにしたIPグループのフォームを開きます。¶
任意の--console-location <latitude,longitude>は、このノードの位置を宣言します。たとえばシンガポールのデプロイなら1.3521,103.8198です。地球儀は最初にそこを中心に表示し、回転させた後はCenter Sibunaでその地点に戻ります。国ごとの活動は、ノードに向かってアニメーションする大円の弧で表され、裏側の半球や平面地図の日付変更線では切り取られます。国の位置は代表的な重心で、矢印は個々の接続ではなく、観測した60秒の窓を表します。サーバーの位置を設定しなければ、明示的に不明のままです。設定したマーカーはテレメトリーが途絶えても見えたままで、古いトラフィックはアニメーションしません。
ポリシーのプレビューは、設定したファイルのルールを含む非公開の候補を構築します。保存では期待するリビジョンを比較し、フィールドの比較の確認を求めます。過去への巻き戻しは現在のルールと比較し、新しいリビジョンを作ります。コミット済みのリビジョンとローカルで適用したリビジョンは別のものです。監査の詳細は、上限のある判断の変化と、実際に操作したロールを保持します。照合の値は伏せ字にされ、文脈が欠けた古いレコードは明示的に欠落のままです。ドレイン、再開、ローカルの禁止の解除には、コマンドのプレビューが必要です。ノードで別のコマンドが実行中に届いたコマンドは、キューに入れずに503 CONSOLENODEで拒否されます。応答が失われた後は、再試行する前に永続的な受領記録を確認してください。意図がコミットされただけでは、実行時の効果が完了したことにはなりません。
リモートで運用するには、HTTPSプロキシを使い、--console-origin、--console-behind-proxy、明示的な--console-trusted-proxyのCIDR、--console-key-fileを設定します。鍵ファイルは16進数64文字を含み、所有者のみの権限を持ち、保存した二要素認証の秘密を保護します。チャレンジのシードとは別に、再起動をまたいで保持してください。ループバック以外からのアクセスには、設定したHTTPSオリジンとプロキシの許可リストが必須です。Sibunaはコンソールのリスナーでも受信のTLSを終端しません。コンソールがTLSを使うのは外向きの接続だけで、rustlsを使います(SID 0012)。
ネイティブのCLIは、同じ認可とストレージの取り決めを通して稼働中のコンソールにアクセスします。資格情報はコマンドラインの値ではなく、非公開のファイルから読みます。
sibuna console geoip update --version 2026-09-09 \
--origin http://127.0.0.1:19446 --username admin \
--password-file ./admin-password
所有者のみのパスワードファイルを使い、先にパスワードの設定を済ませ、必要なら認証アプリまたはリカバリーコードのために--factor-fileを加えます。アカウントとGeoIPの操作では、--token-fileがユーザー名とパスワードの代わりになります。クライアントはHTTP/1.1を話し、リテラルのループバックアドレスを除いてHTTPSを要求し、リダイレクトには決して従わず、各リクエストを20秒、各応答を16 KiBに制限します。geoip statusは有効な世代を読みます。更新では、選んだプロバイダーが公開するファイルをHTTPSでダウンロードし(既定ではパブリックドメインのuser-countryデータセット、--provider dbip --version YYYY-MMならDB-IP Lite)、発行者のチェックサム(または--checksumで与えたもの)を検証し、sibuna-geoipで範囲を上限内で検証し、新しい世代を永続化してローカルで有効にします。失敗した更新は以前の世代を保ちます。CLIのタイムアウト(--timeout、既定1200秒)は待つのをやめるだけで、提出済みのストレージの作業は取り消しません。DB-IP LiteにはCC BY 4.0の帰属表示が必要で、そのデータが有効な間だけ表示されます。SIBUNA_GEOIP_DATA=<snapshot>付きのビルドは、最初の永続的なインポートまで、検証済みのスナップショット(geoip-snapshotツールで書き出したもの)を埋め込みます。コンソールなしのビルドはこれをGEOIP001で拒否します。不明なアドレス、サンプルの損失、古いデータは見えたままです。国のデータをインポートしてもトラフィックは生まれず、すでに期限切れになったサンプルに情報が付加されることもありません。
クラスターのメンバーは、共有データベースのメンバーシップ表(console_nodes)を通して、起動時、毎分、そして適用中のポリシーまたは制御のリビジョンが変わってから2秒以内に自らを通知し、すべてのコンソールのNodesページに現れます。リーダー選出はありません。SQLiteのノードはロールsingleと、自分自身をリーダーとして報告します。PostgreSQLのノードはロールunknownを報告し、リーダーは報告しません。PostgreSQLのフェイルオーバーはSibunaからは見えないからです(SID 0007)。このコンソールがヘルスチェックすべきデータプレーンのリスナーを持つピアには--console-probe <node-id>=<http://ip:port>を、他のコンソールが表示するリンクには--console-advertise <origin>を設定します。直接のライブテレメトリーには--console-peer <node-id>=<https://origin>(繰り返し指定可、最大8)と専用の--console-peer-key-fileを使います。ピアには--console-behind-proxyが必要です。両端が互いを列挙し、信頼できるHTTPSのイングレスを使わなければなりません。ピア鍵は16進数64文字を含む所有者のみのファイルで、コンソール鍵やチャレンジのシードとは独立に用意します。ピアは、ringプロバイダーを使うrustlsによる、認証付きのTLS WebSocketで通信します(SID 0012)。--console-peer-ca-fileは、非公開の管理用PKIのためのPEMのトラストアンカーを任意で与えます。与えなければ、クライアントはシステムのルートを使います。ホスト名の検証は常に適用され、無効にできません。各管理用オリジンのホスト(DNS名またはIPアドレスのリテラル)は、ピアの証明書に名前が記載されていなければなりません。拒否された証明書はピアをrejectedとし、peer.rejectedの監査行を一つ書きます。鍵のローテーションとCAファイルの変更には、調整した再起動が必要です。ピアの証明書は再起動なしで更新できます。Nodes APIとその購読は、受信からの経過時間、時計のずれ、起動の変化、サンプリングの損失を報告します。欠けた観測は利用不可のままで、切断された値は古いままです。受信した統計が別のノード自身の寄与になることはありません。ダッシュボードのLive traffic scopeは、一つのノードを選ぶか、設定したノードを合算します。Node coverage and locationsは、欠けている、古い、時計がずれているソース、観測時刻、設定した宛先を示します。国の順位は、省かれたソースの行による不確かさを示します。矢印は受信したノードを保持し、欠けたノードの位置をでっち上げることはありません。合算したレートは、寄与するソースのどれかに連続した区間が欠けていれば未観測のままです。一つのノードを選ぶと、保持している秒単位のデータと現在の分のパスの順位を調べられます。リモートのクエリは認証付きのピア接続を使います。クエリの応答は4 KiBのWebSocketメッセージ一つに収まらなければならないので、配信するコンソールは収まらないページの行を半分にします。欠けたピアは利用不可のままで、履歴のカーソルはノードの再起動をまたげません。分単位の履歴は、独自のノードの選択とノードごとの行を保持します。ナビゲーションとモバイルのヘッダーは、選んだトラフィックのソースとは独立に、配信しているコンソールのノードを示します。ローカルのコマンドはノードごとのままです。
Trafficのタイルは、選んだノードについて、保持している確定済みの分単位のレコードの直近24時間で開きます。期間の選択では、1時間、7日、90日、ライブの起動以降の合計も選べます。Yesterdayとの差分には、選んだすべてのノードから完全に一致する観測範囲が必要です。地球儀とスパークラインは、引き続き別のライブの60秒の窓を表します。保持データの走査は完了の1分後に更新され、置き換えられるまで以前の値とその経過時間を表示し続けます。ソースや期間を変えると古い範囲は破棄されます。欠けた履歴がゼロになることはありません。
Compare retained trafficは、二つの確定済みの分の窓を並べて表示します。昨日の同じ窓、直前の期間、または二つ目のノードです。期間と終了オフセットの選択で、両方のUTCの範囲を固定します。各操作は片側につき最大16個のコンパクトなページを読み、1ページには96個の保存されたレコードがあります。これで、再起動が重ならない24時間の窓を1バッチで扱えます。Continueはより長い走査のために同じ境界を保ちます。完全な観測範囲、不完全な観測範囲、欠けた履歴は明示されたままです。レートの百分率には、等しいUTCの窓での重ならない完全な区間が必要で、観測したミリ秒で正規化します。参照がゼロで新しいトラフィックがあれば"New"と表示します。主のTrafficの期間は独立したままです。分単位の形式は過去のプロキシのモードを記録しないので、オリジンの応答の比較は、forward-authでのゼロを観測した応答と解釈するのではなく、利用不可のままにします。
Compare retained path rankingsは、二つの確定済みの窓またはノードを選びます。ノード0は、退役したメンバーも含めて、保持しているすべてのノードを含みます。一つの操作は最大16個の不変のアーカイブを読み、その識別とチェックサムを確認し、表示する行を選ぶ前にすべてのカウンターを統合します。アーカイブは60秒の遅着サンプルの窓の後で封印されるので、最新の確定済みの分はまだ保留中のことがあります。Continueは元の窓とカーソルを保ちます。境界が表すのはサンプリングしたパスの接頭辞であり、正確なリクエストの合計ではありません。ページには、部分的な走査、切り詰め、保持期間の境界、報告されたキューの損失を示します。アーカイブが欠けていても、トラフィックがゼロであることや観測範囲が完全であることの根拠にはなりません。
Securityは直近24時間で開き、選んだ期間を60個の等しい時間区間に分けます。その集計は、作業量の上限の下でストレージスレッドが実行します。SQLiteでは、上限は--console-query-steps個の仮想マシンのステップ(100,000から50,000,000、既定400万)です。--consoleとともに設定してください。無効な値や繰り返した値は拒否されます。PostgreSQLでは、上限は読み込みのトランザクションで設定する2,000 msのステートメントタイムアウトです(SID 0013)。--console-query-stepsを変えても変わりません。上限を使い果たしたクエリは、より狭い期間を求めます。ステップ数が抑えるのはクエリの作業量であり、経過時間ではありません。グラフは目盛りを共有します。Trendの値を展開すると、UTCでの区間の開始時刻と、グループ化した正確なカウントが表示されます。これらは保持している検出なので、インシデントの観測範囲が欠けていても、攻撃がなかったと解釈することはできません。
ウォールディスプレイはキオスクのセッションを使います。Accountで、運用者がディスプレイに名前を付け、Create display codeを選びます。ディスプレイは10分以内に一回限りのコードをサインインのフォームに貼り付けます。そのセッションは読み取り専用で、統計に限られ、12時間以内に失効します。アカウントのページは、移動したときや非表示になったときに表示したコードを消去します。非表示にしても未使用の許可は取り消されず、交換の期限は引き続き適用されます。コードを決してURLに含めてはいけません。ディスプレイはTrafficとSecurityを共有します。Securityは、インシデントのアドレスやペイロードの証拠を含めずに、モジュールの集計の傾向とリクエストの結果を示します。自動の切り替えは任意で、最初は無効であり、動きを減らす設定、古いデータ、Pauseのいずれかで中断します。
通知先(拒否の急増、禁止、到達できないメンバー、リーダーの変更についての署名付きWebhookとsyslog)はSettingsにあります。Webhookの秘密には--console-key-fileが必要です。保存した通知先の意味を保つためにリーダーの変更の種類は定義されたままですが、リーダー選出がないので、どのノードもこれを発生させません。各通知先は独自のクールダウンと、3回の再試行の予算を持ちます。配信の監査レコードは結果を示します。完了したキューの履歴は7日と4,096件のイベントに制限されます。Webhookには安定したIdempotency-Keyが含まれるので、受信側は、ネットワークでの完了が不確かな場合でも、繰り返しの効果を抑えられます。WebhookはHTTPSで送られ、平文のHTTPはリテラルのループバックアドレスに対してだけ使われます。応答のボディーは64 KiBまで読みます。syslogのUDP/TCPの選択は外向きの通知にだけ適用され、保護するWebトラフィックとは独立です。手動のテストは意図と完了をAuditに記録し、通知先の結果を更新します。監査上の完了が確認されていない場合は、運用者が再試行する前にそのことを明示します。
Settingsでは保持期間も管理します。分単位の履歴は1から90日、順位は1から7日、インシデントは1から30日、監査は1から365日です。上限の値が既定値で、順位は512 MiBの上限を保ちます。保持期間の値を保存するには確認が必要です。後始末で、古いレコードを上限のあるバッチで永久に削除するからです。後で値を増やしても、削除した履歴は戻りません。古い編集は拒否され、成功した変更はAuditに現れます。
応答ページ(チャレンジ、拒否、レート制限、禁止、過負荷)は、Settingsで、固定のプレースホルダーを持つ上限のあるHTMLとして編集できます。下書きはサンドボックス化したタブでプレビューでき、保存したページは次のポリシースナップショットから配信されます。
Policiesページでのポリシーのワークフロー:管理するルールの並べ替え、保持している検査の検出に対する下書きの再生、IPグループと、有効なGeoIPの世代に固定した国のブロックの管理、管理するセットのエクスポートとアトミックなインポート(sibuna console policies exportとsibuna console policies import --file <set.json>も使えます)。インポートは1から128個の文書を運ぶ一つのリクエストで、各文書は最大4 KiB、全体で最大256 KiBです。約96 KiBを超えるセットについては、ページの注記がコマンドラインでのインポートを示します。適用中のルールは、今日記録されたヒット数、1時間ごとのスパークライン、アクセシブルな表を示します。ヒットとは、宣言的な照合の評価が成功したことです。一致したWEIGHルールと最初の終端の一致が数えられます。それより前の検査やレピュテーションによる判断で、評価されないことがあります。非公開のテストはこれらのカウンターを増やしません。Compare rule hitsは、記録された一つのノードについて二つの確定済みの期間を固定します。リビジョンの履歴にはCompare hits around this editがあり、編集した分を除き、選んだ長さまでの等しい利用可能な期間を使います。任意の適用リビジョンのフィルターで、関係のない世代を比較から除けます。起動、切り替え、欠けた書き込み、保持期間によって、観測範囲の欠落が目に見える形で残ります。百分率には両側で完全な観測範囲が必要です。ルールの観測と1時間ごと・1日ごとの要約は、分単位の保持期間の設定に従います。編集の前後で観測された変化は比較であり、編集がトラフィックの変化を引き起こした証拠ではありません。
新しいGeoIPの世代をインポートしても、国から導いた既存のレピュテーションの行は自動的には更新されません。国の操作をプレビューして、追加、保持、削除される接頭辞を比べ、適用する前にレビューした差分をページ単位で確認してください。置き換えでは、その国が所有する古い行を削除し、独立に管理している接頭辞は保ちます。世代やポリシーのリビジョンが変わった場合は新たなプレビューが必要で、重なる独立した編集は拒否されます。Eventsページには、保持しているWAFの検出とハニーポットのインシデントがあります。完全なアクセスログではありません。GeoIPを読み込んでいると、ストレージスレッドはインシデントのバッチのトランザクションの中で、各インシデントの国と世代を記録します。これは永続化の時点での帰属であり、リクエスト時の位置を再構成したものではありません。後のインポートは記録済みの対応付けを変えません。国のフィルターは、大文字の2文字のコード、読み込んだ世代にないアドレスを表すunknown、対応付けのデータを持たないインシデントを表すnot_recordedを受け付けます。ソースのグループは、国の混在や観測範囲を明示的に報告します。地球儀のView events操作は、選んだノードを保ったまま、その国の直近1時間の保持しているインシデントを開きます。StatisticsページのSecurity表示は、ライブのレート制限、チャレンジ、禁止の割合と、1時間、1日、7日、30日にわたる保持している検査とハニーポットの検出を組み合わせます。カテゴリー、ソース、パスのリンクは、同じノードと固定した時間の境界で、通常のインシデントのワークフローを開きます。インシデントのフィルターを適用すると、新しい期間が始まります。検出には監査レコードが含まれ、遮断したリクエストの合計とは別のものです。レピュテーションとルールのヒットの帰属がない場合は、記録なしと表示します。イベントと監査のフィルターは、ラベルをその入力欄と一緒に置き、Apply操作を別に配置し、列を利用できる内容の幅に合わせます。認証付きのWebSocket一つがナビゲーションをまたいで存続し、統計、インシデントの要約、ノードの状態、ポリシーのリビジョン、チャレンジ、監査の要約を運びます。新しいインシデントと監査のレコードはLoad latest recordsの後ろで待つので、読んでいる間に表が動くことはありません。ポリシーの更新は、開いている下書きを置き換えずに、現在のコミット済みと適用中のリビジョンを示します。フローのカウンターはライブで更新されます。既定以外のチャレンジの計時区分を選んだ場合は、明示的に更新してください。過去のクエリ、詳細の読み込み、変更はHTTPリクエストのままです。
ページのフラグメントはブックマークでき、ブラウザーの「戻る」と「進む」で認証済みのページを開き直せます。サイドバーは、このブラウザーで選んだテーマと表示間隔も記憶します。既定のテーマはSystemです。SID 0007はCommittedです。コンソールは、ヘッドレスChromiumでゴールデンフィクスチャとブラウザーのワークフローに合格しています(cargo xtask browser console、SID 0010のcriterion 5)。エンドツーエンドのスイートはcmd/sibuna/tests/console_*.rsで、そのPostgreSQLクラスターのシナリオはSIBUNA_TEST_DATABASE_URLを設定すると実行されます。SID 0010の記録によれば、コンソールを組み込んだうえで無効にした場合、ストレージのみの場合、有効にしてアイドル状態の場合のいずれでも、製品の16個のワークロードは、コンソールなしでビルドしたデーモンとの差が約1%以内に収まり、これはノイズの範囲内です。負荷の下で八つのダッシュボードを動かすSID 0007の正式な分離の判定は、まだ測定していません(第VIII部)。WebAssemblyアプリケーション全体には非圧縮で768 KiBという上限があり、デーモンのビルドスクリプトがビルドを失敗させることでこれを強制します。また、640 KiBというレビューのしきい値があります。1.0.0-beta.3のモジュールは724,330バイト(gzipで272,568バイト)で、レビューのしきい値を超えており、SID 0007はこれをレビュー対象として記録しています。これらはコンソールのワークフローに余地を残すためのプロジェクトの上限であり、ブラウザーでの読み込みと応答性の測定の代わりにはなりません。モジュールの線形メモリは、宣言した最大値の16 MiBまで必要に応じて伸びます。
デプロイの構成¶
リバースプロキシ¶
sibuna --port 80 --upstream-host 127.0.0.1 --upstream-port 3000 \
--secret-file /etc/sibuna/secret --difficulty 16 --algorithm posw
許可されたリクエストは、X-Forwarded-For、X-Forwarded-Proto、X-Real-IP、X-Sibuna-Status、X-Sibuna-Ruleヘッダー付きでオリジンに届きます。ホップごとのヘッダー、Sibuna自身が書くフィールド、別形式の転送フィールド(Forwarded、X-Forwarded-Host、X-Forwarded-Port)は、クライアントがその名前をアンダースコアで綴った場合(X_Forwarded_For)も含めて取り除かれます。X-Real-IPは、リクエストの判定に使ったクライアントです。X-Forwarded-Forはソケットの相手だけで、クライアントが書いた項目は決して含みません。転送された識別情報を信頼する場合は、受信した連鎖の後ろにソケットの相手を続けたものです。したがってオリジンは、クライアントをX-Real-IPから、またはX-Forwarded-Forの右側から読まなければならず、左端の項目から読んではなりません。オリジンが受け取るパスは、ポリシーが判定した正規形です(SID 0009)。正規形を持たないパスには400で応答します。
HTTP/1.1のWebSocketのアップグレードは、オリジンのハンドシェイクを受け入れる前に、許可とポリシーの確認を通ります。サブプロトコルと拡張の交渉はエンドツーエンドのままです。二つのスレッドが方向ごとに一つずつバイトを中継し、それぞれが一つの固定バッファーを持ち、先読みしたバイトとハーフクローズも扱います。したがってアップグレードした接続は二つのスレッドを持ち、すべての接続がアップグレードされると、接続スレッドの数は--max-connectionsの2倍に達し得ます。アップグレードしたソケットは通常の接続数の上限とシャットダウンの登録簿の中にとどまりますが、HTTPのアイドル期限とは独立に--websocket-idle-timeout(既定300秒)を使います。どちらの方向のトラフィックもこの上限を更新しますが、期間全体で1バイトも受け取らない相手がいれば、もう一方の方向がどれほど忙しくても中継は終わります。ハンドシェイク後のフレームはWAFの検査の入力になりません。HTTPS/WSSでは、Sibunaの非公開のHTTP/1.1リスナーの前に、TLSを終端するイングレスを置きます。Sibuna自身はブラウザーのTLSを終端しません。
イングレスはブラウザーとHTTP/2を交渉し、SibunaにはHTTP/1.1で転送できます。SibunaでのネイティブのHTTP/2のサポートは、後の更新に先送りしています。この構成は、ネイティブのgRPCのようなアプリケーションに対して、エンドツーエンドのHTTP/2の意味論を提供しません。
Content-Lengthのリクエストボディーは、バイトとMIMEヘッダーを保ったまま固定バッファーを通してストリームされます。マルチパートのアップロードでは、境界、繰り返されたフィールド名、ファイル名、パートの型が保たれます。WAFが調べるのはボディーの先頭8 KiBまでです。マルチパートのメタデータとファイル以外のフィールドはテキストの検査の入力のままで、ファイルのペイロードは中身を見ません。filenameが空のパートは普通のフィールドです。認識したバイナリのトップレベルのMIMEタイプ(SVGを除く画像、音声、動画、PDF、ZIP、gzip、7z、protobuf、octet-stream)のボディーの中身を見ないのは、その先頭部分もバイナリに見える場合、つまり16バイトのうち少なくとも1バイトが、タブ、改行、垂直タブ、改ページ、復帰以外の制御バイトである場合だけです。そうでなければテキストとして検査します(SID 0004)。JSON、XML、SVG、URLエンコードのフォーム、不明な型はテキストの検査を保ちます。あいまいな、または不正な形式のMIMEのメタデータは、テキストの検査に戻ります。マルチパートのパースは、同じ先頭部分の中で32パート、パートあたり2 KiBのヘッダーに制限され、区切りの後のRFC 2046の転送用の詰め物を受け付けます。
これはアップロードとの互換性であり、ファイルの検証やマルウェアの走査ではありません。バックエンドは、クライアントのContent-Typeの宣言を信頼するのではなく、受け付けるメディアタイプを強制しなければなりません。検査する先頭部分より後のフィールドは、大きなアップロードファイルの後にあるものも含めて検査されません。圧縮されたペイロードは、検査のために展開されません。アップロードも、許可、パス、クエリ、ヘッダーの確認を通り、接続の期限の対象のままです。チャンク形式のリクエストボディーは、検査の前に接続バッファーの中でデコードされます(SID 0009)。バッファーの中で終わるボディーは、Content-Length付きでバックエンドに届きます。それより長いものはSibunaが読み込みごとに一つのチャンクとしてチャンク化し直すので、バックエンドがクライアントのチャンクサイズ、拡張、トレーラーを見ることはありません。単独のCRやLF、サイズの前後の空白、不正な形式の拡張を含むチャンク行や、4 KiBを超えるチャンク行は400で拒否されます。16 KiBを超えるトレーラー部も同様です。他のコーディングを指定したTransfer-Encodingには501を返します。チャンク形式のリクエストをパースできないバックエンドでも、約44 KiB未満のボディーにはContent-Lengthが届きます。リクエストボディーを運んだオリジンへの接続は、そのやり取りの後で閉じられ、プールには戻りません。100-continueを待つクライアントは、ボディーを送る前にローカルでそれを受け取ります。サポートしないexpectationには417を返します。Expectヘッダーはバックエンドに転送する前に消費されます。
イングレスの背後でのforward auth¶
--mode forward_authでは、デーモンはイングレスのサブリクエストに、200(と監査用のヘッダーX-Sibuna-Status、X-Sibuna-Rule、X-Sibuna-Rule-Hash)、チャレンジには401、拒否には403、レート制限時には429で応答します。イングレスはクライアントのアドレスと元のURLを転送しなければなりません。forward-authモードは既定でそれらを信頼します。イングレスだけが接続できるように、このリスナーは非公開のアドレスにバインドしてください。X-Forwarded-Uri(Caddy)またはX-Original-URI(Nginx)とX-Forwarded-Methodによって、ポリシーの評価のためにアプリケーションのリクエストを復元します。元のパスは、リクエスト行のパスと同じように正規形に変換されます。重複した、または矛盾する元のURLのフィールドや、origin-formでない元のURIは400で拒否されます。デーモンの内部ルートは常に実際のリクエストのURIを使います。forward-authは、イングレスが省いたボディーを検査しません。
map $http_upgrade $sibuna_connection_upgrade {
default upgrade;
'' close;
}
server {
listen 443 ssl;
location / {
auth_request /__sibuna_auth;
auth_request_set $sibuna_auth_status $upstream_status;
auth_request_set $sibuna_retry_after $upstream_http_retry_after;
auth_request_set $sibuna_status $upstream_http_x_sibuna_status;
auth_request_set $sibuna_rule $upstream_http_x_sibuna_rule;
auth_request_set $sibuna_rule_hash $upstream_http_x_sibuna_rule_hash;
error_page 401 = @sibuna_challenge;
error_page 500 = @sibuna_auth_error;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $sibuna_connection_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Sibuna-Status $sibuna_status;
proxy_set_header X-Sibuna-Rule $sibuna_rule;
proxy_set_header X-Sibuna-Rule-Hash $sibuna_rule_hash;
proxy_read_timeout 300s;
proxy_pass http://127.0.0.1:3000;
}
location = /__sibuna_auth {
internal;
proxy_pass http://127.0.0.1:8080/;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
proxy_set_header X-Forwarded-Method $request_method;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Uri "";
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header User-Agent $http_user_agent;
proxy_set_header Cookie $http_cookie;
}
location @sibuna_challenge {
rewrite ^ /__sibuna/challenge break;
proxy_pass http://127.0.0.1:8080;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
proxy_set_header X-Forwarded-Method $request_method;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
}
location @sibuna_auth_error {
add_header Retry-After $sibuna_retry_after always;
if ($sibuna_auth_status = 429) { return 429; }
return 503;
}
location /__sibuna/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header X-Forwarded-For $remote_addr;
}
}
example.com {
handle /__sibuna/* {
reverse_proxy localhost:8080
}
handle {
forward_auth localhost:8080 {
uri /
header_up X-Forwarded-For {remote_host}
header_up -X-Original-URI
copy_headers X-Sibuna-Status X-Sibuna-Rule X-Sibuna-Rule-Hash
}
reverse_proxy localhost:3000
}
}
/__sibuna/*の名前空間(中間ページ、チャレンジ、検証、ソルバーの資源)は、どちらのレシピでもデーモンに直接届かなければなりません。nginxのエラーページは元のURIとメソッドを渡すので、中間ページは認可が決めた要件を運びます。それらがなくてもページは動きますが、発行はブラウザーが報告するURLの評価に戻ります。Caddyは元のURIとメソッドのメタデータを自ら与えます。排他的なhandleブロックによって、チャレンジと検証のルートがforward-authの事前確認に入らないようにします。Nginxでは、アプリケーションのWebSocketのために、上に示した明示的なUpgrade/Connectionヘッダーが必要です。Nginxのエラーハンドラーは、二度目の認可判断をしたりアップロードのボディーを消費したりせずに、内部のチャレンジのルートを描画します。その認証モジュールが直接受け付けるのは2xx、401、403だけなので、例ではレート制限による認証エラーをRetry-After付きの429に戻します。それ以外の認可の失敗は503で閉じたままです。Nginxは独自の403のボディーを返しますが、CaddyはSibunaの拒否ページを転送します。どちらのレシピも、受信したSibunaの監査用ヘッダーを実際の認可の応答で置き換えます。通常のTLS証明書とアプリケーションのアップロードや期限の制限はイングレスで設定してください。例が示すのはルーティングの論理です。リポジトリでは、これらのレシピを実際のイングレスに対してまだテストしていません。レシピが依拠する転送メタデータの規則は、sibuna-httpの単体テストで確かめています。
イングレスから受け取るJA4フィンガープリント¶
JA4フィンガープリントは、クライアントがTLS接続をどのように開くかを要約したものです。これはクライアントの最初のハンドシェイクメッセージであるClientHelloから計算します。クライアントのTLSライブラリは、HTTPのバイトを一つも送らないうちにこのメッセージを確定するので、クライアントはHTTPリクエストの中からフィンガープリントを変えられません。ブラウザー、ライブラリ、ボットはこの値が異なります。そのためJA4は、どのクライアントも好きなように書けるUser-Agentの値よりも強いシグナルになります(SID 0014)。JA4はFoxIOが定義しました。フィンガープリントは36文字で、_でつないだ三つの部分から成ります。
t13d1516h2_8daaf6152771_02713d6af862
^^^^^^^^^^ ^^^^^^^^^^^^ ^^^^^^^^^^^^
a b c
a プロトコル(t TCP、q QUIC、d DTLS)、TLSバージョン(13はTLS 1.3)、
SNIありならd、なしならi、暗号スイートの数(2桁)、
拡張の数(2桁)、ALPNコード(h2はHTTP/2)
b ソートした暗号スイートのハッシュ(小文字の16進数12桁)
c ソートした拡張と署名アルゴリズムのハッシュ
(小文字の16進数12桁)
ClientHelloを見るのはTLSを終端するコンポーネントだけなので、JA4を計算できるのもそれだけです。SibunaはTLSを終端しません。イングレスの背後で平文のHTTP/1.1を提供し、ブラウザーとはイングレスがTLS、HTTP/2、HTTP/3で通信します。すでにJA4を計算するイングレスもいくつかあります。そこで、イングレスにフィンガープリントを計算させてリクエストヘッダーで送らせ、Sibunaはそこから読み取ります。
--ja4-header <name>がそのヘッダーを指定します。既定では無効で、既定の名前もありません。イングレスが使うヘッダーの名前を常に指定します。Sibunaは名前を小文字で保存し、大文字小文字を区別せずに照合します。自身が書き込む、または取り除くフィールドの名前(X-Forwarded-*、X-Real-IP、X-Sibuna-*、Forwarded。-の代わりに_を使ったものも含む)は拒否します。このオプションを指定すると、起動時のバナーにJA4: from cf-ja4 (trusted)のような行を表示します。
このヘッダーは、転送されたフィールドを信頼する場合にだけ読みます。これはX-Forwarded-Forを左右するのと同じ判断で、--trust-forwardedを指定するか、--no-trust-forwardedなしのforward-authモードです。信頼しない相手からのヘッダーは無視します。信頼する場合、その名前のフィールドがちょうど一つあり、その値がJA4の形式であれば、リクエストはフィンガープリントを持ちます。値が不正な形式であるか、フィールドが繰り返されていれば、リクエストはフィンガープリントを持ちません。これを二つのカウンターが観測します。sibuna_ja4_present_totalはフィンガープリントを持つリクエストを数え、sibuna_ja4_invalid_totalはヘッダーが不正な形式であるか繰り返されていたリクエストを数えます。信頼しない相手からのリクエストは、どちらのカウンターも増やしません。
リバースプロキシモードでは、Sibunaがヘッダーを信頼する場合にだけ、オリジンはそのヘッダーを受け取ります。信頼しない場合、Sibunaはオリジンに送るリクエストから、その名前のフィールドをすべて取り除きます。クライアントが名前の-を_で綴った場合も同じです。したがってクライアントは、その名前で偽造したフィンガープリントをオリジンに渡せません。信頼する場合、フィールドはその綴りのまま変更されずに通過し、_を使った別名はやはり取り除かれます。--ja4-headerがなければ、その名前のフィールドは普通のフィールドです。
Cloudflare。マネージド変換"Add bot protection headers"は、オリジンに送るリクエストに、cf-bot-score、cf-verified-bot、cf-ja3-hashとともにcf-ja4を加えます。これにはBot Management付きのEnterpriseプランが必要です。CloudflareとSibunaの間にあるイングレスは、このフィールドを変更せずに渡さなければなりません。Sibunaは次のように起動します。
sibuna --ja4-header cf-ja4 --trust-forwarded -s /etc/sibuna/secret
Sibunaの前にあるイングレスは、Cloudflareのアドレスからの接続だけを受け付けなければなりません。そうしないと、クライアントはCloudflareを迂回して自分のcf-ja4を送れてしまいます。
nginx。FoxIOのja4-nginx-moduleは、nginxの中でJA4を計算し、$http_ssl_ja4として公開します。これには、モジュールのClientHello取得パッチを当て、--with-http_ssl_module付きでビルドしたnginx 1.26以降が必要です。proxy_set_headerはクライアントの同名のフィールドを置き換えるので、Sibunaに届くlocationごとに、自らヘッダーを設定します。
# リバースプロキシ:Sibunaは --ja4-header x-ja4 --trust-forwarded で動かす
location / {
proxy_set_header X-JA4 $http_ssl_ja4;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_pass http://127.0.0.1:8080;
}
# forward auth:Sibunaは --mode forward_auth --ja4-header x-ja4 で動かす
location = /__sibuna_auth {
internal;
proxy_pass http://127.0.0.1:8080/;
proxy_set_header X-JA4 $http_ssl_ja4;
# ... 上記のforward-authの設定例にある残りのフィールド
}
forward-authのレシピでは、同じproxy_set_header X-JA4 $http_ssl_ja4;の行を@sibuna_challengeとlocation /__sibuna/にも置きます。この行を省いたlocationは、クライアント自身のX-JA4をSibunaに渡し、Sibunaはそれを信頼してしまいます。
Apache Traffic Server。ja4_fingerprintプラグインは、plugin.configのja4_fingerprint.soという行で有効になります。オプションはありません。このプラグインは、各TLS接続のリクエストに、フィンガープリントを持つja4フィールドと、プロキシの名前を持つx-ja4-viaフィールドを加えます。Sibunaは--ja4-header ja4 --trust-forwardedで起動します。プラグインの文書は、クライアントが送ったja4フィールドを置き換えるかどうかを述べていません。値を信頼する前に、使っているバージョンでこれを確かめるか、プラグインが自身のフィールドを加える前にクライアントのフィールドを取り除かなければなりません。
ルールはja4フィールドでフィンガープリントと照合します(第X部「ポリシーのスキーマ」)。値は、フィンガープリント全体(等しくなければならない)か、*が続く接頭辞(フィンガープリントがそれで始まらなければならない)のどちらかです。"*"だけなら任意のフィンガープリントに一致します。フィンガープリントのないリクエストがja4ルールに一致することはありません。大文字のT13D*のように、どのフィンガープリントも一致し得ないパターンを、ローダーはINVALID POLICY JA4で拒否します。照合はバイトを比較するだけで、メモリを割り当てません。
{ "rules": [
{ "name": "deny-known-scanner", "action": "DENY",
"ja4": "t13i010400_0f2cb44170f4_5c4c70b73fa0" },
{ "name": "weigh-no-sni", "ja4": "t13i*", "action": "WEIGH", "weight": 15 },
{ "name": "weigh-headless", "user_agent": "Headless", "action": "WEIGH",
"weight": 30 },
{ "name": "challenge-tls12-checkout", "path": "/checkout/*", "ja4": "t12*",
"action": "CHALLENGE" }
] }
最初のルールは一つのフィンガープリントを完全一致で拒否します。この値は例であり、既知のスキャナーではありません。次の二つは判断する代わりに、リクエストのスコアに重みを加えます。サーバー名を送らなかったTLS 1.3のクライアントと、User-Agentで分かるヘッドレスブラウザーです。後のルールが先に判断しなければ、両方のシグナルを示すリクエストはスコアが45になって既定の拒否のしきい値40に達し、一方だけを示すリクエストにはチャレンジします。最後のルールは、チェックアウトのパスでTCP上のTLS 1.2を交渉したすべてのクライアントに、接頭辞によってチャレンジします。拒否ではなくチャレンジにするのは、正当な古いクライアントの多くが今もTLS 1.2を使うからです。ルールはこのようにJA4を他のシグナルと組み合わせるべきです。JA4の値が示すのはTLSライブラリとその設定であり、人や機器ではありません。多くのクライアントが一つのライブラリを共有し、特化したライブラリはブラウザーのClientHelloを模倣できます。JA4は自動化のコストを上げますが、身元を証明するものではありません。同じ理由から、Sibunaは禁止とレピュテーションをアドレスをキーとして保持し、フィンガープリントをキーにすることはありません。
インシデント(WAFによる拒否、ハニーポットへのアクセス、監査の検出)は、そのリクエストがフィンガープリントを持っていれば、それを列security_incidents.ja4に記録します。コンソールはインシデントの証拠の中で、これを"JA4 fingerprint"として、値または"Not recorded"とともに表示します。Eventsのフィルターはフィンガープリントまたは接頭辞を受け付けます。管理するルールのエディターにはJA4フィールドがあり、policies.ja4_patternに保存されます。ポリシーのテストフォームはフィンガープリントを受け取ります。
宣言的なポリシー¶
{
"default_action": "CHALLENGE",
"waf": true,
"thresholds": { "challenge_at": 10, "deny_at": 40, "bits_step": 5 },
"ip_rules": { "10.0.0.0/8": "ALLOW", "192.0.2.0/24": "DENY", "2001:db8::/32": "DENY" },
"rules": [
{ "name": "deny-cf-workers", "headers": { "CF-Worker": ".*" }, "action": "DENY" },
{ "name": "deny-amazonbot", "user_agent": "Amazonbot", "action": "DENY" },
{ "name": "api-with-key", "path": "/api/*", "headers": { "X-Api-Key": ".*" },
"action": "ALLOW" },
{ "name": "protect-checkout", "path": "/checkout/*", "action": "CHALLENGE",
"challenge": { "difficulty": 20, "algorithm": "posw" } },
{ "name": "headless", "user_agent": "Headless", "action": "WEIGH", "weight": 30 },
{ "name": "internal-vpc", "remote_addresses": ["10.0.0.0/8", "fd00::/8"],
"action": "ALLOW" }
]
}
ローダーは安全側に失敗します。不明なキー、綴りを誤った動作、不正な形式のアドレス、範囲外の数値があるとファイル全体を拒否し、診断はルールとフィールドを示し、デーモンは起動しません。不明なオプションや範囲外の値を含むコマンドラインも、同じように拒否されます。rulesがあれば組み込みの表を置き換えます。ip_rulesはレピュテーショントライに供給され、数千の接頭辞まで扱えます。waf: falseはファイルからGateの運用構成を選びます。スキーマにはさらに二つのキーがあります(第X部)。inspectionは各WAFのカテゴリーをdisabled、audit、enforceのいずれかに設定し、ルールのlimitsオブジェクトはルールに専用のクォータを与えます。ルールのja4フィールドは、信頼するイングレスが転送したJA4フィンガープリントと、完全一致または*が続く接頭辞で照合します。これには--ja4-headerが必要です(「イングレスから受け取るJA4フィンガープリント」を参照)。パスのパターンは正規形のリクエストのパスと照合するので(SID 0003)、パターンはその形で書かなければなりません。
永続ストレージとクラスタリング¶
--data-dir /var/lib/sibunaはSQLiteファイル/var/lib/sibuna/sibuna.dbを開き(WALモード、synchronous=NORMAL、ビジータイムアウト付き)、ストレージスレッドを起動します。--database-url(または--database-url-file)は、代わりにPostgreSQLデータベースに接続します。ストレージスレッドは単一スレッドのtokioランタイムと小さな接続プールを所有し、SQLを実行する唯一の場所です。起動時、ポリシーのリビジョンが変わったとき(policies、ip_reputation、policy_inspectionへの書き込み)、レピュテーションの項目が期限切れになったときに、スレッドはポリシーファイルとデータベースからエンジンを再構築して公開します。リクエストがSQLを待つことはありません。再構築では読み込みの前後でリビジョンを読み、その間に書き手がコミットしていれば候補を破棄します。
スキーマ¶
| 表 | 目的とキー |
|---|---|
policy_revision |
ポリシーのリビジョン、1行。三つのポリシーの表のトリガーがこれを進めます。 |
policies |
順序付きの動的なルール、キーはid。NULLを許すja4_patternはルールのJA4の条件で、最大37バイト。 |
policy_inspection |
カテゴリーごとに保存したWAFのモード、1行。 |
ip_reputation |
スコア、ヒット数、期限。キーはアドレスまたは接頭辞。 |
incident_receipts |
各ノードの永続的なインシデントの受領記録(最後にコミットしたバッチの次のシーケンス)。キーはノード。 |
security_incidents |
64成分の埋め込みベクトル(256バイト)を持つ、上限のある一つのイベントのレコード。キーはnode_id << 40 | sequence。NULLを許すja4はリクエストのJA4フィンガープリントで、ちょうど36バイト。 |
incidents_fts |
SQLiteでは、パスとペイロードの正規化したトークンに対するFTS5の表。PostgreSQLでは、同じトークンがGIN索引付きのsecurity_incidentsのtsvector列searchです。 |
sibuna_schema |
適用したすべてのマイグレーション。キーはコンポーネントとバージョン。 |
中核のスキーマはcrates/storage/src/schema.rsで、方言ごとに一度ずつ書かれています。コンソールがあると、コンポーネントconsoleが、名前がconsole_で始まる33個の表を加えます(SID 0013、crates/console-storage/src/schema/)。マイグレーションはコンポーネントごとに番号が付き、バイナリにコンパイルされます。中核のマイグレーション2で二つのJA4の列が加わります。それより前に作成したデータベースは、起動時にマイグレーションされます。保留中のマイグレーションはすべて一つのトランザクションで実行され、ノードは、コンポーネントのバージョンが自分の知るものより新しいデータベースを拒否します。省略して印刷したスキーマは、アップグレードのスクリプトではありません。SQLiteの表はSTRICTで、CHECK制約がRustの型を写しているので、デーモンが表現できない行はデータベースが拒否します。列挙値は小文字で保存します。'DENY'を直接書き込むと拒否されます。
運用¶
sibuna.dbにはsqlite3シェルを使い(WALモードなので、デーモンの実行中も読めます)、クラスターのデータベースにはpsqlを使います。
-- 動的なルールを追加する。各ノードは次のティックで再構築する。
INSERT INTO policies (id, name, priority, path_pattern, action, difficulty, algorithm,
header_matchers, cidr_matchers, weight, enabled, created_at, updated_at)
VALUES ('p-checkout', 'protect-checkout', 10, '/checkout/*', 'challenge', 20, 'posw',
'{"X-Api": "v2"}', '["10.0.0.0/8"]', 0, 1, unixepoch(), unixepoch());
-- あるアドレスをクラスター全体で1日間禁止する。
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.id, 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向けに書いています。PostgreSQLでは、enabledはTRUE、時刻はunixepoch()の代わりにCAST(extract(epoch FROM now()) AS BIGINT)、検索はsecurity_incidentsに対するWHERE search @@ CAST('union' AS tsquery)です。pathとoffending_payloadは生のリクエストのバイト(BLOBまたはBYTEA)を保持します。制約に反する直接の書き込みはデータベースが拒否し、ノードには届きません。PostgreSQLでは、リビジョンのトリガーがNOTIFY sibuna_policyも発行するので、他のノードはすぐにティックします。保証となるのは引き続きポーリングです。
\(-50\)以下のスコアはトライのdeny接頭辞に、\(50\)以上のスコアはallowになり、banned_untilが禁止の期間を区切ります。ハニーポットへのアクセスは自動的に\(-100\)のレコードを挿入するので、共有PostgreSQLデータベースでは、一つのノードで作動した罠がすべてのノードでそのアドレスを禁止します。
トランザクションの受領記録が再試行を安全にする¶
ストレージスレッドは保留中のレコードを最大32件集め、一つのSQLトランザクションを作ります。トランザクションはインシデントを挿入し、全文索引を更新し、ハニーポットによるレピュテーションの変更を適用します。各発行者(ノード)は単調に増加する受領記録、つまりincident_receiptsの自分の行を持ちます。データを変更する文はすべてその受領記録で守られ、トランザクションは最後にそれを進め、決して戻しません。
コミットに失敗すると、保留中のバッチをメモリに保持し、incident_write_failuresを増やします。ティックでは引き続きポリシーのポーリングを試みます。512レコードのキューが満杯になるとincidents_droppedを数えます。ディスクを待ってHTTPの応答をブロックすることはありません。保留中のバッチは32レコード分の空間を加えます。コミット前にプロセスが死ぬと、キューに入ったデータは失われ得ます。これは上限のある非同期のフォレンジックの経路であり、キューに入れた時点で永続化されるメッセージキューではありません。
キャンペーンのクラスタリング¶
各インシデントのペイロードは、バイトのトライグラム(数字と大文字小文字を同一視)に対するハッシュトリックで64次元の単位ベクトルに埋め込まれ、256バイトとしてsecurity_incidents.embeddingに保存されます。ストレージスレッドは、全ノードの最新16,384個の埋め込みベクトルをメモリ(4 MiB)に保持し、ティックごとにデータベースから更新します。挿入の前に、同じバッチ内の先のレコードも含めて、それらのうち最も近いものを探します。コサイン距離が\(0.35\)以下なら、新しいインシデントはそのインシデントのcampaign_idに加わり、そうでなければ自身の識別子を名前とするキャンペーンを始めます。窓より古いインシデントとは比較しません。類似度はヒューリスティックです。回帰テストの例では関連するSQLのペイロードがまとまりますが、攻撃のどの組も同じキャンペーンに属するという保証ではありません。モデルは実行せず、何も学習しません。
クラスタリング¶
クラスターとは、一つのPostgreSQLデータベースを共有するノードの集合です。postgres-tlsフィーチャーでビルドし(cargo build --release -p sibuna --features postgres-tls。postgresも含みます)、各メンバーをデータベースと固有のノードIDで起動します。
sibuna --database-url-file /etc/sibuna/database-url --cluster-node 1 \
--secret-file /etc/sibuna/secret
すべてのメンバーは同じマスターシークレットと、1から8,388,607の一意な--cluster-nodeを使わなければなりません。URLファイルはpostgres://のURLを一つ持ち、所有者だけが読めなければなりません。バナーがURLを表示することはありません。書き込みはPostgreSQLのプライマリーに送られます。各ノードのストレージスレッドは、コミットされたリビジョンの変化を(NOTIFYまたはポーリングで)見て、エンジンを再構築します。
ノードはネットワーク越しに共有データベースに到達するので、その接続を暗号化して検証します。サーバーには自分たちの認証局が署名した証明書を与え、URLでその認証局を指定します。postgres://sibuna:...@db.internal:5432/sibuna?sslmode=verify-full&sslrootcert=/etc/sibuna/db-ca.pemです。サーバーでは、pg_hba.confのhostssl行を通してだけTCPを受け付けます。
起動時、デーモンはデータベースの接続について1行表示します。verify-fullなら、証明書とホスト名を検証したと表示します。それより弱いモードでは、警告とヒントを表示します。sslmodeがなければモードはpreferです。サーバーがTLSを提供する場合にだけ接続は暗号化され、サーバーは検証されません。postgres-tlsなしでビルドしたデーモンは、require、verify-ca、verify-fullを拒否して欠けているフィーチャーを示し、平文に戻ることは決してありません。証明書が拒否されると、起動はすぐに停止します。ヒントは、sslrootcertと、URLのホストがサーバーの証明書にある名前であることを確認するよう求めます。sslrootcertはシステムのトラストストアに自分たちの認証局を加えますが、システムの認証局を取り除くことはしません(SID 0011、SID 0012)。
Sibunaは独自のデータベースを複製せず、リーダーも選出しません。複製、フェイルオーバー、バックアップはPostgreSQLの役割です(ストリーミングレプリケーション、Patroni、マネージドサービス)。コンソールのノード表示にはリーダーがありません。SQLiteのノードにはロールsingleを、PostgreSQLのノードにはunknownを表示し、quorumはノードの直前のデータベースとの往復が成功したことだけを意味します。データベースに到達できなければ、最後に公開したエンジンが配信を続け、インシデントは上限のあるリングに溜まり、満杯になるとカウンターを増やして破棄され、ストレージスレッドはバックオフしながら再試行します。ノードは再接続するまで最後のポリシーを保ちます。Zaxonliteのデータディレクトリ(SID 0005)は読みません。ポリシーはsibuna console policies exportとsibuna console policies importで移し、フォレンジックの履歴は移行しません。
クラスターでのチャレンジのルーティング¶
チャレンジ鍵は--cluster-nodeに結び付いています。チャレンジの発行と検証は同じメンバーで行ってください。トークンは共有のシードを使い、他のメンバーでも有効です。ローカルのレートのクォータは全体のクォータにはならず、プロセスを再起動すると使用済み集合は消えます。一つのローカルなPostgreSQLに三つのノードを置くと、直接書き込んだポリシーの行は1ティック以内に三つすべてに届き、一つのノードでのハニーポットによる禁止は他のノードに届き、インシデントの識別子は衝突しません(crates/storage/tests/multi_node.rs、SID 0011の基準2。SIBUNA_TEST_DATABASE_URLを設定すると実行されます)。
パッケージング¶
GitHubのどのリリースにも、プラットフォームごとに同じ実行ファイルが含まれます。これはリリースタグから既定のフィーチャー(SQLiteストレージとコンソール)でビルドしたものです。PostgreSQLのクラスターには、自分たちでビルドしたものが必要です(後述)。
| プラットフォーム | リリースアセット |
|---|---|
| Linux x86-64、ARM64 | sibuna-linux-amd64.tar.gzとsibuna-linux-arm64.tar.gzには、どのディストリビューションでも動く静的なmuslの実行ファイルが入っています。sibuna_<version>-1_amd64.deb、sibuna_<version>-1_arm64.deb、sibuna-<version>-1.x86_64.rpm、sibuna-<version>-1.aarch64.rpmは、それをsystemdサービスとともにインストールします。Arch Linuxではsibuna-bin-<version>-1-x86_64.pkg.tar.zstが同じことをします。 |
| macOS arm64、x86-64 | sibuna-macos-arm64.tar.gz、sibuna-macos-amd64.tar.gz。macOS 12以降に対応します。 |
| Windows x86-64 | sibuna-windows-amd64.zipにはsibuna.exeが入っています。Windows 10またはServer 2016以降に対応します。 |
| FreeBSD 15.1、OpenBSD 7.9(amd64) | sibuna-<version>-freebsd-15.1-amd64.pkgとsibuna-<version>.tgz。 |
| Homebrew、Kubernetes、コンテナー | sibuna.rb、helm-sibuna-<version>.tgz、そしてamd64とarm64向けのイメージghcr.io/insanai/sibuna:<version>。イメージのダイジェストはIMAGE-DIGEST.txtにあります。 |
| ソース | sibuna-<version>-source.tar.gz。 |
各アーカイブとパッケージには、LICENSE、NOTICE、LICENSES/(実行ファイルに含まれるクレートを記したTHIRD-PARTY-RUST.txtを含む)、README.md、SECURITY.md、sibuna.build.jsonが入っています。このマニフェストは、バージョン、コミット、Rustのターゲット、コンパイラーのバージョン、フィーチャー、そして実行ファイルとその二つのWebAssemblyモジュールのSHA-256を記録します。リリースワークフローは、何かを公開する前にすべての実行ファイルをそれぞれのプラットフォームで起動し、Debian、Fedora、Arch Linux、FreeBSD、OpenBSDでパッケージのインストール、再インストール、削除を行います。
アセットには署名がありません。インストールする前に、ダウンロードしたものを同じリリースのSHA256SUMSと照合します。
sha256sum --ignore-missing -c SHA256SUMS # Linux
shasum -a 256 --ignore-missing -c SHA256SUMS # macOS, FreeBSD
sha256 -C SHA256SUMS sibuna-1.0.0-beta.3.tgz # OpenBSD
macOSでは、ブラウザーでダウンロードしたファイルに隔離属性が付き、これが署名のない実行ファイルを止めます。照合の後、xattr -d com.apple.quarantine sibunaでこの属性を取り除きます。
systemdサービス¶
Debian、RPM、Archのパッケージは、/usr/bin/sibuna、ユニットsibuna.service、(systemd-sysusersによる)アカウントsibuna、ヘルパー/usr/lib/sibuna/seed.sh、設定ファイル/etc/sibuna/service.envをインストールします。インストールしても何も起動しません。設定ファイルにオリジンをIPリテラルで設定し、サービスを起動します。
sudoedit /etc/sibuna/service.env # SIBUNA_UPSTREAM_HOST, SIBUNA_UPSTREAM_PORT
sudo systemctl enable --now sibuna
curl -s http://127.0.0.1:8080/__sibuna/health
サービスは、SIBUNA_HOSTとSIBUNA_PORTで別の指定をしない限り、127.0.0.1:8080で待ち受けます。SIBUNA_OPTIONSは、空白で区切った追加のオプションを渡します。たとえば--mode forward_authや--console 127.0.0.1:19446です。起動のたびに、seed.shは許可シード/var/lib/sibuna/admission.seed(16進数64文字、モード0600、所有者sibuna)がなければ作成します。既存のシードを置き換えることはありません。新しいシードはすべてのセッションを終わらせてしまうからです。デーモンはSQLiteデータベースを、モード0700のディレクトリ/var/lib/sibunaに保存します。ユニットは、ケーパビリティなし、読み取り専用のシステム(ProtectSystem=strict)、プライベートな/tmpとデバイス、新しい特権なしで動きます。
アップグレードは設定ファイル、シード、状態を保ち、サービスを再起動しません。バックアップの後で自分たちで再起動します。削除はサービスを停止して無効にしますが、アカウント、シード、設定、状態は残します。これらはホストを退役させるときに自分たちで削除します。
FreeBSDとOpenBSDのパッケージがインストールするのは、/usr/local/bin/sibunaとその文書だけです(pkg add、またはOpenBSDのミラー以外から入手したパッケージにはpkg_add -D unsigned)。サービス、アカウント、状態は作成しません。デーモンは、専用のシードとデータディレクトリを持つ特権のないユーザーで実行します。
Homebrew¶
sibuna.rbは、マシンに合ったリリースアーカイブ(macOSまたはLinux、arm64またはx86-64)をインストールします。ソースからはビルドしません。HomebrewのRustにはwasm32-unknown-unknown向けの標準ライブラリがなく、埋め込む二つのWebAssemblyモジュールのビルドにはそれが必要だからです。アーカイブには、リリースワークフローが確認済みの実行ファイルが入っています。Homebrewはtapからしかformulaをインストールしないので、formulaをローカルのtapに置きます。
brew tap-new "$USER/local"
cp sibuna.rb "$(brew --repository)/Library/Taps/$USER/homebrew-local/Formula/"
brew install "$USER/local/sibuna"
このformulaはサービスを起動しません。注意書き(caveats)はシードの作り方を示し、テストは同じデータディレクトリでデーモンを2回起動します。
コンテナーとKubernetes¶
イメージghcr.io/insanai/sibuna:<version>は、distrolessのベースに静的な実行ファイルを載せたものです。CA証明書とユーザー65532を含み、シェルもパッケージマネージャーもありません。エントリーポイントはsibunaなので、引数はデーモンのオプションです。リリースワークフローはこのイメージを、読み取り専用、ケーパビリティなしで、シードを読み取り専用でマウントし、状態用のボリュームを付けて実行し、1回再起動します。
docker run -d --read-only --cap-drop=ALL --security-opt=no-new-privileges \
-v "$PWD/admission.seed:/run/admission.seed:ro" -v sibuna-state:/var/lib/sibuna \
-p 8080:8080 ghcr.io/insanai/sibuna:1.0.0-beta.3 \
--host 0.0.0.0 --secret-file /run/admission.seed --data-dir /var/lib/sibuna/data \
--upstream-host 10.0.0.5 --upstream-port 3000
Helmチャートhelm-sibuna-<version>.tgzは、そのイメージのPodを一つ実行します。自分たちで作成するSecret(secret.existingSecret、キーadmission.seed)が必要なので、シードがvaluesやテンプレートに現れることはありません。Podは、Restrictedのポッドセキュリティ標準の下で、読み取り専用のルートファイルシステムを持つUID 65532として動きます。Recreateでアップグレードするレプリカ一つが、ReadWriteOnceのボリュームの書き手を一つに保ちます。Sibunaはこのボリュームのdata/にSQLiteの状態を保存し、アンインストールしてもボリュームクレームは残ります。プローブは/__sibuna/healthを呼びます。ServiceはClusterIPで、チャートはingressもコンソールも作成しません。チャートのNetworkPolicyは、networkPolicy.ingressFromとnetworkPolicy.egressToがクライアントとオリジンを許可するまで、すべての通信を拒否します。upstream.hostはIPリテラルでなければならず、extraArgsは追加のデーモンオプションを渡します。ワークフローは、Restricted標準を強制するkindクラスターで、チャートのインストール、アップグレード、アンインストールを行います。
kubectl -n sibuna create secret generic sibuna-admission --from-file=admission.seed
helm install gateway ./helm-sibuna-1.0.0-beta.3.tgz --namespace sibuna \
--set secret.existingSecret=sibuna-admission \
--set upstream.host=10.0.0.5 --set upstream.port=3000
ソースからビルドする¶
私たちは Rust 1.100 でビルドとテストを行います。サポートする最小バージョンは引き続き Rust 1.94 です。
リリース用ツールチェーンを rustup toolchain install 1.100.0 --profile minimal --target wasm32-unknown-unknown でインストールし、以下のコマンドでは cargo +1.100.0 で選択します。
cargo build --release -p sibunaは、既定のフィーチャー(SQLiteストレージとコンソール)でtarget/release/sibunaを生成します。sqlxはSQLiteを同梱し、ring(rustls)はビルド時にCコンパイラーを必要とします。バイナリはシステムのCランタイムを動的にリンクします。ビルドスクリプトはWebAssemblyのソルバーとコンソールのインターフェースもビルドするので、rustup target add wasm32-unknown-unknownが必要です。SIBUNA_POW_WASM=<path>とSIBUNA_CONSOLE_WASM=<path>を指定すると、代わりにビルド済みのモジュールを埋め込みます。cargo build --release -p sibuna --no-default-featuresは、外部クレートをまったく使わない、メモリ上のファイアウォールを生成します。この場合、--data-dirと--database-urlは起動時にStorageDisabledで、sibuna consoleはCONSOLEBUILDで拒否されます。cargo build --release -p sibuna --features postgres-tlsは、データベースへの検証付きTLSを備えたPostgreSQLのクラスターを加えます。OpenSSLは必要ありません。- リリースの静的なLinux実行ファイルは、
musl-gccをCコンパイラーとして(CC_x86_64_unknown_linux_musl=musl-gcc)、cargo build --release --locked -p sibuna --target x86_64-unknown-linux-musl(またはaarch64-unknown-linux-musl)でビルドしたものです。
リリースプロファイルはfat LTOと一つのコード生成単位を使います。ワークフローは二つのWebAssemblyモジュールを一度だけビルドしてすべてのプラットフォームに渡すので、リリースのすべての実行ファイルはバイト単位で同一のモジュールを埋め込みます。依存関係が変わったら、cargo xtask licensesでLICENSES/THIRD-PARTY-RUST.txtを再生成します。
Windowsでは、デーモンはCtrl+C、Ctrl+Break、コンソールを閉じるイベントで停止します。Windowsサービスとしては動きません。Windowsのファイルにはモードビットがないので、Sibunaは他者が読めるかもしれない鍵、認証情報、データベースURLのファイルを拒否できません。これらのファイルはACLで制限します。コンソールのメモリとCPUのゲージは/procから読むので、他のシステムでは使えません。