> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Guard

치트 방지·WAF·차단 정책 기능




GS2-Guard는 GS2의 API 엔드포인트에 대한 접근을 보호하기 위한 기능을 제공합니다.
특정 국가나 지역, IP 주소, 익명화된 IP, 호스팅 사업자의 IP, 평판이 나쁜 IP 등 다양한 조건으로 발신지를 판정하여, API 요청을 허용·거부하는 구조를 구축할 수 있습니다.

부정 이용이나 치트 행위, 공격적인 트래픽으로부터 게임 서버를 지키기 위한, 이른바 게임 전용 경량 WAF(Web Application Firewall)로 기능합니다.

GS2-Guard는 게임 클라이언트에서 직접 이용하는 기능이 아니라, 운영 측에서 차단 정책을 정의하고 다른 GS2 마이크로서비스의 API에 적용하기 위한 구조입니다.

## 차단 정책

GS2-Guard의 네임스페이스에는 `BlockingPolicyModel`을 1개 설정할 수 있으며, 여기에 접근 제어 규칙을 기술합니다.
GS2의 각 마이크로서비스의 네임스페이스에서 대상 GS2-Guard 네임스페이스를 참조함으로써, 해당 마이크로서비스에 대한 API 요청에 차단 정책이 적용됩니다.

차단 정책에서 설정할 수 있는 주요 항목은 다음과 같습니다.

- 기본 제한 (defaultRestriction): 기본적으로 API 요청을 허용할지 거부할지
- 예외적으로 허용할 서비스 (passServices): 제한을 적용하지 않을 GS2 서비스명 목록
- 지리적 제한 (locationDetection / locations / locationRestriction): 요청 발신지의 국가·지역을 판정하여, 특정 국가·지역만 허용·거부
- 익명 IP 제한 (anonymousIpDetection / anonymousIpRestriction): Tor 출구 노드나 VPN 등, 익명화 서비스를 경유한 요청을 판정하여 허용·거부
- 호스팅 사업자 IP 제한 (hostingProviderIpDetection / hostingProviderIpRestriction): 클라우드 사업자 등 호스팅에서 유래한 IP의 요청을 판정하여 허용·거부
- 평판이 나쁜 IP 제한 (reputationIpDetection / reputationIpRestriction): 공격의 발판으로 알려지는 등 평판이 나쁜 IP의 요청을 판정하여 허용·거부
- 개별 IP 주소 제한 (ipAddressesDetection / ipAddresses / ipAddressRestriction): 임의의 IP 주소·CIDR 범위를 지정하여 허용·거부

```mermaid
graph LR
  Client["게임 클라이언트"] -- API 요청 --> Guard["GS2-Guard<br/>(차단 정책 판정)"]
  Guard -- 허용 --> Microservice["다른 GS2 마이크로서비스"]
  Guard -- 거부 --> Block["403 / 접근 거부"]
```

### 검출과 제한의 분리

각 검출 조건(Detection)은 "비활성"과 "활성" 중 하나를 가지며, 검출 조건이 활성인 경우 "대응하는 제한(Restriction)"이 적용됩니다.
이를 통해 검출만 수행하여 로그에 남겨두고, 한동안 상황을 확인한 후에 본격적으로 거부를 활성화하는 등의 단계적인 운영이 가능합니다.

### 기본 동작과 화이트리스트 / 블랙리스트의 구분 사용

`defaultRestriction`을 "허용"으로 설정한 후 개별 판정 조건에서 "거부"를 조합함으로써 블랙리스트형 정책을 구축할 수 있습니다.
반대로 `defaultRestriction`을 "거부"로 설정한 후 `passServices`나 `ipAddresses`로 예외를 허용함으로써 화이트리스트형 정책을 구축할 수 있습니다.

## 다른 마이크로서비스에 대한 적용

GS2-Guard는 단독으로 사용하는 서비스가 아니라, 다른 마이크로서비스의 네임스페이스에서 참조되어야 비로소 효과를 발휘합니다.
각 마이크로서비스의 네임스페이스 설정에서 GS2-Guard의 네임스페이스를 지정하면, 해당 네임스페이스로 향하는 API 요청에 설정된 차단 정책이 적용됩니다.

여러 마이크로서비스에서 동일한 GS2-Guard 네임스페이스를 참조함으로써 횡단적으로 접근 제어를 통일할 수 있습니다.

## 트랜잭션 액션

GS2-Guard에서는 트랜잭션 액션을 제공하지 않습니다.

## 마스터 데이터 관리

GS2-Guard는 GS2에서 일반적인 "마스터 데이터 임포트/익스포트"가 아니라, 네임스페이스 자체의 설정으로 차단 정책을 보유합니다.
차단 정책은 관리 콘솔에서 설정하는 것 외에도, GS2-Deploy를 사용해 CI에서 등록하는 워크플로우를 구성할 수도 있습니다.

차단 정책 등록의 YAML 예시는 다음과 같은 형태입니다.

```yaml
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
```

## 구현 예제

GS2-Guard는 관리 API 중심의 마이크로서비스입니다. 게임 엔진용 SDK(Unity / Unreal Engine / Godot)에는 전용 Domain 클래스가 제공되지 않습니다.

네임스페이스의 생성·취득이나 차단 정책 설정과 같은 조작은 게임 클라이언트에서 직접 호출하는 것이 아니라, 다음 중 하나의 수단으로 조작하는 것을 권장합니다.

- 관리 콘솔
- GS2 CLI
- 각종 언어용 일반 SDK (C# / Go / Python / TypeScript / PHP / Java)
- GS2-Deploy를 통한 템플릿 관리

각 SDK의 상세 내용은 해당 레퍼런스 페이지를 참조하십시오.

## 더 실무적인 정보

### 단계적인 정책 도입

새롭게 차단 정책을 도입할 때, 처음부터 모든 항목을 거부로 설정하면 예상치 못하게 정상적인 플레이어를 차단해 버릴 우려가 있습니다.
처음에는 검출만 활성화하여 로그로 영향 범위를 확인한 후, 단계적으로 거부 설정으로 전환해 나가는 운영이 권장됩니다.

### 서비스별 예외 설정

`passServices`를 활용하면 특정 GS2 마이크로서비스에 대해서는 차단 정책을 적용하지 않는 등의 예외 설정이 가능합니다.
예를 들어 로그인 처리나 버전 체크는 엄격한 IP 제한을 완화해 두고, 과금이나 랭킹처럼 부정의 영향이 큰 API에만 엄격한 정책을 적용하는 등의 운영이 가능합니다.

## 상세 레퍼런스

[GS2-Guard API 레퍼런스](../../api_reference/guard)