TLS-Gate — OZM Admin Audit (Betrieb, Sicherheit, Prüfung)

Gilt für: RC1.0 (App-Version siehe VERSION, Code-Stand siehe BUILD bzw. Kopfzeile von bin/tg-dash) · Stand 2026-10-16
Für wen: alle, die eine TLS-Gate-Instanz aufsetzen, betreiben, prüfen oder wiederherstellen — ohne das Projekt vorher zu kennen.

Dieses Dokument ersetzt docs/SECURITY.md und docs/IDENTITAET.md. Jede Aussage hier ist am Code geprüft; was nicht geprüft ist,
steht als UNKNOWN da. UNKNOWN ist ein gültiger Zustand, kein Fehler und kein Platz für eine Vermutung.

0. In fünf Sätzen

1. TLS-Gate ist eine PHP-Anwendung (Apache 2.4 + PHP-FPM 8.4 + MySQL 8), die SSL-Bestand, Katalog, Buchungen, SOAP- und
   NetBox-Zugänge je Gruppe verwaltet — mit Login (Passwort + TOTP) und einem Audit, das sich nicht ändern lässt.
2. Die Umgebung (Webserver, PHP, MySQL, Zertifikat, root) gehört dem Rechenzentrum. TLS-Gate installiert nichts, es wird mit
   deploy/node/bend.sh auf die vorhandene Umgebung gebogen.
3. Jeder Fehler ist rot und hält an. Nichts geht still weiter.
4. Ein Backup zählt erst, wenn es eingespielt wurde: jeder Snapshot wird vor dem Verpacken probeweise eingespielt.
5. Der Wurzelschlüssel ist das eine Geheimnis, das nie verloren gehen darf und nie rotiert wird, wenn man einen Dump zurückspielt.

1. Die vier Schichten: SOT → UI → bash → cron

Faustregel: Was in der DB steht, gilt. Was die UI zeigt, kommt aus der DB. Was die CLI tut, tut auch die UI (oder umgekehrt), mit
denselben Regeln im selben Code. Der cron schaut nur zu und meldet.

2. Dateien, Pfade, Rechte

Nichts davon liegt im Repo. Die Umgebung der App kommt ausschließlich aus Variablen:

3. Aufsetzen: deploy/node/bend.sh

bend.sh installiert nichts. Es fasst nur an, was der App gehört (App-Baum, state/, Schlüssel, Umgebungsdatei, Inhalt der
eigenen DB). Pool, vhost und cron legt es als Vorlage in den Protokollordner; einsetzen tut sie der Mensch der Umgebung.

MODE=prod SITE=gate.example.org ADMIN_EMAIL=admin@example.org ADMIN_GROUP=ozm deploy/node/bend.sh

3.1 Die Schritte (jeder rot = Abbruch, Protokoll nennt den Schritt)

Erster Lauf auf einer RZ-VM endet bei Schritt 8 rot, solange Pool und vhost fehlen. Das ist gewollt: Vorlagen aus
/root/tlsgate-bend/<zeit>/vorlage-pool.conf, vorlage-vhost.conf, vorlage-cron einsetzen (Passwort aus /root/.tlsgate.env
in den Pool), FPM neu starten, denselben Befehl wiederholen. bend.sh ist idempotent.

3.2 Variablen (Auswahl; vollständig im Kopf von bend.sh)

Was im RZ beim Menschen bleibt und bend.sh nie anfasst: die Apache-Kette (wo TLS terminiert, wer weiterleitet — übernommen werden
nur DocumentRoot <app>/public und die SetHandler-Zeile aus vorlage-vhost.conf), das produktive Zertifikat (nur das vorhandene,
nach Freigabe durch Review und Crew), eine externe MySQL-Instanz (DB_SETUP=skip, dba.sql an den DBA), DNS, Firewall, Monitoring.

deploy/node/build.sh ist kein Weg für das RZ: es installiert Pakete und schreibt Webserver-Konfiguration. Es bleibt nur, um
eine Wegwerf-Node (Container) für Tests zu bauen.

