> For AI agents: the complete documentation index is available at /ja/llms.txt, the full documentation bundle is available at /ja/llms-full.txt. # appsettings.json の設定 `appsettings.json` ファイルは GZCTF のコア設定ファイルで、コンテナ内にマウントすることで設定します。この記事では、設定ファイルの各フィールドの意味を説明します。 :::info `appsettings.json` の更新は、GZCTF サービスを再起動するたびに反映されます。 ::: ## 設定ファイルの構造 以下に完全な設定ファイルの例を示します： ```json { "AllowedHosts": "*", "ConnectionStrings": { "Database": "Host=db:5432;Database=gzctf;Username=postgres;Password=" // redis is optional // "RedisCache": "cache:6379,password=", // local disk storage (default) or s3-compatible storage (optional) // "Storage": "disk://path=./files" or "s3://accessKey=;secretKey=;bucket=;region=" }, "Logging": { "LogLevel": { "Default": "Information", "Microsoft": "Warning", "Microsoft.Hosting.Lifetime": "Information" }, "Loki": { "Enable": true, "EndpointUri": "http://loki:3100", "Labels": [ { "Key": "app", "Value": "gzctf" } ], "PropertiesAsLabels": ["app"], "Credentials": { "Login": "login", "Password": "password" }, "Tenant": "my-tenant", "MinimumLevel": "Trace" } }, "Telemetry": { "Prometheus": { "Enable": false, "TotalNameSuffixForCounters": false }, "OpenTelemetry": { "Enable": false, "Protocol": "Grpc", "EndpointUri": "http://jaeger-collector:4317" }, "AzureMonitor": { "Enable": false, "ConnectionString": "InstrumentationKey=12345678-abcd-abcd-abcd-12345678..." }, "Console": { "Enable": false } }, "EmailConfig": { "SenderAddress": "", "SenderName": "", "UserName": "", "Password": "", "Smtp": { "Host": "localhost", "Port": 587, "BypassCertVerify": false } }, "XorKey": "", "ContainerProvider": { "Type": "Docker", // or "Kubernetes" "PortMappingType": "Default", "EnableTrafficCapture": false, "PublicEntry": "ctf.example.com", // or "xxx.xxx.xxx.xxx" "DockerConfig": { // optional "ChallengeNetwork": "", "Uri": "unix:///var/run/docker.sock", "UserName": "", "Password": "" }, "KubernetesConfig": { // optional "Namespace": "gzctf-challenges", "ConfigPath": "kube-config.yaml", "AllowCIDR": [ // allow the cluster CIDR for LB "10.0.0.0/8" ], "DNS": [ // custom DNS to avoid cluster DNS "8.8.8.8", "223.5.5.5" ] } }, "RequestLogging": false, "DisableRateLimit": false, "Registries": { "ghcr.io": { "UserName": "...", "Password": "ghp_..." } }, "CaptchaConfig": { "Provider": "None", "SiteKey": "...", "SecretKey": "...", // optional "HashPow": { "Difficulty": 18 } }, "ForwardedOptions": { "ForwardedHeaders": 7, // a flag enum, see following link "ForwardLimit": 1, "ForwardedForHeaderName": "X-Forwarded-For", // use the following options to allow proxy "KnownIPNetworks": ["10.0.0.0/8"], "KnownProxies": ["10.0.0.1"] }, "Kestrel": { "Limits": { "MaxResponseBufferSize": 2048, "MaxRequestBufferSize": 1048576, "MaxRequestLineSize": 8192, "MaxRequestHeadersTotalSize": 32768, "MaxRequestHeaderCount": 100, "MaxRequestBodySize": 27262946, "KeepAliveTimeout": "0.0:5:0", "RequestHeadersTimeout": "0.0:5:0", "MaxConcurrentConnections": null, "MaxConcurrentUpgradedConnections": null }, "AddServerHeader": true, "AllowResponseHeaderCompression": true, "AllowSynchronousIO": false, "AllowAlternateSchemes": false, "DisableStringReuse": false, "ConfigurationLoader": null } } ``` ## コア機能の設定フィールド ### ConnectionStrings ここでは、データベースの接続を構成できます。 #### `Database` このフィールドは必須です。 GZCTF は PostgreSQL をバックエンドデータベースおよびデータ永続化に使用します。 :::info GZCTF はデータベースとして PostgreSQL のみをサポートしており、MySQL などの他のデータベースはサポートしていません。設定ファイルに正しいデータベース接続文字列を記入してください。 ::: #### `RedisCache` このフィールドはオプションです。 GZCTF は Redis をキャッシュおよびメッセージキューとして使用します。単一インスタンスのデプロイでは Redis は必須ではなく、GZCTF のメモリキャッシュを直接使用できます。複数インスタンスのデプロイでは、Redis は必須であり、共有キャッシュおよび SignalR の Scale-Out ブロードキャストとして使用されます。 v1.0以降、GZCTFは[ガーネット](https://github.com/microsoft/garnet)をキャッシュサービスとして使用することをサポートしています。 #### `Storage` このフィールドはオプションです。 GZCTFは2種類のストレージプロバイダーをサポートしています: - **ローカルディスクストレージ（デフォルト）** `disk://path=./files` - `path`: 任意。ファイルをローカルに保存するパス（デフォルト: `./files`） - **S3互換ストレージ** (AWS S3、MinIO、DigitalOcean Spaces など) `s3://accessKey=...;secretKey=...;bucket=...;region=...` または便宜上、以下のスキームを使用できます: - `aws.s3://...` (equivalent to `s3://...`) パラメータ: - `accessKey`: 任意。Access Key ID - `secretKey`: 任意。Secret Access Key - `bucket`: Bucket 名 - `region`: リージョン（例：`us-east-1`） - `endpoint`: 任意。カスタムエンドポイント URL（MinIO または他の S3 互換サービス用） - `useHttp`: 任意。HTTPS の代わりに HTTP を使用するかどうか（デフォルト: false） - `forcePathStyle`: 任意。パススタイル URL を使用するかどうか（デフォルト: false）。**カスタム `endpoint` を使う場合は `true` が必須**（MinIO/RustFS などの S3 互換サービス）。そうでないと仮想ホスト形式（`.`）になり失敗します。 詳細については、以下のリンクを参照してください: - [AWS S3](https://docs.aws.amazon.com/s3/index.html) - [MinIO S3](https://docs.min.io/) ### Logging ロギングレベルとスコープを設定することができます。さらに、GZCTF は Loki サーバーへのログ送信もサポートしています。 - **LogLevel**: 名前空間ごとの最小ロギングレベル。 - **Loki**: Loki サーバーの設定。 - **Enable**: 有効にするかどうか。 - **EndpointUri**: Loki サーバーの URI。 - **Labels**: 任意。グローバルログイベントラベル。 - **PropertiesAsLabels**: 任意。Loki のラベルにマップするべきプロパティのリスト。 - **Credentials**: 任意。基本認証に使用される資格情報。 - **Tenant**: 任意。Loki サーバーへのログ送信に使用されるテナント ID。 - **MinimumLevel**: 任意。最小ロギングレベル。 利用可能なロギングレベル: Trace, Debug, Information, Warning, Error, Critical, None。 ### Telemetry GZCTF はメトリクスと分散トレーシングをサポートしています。使用するプロバイダーを設定できます。 - **Prometheus**: Prometheus エンドポイント。 - **Enable**: 有効にするかどうか。 - **TotalNameSuffixForCounters**: 任意。カウンタに `_total` サフィックスを含めるかどうか。 - **OpenTelemetry**: メトリクスとトレーシングデータを OpenTelemetry にエクスポートします。 - **Enable**: 有効にするかどうか。 - **Protocol**: `Grpc` または `HttpProtobuf`。 - **EndpointUri**: テレメトリーデータがプッシュされる OpenTelemetry エンドポイント URI。 - **AzureMonitor**: メトリクスとトレーシングデータを ApplicationInsights にエクスポートします。 - **Enable**: 有効にするかどうか。 - **ConnectionString**: 接続文字列。 - **Console**: トレーシングデータをコンソールにエクスポートします。 - **Enable**: 有効にするかどうか。 ### EmailConfig ここではメール送信に関する情報を設定します。メールでの登録やその他のメール機能を使用する場合、この項目は必須です。 - **SenderAddress:** 送信者のメールアドレス - **SenderName:** 送信者の名前 - **UserName:** SMTP サーバーのユーザー名 - **Password:** SMTP サーバーのパスワード - **Smtp:** SMTP サーバーのアドレスとポート - **BypassCertVerify:** 証明書の検証をバイパスするかどうか :::info 一部のクラウドサービスプロバイダの制限により、465 ポートを使用してメールを送信できない場合があります。その場合は、587 ポートを試してみてください。 ::: ### XorKey ここでは暗号化キーを設定します。これは、データベース内のゲームの秘密鍵情報を暗号化するために使用されます。任意の長さの任意の文字列を使用できます。 ### ContainerProvider ここではコンテナバックエンドを設定します。これは、ゲームで動的にコンテナを作成するための必須項目です。 - **Type:** コンテナバックエンドのタイプ。`Docker`または`Kubernetes`を選択できます。 - **PublicEntry:** コンテナバックエンドの公開アドレス。これは、ゲームのアクセスアドレスを生成し、参加チームに表示するために使用されます。 - **PortMappingType:** ポートマッピングのタイプ。`Default`または`PlatformProxy`を選択できます。 - **EnableTrafficCapture:** トラフィックキャプチャを有効にするかどうか。`PortMappingType`が`PlatformProxy`に設定されている場合のみ使用できます。有効にすると、`/app/files/capture`ディレクトリにトラフィックが記録されます。 #### Docker :::warning Docker Swarm は v1.8.0 以降サポートされなくなりました。より高いセキュリティとスケーラビリティのため、Kubernetes の使用を推奨します。 ::: - **Uri:** Docker API Server のアドレス - ローカルの Docker を使用する場合は、`Uri` を空にし、`/var/run/docker.sock` をコンテナの対応する位置にマウントします。 - 外部の Docker を使用する場合は、`Uri` を対応する Docker API Server に指定します。**API 認証を使用することを推奨します。** - **ChallengeNetwork:** **v1.8.0 以前** チャレンジコンテナが所属するネットワークを指定します。指定しない場合は、デフォルトの Docker ネットワークが使用されます。 **v1.8.0 以降** チャレンジネットワークを作成するための**ネットワークプレフィックス**として扱われます。GZCTF はネットワークモードごとに 2 つのネットワークを自動的に作成します。オープンネットワークモードには `-open`、隔離ネットワークモードには `-isolated` が使用されます。 また、自分で `-custom` ネットワークを作成してカスタムネットワークモードに利用することもできます。要件に合わせて自由に設定してください。 - **UserName, Password:** Docker API Basic Auth のユーザー名とパスワード。オプションです。 #### Kubernetes - **Namespace:** Kubernetes の名前空間。チャレンジインスタンスを作成するための名前空間で、デフォルトは`gzctf-challenges`です。 - **ConfigPath:** Kubernetes の設定ファイルのパス。クラスタに接続するために使用します。デフォルトは`kube-config.yaml`です。 - **AllowCIDR:** Pod へのアクセスを許可する CIDR ホワイトリスト。 - **DNS:** クラスタ DNS を避けるためのカスタム DNS サーバーリスト。 デフォルトの動作は、クラスタ接続設定を`kube-config.yaml`ファイルに入れ、それを`/app`ディレクトリにマウントすることです。実験的な機能は、動作を理解していない限り、変更しないでください。 :::info `kube-config.yaml`ファイルの`server`フィールドを変更し、クラスタの API Server アドレスを指定することに注意してください。クラスタのデフォルトアドレスは通常`https://127.0.0.1:6443`で、クラスタの実際のアドレスに変更する必要があります。 ::: :::info **v1.8.0 以前** 基本的なネットワーク分離を実現するために、GZCTF はチャレンジの Namespace に `gzctf-policy` という名前の NetworkPolicy を作成してアクセスを制限します。GZCTF はこの NetworkPolicy が既に存在するかどうかを自動的に検出し、存在する場合は再作成しません。そのため、この NetworkPolicy を作成または編集することでネットワークポリシーをカスタマイズできます。 **v1.8.0 以降** GZCTF はチャレンジの Namespace に `gzctf-network-open` と `gzctf-network-isolated` という 2 つの NetworkPolicy を作成し、それぞれオープンネットワークモードと隔離ネットワークモードのアクセス制御に使用します。GZCTF がこれらの NetworkPolicy を自動的に管理するため、手動で変更・削除しないでください。 同じ Namespace 内に**追加の NetworkPolicy** を作成することで、独自のネットワークポリシーを定義できます。ターゲット Pod は次のラベルを使用して選択できます。 - `gzctf.gzti.me/TeamId`: 特定のチームを選択 - `gzctf.gzti.me/UserId`: 特定のユーザーを選択 - `gzctf.gzti.me/ChallengeId`: 特定のチャレンジを選択 - `gzctf.gzti.me/NetworkMode`: 特定のネットワークモードを選択（`open`、`isolated`、`custom`） ::: ### RequestLogging ここでは、リクエストログの記録を有効にするかどうかを設定します。有効にすると、ログに各リクエストの詳細情報が出力されます。この出力には静的ファイルのリクエストは含まれません。 :::warning この設定項目はリクエストの具体的な情報を記録しますが、**ログファイルのサイズおよびプラットフォームの同時実行性能に大きな影響**を与える可能性があるため、デバッグ時にのみ有効にしてください。 ::: ### DisableRateLimit ここでは、リクエストの頻度制限を有効にするかどうかを設定します。有効にすると、事前に設定したルールに基づいて、各 IP と API のリクエスト頻度が制限されます。 :::danger **この設定はプラットフォームの安全性の基礎となるものであり、テスト環境以外で無効化した場合の結果については自己責任となります。** 正しく設定されたほとんどのケースでは、ユーザーがレート制限に達することはありません。通常の使用中に頻繁にレート制限が発生したり、バックエンドログに異常なIP情報（例：同一IPから大量のリクエスト）が表示される場合は、**リバースプロキシの信頼できるプロキシ設定**を確認してください。 この設定を有効にすると、GZCTF は非常に少ないリソースで通常のリクエストの数十倍に達する悪意のあるリクエストを防ぎ、プラットフォームの正常な動作を確保することができます。 ::: ### RegistryConfig :::warning **この設定項目は非推奨となり、`Registries` フィールドを使用して定義してください。** ::: ### Registries ここでは、Docker Registry のユーザー名とパスワードを設定します。これは、ゲームで動的にコンテナを作成する際にイメージをプルするための認証で、オプションです。 ```json "Registries": { "ghcr.io": { "UserName": "...", "Password": "ghp_..." }, "docker.io": { "UserName": "...", "Password": "..." }, "your.custom.registry": { "UserName": "...", "Password": "..." } } ``` 上記の形式に従って、他のレジストリの設定をカスタマイズできます。`UserName` と `Password` フィールドは必須です。 :::info パスワードに特殊文字（`":@`など、ただし`_`は使用可能）が含まれていないことを確認してください。そうでないと、テンプレートインジェクションの問題が発生し、Secret の作成に失敗する可能性があります。 ::: ### CaptchaConfig ここでは、キャプチャ関連の情報を設定します。これは、登録、アカウントの回復、ログイン時のキャプチャの検証に使用されます。オプションです。 - **Provider:** キャプチャのプロバイダ。`None`、`HashPow`または`CloudflareTurnstile`を選択できます。 - **SiteKey:** キャプチャの Sitekey - **SecretKey:** キャプチャの Secretkey :::tip 安全性を確保し、プラットフォームが悪意のある登録やメールのクォータ消費などの問題に巻き込まれないようにするため、キャプチャ機能の有効化を強くお勧めします。 `CloudflareTurnstile` キャプチャプロバイダーの使用を推奨します。[関連文書](https://www.cloudflare.com/application-services/products/turnstile/)。 ::: #### HashPow HashPow キャプチャの関連情報を設定します。オプションです。 :::info **安全なコンテキスト**: この機能は[安全なコンテキスト](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts)（HTTPS）でのみ利用できます。 ::: - **Difficulty:** HashPow キャプチャの難易度。ハッシュビットの先頭にあるゼロの数を指定するために使用されます。利用可能な範囲は 8 から 48 です。 #### GoogleRecaptcha :::warning **v1.2.2 で削除されました。** 上流依存関係のメンテナンス不足のため、Google ReCaptcha のサポートは削除されました。 代わりに `CloudflareTurnstile` CAPTCHA プロバイダをご利用ください。 ::: ### ForwardedOptions ここでは、リバースプロキシの関連情報を設定します。これは、実際の IP アドレスを取得するために使用されます。オプションです。 - **ForwardedHeaders:** リバースプロキシが転送するヘッダーの列挙型。デフォルトは`7`を使用してください。詳細は [ForwardedHeaders 列挙型](https://learn.microsoft.com/ja-jp/dotnet/api/microsoft.aspnetcore.httpoverrides.forwardedheaders)を参照してください。 - **ForwardLimit:** リバースプロキシの層数制限 - **ForwardedForHeaderName:** リバースプロキシの IP アドレスヘッダー名 - **KnownIPNetworks:** リバースプロキシが信頼するネットワークのリスト。CIDR で表現します。 - **KnownProxies:** リバースプロキシが信頼するプロキシのリスト。IP アドレスまたはドメイン名で表現します。 :::info リバースプロキシの信頼リストを無視し、任意の IP アドレスからのアクセスを許可したい場合は、[Linux および非 IIS のリバース プロキシのスキームを転送する](https://learn.microsoft.com/ja-jp/aspnet/core/host-and-deploy/proxy-load-balancer#forward-the-scheme-for-linux-and-non-iis-reverse-proxies)を参照し、環境変数`ASPNETCORE_FORWARDEDHEADERS_ENABLED`を`true`に設定してください。 ::: 他のフィールドについては、公式ドキュメントの説明を参照してください：[プロキシ サーバーとロード バランサーを使用するために ASP.NET Core を構成する](https://learn.microsoft.com/ja-jp/aspnet/core/host-and-deploy/proxy-load-balancer)および[ForwardedHeadersOptions クラス](https://learn.microsoft.com/ja-jp/dotnet/api/microsoft.aspnetcore.builder.forwardedheadersoptions) ### Kestrel :::warning ほとんどの場合、Kestrel の設定を変更する必要はありません。 Kestrel は GZCTF が内蔵して使用している Web サーバーです。 この設定を利用すると、HTTP プロトコルを指定したり、リクエストのサイズ上限を変更したりと、Kestrel の動作を自由に制御することができます。 他の設定フィールドについては、公式ドキュメントの`KestrelServerOptions`クラスの属性を参照してください：[KestrelServerOptions クラス](https://learn.microsoft.com/ja-jp/dotnet/api/microsoft.aspnetcore.server.kestrel.core.kestrelserveroptions)。 :::