131 lines
6.9 KiB
Markdown
131 lines
6.9 KiB
Markdown
### 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 = <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 den umgebungsspezifischen Prefix, z.B. `DEV_ENC:<payload>`, `INT_ENC:<payload>`, `PROD_ENC:<payload>` (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`).
|
|
|
|
|