3.3 Review-Dummy (nur MODE=review)

deploy/node/review-dummy.sh legt zwei Gruppen an — bwa (MFA-Modus code) und ozm (MFA-Modus qr) — je sechs Konten
(admin, gadmin, user1, user2, ro, neu ohne MFA) als <kürzel>@<gruppe>.review.test, je Gruppe eigenen Beispielbestand und
eine Buchung aus der Matrix. Klartext-Passwörter und TOTP-Secrets stehen in /root/.tlsgate-review-users.tsv (0600). Nie auf
einer Produktions-Instanz; das Skript verweigert ohne REVIEW_DUMMY=1.

deploy/node/review-check.sh meldet jeden an (Passwort + TOTP über Apache → Pool → DB) und prüft, dass jede Gruppe ihren Bestand
sieht und den der anderen nicht. Wiederholbar: Erst-Login-Konten werden vorher zurückgesetzt, ein im selben 30-s-Fenster schon
benutzter Code wird abgewartet (Replay-Schutz, §8.1).

4. Rollen und Gruppen

Zwei Achsen entscheiden über jeden Zugriff: die Rolle des Kontos und die Art seiner Gruppe — nie der Name der Gruppe.

Rollen in Rangfolge (src/Auth/Auth.php, ROLES): readonly < user < group_admin < admin. Jede Seite verlangt eine
Mindestrolle (Auth::requireLogin); darunter 403, ohne Anmeldung Umleitung auf login.php.

Diese Tabelle ist tests/test_roles.sh: der Test prüft zuerst, dass jede Seite unter public/ darin steht und Mindestrolle,
Methode und SSL-Sperre genau dem Code entsprechen, dann je Rolle in zufällig benannten Gruppen beider Arten jeden Zugriff. Eine
neue Seite ohne Eintrag oder ein geänderter requireLogin ohne Test ist rot.

Regeln, die der Code zusätzlich erzwingt (alle im Test belegt):

• Gruppenart: eigen (eigene Organisation) oder reseller. SSL-Seiten nur für eigen (Auth::sslAllowed).
• admin ist global und gehört nur in eine Gruppe vom Typ eigen; user add … admin in einer Reseller-Gruppe wird abgelehnt.
• Rolle, Gruppe und Aktiv-Status werden bei jedem Request aus der DB gelesen: ein Rollenwechsel, lock oder disable wirkt
  sofort, auch auf laufende Sitzungen.
• MFA-Modus je Gruppe: code (Secret einmal einrichten, dann Codes) oder qr (nach jedem Passwort-Login ein neues Secret).
  Neue Gruppen bekommen TLSGATE_MFA_DEFAULT (Standard qr).
• Buchungen (src/Catalog/Bookings.php): readonly bucht nichts; ein user nur für sich; der Admin der Gruppe für Personen
  seiner Gruppe; Kategorien der Achse „access“ nur für Konten mit Rolle admin. Jede Ablehnung steht mit Grund im Audit.

5. Täglicher Betrieb

Einstieg: bin/tg-dash (als root). Oben steht der Zustand der Instanz — Umgebung, DB, Schema, Integrität, letzter bend.sh-Lauf
— darunter ein Menü. Vor jeder Aktion zeigt das Menü den gleichwertigen Befehl; wer ihn kennt, tippt direkt bin/tg ….
bin/tg-dash status gibt nur den Zustand aus (Exit 1 bei Rot) und taugt für einen schnellen Blick per ssh.

Im Menü (tg-dash 23–30) läuft jeder Abgleich zuerst als Probe (--dry-run); geschrieben wird erst nach „j“. --force (leere oder
stark geschrumpfte Liste trotzdem übernehmen) gibt es dort bewusst nicht — das bleibt eine Entscheidung von Hand. Mehrere Zugänge in
einer Gruppe: TLSGATE_CRED=<label> dazu.

