feature: game validator

Author: lukepolo

.dockerignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.env
+.git
+gamedata/ccs.gamedata.json

.github/workflows/build.yaml

@@ -0,0 +1,47 @@
+name: Build
+
+on:
+  push:
+    branches:
+      - "main"
+  workflow_dispatch:
+
+jobs:
+  build-push-and-release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and Push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          push: true
+          tags: |
+            ghcr.io/${{ github.repository_owner }}/gamedata-validator:latest
+            ghcr.io/${{ github.repository_owner }}/gamedata-validator:${{ github.sha }}
+          # Registry-backed cache: a dedicated :buildcache tag on ghcr stores
+          # the layer cache across runs (no 10GB GHA-cache ceiling, survives
+          # branch/PR boundaries). First build is a full rebuild; every
+          # subsequent build reuses unchanged layers.
+          cache-from: |
+            type=registry,ref=ghcr.io/${{ github.repository_owner }}/gamedata-validator:buildcache
+          cache-to: |
+            type=registry,ref=ghcr.io/${{ github.repository_owner }}/gamedata-validator:buildcache,mode=max
+
+      - name: Delete Package Versions
+        uses: actions/delete-package-versions@v5
+        with:
+          package-name: gamedata-validator
+          package-type: container
+          min-versions-to-keep: 8
+          ignore-versions: '^buildcache-*'

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.env
+gamedata/ccs.gamedata.json

Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1
+WORKDIR /app
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends libstdc++6 && \
+    rm -rf /var/lib/apt/lists/* && \
+    pip install --no-cache-dir commentjson
+
+COPY lib/s2binlib.so ./lib/s2binlib.so
+COPY main.py s2binlib.py ./
+COPY gamedata ./gamedata
+
+ARG CCS_GAMEDATA_REF=main
+RUN python -c "import urllib.request; urllib.request.urlretrieve('https://raw.githubusercontent.com/roflmuffin/CounterStrikeSharp/${CCS_GAMEDATA_REF}/configs/addons/counterstrikesharp/gamedata/gamedata.json', 'gamedata/ccs.gamedata.json')"
+
+ENTRYPOINT ["python", "main.py"]

README.md

@@ -0,0 +1,58 @@
+# gamedata-validator
+
+Validates the CS2 byte-pattern **signatures** our server plugins rely on against an existing CS2
+install. When Valve ships an update, a signature can silently stop matching — the hook just stops
+firing. This scans the game binaries and reports any signature that no longer resolves.
+
+It runs against a game-server node's already-downloaded install (mounted at
+`/serverdata/serverfiles/game`), so it does **not** download anything and only needs the Linux
+binaries that the node already has.
+
+## What it checks
+
+Two sets, both in [CounterStrikeSharp `gamedata.json`](https://github.com/roflmuffin/CounterStrikeSharp/blob/main/configs/addons/counterstrikesharp/gamedata/gamedata.json)
+format:
+
+- `fivestack` — our own custom signatures (`gamedata/fivestack.gamedata.json`). Mirror of the source
+  of truth in `game-server/gamedata/fivestack.gamedata.json`; keep them in sync.
+- `upstream-ccs` — upstream CounterStrikeSharp gamedata, fetched into `gamedata/ccs.gamedata.json`
+  at image build time.
+
+Only `signatures` entries with a `linux` pattern are scanned (`offsets`-only entries are skipped).
+
+## Result
+
+Prints a single machine-readable line and exits non-zero if any signature does not resolve to
+exactly one match (`count != 1`):
+
+```
+GAMEDATA_VALIDATION_RESULT {"build_id":..., "status":"pass|fail", "broken":[...], "results":[...]}
+```
+
+## Run
+
+```bash
+pip install -r requirements.txt
+python main.py --game-path /path/to/cs2/game        # dir containing csgo/ and bin/
+```
+
+Flags: `--build-id <id>` (label only), `--gamedata name=path` (repeatable) to override the sets.
+
+## Docker
+
+```bash
+docker build -t ghcr.io/5stackgg/gamedata-validator:latest .
+docker run --rm -v /serverdata/serverfiles:/serverdata/serverfiles:ro \
+  ghcr.io/5stackgg/gamedata-validator:latest
+```
+
+`./push-latest.sh` builds and pushes from a local checkout. CI publishes
+`ghcr.io/5stackgg/gamedata-validator:latest` on push to `main`.
+
+## Layout
+
+| Path | Purpose |
+| --- | --- |
+| `main.py` | load gamedata → scan the install → report |
+| `s2binlib.py`, `lib/s2binlib.so` | native pattern scanner |
+| `gamedata/fivestack.gamedata.json` | our custom signatures |

gamedata/fivestack.gamedata.json

@@ -0,0 +1,9 @@
+{
+  "FiveStack_ConnectClient": {
+    "signatures": {
+      "library": "engine2",
+      "linux": "55 48 89 E5 41 57 41 56 41 89 CE 41 55 41 54 4D 89 CC 53 48 89 D3 48 81 EC ? ? ? ? 8B 45 20",
+      "windows": "4C 8B CE 8B D3 ? ? ? ?"
+    }
+  }
+}

lib/s2binlib.so

@@ -0,0 +1,60 @@
+import argparse
+import json
+import sys
+from os import path
+
+import commentjson
+import s2binlib
+
+SETS = {
+    "fivestack": "gamedata/fivestack.gamedata.json",
+    "upstream-ccs": "gamedata/ccs.gamedata.json",
+}
+
+
+def load_signatures(file_path):
+    signatures = {}
+    with open(file_path) as f:
+        for name, entry in commentjson.load(f).items():
+            sig = entry.get("signatures") if isinstance(entry, dict) else None
+            lib = sig and (sig.get("library") or sig.get("lib"))
+            if lib and sig.get("linux"):
+                signatures[name] = {"lib": lib, "linux": sig["linux"]}
+    return signatures
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Validate CS2 gamedata signatures against a game install"
+    )
+    parser.add_argument("--game-path", default="/serverdata/serverfiles/game")
+    parser.add_argument("--build-id", type=int, default=None)
+    args = parser.parse_args()
+
+    s2binlib.initialize(args.game_path, "csgo", "linux")
+
+    results = []
+    for set_name, file_path in SETS.items():
+        if not path.exists(file_path):
+            print(f"[skip] missing {file_path}", flush=True)
+            continue
+        for name, sig in load_signatures(file_path).items():
+            _, count = s2binlib.pattern_scan(sig["lib"], sig["linux"])
+            results.append(
+                {"set": set_name, "signature": name, "count": count, "ok": count == 1}
+            )
+
+    broken = [r for r in results if not r["ok"]]
+    result = {
+        "build_id": args.build_id,
+        "status": "fail" if broken else "pass",
+        "broken": broken,
+        "results": results,
+    }
+
+    print("GAMEDATA_VALIDATION_RESULT " + json.dumps(result), flush=True)
+    sys.exit(1 if broken else 0)
+
+
+if __name__ == "__main__":
+    main()

main.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+IMAGE="ghcr.io/5stackgg/gamedata-validator"
+CACHE_REF="${IMAGE}:buildcache"
+SHA="$(git rev-parse HEAD)"
+
+if [ "$#" -gt 0 ]; then
+  TAGS=( "$@" )
+else
+  # shellcheck disable=SC2206
+  TAGS=( ${TAGS:-latest} )
+fi
+
+cd "$(dirname "$0")"
+
+tag_args=()
+for t in "${TAGS[@]}"; do
+  tag_args+=( --tag "${IMAGE}:${t}" )
+done
+tag_args+=( --tag "${IMAGE}:${SHA}" )
+
+echo "building + pushing ${IMAGE} with tags: ${TAGS[*]} ${SHA}"
+docker buildx build \
+  --platform linux/amd64 \
+  --push \
+  "${tag_args[@]}" \
+  --cache-from "type=registry,ref=${CACHE_REF}" \
+  --cache-to "type=registry,ref=${CACHE_REF},mode=max" \
+  .

push-latest.sh

@@ -0,0 +1 @@
+commentjson