PingWAF WAF
日本語
English EN 简体中文 ZH Español ES Français FR 日本語 JA
GitHub
概要 機能 クイックスタート ドキュメント GitHub ↗

クイックスタート

5 分で起動、10 分で保護

公式の 2 つの道筋。評価には同梱の compose、本番には自前ビルド。

方法 A Docker Compose 方法 B ソースからビルド 所要 約 5 分 保存先 PostgreSQL 14+

始める前に

compose なら Docker だけで十分です。ソースからビルドする場合は Rust、Node、protoc が必要です。

Docker

Engine 24+ と Compose v2

コントロールプレーン、エージェント、PostgreSQL をまとめて起動します。

PostgreSQL

14+（16 推奨）

サイト、ルール、バージョンを保存します。

ポート

9080 · 9090 · 80 · 443

9080 が API とコンソール、9090 が gRPC です。

TLS

初回起動時は自己署名

コンソールを公開する前に置き換えるか信頼してください。

クイックスタート

Docker Compose

compose は all-in-one モードで PingWAF を PostgreSQL と一緒に起動します。

  1. リポジトリを取得

    compose とサンプル TOML はリポジトリ直下にあります。

    bash 
    git clone https://github.com/shuaiZend/PingWAF.git
cd PingWAF

  2. スタックを起動

    外部から到達できるホストでは JWT_SECRET と ADMIN_PASSWORD を先に設定します。

    bash 
    export JWT_SECRET="$(openssl rand -hex 32)"
export ADMIN_PASSWORD="$(openssl rand -hex 16)"
docker compose up -d

  3. コンソールを開く

    初回起動で生成した自己署名証明書で HTTPS を提供するため、信頼するか独自証明書をアップロードするまでブラウザは警告します。

    bash 
    curl --connect-timeout 2 --max-time 3 http://localhost:9080/healthz
# {"status":"ok","database":"up"}

  4. 最初のサイトを追加

    エージェントに向けるドメインでサイトを作成し、そのサイトに必要な防御だけを有効にします。

公開バイナリは Linux amd64/arm64 向けです。Docker イメージは両アーキテクチャに対応します。
localhost:9080/sites
トラフィックと保護状態を表示するコンソールのサイト一覧
サイト一覧が適用の起点です。1 行が 1 ホスト名に対応します。

クイックスタート

ソースからビルド

独自ビルドや監査可能なバイナリが必要な場合の道筋です。

  1. ツールチェーンを導入

    protoc は必須です。無い場合 proto クレートがプレースホルダに退避し、後続のクレートがビルドできません。

    bash 
    # macOS
brew install protobuf

# Debian / Ubuntu
sudo apt install protobuf-compiler cmake

  2. コンソールをビルド

    コンソールはバイナリに埋め込まれるため先にビルドします。

    bash 
    cd web && npm ci && npm run build && cd ..

  3. バイナリをビルド

    full フィーチャーには WAF エンジン、チャレンジ、証明書自動化が含まれます。

    bash 
    cargo build --release --bin pingwaf --features full

  4. all-in-one で起動

    PostgreSQL を指定します。スキーマは初回起動時に作成されます。

    bash 
    ./target/release/pingwaf all-in-one \
  --db-url "postgres://pingwaf:pingwaf@localhost:5432/pingwaf"
Linux では install.sh（--mode all-in-one）でビルドを省略できます。
localhost:9080/agents
登録済みエッジエージェントとハートビートを表示するエージェントページ
自前ビルドをコントロールプレーンとして動かし、後からエージェントを登録できます。

初回ログイン

コントロールプレーンは初回起動時に管理者を作成し、コンソールはパスワード変更を強制します。

defaults.env

コンソール https://localhost:9080
メール admin@pingwaf.local
パスワード pingwaf123
JWT シークレット 16 文字以上

公開前に既定値を必ず変更

PINGWAF_JWT_SECRET と PINGWAF_ADMIN_PASSWORD には動作する既定値があります。両方を設定し、PINGWAF_ALLOW_REGISTRATION を false にし、9080 は社内ネットワークか VPN 内に留めてください。
bash 
export PINGWAF_JWT_SECRET="$(openssl rand -hex 32)"
export PINGWAF_ADMIN_PASSWORD="$(openssl rand -hex 16)"
export PINGWAF_ALLOW_REGISTRATION=false
localhost:9080/login
メールアドレスとパスワード欄を備えた PingWAF のログイン画面
初期管理者アカウントでログインします。パスキーは後から設定で登録できます。

次のステップ

コントロールプレーンが応答すれば、あとは設定だけです。

サイトを作成

サイトはドメインをオリジンプール、ルート、有効化した防御に結び付けます。

サイトモデル

エージェントを接続

制御ノードで pingwaf server、各エッジで pingwaf agent を実行します。gRPC :9090 で登録されます。

分散デプロイ

防御を有効化

サイト単位で WAF エンジン、CC シールド、ボットポリシーを有効にします。有効にするまで何も適用されません。

機能

ログを外部へ

リクエストログは Elasticsearch へ、生データは再現用に PostgreSQL へ保存します。

可観測性

起動しないとき

pingwaf-proto でビルドが失敗する

protoc がありません。protobuf-compiler（または brew install protobuf）を導入して再ビルドしてください。無い場合はプレースホルダに退避します。

ブラウザが証明書を拒否する

コンソールは自己署名証明書で HTTPS を提供します。ダウンロードした証明書を信頼するか、設定 → コントロールプレーン HTTPS で独自証明書をアップロードしてください。PINGWAF_TLS_SANS で実際のホスト名を指定します。

エージェントが一覧に出ない

:9090 の gRPC に到達できるか（PINGWAF_SERVER_URL）、ファイアウォールや TLS 終端プロキシに遮られていないかを確認してください。

443 が開かない

443 は証明書の発行またはアップロード後に開きます。それまではエージェントは 80 番の HTTP のみ提供します。

詳しい手順が必要ですか

デプロイとアーキテクチャのドキュメントで、systemd、分散構成、設定の優先順位、環境変数の全一覧を説明しています。

デプロイガイド GitHub