Code ändern heißt immer: Repo aktualisieren, bend.sh laufen lassen. Nur so passen Manifest, BUILD und Schema zusammen.
Eine Datei von Hand in den App-Baum zu legen ist ein Befund des Scans (§6.2) — auch wenn root es war.

Zugänge ohne Token sind normal. SOAP- und NetBox-Zugänge kommen von Menschen, nicht aus einem Skript. Bis dahin stehen sie
in bend.sh und im Dashboard als UNKNOWN. Der Seed legt je Gruppe einen abgeschalteten Platzhalter sample an; er zählt nicht.

6. Prüfen

6.1 Doktor — bin/TLS-node-doktor.bash (nur lesend)

Prüft Voraussetzungen (PHP CLI und FPM), DB (Verbindung, Zeichensatz, Schema-Stand, Rechte des App-Benutzers, Trigger), Dateien
und Rechte (Code nicht schreibbar, state/ und Schlüssel), Integrität gegen das Manifest, Apache (vhost, Module), Pool
(disable_functions inkl. phpinfo, open_basedir, clear_env, Umgebung) und von außen über HTTPS (Header, Cookie, keine
Pfade außerhalb von public/). Exit = Anzahl FAIL. bend.sh ruft ihn in Schritt 8.

6.2 Integrität — bin/TLS-app-scan.bash

Vergleicht den App-Baum mit dem Manifest des letzten bend.sh-Laufs: NEU, GEAENDERT, RECHTE, FEHLT. Abweichung → Ausgabe
(cron schickt sie an MAILTO), Zeile in syslog (logger -t tlsgate-scan, auth.warning), Exit 1, und der Doktor ist rot.
cron-Vorlage: */10 * * * * root APP_DIR=… …/bin/TLS-app-scan.bash -q. Das ist Erkennen, nicht Verhindern (§8.8).

6.3 Tests — tests/run_all.sh

Alle Suiten gegen einen echten MySQL-8-Server, je Suite eine eigene Wegwerf-DB (tests/README.md). Für RC1.0 maßgeblich:
test_roles (Rollen × Gruppenart), test_auth/test_mfa (Login), test_migrate (Migration = frisch), test_secrets,
test_guard, test_credentials, test_katalog.

7. Sichern und Wiederherstellen

Jeder grüne bend.sh-Lauf endet mit /root/tlsgate-bend/<zeit>/tlsgate-snapshot-<host>-<zeit>.zip.enc (AES-256, PBKDF2 600 000).
Inhalt: tlsgate.sql.gz, secrets/root.key, secrets/tlsgate.env, Benutzer-Zugänge, GEHEIMNISSE.md, RESTORE.md, dba.sql,
Vorlagen, Protokoll, SHA256SUMS.

Restore-Probe: Vor dem Verpacken wird der Dump in eine Wegwerf-DB eingespielt und Tabelle für Tabelle (COUNT(*)) plus Trigger
mit der Quelle verglichen. Weicht etwas ab, ist der Lauf rot. Ohne MySQL-Admin-Zugang: UNKNOWN im Snapshot vermerkt.

openssl enc -d -aes-256-cbc -pbkdf2 -iter 600000 -in <datei>.zip.enc -out snap.zip && unzip snap.zip

MODE=restore SITE=<host> SNAPSHOT_DIR=<entpackter Ordner> deploy/node/bend.sh

• Die DB muss leer sein; eine gefüllte DB wird nie überschrieben.
• Root-Zugänge der Umgebung und DB-Passwörter dürfen neu sein: neue Werte vorher in /root/.tlsgate.env (und in den Pool).
• Der Wurzelschlüssel nicht. Er muss byte-gleich zurück, sonst sind alle TOTP-Secrets, SOAP- und NetBox-Zugänge im Dump
  unlesbar. Eine vorhandene, abweichende Schlüsseldatei überschreibt bend.sh nie.
• Belegt im Container: Restore in eine frische Maschine mit neuen DB-Passwörtern, danach Anmeldung aller Konten mit ihren alten
  TOTP-Secrets (49 grün, 0 rot).

