60090 - pacman (Schulungsobjekt) — Hintergründe
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/6-hintergruende/60090-pacman-schulungsobjekt.md
pacman (Schulungsobjekt) — Hintergründe
Begründungen zu argocd/apps/tech/pacman/ (Go-Server, Frontend-Skripte, Chart). pacman ist ein Pacman-Canvas-Fork, der in der IT-Security-Schulung zeigt, was ein Webserver über
einen Besucher herausfinden kann, mit einem Grafana-Dashboard als „Auflösung“. Zweck, Ablauf und Offenlegung stehen in
300f0 und im README des Charts. Hier stehen die Implementierungsentscheidungen.
Übersicht dieser Kategorie: 60000.
Rahmen: Die Erhebung von Besucherdaten ist ausschließlich für den abgegrenzten Schulungskontext mit informierten, einverstandenen Teilnehmenden gedacht, die vorher mündlich aufgeklärt
werden. Das Trainingsmodus-Flag ist deshalb standardmäßig aus.
Server (Go)
Auslieferung und Vendoring
Der Server liefert die vendorten Pacman-Canvas-Assets aus und schreibt je Request eine strukturierte JSON-Zeile (Client-IP, User-Agent und, falls eine MMDB-Geo-Datenbank gemountet ist, den
aufgelösten Standort). Änderungen am vendorten Spiel werden nicht in dessen Dateien vorgenommen, sondern im Server, damit ein erneutes Vendoring vom Upstream ein sauberer Diff bleibt statt
eines Merge-Konflikts:
serveStaticschreibt/aufindex.htmum. Der vendorte Quellcode liefertindex.htm, nichtindex.html, und Goshttp.FileServererkennt einen impliziten Verzeichnis-Index nur unter dem Namen
.html. Ohne die Umschreibung fiele/auf das Verzeichnislisting des FileServers statt auf das Spiel.serveIndexWithFingerprintinjiziert das<script>-Tag fürfingerprint.jsund das Flagwindow.PACMAN_TRAINING_MODEinindex.htm, statt das vendorte HTML zu editieren.- Der Trainingsmodus (
TRAINING_MODE,trainingMode.enabled) wird serverseitig gerendert und nicht clientseitig entschieden. So wirkt er für jeden Besucher konsistent und ist kein clientseitiger Schalter,
den ein neugieriger Besucher per Devtools umlegen könnte. handleLeaderboardersetzt das ursprünglichedata/db-handler.phpdes Spiels (PHP, wurde in diesem reinen Go-Setup nie ausgeliefert).
Bestenliste
- Nur im Speicher. Es ist keine PVC gemountet (
readOnlyRootFilesystem: true), und der Server kann mit 1–3 Replicas hinter einem einfachen ClusterIP-Service ohne Session-Affinity laufen. Die Einträge sind daher
pro Pod: Eine Einreichung kann auf einem anderen Pod landen als ein späteres Listing, ein Scale-Down oder Neustart verwirft alles. Für dieses Schulungs-/Demo-Spiel akzeptabel und im README dokumentiert,
statt es mit geteiltem Speicher zu lösen. - Die Seitengröße (10) spiegelt das
LIMIT 10des altendb-handler.php.maxLeaderboardEntriesbegrenzt den Speicherverbrauch, da nur die Top-Scores je ausgeliefert werden. maxPointsPerLevelspiegeltvalidateScoreWithLevel()inpacman-canvas.js(104 Pillen + 4 Powerpillen + 4 Geister je Fright-Zyklus, mal 4 Geister) und wird manuell synchron gehalten. Beide Seiten sind
dieselbe Anti-Cheat-Grenze, unabhängig angewendet: der Client für die UX, der Server, weil man dem Client nicht trauen kann.nicknamePatternakzeptiert nur die vonnickname.jserzeugten Tags<NAME>-<HEX4>und weist alles andere ab, damit die öffentliche Bestenliste nicht zum Ablegen beliebiger Strings taugt. Der eingegebene
Klarname erreicht diesen Endpunkt nie, nur das abgeleitete Tag.
Zugriffslog
- Je Request eine Zeile
http_access, getrennt davon je Seitenaufruf eine Zeileclient_fingerprint(POST vonfingerprint.js). In Grafana lassen sich beide überremote_ip(und grob über die Zeit)
korrelieren. clientIPliefert die echte Besucher-IP (v4 oder v6). Cloudflare setztCF-Connecting-IPam Edge als einzelnen, verbindlichen Wert, bevor der Request den Cluster erreicht, anders als
X-Forwarded-For, das eine mehrstufige Kette tragen kann. Fallback ist der ersteX-Forwarded-For-Eintrag, dann die rohe TCP-Gegenstelle. Beide Header gelten nur, wenn die TCP-Gegenstelle inTRUSTED_PROXY_CIDRSliegt (Pod-CIDR10.42.0.0/16, dahinter sitzt Traefik) und der Wert eine gültige IP ist; sonst wäre die IP im Log und im GeoIP-Lookup für jeden Absender fälschbar. Restlücke: Traefik reichtCF-Connecting-IPungeprüft durch, wer Traefik direkt im LAN anspricht, kann die IP weiter setzen.- Timeouts und Rate-Limit. Der Server läuft mit
ReadHeaderTimeout5 s,ReadTimeout10 s,WriteTimeout15 s undIdleTimeout60 s (vorherhttp.ListenAndServeohne Timeouts, Slowloris-anfällig)./api/fingerprintund/api/leaderboardhaben ein Rate-Limit je Client-IP (Fixed-Window,RATE_LIMIT_PER_MINUTE, Standard 60, danach429mitRetry-After), damit keine Log-Flutung in VictoriaLogs möglich ist. Der Zähler liegt im Speicher des Pods, höchstens 10.000 Schlüssel; ist die Tabelle voll, werden neue Clients abgewiesen, bis Fenster ablaufen. Das von Cloudflare am Edge ermittelte Land dient als unabhängige
Gegenprobe zum lokalen DB-IP-GeoIP-Lookup. - Alle Header-Felder sind passive Request-Header-Erfassung, ohne dass der Besucher etwas tun muss: Browser/OS per Client Hints, Content-Negotiation, Fetch-Kontext und die Opt-out-Signale selbst
(DNT/GPC). Dass ein Header „don’t track me“ im Log landet, ist selbst Teil der Aussage der Demo. parseUserAgentist bewusst einfaches, geordnetes Substring-Matching, keine UA-Parser-Bibliothek, für die Standardbrowser reicht das im Klassenraum. Die Reihenfolge ist entscheidend:- Fast jeder UA behauptet, mehrere Browser zu sein (Edge und Opera enthalten aus Kompatibilität
Chrome/undSafari/), deren eigene Marker müssen zuerst geprüft werden. - iPhone-/iPad-UAs enthalten
like Mac OS X, iOS muss vor dem einfachenMac OS Xgeprüft werden, sonst würde jedes iPhone als macOS gemeldet. - Android-UAs enthalten ebenfalls
Linux, Android muss zuerst geprüft werden.
- Fast jeder UA behauptet, mehrere Browser zu sein (Edge und Opera enthalten aus Kompatibilität
- Browser und OS werden serverseitig aus dem
user_agentgeparst, damit Grafana sie als eigene Tabellenspalten zeigen kann, statt dass jeder den einen rohen User-Agent lesen muss.
GeoIP
Quelle ist DB-IP City Lite (db-ip.com, CC BY 4.0): kostenlos, kein Account und kein Lizenzschlüssel, monatlicher Direct-Download (siehe README). Standardmäßig an, weil das der Zweck der App ist. Schlägt der
Download trotzdem fehl, läuft der Server weiter und loggt nur die rohe IP.
Trainingsmodus
trainingMode.enabled koppelt das Namensfeld im Nickname-Overlay an dieselbe versteckte Autofill-Ernte (E-Mail, Telefon, Adresse, PLZ), die fingerprint.js für die eigene Ecke nutzt. Standard ist aus.
- Achtung: Der Host ist über
ingress.hostsöffentlich ohne Auth und ohne IP-Allowlist erreichbar (pacman-prod.pke-lab.de).enabled: truewirkt serverseitig für jeden Request auf/,
nicht nur für eine informierte, freiwillig teilnehmende Gruppe, sondern für jeden, der die URL in diesem Zeitraum aufruft (Suchmaschinen-Crawler, alte Links, zufällige Besucher eingeschlossen). - Deshalb nur für die Dauer der jeweiligen Unterrichtsstunde aktivieren und danach wieder auf
falsesetzen (neues Chart-Release, siehe README). Der Serverstart loggt beienabled: true
zusätzlich eine Warnzeile („training mode ENABLED“) als Erinnerung.
Frontend
fingerprint.js
Clientseitige Erfassung für die Schulungsdemo. Sie ist nicht Teil des vendorten pacman-canvas-Spiels, sondern von uns ergänzt und serverseitig eingebunden. Sie liest ausschließlich Browser-APIs, auf die
eine Seite ohne jede Berechtigungsabfrage zugreifen kann. Geolocation, Kamera und Mikrofon werden bewusst nicht verwendet: Sie zeigen einen sichtbaren Browser-Dialog, was den Punkt „niemand bemerkt es“
der Demo zunichtemachen würde.
- Hash: FNV-1a mit 32 Bit ist schnell, synchron und braucht keinen WebCrypto-Roundtrip. Er ist nicht kryptografisch, muss nur unterscheidbare Eingaben unterscheiden, und mehr braucht ein Fingerprint nicht.
harvestAutofillist die eine bewusst invasivere Technik: ein echtes, sichtbares Feld („Name für die Bestenliste“, ein plausibles Spiel-UX-Element) im selben<form>wie unsichtbare
E-Mail-/Telefon-/Adressfelder. Ein vollständig unsichtbares Köder-Formular funktioniert gegen modernes Chrome nicht: Das Befüllen eines Felds aus einem gespeicherten Profil erfordert einen echten Klick des
Nutzers auf den Autofill-Vorschlag, den JavaScript nicht auslösen kann. Chrome füllt aber alle passenden Felder eines Formulars gemeinsam, sobald der Nutzer einen Vorschlag annimmt, die versteckten Felder
fahren also mit. Das entspricht der Funktionsweise echter täuschender Formulare (ein glaubwürdig aussehendes Einzelfeld verbirgt ein größeres Formular) und wird danach offengelegt.- Die versteckten Felder liegen außerhalb des sichtbaren Bereichs (off-screen, Größe 0 und
opacity:0), nicht mitdisplay:none/visibility:hidden: Manche Browser schließen solche Felder vom Autofill
komplett aus. Der Besucher bekommt eine echte Chance, den Dialog zu bemerken, mit dem Namensfeld zu interagieren (das ist es, was Chromes Autofill-Dropdown auslöst) und abzusenden oder zu ignorieren,
bevor die Werte in jedem Fall eingesammelt und entfernt werden. - Zwei getrennte Wege: Das Widget in der Ecke erntet unbedingt, unabhängig vom Trainingsmodus-Flag. Das Namensfeld der Bestenliste (siehe unten) nutzt denselben Trick nur bei
window.PACMAN_TRAINING_MODE === true.
nickname.js (Bestenlisten-Identität)
- Beim ersten Besuch fragt ein Overlay (
#nickname-overlay) nach einem Anzeigenamen, mit einem echten, einzelnen<input name="name" autocomplete="name">mit echter Browser-Autofill-Unterstützung. - Der eingegebene Name verlässt den Browser nie. Er erzeugt und speichert nur ein pseudonymes Tag
<NAME>-<HEX>, das Einzige, waspacman-canvas.jsan die öffentliche/api/leaderboardschickt. Das Tag ist
mit Zeit und Zufall gesalzen, damit derselbe Name zweimal (verschiedene Personen oder dieselbe Person nach einem Reset) auf der gemeinsamen öffentlichen Bestenliste nicht kollidiert. Der Hash ist derselbe
FNV-1a wie infingerprint.js. - Im Trainingsmodus verdrahtet dasselbe sichtbare Namensfeld die versteckte Autofill-Ernte. Was dort eingesammelt wird, geht an
/api/fingerprint(nur Server-Log, getrennte Pipeline, dieselbe Log-Zeile
client_fingerprintwie die Ernte der Ecke, korrelierbar in Grafana) und taucht nie im Nickname oder auf der Bestenliste auf.ajax_add()inpacman-canvas.jsschickt nur das Nickname-Tag an
/api/leaderboard, diese Daten berühren diesen Endpunkt nie. - Das Tag und das Konfigurationsobjekt werden für
pacman-canvas.js(Game-Over-Einreichung) und den Link „Namen ändern“ im Info-Panel bereitgestellt.