#appsettings.json 配置

appsettings.json 文件是 GZCTF 的核心配置文件，通过挂载入容器内的方式进行配置。本篇将介绍配置文件的各个字段的含义。

#配置文件结构

此处给出一个完整的配置文件示例：

{
  "AllowedHosts": "*",
  "ConnectionStrings": {
    "Database": "Host=db:5432;Database=gzctf;Username=postgres;Password=<Database Password>"
    // redis is optional
    // "RedisCache": "cache:6379,password=<Redis Password>",
    // external storage (minio s3, aws s3, azure blob) is optional, aws s3 for example
    // "Storage": "minio.s3://keyId=<YOUR_KEY_ID>;key=<YOUR_KEY>;bucket=<YOUR_BUCKET>;region=<YOUR_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,
      "Port": 3000,
      "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": "<Random Key Str>",
  "ContainerProvider": {
    "Type": "Docker", // or "Kubernetes"
    "PortMappingType": "Default",
    "EnableTrafficCapture": false,
    "PublicEntry": "ctf.example.com", // or "xxx.xxx.xxx.xxx"
    "DockerConfig": {
      // optional
      "SwarmMode": false,
      "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,
  "RegistryConfig": {
    "UserName": "",
    "Password": "",
    "ServerAddress": ""
  },
  "CaptchaConfig": {
    "Provider": "None",
    "SiteKey": "...",
    "SecretKey": "...",
    // optional
    "GoogleRecaptcha": {
      "VerifyAPIAddress": "https://www.recaptcha.net/recaptcha/api/siteverify",
      "RecaptchaThreshold": "0.5"
    },
    // 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
    "TrustedNetworks": ["10.0.0.0/8"],
    "TrustedProxies": ["10.0.0.1"]
  },
  "Kestrel": {
    "Endpoints": {
      "Web": {
        "Url": "http://*:8080"
      },
      "Prometheus": {
        "Url": "http://*:3000"
      }
    },
    "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 作为后端数据库和数据持久化。

此连接字符串的一般格式为:

请将 <Database Password> 替换为你的 PostgreSQL 数据库密码 (通常是通过 POSTGRES_PASSWORD 环境变量设置)

更多参数可以参考 Npgsql 连接字符串参数文档

#RedisCache

可选参数。

GZCTF 使用 Redis 作为缓存和消息队列。单实例部署的情况下 Redis 不是必须的，可以直接采用 GZCTF 的内存缓存；多实例部署的情况下，Redis 是必须的，用作共享缓存和 SignalR 的 Scale-Out 广播。

在 v1.0 后支持使用 Garnet 作为缓存服务。

#Storage

可选参数。

GZCTF 支持使用外部存储，如 AWS S3、Azure Blob 等。GZCTF 会将所有文件存储在外部存储。

我们支持以下格式，他们所对应的 ConnectionString 格式如下：

• MinIO S3

  minio.s3://keyId=...;key=...;bucket=...;region=...;serviceUrl=...

  • keyId：可选。Access Key ID
  • key：可选。Secret Access Key
  • bucket：Bucket 名称
  • region：区域 (例如 us-east-1)
  • serviceUrl：MinIO 服务的地址

• AWS S3

  aws.s3://keyId=...;key=...;bucket=...;region=...

  • keyId：可选。Access Key ID
  • key：可选。Secret Access Key
  • bucket：Bucket 名称
  • region：区域 (例如 us-east-1)
  • serviceUrl：可选。兼容 S3 的服务的地址

• Azure Blob

  azure.file://account=...;key=...

  详细可以参考 快速入门：适用于 .NET 的 Azure Blob 存储客户端库

更多详细内容，请查阅：

• AWS: https://github.com/robinrodricks/FluentStorage/wiki/AWS-S3-Storage, https://github.com/robinrodricks/FluentStorage/wiki/MinIO-Storage
• Azure.Blobs: https://github.com/robinrodricks/FluentStorage/wiki/Azure-Blob-Storage

如果你需要更多 FluentStorage 的 Provider，请提交 Issue 说明。

#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: 是否启用。
  • Port: 可选。Prometheus /metrics 的监听端口。如果配置了此项，需要额外手动配置 Kestrel.Endpoints 以使得服务器正常监听指定的端口。
  • TotalNameSuffixForCounters: 可选。是否在计数器中包含 _total 后缀。

• OpenTelemetry：将测量和追踪数据导出到 OpenTelemetry。

  • Enable：是否启用。
  • Protocol：Grpc 或 HttpProtobuf。
  • EndpointUri：将数据推送到的 OpenTelemetry 地址。

• AzureMonitor：将测量和追踪数据导出到 ApplicationInsights。

  • Enable：是否启用。
  • ConnectionString：连接字符串。

• Console：将追踪数据导出到控制台。

  • Enable：是否启用。

#EmailConfig

此处配置邮件发送相关信息，若采用邮箱注册和其他相关邮件功能，此处为必填项。

• SenderAddress: 发件人邮箱地址
• SenderName: 发件人名称
• UserName: SMTP 服务器用户名
• Password: SMTP 服务器密码
• Smtp: SMTP 服务器地址和端口
• BypassCertVerify: 是否跳过证书验证

#XorKey

此处配置加密密钥，用于加密数据库中比赛的私钥信息，可为任意长度的任意字符串。

#ContainerProvider

此处配置容器后端，为比赛动态创建容器的必填项。

• Type: 容器后端类型，可选 Docker 或 Kubernetes。
• PublicEntry: 容器后端的公网地址，用于生成比赛的访问地址，展示给参赛队伍。
• PortMappingType: 端口映射类型，可选 Default 或 PlatformProxy。
• EnableTrafficCapture: 是否开启流量捕获，仅在 PortMappingType 设置为 PlatformProxy 时可用。若开启，将会记录流量于 /app/files/capture 目录下。

#Docker

• SwarmMode: 是否为 Swarm 模式，若为 Swarm 模式，将会使用 Swarm API 进行管理。

• Uri: Docker API Server 地址

  • 如需使用本地 docker，请将 Uri 置空，并将 /var/run/docker.sock 挂载入容器对应位置
  • 如需使用外部 docker，请将 Uri 指向对应 docker API Server，外部 API 鉴权尚未实现，不推荐此部署方式

• ChallengeNetwork: 指定题目容器所在的网络，若不指定，将会使用默认网络。

• 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 目录下。实验功能若非了解行为请勿更改。

#RequestLogging

此处配置是否开启请求日志记录，若开启，将会在日志中输出每个请求的详细信息。此处输出不包括静态文件的请求。

#DisableRateLimit

此处配置是否开启请求频率限制，若开启，将会根据预设规则限制每个 IP 和 API 的请求频率。

#RegistryConfig

此处配置 Docker Registry 的用户名和密码，用于比赛动态创建容器时拉取镜像的验证，可选项。

• UserName: Docker Registry 用户名
• Password: Docker Registry 密码
• ServerAddress: Docker Registry 地址，请注意不需要包含 https:// 前缀

#CaptchaConfig

此处配置验证码相关信息，用于注册、找回账号和登录时的验证码验证，可选项。

• Provider: 验证码提供商，可选 None、HashPow、GoogleRecaptcha 或 CloudflareTurnstile
• SiteKey: 验证码 Sitekey
• SecretKey: 验证码 Secretkey

#HashPow

配置 HashPow 验证码的相关信息，可选项。

• Difficulty: HashPow 验证码的难度，用于指定哈希二进制前导零位数，范围为 8 至 48。

#GoogleRecaptcha

配置 Google Recaptcha v3 的相关信息，可选项。

• VerifyAPIAddress: Google Recaptcha 验证 API 地址
• RecaptchaThreshold: Google Recaptcha 阈值，用于判断验证码是否有效

#ForwardedOptions

此处配置反向代理的相关信息，用于获取真实 IP 地址，可选项。

• ForwardedHeaders: 反向代理转发的标头枚举，默认请使用 7，详情请见 ForwardedHeaders 枚举
• ForwardLimit: 反向代理层数限制
• ForwardedForHeaderName: 反向代理 IP 地址头名称
• TrustedNetworks: 反向代理信任的网络列表，使用 CIDR 表示
• TrustedProxies: 反向代理信任的代理列表，使用 IP 地址或域名表示

其他字段请参考官方文档描述：配置 ASP.NET Core 以使用代理服务器和负载均衡器 及 ForwardedHeadersOptions 类

#Kestrel

Kestrel 为 GZCTF 自带并使用的 Web 服务器。利用此配置可以自行控制 Kestrel 的行为，例如指定 HTTP 协议、修改请求大小上限等等。

• Endpoints: Web 服务器监听的 URL。也可以通过环境变量或启动参数来配置，具体参考 为 ASP.NET Core Kestrel Web 服务器配置终结点。
• 其他的可配置字段请参照官方文档中 KestrelServerOptions 类的属性: KestrelServerOptions 类