Dumps älterer Instanzen (vor ebdb1eb) tragen Trigger mit einem ; im Körper und ließen sich nicht einspielen (Fehler 1064);
bend.sh repariert das Muster beim Dumpen, die Restore-Probe belegt es.

8. Sicherheit

8.1 Anmeldung

• Passwort (Argon2id, 15–128 Zeichen, keine Zeichenklassen-Regeln, keine Zwangsrotation — NIST SP 800-63B) und TOTP für jede Rolle.
• TOTP-Secrets versiegelt (§8.3). Replay-Schutz: jeder Code gilt nur einmal (totp_last_step).
• Sperren: Konto nach 5 Fehlversuchen (Passwort oder TOTP) für 15 min, IP nach 10 Fehlversuchen in 15 min. Alle Fehlpfade melden
  dasselbe; bei unbekanntem Konto wird trotzdem ein Argon2id-Hash gerechnet. Zwischen Passwort und TOTP höchstens 5 min.
• Sitzung: __Host--Cookie, Secure, HttpOnly, SameSite=Strict, neue Session-ID nach jedem Schritt, 30 min Inaktivität / 12 h absolut.
• CSRF-Token auf jedem Formular (auch Logout, nur POST). Header: strikte CSP (default-src 'none'; script-src 'self'),
  frame-ancestors 'none', X-Frame-Options: DENY, nosniff, no-referrer, no-store. Kein Inline-JS.

8.2 Audit

audit_log ist per Trigger append-only (UPDATE und DELETE werfen Fehler). Jede Web-Aktion und jeder CLI-Aufruf steht dort mit
Akteur (cli:root, Konto, Gruppe), Ziel und Ergebnis (ok, denied, failed) — ohne Passwörter, Tokens oder Secrets. Grenze:
wer DDL-Rechte hat, kann Trigger entfernen; der Schutz ist die Trennung tlsgate_ddl (nur migrate) / tlsgate_app (nur DML, im Pool).

8.3 Geheimnisse

• Ein Wurzelschlüssel, getrennte Unterschlüssel je Zweck (src/Security/Secrets.php): XChaCha20-Poly1305, Unterschlüssel per KDF
  für totp, soap, outbox, netbox. Jeder Blob ist an seinen Datensatz gebunden (Gruppe, Label, Konto): eine kopierte Zeile
  öffnet sich nirgendwo anders.
• SOAP- und NetBox-Zugänge gehören der Gruppe und liegen nur versiegelt in der DB. Eingabe nur über Prompt bzw. stdin, nie als
  Argument (Prozessliste, History); nie zurück ins HTML; die Wertobjekte verraten sich nicht bei var_dump/json_encode/serialize.
• WSDL nur https://; TLSGATE_SOAP_HOSTS schränkt die Ziele ein. Kein Mock: ohne Zugang zeigt die App „nicht verfügbar“ mit Grund.
• Wer nur die DB oder nur den Schlüssel hat, öffnet nichts. Wer beides hat, öffnet alles dieser Instanz.
• key rotate hängt eine neue key_id an; alte bleiben lesbar, bis key migrate neu versiegelt hat.

8.4 Auslieferung

• DocumentRoot ist nur public/. src/, bin/, database/, state/ liegen nicht im Web — durch Struktur, nicht durch
  Sperrlisten. Der Doktor ruft Pfade außerhalb von public/ von außen ab und erwartet, dass keiner 200 liefert.
• Ein eigener FPM-Pool (deploy/node/tlsgate-pool.conf.example): clear_env = yes, open_basedir auf App, State und Schlüssel,
  display_errors off, expose_php off, disable_functions = exec,passthru,shell_exec,system,proc_open,popen,pcntl_exec, pcntl_fork,dl,putenv,mail,phpinfo. Die App braucht keine davon. phpinfo steht dort, weil eine info.php — der erste Reflex
  nach jedem Install — sonst $_SERVER mit dem DB-Passwort des Pools im Browser zeigt.
