GS2-Guard

Cheat prevention, WAF, and blocking policy feature

GS2-Guard provides the ability to protect access to GS2 API endpoints. It allows you to determine the request source by various conditions such as country or region, IP address, anonymous IP, IP of hosting providers, and IPs with bad reputation, and to allow or deny API requests accordingly.

It functions as a kind of lightweight WAF (Web Application Firewall) for games, protecting the game server from misuse, cheating, and abusive traffic.

GS2-Guard is not a feature used directly from the game client; it is a mechanism for operators to define blocking policies and apply them to APIs of other GS2 microservices.

Blocking Policy

A BlockingPolicyModel can be configured per namespace in GS2-Guard, where the access control rules are described. By referencing the target GS2-Guard namespace from the namespace of each GS2 microservice, the blocking policy is applied to API requests to that microservice.

The main items that can be configured in a blocking policy are as follows.

  • Default restriction (defaultRestriction): Whether to allow or deny API requests by default.
  • Pass services (passServices): List of GS2 service names exempt from the restrictions.
  • Geographic restriction (locationDetection / locations / locationRestriction): Determines the source country / region of the request, and allows or denies specific countries / regions.
  • Anonymous IP restriction (anonymousIpDetection / anonymousIpRestriction): Determines requests from anonymizing services such as Tor exit nodes or VPNs, and allows or denies them.
  • Hosting provider IP restriction (hostingProviderIpDetection / hostingProviderIpRestriction): Determines requests from hosting-origin IPs such as cloud providers, and allows or denies them.
  • Bad reputation IP restriction (reputationIpDetection / reputationIpRestriction): Determines requests from IPs with bad reputation, such as those known to be used as attack relays, and allows or denies them.
  • Individual IP address restriction (ipAddressesDetection / ipAddresses / ipAddressRestriction): Specifies arbitrary IP addresses or CIDR ranges to allow or deny.
graph LR
  Client["Game Client"] -- API Request --> Guard["GS2-Guard<br/>(Blocking Policy Evaluation)"]
  Guard -- Allow --> Microservice["Other GS2 Microservice"]
  Guard -- Deny --> Block["403 / Access Denied"]

Separation of detection and restriction

Each detection condition (Detection) takes either “disabled” or “enabled”, and when the detection condition is enabled, the corresponding restriction is applied. This enables phased operation, such as initially performing only detection and recording it to logs, then later enabling actual denial after observing the situation for a while.

Default behavior and whitelist / blacklist usage

By setting defaultRestriction to “Allow” and combining “Deny” in individual conditions, you can build a blacklist-style policy. Conversely, by setting defaultRestriction to “Deny” and allowing exceptions with passServices or ipAddresses, you can build a whitelist-style policy.

Application to other microservices

GS2-Guard is not a service to be used by itself; it takes effect only when it is referenced from namespaces of other microservices. By specifying the GS2-Guard namespace in the namespace settings of each microservice, the configured blocking policy is applied to API requests destined for that namespace.

By referencing the same GS2-Guard namespace from multiple microservices, access control can be unified across services.

Transaction Actions

GS2-Guard does not provide transaction actions.

Master Data Management

GS2-Guard does not use the typical GS2 “master data import/export”; instead, the blocking policy is held as part of the namespace’s own settings. The blocking policy can be configured via the management console, or registered from CI using GS2-Deploy.

A YAML example for registering a blocking policy is as follows.

blockingPolicy:
  defaultRestriction: Allow
  passServices:
    - account
    - version
  locationDetection: Enable
  locations:
    - JP
  locationRestriction: Deny
  anonymousIpDetection: Enable
  anonymousIpRestriction: Deny
  hostingProviderIpDetection: Enable
  hostingProviderIpRestriction: Deny
  reputationIpDetection: Enable
  reputationIpRestriction: Deny
  ipAddressesDetection: Enable
  ipAddresses:
    - 203.0.113.0/24
  ipAddressRestriction: Deny

Example Implementation

GS2-Guard is a microservice centered on management APIs. No dedicated Domain class is provided in the game engine SDKs (Unity / Unreal Engine).

Operations such as creating and retrieving namespaces and configuring blocking policies are not intended to be called directly from the game client; we recommend operating via one of the following means.

  • Management console
  • GS2 CLI
  • General-purpose SDKs for various languages (C# / Go / Python / TypeScript / PHP / Java)
  • Template management via GS2-Deploy

For details on each SDK, see the corresponding reference page.

More practical information

Phased policy rollout

When introducing a new blocking policy, immediately setting all items to “Deny” can lock out legitimate players unexpectedly. A recommended approach is to first enable detection only, review the impact from the logs, and then gradually switch over to deny settings.

Per-service exceptions

By using passServices, you can apply exceptions such as not applying the blocking policy to specific GS2 microservices. For example, you can relax strict IP restrictions for login and version check processes, and apply a strict policy only to APIs such as billing and ranking where the impact of fraud is high.

Detailed Reference

Reference of GS2-Guard