### Admin-Leitfaden: *_SECRET-Werte in Env-Dateien verschlüsseln Diese Anleitung beschreibt, wie das PowerOn-Gateway-Tool `scripts/script_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 `encryptValue` aus `modules/shared/configuration.py`. Stellen Sie sicher, dass dieser Pfad importierbar ist (Start im Gateway-Verzeichnis oder `PYTHONPATH` setzen). Das Script fuegt `gateway` automatisch zu `sys.path` hinzu. --- ### Vorbedingungen 1. `requirements.txt` im Projekt (Minimalbeispiel): ``` cryptography>=41.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`, `_getMasterKey`, `encryptValue`, `decryptValue`) - 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 = ` 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 = ` - `int = ` - `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=`). 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 den umgebungsspezifischen Prefix, z.B. `DEV_ENC:`, `INT_ENC:`, `PROD_ENC:` (abhaengig von `APP_ENV_TYPE`). - 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`).