• Hinter einem Proxy muss die echte Client-Adresse als REMOTE_ADDR ankommen (mod_remoteip); X-Forwarded-For wird nicht
  ausgewertet. Sonst stehen Proxy-Adressen im Audit und die IP-Sperre trifft alle.

8.5 CLI-Guard

Die CLIs laufen nur als root, per sudo (Aufrufer in einer Operator-Gruppe: sudo, wheel, admin) oder als Besitzer der Instanz
(wem State und Schlüssel gehören); sonst Exit 3, nichts wird geschrieben. Der Web-Prozess kommt nie durch. Es gibt kein CLI-Login:
das Betriebssystem ist die Authentisierung, TOTP gilt fürs Web. Grenze: der Guard ordnet zu („wer war es“) und schützt vor
Fehlbedienung und dem Web-Prozess; die Zugriffsgrenze sind die Dateirechte.

8.6 Was ein Code im Pool kann

Jede PHP-Datei, die im Pool läuft, hat die Rechte des Pools: sie liest per getenv() das DB-Passwort (Weg „Passwort“) und
root.key (der Pool muss ihn lesen, sonst keine TOTP-Prüfung). Eine .env-Datei statt Pool-Variablen ändert daran nichts — was
der Pool lesen muss, liest auch Code im Pool. Die Abwehr ist deshalb Integrität, nicht Geheimhaltung: Code root-eigen und für
den Pool nicht schreibbar, die App schreibt nur nach state/ (außerhalb von public/), disable_functions, Manifest-Scan.

8.7 Weg „Identität“ (optional, DB_AUTH=socket)

Statt eines Passworts ist der Pool jemand: eigener OS-Benutzer je Instanz, MySQL-Benutzer gleichen Namens
IDENTIFIED WITH auth_socket, Anmeldung über den Unix-Socket. Im Pool steht kein Passwort mehr.

Was es bringt: kein mitnehmbares DB-Geheimnis (nicht in Pool-Datei, Backups, phpinfo-Resten) und keine Nachbarn — im Container
belegt mit zwei Instanzen: Pool A liest weder Schlüssel, state/, Umgebungsdatei noch Pool-Datei von B und kommt nicht in B's DB,
auch ohne open_basedir (das OS sperrt). Was es nicht bringt: gegen Code im eigenen Pool hilft es nicht (§8.6).
Nachbauen: tests/identitaet/instanz.sh, tests/identitaet/probe.sh (nur im Wegwerf-Container).

Status RC1.0: auf der Review-Instanz nicht getestet (dort nur ein Pool), für die finale Konfiguration vermerkt, nicht
entschieden. UNKNOWN: Umstellen einer laufenden Instanz, MODE=restore mit socket, MariaDB (unix_socket), CLI ohne Passwort.

8.8 Integrität und Reaktion

Der Scan erkennt, er verhindert nicht: im Fenster bis zum nächsten Lauf (≤ 10 min) kann eine fremde Datei den Schlüssel lesen.
Nach einem Befund gelten für diese Instanz Schlüssel, Sitzungen und alles, was der Schlüssel öffnet, als bekannt. Mindestens:
Datei sichern (Beweis) und entfernen, Audit und auth.log lesen, DB-Passwörter neu (Umgebungsdatei, Pool, bend.sh), SOAP-/NetBox-
Zugänge beim Anbieter neu und in TLS-Gate ersetzen, alle Konten reset-mfa. Ob zusätzlich der Wurzelschlüssel rotiert wird
(key rotate + key migrate), entscheidet der Mensch im Raum — nicht festgelegt.

8.9 Souveränität

Keine externen CDNs, Schriften oder Bibliotheken; keine Telemetrie; das einzige Cookie ist die Sitzung. Ausgehend nur zu den
Zielen, die eine Gruppe als Zugang hinterlegt (Registrar per SOAP, NetBox), optional eingeschränkt per Allowlist.

9. Wenn etwas rot ist

10. Bekannte Reste und Offenes (RC1.0)

