diff --git a/poweron/appdoc/doc_admin_encrypt_env_secret.md b/poweron/appdoc/doc_admin_encrypt_env_secret.md new file mode 100644 index 0000000..5be3eef --- /dev/null +++ b/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 = ` + +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 `ENV_ENC:`. + - 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`). + + diff --git a/poweron/testdata-wait/PowerOn NDA 2025.docx b/poweron/testdata-wait/PowerOn NDA 2026.docx similarity index 51% rename from poweron/testdata-wait/PowerOn NDA 2025.docx rename to poweron/testdata-wait/PowerOn NDA 2026.docx index 66ea0b5..364fb26 100644 Binary files a/poweron/testdata-wait/PowerOn NDA 2025.docx and b/poweron/testdata-wait/PowerOn NDA 2026.docx differ