admin tool doku

poweron/appdoc/doc_admin_encrypt_env_secret.md

@@ -0,0 +1,131 @@
+### Admin-Leitfaden: *_SECRET-Werte in Env-Dateien verschlüsseln
+
+Diese Anleitung beschreibt, wie das PowerOn-Gateway-Tool `tool_security_encrypt_all_env_files.py` alle unverschlüsselten `*_SECRET`-Variablen in `env_dev.env`, `env_int.env` und `env_prod.env` verschlüsselt.
+
+---
+
+### 1) Einsatz in beliebigen Repositories & Voraussetzungen
+
+Das Tool kann in jedem Repository eingesetzt werden, sofern die untenstehenden Vorbedingungen erfüllt sind. Standardmäßig ist es im Ordner `gateway` integriert und erwartet dort seine Abhängigkeiten. In anderen Repos müssen Sie die Gateway-Komponenten bereitstellen oder den `PYTHONPATH` entsprechend setzen.
+
+- **Ausführungspfad**: Entweder im Verzeichnis, das die Gateway-Module `modules/shared` enthält (z. B. `gateway`), oder mit gesetztem `PYTHONPATH`, sodass `modules/shared/configuration.py` importiert werden kann.
+- **Python**: Python 3.10+ mit Abhängigkeiten (siehe Kapitel „Vorbedingungen“). Installation z. B.:
+  - Windows PowerShell im Repo-Root: `python -m venv .venv && .\.venv\Scripts\Activate.ps1`
+  - `pip install -r requirements.txt`
+- **Dateien**:
+  - Eine `config.ini` (im gleichen Projektteil wie die `modules`), die zumindest `APP_ENV_TYPE` und `APP_KEY_SYSVAR` enthält.
+  - Die zu verarbeitenden Env-Dateien: `env_dev.env`, `env_int.env`, `env_prod.env` (oder eine Teilmenge via `--files`).
+- **Rechte**: Schreibrechte auf die Env-Dateien, Leserechte auf die Masterkey-Quelle (siehe Punkt 2).
+
+Hinweis: Das Tool importiert `encrypt_value` aus `modules/shared/configuration.py`. Stellen Sie sicher, dass dieser Pfad importierbar ist (Start im Gateway-Verzeichnis oder `PYTHONPATH` setzen).
+
+---
+
+### Vorbedingungen
+
+1. `requirements.txt` im Projekt (Minimalbeispiel):
+   ```
+   cryptography>=42.0.0
+   ```
+   Falls Sie das Tool im bestehenden Gateway verwenden, nutzen Sie stattdessen die dortige Datei `gateway/requirements.txt`.
+
+2. Notwendige Gateway-Komponenten (sofern außerhalb von `gateway` verwendet):
+   - `modules/shared/configuration.py` (liefert `APP_CONFIG`, `_get_master_key`, `encrypt_value`, `decrypt_value`)
+   - Optional, aber unterstützt: `modules/shared/auditLogger.py` (Audit-Events; Ausfall ist toleriert)
+   - `config.ini` im gleichen Baum wie `modules`, mit mindestens:
+     - `APP_ENV_TYPE = dev|int|prod` (kann pro Env-Datei zusätzlich gesetzt werden)
+     - `APP_KEY_SYSVAR = <OS_ENV_NAME|Pfad_zur_Keydatei>`
+
+3. Struktur/Importpfade sicherstellen:
+   - Entweder das Tool im Ordner ausführen, der die `modules`-Struktur enthält (z. B. `gateway`).
+   - Oder `PYTHONPATH` so setzen, dass `modules` auflösbar ist, z. B. PowerShell:
+     ```powershell
+     $env:PYTHONPATH = (Resolve-Path .) 
+     python tool_security_encrypt_all_env_files.py --dry-run
+     ```
+
+---
+
+### 2) Masterkey: Herkunft pro Umgebung
+
+Die Verschlüsselung verwendet pro Umgebung einen Masterkey, der in `modules/shared/configuration.py` über `_get_master_key(env_type)` ermittelt wird. Quelle des Keys:
+
+1. `APP_KEY_SYSVAR` (aus `config.ini` oder `.env`) gibt entweder
+   - den **Namen einer OS-Umgebungsvariablen** an, die den Masterkey direkt enthält, oder
+   - einen **Dateipfad** zu einer Key-Datei an.
+
+2. Auflösung in dieser Reihenfolge:
+   - Wenn eine OS-Umgebungsvariable mit dem Namen `APP_KEY_SYSVAR` existiert, wird deren Wert direkt als Masterkey verwendet.
+   - Wenn keine OS-Variable gefunden wird, wird der Wert als Pfad interpretiert. Existiert die Datei, wird sie gelesen. Erwartetes Format je Zeile: `env = key`, z. B.:
+     - `dev = <masterkey_dev>`
+     - `int = <masterkey_int>`
+     - `prod = <masterkey_prod>`
+     Für die Zielumgebung (z. B. `prod`) wird die passend benannte Zeile verwendet.
+
+3. Der abgeleitete Key wird per PBKDF2 in einen 32-Byte-Schlüssel umgewandelt und für Fernet genutzt. Der verschlüsselte Wert erhält ein Präfix gemäß Umgebung: `DEV_ENC:`, `INT_ENC:`, `PROD_ENC:` (weitere unterstützt: `TEST_ENC:`, `STAGING_ENC:`).
+
+Wichtig: Die Umgebung für die Verschlüsselung wird pro Datei aus der jeweiligen Datei selbst gelesen (`APP_ENV_TYPE=<dev|int|prod>`). D. h. `env_prod.env` wird mit `prod`-Key verschlüsselt, unabhängig von der aktuellen Prozess-Umgebung.
+
+---
+
+### 3) Anwendung und Verhalten
+
+Tool: `gateway/tool_security_encrypt_all_env_files.py`
+
+- Standardlauf (alle drei Dateien, mit Backup):
+  ```bash
+  python tool_security_encrypt_all_env_files.py
+  ```
+  Wirkung:
+  - Liest je Datei `APP_ENV_TYPE`.
+  - Findet alle Schlüssel, deren Name auf `_SECRET` endet, und deren Werte noch kein `*_ENC:`-Präfix haben.
+  - Unterstützt einzeilige und mehrzeilige JSON-Werte (Klammer-Auf/Zu wird erkannt).
+  - Verschlüsselt die Werte mit dem passenden Umgebungs-Key und ersetzt die Originalwerte in der Datei durch `ENV_ENC:<payload>`.
+  - Legt vor Änderungen eine Backup-Datei mit Zeitstempel neben der Originaldatei an, z. B. `env_prod.env.20251015_101530.backup`.
+
+- Trockenlauf (nur anzeigen, nichts schreiben):
+  ```bash
+  python tool_security_encrypt_all_env_files.py --dry-run
+  ```
+  Wirkung: Listet, welche Zeilen/Keys verschlüsselt würden. Es werden keine Änderungen vorgenommen und keine Backups erstellt.
+
+- Ohne Backups ausführen:
+  ```bash
+  python tool_security_encrypt_all_env_files.py --no-backup
+  ```
+  Wirkung: Schreibt Änderungen ohne vorherige Backup-Datei.
+
+- Nur bestimmte Dateien verarbeiten:
+  ```bash
+  python tool_security_encrypt_all_env_files.py --files env_dev.env env_prod.env
+  ```
+
+Ausgabe/Ergebnis:
+- Pro Datei: Anzahl gefundener Secrets, Anzahl verschlüsselter Secrets, ggf. Backup-Datei, Fehler.
+- Zusammenfassung am Ende über alle verarbeiteten Dateien.
+
+Was wird als „bereits verschlüsselt“ erkannt?
+- Alle Werte, die mit einem der Präfixe beginnen: `DEV_ENC:`, `INT_ENC:`, `PROD_ENC:`, `TEST_ENC:`, `STAGING_ENC:`. Diese werden übersprungen.
+
+Fehlerbilder und Checks:
+- Fehlt `APP_KEY_SYSVAR` in `config.ini`/`.env` oder zeigt er auf eine nicht existierende OS-Variable/Datei, schlägt die Verschlüsselung fehl.
+- Fehlt in einer Key-Datei der passende Eintrag für die Zielumgebung, wird ein Fehler gemeldet.
+- Schreibfehler (z. B. fehlende Rechte) verhindern das Aktualisieren der Env-Datei.
+
+---
+
+### Best Practices
+
+- Änderungen zuerst mit `--dry-run` prüfen.
+- Vor Produktivläufen sicherstellen, dass `APP_KEY_SYSVAR` korrekt auf OS-Variable oder Key-Datei zeigt und die Datei einen Eintrag für die Zielumgebung enthält.
+- Backups beibehalten, um bei Bedarf Änderungen zurückzurollen.
+- JSON-Secrets in Env-Dateien korrekt mit `{ ... }` kapseln; das Tool erkennt und ersetzt mehrzeilige JSON-Blöcke vollständig.
+
+---
+
+### Referenz
+
+- Schlüsselauflösung und Verschlüsselung: `gateway/modules/shared/configuration.py` (`_get_master_key`, `_derive_encryption_key`, `encrypt_value`).
+- Batch-Tool: `gateway/tool_security_encrypt_all_env_files.py` (`encrypt_all_secrets_in_file`, `process_all_env_files`).
+
+