• Ungenutzte Tabellen bleiben (Entscheidung RC1.0): Bestellschicht und Node-CA des Ursprungs-Repos (cert_orders, order_events,
  order_checks, cert_revocations, device_certs, device_cert_revocations, assets) stehen im Schema und werden migriert, damit
  Migrator und Bestands-DBs unverändert bleiben. Kein Code in diesem Repo schreibt sie.
• database/order_states.json, deploy/nginx.conf.example gehören zum Ursprungs-Repo (nginx-Node, Bestellschicht); die RZ-Node ist Apache.
• src/Modules/Chain.php (Modulkette) wird nur angezeigt (Dashboard), sperrt keine Seite.
• Nicht aufgerufene Methoden (grep über das ganze Repo, §11): CredentialStore::byId (Bestellschicht), Chain::requireModule
  (Modulkette nicht verdrahtet), Getter SoapCredential::groupId, NetBoxCredential::groupId, NetBoxCredential::kontoBindung.
  Bleiben bis zur Entscheidung über die Altlasten; keine davon ist von außen erreichbar.
• Review-TSV und Manifest gelten je Host, nicht je Instanz (mehrere Instanzen auf einem Host: §8.7).
• Offen seit M1: WebAuthn/Passkeys, Abgleich gegen geleakte Passwörter, Aufbewahrungsfrist für audit_log/login_attempts,
  Benutzerverwaltung für group_admin (heute nur admin), eigenes Passwort im Web ändern.
• ACME (acme.sh-Worker, im Ursprungs-Repo als M6 geplant): nach RC1.0, nicht Teil dieses Stands.

11. Prüfstand RC1.0 (OZM Admin Audit, 2026-10-16)

Ein Pool, Weg „Passwort“, Wegwerf-Container wie die Review-Instanz: Ubuntu 22.04 mit systemd, PHP 8.4.26, MySQL 8.0.46, Apache 2.4.

Im Zuge des Audits behoben: Test-Hilfe perm() las unter GNU-stat Dateisystem-Infos statt Rechte (der Schlüssel war immer 0400);
Testserver bekamen feste 5 s ohne Prüfung und wackelten bei langsamem Kaltstart (jetzt tg_wait_web, bis 15 s, sonst klarer Fehler);
test_login_instance ließ seine Test-DB liegen.

Echte Hardware im VPN (2026-10-17, cruncher): Raspberry Pi 5, Debian 12 arm64, PHP 8.4.26 (sury), MySQL 8.4.11 (Oracle-Tarball,
signaturgeprüft), Apache nur an Loopback und wg0: bend.sh MODE=review 0–10 grün (Doktor 0 FAIL, Gegenprobe 49/0, Restore-Probe
16 Trigger). Gefunden und behoben: MySQL 8.4 kennt SET_USER_ID nicht mehr (Fehler 1419 bei migrate). Aus dem VPN login.php 200,
http→https, Pfade außerhalb public/ abgelehnt; aus dem Koffer-LAN keine Verbindung auf 80/443/3306. Das Exponat auf derselben Kiste
lief durch. Umgebung: Ansible-Crumbforest:playbooks/cruncher-tlsgate-env.yml.

Live (omc33, von Branko): erste native Instanz läuft, Gruppe bwa mit Admin und User getestet, weitere Gruppe übertragen, alles im
Audit; Passwörter der getesteten Konten gesperrt bzw. zurückgesetzt. Letzter bend.sh-Lauf dort (20261016T171017Z) rot in Schritt 6 —
Schritte 7–10 sind dort nicht gelaufen; vor der Freigabe einen vollständig grünen Lauf (oder MODE=prod) auf der Instanz.

12. Herkunft

Herausgelöst aus native_php/ von TLS-Gate-Mock-Pipeline (main 35451b0). Dort liegen weiter die Entwurfsdokumente, auf die
Kommentare im Code als TLS-Gate-Mock-Pipeline:docs/… verweisen (Mandanten, Katalog/Buchungen, NetBox-Connector, Dashboard,
Architektur), sowie Bash-Dashboards, Docker-VM, Node-CA und Bestellschicht.