Environment-Variablen sicher verwalten

1. Environment-Variablen vs. Config-Dateien: Kompromisse verstehen

Die Twelve-Factor-App-Methodik empfiehlt, Konfiguration strikt vom Code zu trennen und über Environment-Variablen bereitzustellen, damit dieselbe Codebasis unverändert in Entwicklung, Staging und Produktion läuft. Der Vorteil liegt auf der Hand: Ein Deployment-Skript setzt einfach andere Werte, ohne eine Zeile Code oder eine versionierte Datei anzufassen. Für Datenbank-Hosts, API-Endpunkte oder Feature-Flags ist das ein sinnvoller Standard, der sich in Docker-Containern, Kubernetes-Pods und klassischen Application-Servern gleichermaßen bewährt hat.

Für Secrets gilt diese Empfehlung nur mit Einschränkungen. Environment-Variablen sind prozessgebunden, nicht versioniert und damit schwer zentral auditierbar: Wer wann welchen Wert gesetzt hat, lässt sich ohne zusätzliches Tooling kaum nachvollziehen. Sie tauchen zudem an Stellen auf, an die man selten denkt, etwa in /proc/self/environ, in der Ausgabe von ps auxe oder in Crash-Dumps von Process-Managern. Config-Dateien lassen sich dagegen verschlüsseln, mit Zugriffsrechten versehen und im Code-Review nachvollziehen. Magento selbst fährt einen hybriden Ansatz: Secrets kommen zur Installationszeit aus Environment-Variablen oder CLI-Parametern, landen aber strukturiert in der PHP-Datei app/etc/env.php, nicht in einer rohen .env-Datei.

Die pragmatische Regel lautet deshalb: Environment-Variablen für Bootstrapping, Umgebungs-Identität und nicht-sensitive Konfiguration nutzen, für strukturierte oder besonders kritische Secrets dagegen verschlüsselte Config-Dateien oder einen dedizierten Secrets-Vault vorziehen. Beide Mechanismen schließen sich nicht aus, sie ergänzen sich, wenn man ihre jeweiligen Schwächen kennt.

2. Ungewollte Preisgabe durch phpinfo(), Fehlerseiten und Debug-Ausgaben

Ein erreichbares phpinfo() in Produktion ist eine der unterschätztesten Schwachstellen überhaupt, weil es den kompletten Inhalt der Superglobalen $_ENV und $_SERVER unverschlüsselt in eine öffentlich abrufbare HTML-Seite rendert. Automatisierte Scanner suchen gezielt nach Pfaden wie /phpinfo.php, /info.php oder /test.php, die während der Entwicklung angelegt und beim Deployment vergessen wurden. Ein einziger vergessener Debug-Endpunkt kann Datenbank-Zugangsdaten, API-Keys und interne Hostnamen auf einen Schlag preisgeben.

Weniger offensichtlich, aber genauso gefährlich sind Debug-Ausgaben in Fehlerseiten. Symfony-Whoops-Stacktraces, unbehandelte Exceptions mit aktivem display_errors oder ein versehentliches var_dump($_SERVER) in einem Custom-Block zeigen denselben Umfang an Daten, nur weniger strukturiert. Xdebug-Ausgaben in Produktionsumgebungen sind ein verwandtes Risiko, da sie den vollen Request-Kontext inklusive Environment mitliefern, sobald ein Fehler auftritt.

Die wirksamste Gegenmaßnahme kombiniert mehrere Schichten: phpinfo über disable_functions im produktiven php.ini hart deaktivieren, display_errors=Off und MAGE_MODE=production erzwingen, sowie Logging-Wrapper einsetzen, die nur eine explizite Allowlist an Schlüsseln protokollieren, statt Request- oder Environment-Objekte pauschal zu serialisieren.

<?php

declare(strict_types=1);

namespace Mironsoft\EnvSecurity\Controller\Diagnostics;

/**
 * Dangerous pattern: never expose phpinfo() or raw superglobals in a
 * reachable controller action, even temporarily during development.
 */
final class DangerousDebugEndpoint
{
    public function execute(): void
    {
        // NEVER DO THIS in a reachable action, not even behind a route guess.
        // phpinfo() dumps every environment variable, including DB credentials.
        phpinfo();

        // Equally dangerous: dumping the raw environment or server superglobal.
        var_dump($_ENV, $_SERVER);
    }
}

/**
 * Safe pattern: read only the specific value needed, through a wrapper that
 * never logs or renders the full environment and redacts known secret keys.
 */
final class SafeEnvironmentReader
{
    private const SECRET_KEY_PATTERN = '/password|secret|key|token/i';

    /**
     * Returns a single environment value or a default, never the full set.
     *
     * @param string $name Name of the environment variable to read.
     * @param string|null $default Fallback value if the variable is unset.
     * @return string|null The resolved value or the provided default.
     */
    public function get(string $name, ?string $default = null): ?string
    {
        $value = getenv($name);

        return $value === false ? $default : $value;
    }

    /**
     * Builds a redacted snapshot safe for diagnostic logging.
     *
     * @param array<string, string> $env Raw environment key-value pairs.
     * @return array<string, string> Redacted copy safe to log or display.
     */
    public function redactedSnapshot(array $env): array
    {
        foreach ($env as $key => $value) {
            if (preg_match(self::SECRET_KEY_PATTERN, $key) === 1) {
                $env[$key] = '***REDACTED***';
            }
        }

        return $env;
    }
}

3. .env-Dateien in Docker, CI/CD und dem Mark-Shust-Setup

Der Begriff .env-Datei bedeutet je nach Kontext etwas anderes, und genau diese Mehrdeutigkeit führt regelmäßig zu Fehlkonfigurationen. Docker Compose liest automatisch eine .env-Datei im Projekt-Root, um ${VARIABLE}-Platzhalter innerhalb der compose.yaml selbst zu interpolieren, das ist etwas anderes als die env_file-Direktive, die Werte tatsächlich in den Container injiziert. Wer beides vermischt, wundert sich schnell, warum eine Änderung an der einen Datei keine Wirkung zeigt.

In CI/CD-Pipelines sollte in der Regel gar keine physische .env-Datei im Arbeitsverzeichnis des Jobs existieren. GitHub Actions Secrets, GitLab CI/CD Variables oder das Pendant der jeweiligen Plattform injizieren Werte direkt als Prozess-Environment des Runners, der nach dem Job ohnehin verworfen wird. Ephemere Runner-Umgebungen sind hier ein eingebauter Sicherheitsvorteil, den man durch das Ablegen einer .env-Datei im Repository unnötig aushebeln würde.

Das Mark-Shust-Setup, das diesem Projekt zugrunde liegt, nutzt bewusst kein einzelnes globales .env, sondern ein env/-Verzeichnis mit thematisch getrennten Dateien wie db.env, magento.env, redis.env oder rabbitmq.env, jeweils über env_file gezielt dem passenden Service in der Compose-Datei zugeordnet. Diese Trennung reduziert die Blast-Radius eines einzelnen geleakten Files und macht Reviews übersichtlicher, ersetzt aber nicht die Pflicht, das gesamte env/-Verzeichnis konsequent aus der Versionskontrolle auszuschließen.

#!/usr/bin/env bash
# scan-env-leaks.sh - quick local audit for the Mark Shust docker-magento env/ layout
set -euo pipefail

ENV_DIR="env"
SECRET_PATTERN="PASSWORD|SECRET|KEY|TOKEN"

echo "[CHECK] env/ directory must never be tracked by git"
if git ls-files --error-unmatch "${ENV_DIR}" >/dev/null 2>&1; then
  echo "FAIL: files under ${ENV_DIR}/ are tracked in git, remove them and rotate secrets"
  exit 1
fi

echo "[CHECK] scanning env/*.env files for obviously weak defaults"
for file in "${ENV_DIR}"/*.env; do
  if grep -Eiq "${SECRET_PATTERN}=(magento|password|changeme|admin)$" "${file}"; then
    echo "WARNING: ${file} contains a default or weak credential"
  fi
done

echo "[CHECK] no .env file should exist in a CI job working directory"
if [ -n "${CI:-}" ] && [ -f ".env" ]; then
  echo "FAIL: .env file present in CI, secrets must be injected via the CI secret store"
  exit 1
fi

echo "[OK] no obvious environment file leaks detected"

4. Präzedenz und versehentliche Overrides zwischen Shell, Docker und CI

Docker Compose löst ${VARIABLE}-Platzhalter innerhalb der YAML-Datei zunächst gegen die Shell-Environment auf, bevor überhaupt auf die projektweite .env-Datei zurückgegriffen wird. Die Shell gewinnt also bei der Interpolation. Sobald die Werte für den Container feststehen, gilt eine zweite, unabhängige Rangfolge: Der environment:-Block eines Service überschreibt immer Werte aus env_file, und beide überschreiben eine ENV-Anweisung, die im Dockerfile ins Image gebacken wurde. Zwei getrennte Präzedenz-Systeme, die leicht verwechselt werden.

Das führt zu einem realen, wiederkehrenden Fehlerbild: Ein Entwickler setzt lokal export DB_PASSWORD=test zum Debuggen, vergisst das unset, und die nächste docker compose up-Ausführung interpoliert diesen Wert still über die eigentlich in env/db.env hinterlegte Konfiguration, ohne dass eine Fehlermeldung erscheint. In CI-Pipelines mit wiederverwendeten Runnern kann derselbe Effekt auftreten, wenn ein vorheriger Job Environment-Variablen exportiert, die im nächsten Job nicht bereinigt wurden.

Der zuverlässigste Schutz ist, den tatsächlich aufgelösten Zustand vor jedem Deployment sichtbar zu machen, statt sich auf die Dokumentation der Präzedenzregeln zu verlassen. docker compose config rendert die vollständig aufgelöste Compose-Konfiguration inklusive aller interpolierten Werte, wodurch Overrides sofort auffallen, bevor sie in Produktion landen. Ein kurzer manueller Blick auf diese Ausgabe vor jedem docker compose up in einer produktionsnahen Umgebung ist deutlich zuverlässiger, als sich auf die korrekte Reihenfolge im eigenen Gedächtnis zu verlassen.

Ähnliche Vorsicht gilt für CI-Systeme mit gecachten oder wiederverwendeten Job-Containern: Ein Build-Cache, der eine vorherige Environment-Variable konserviert, kann in einem späteren, scheinbar unabhängigen Job unbemerkt wieder auftauchen. Saubere, isolierte Runner-Instanzen pro Job, kombiniert mit einem expliziten env -i für kritische Deployment-Skripte, schließen diese Lücke zuverlässiger als jede Dokumentation.

5. Magentos app/etc/env.php: Zugangsdaten, Crypt-Key und Cache-Backends

app/etc/env.php wird von setup:install generiert und ist keine .env-Datei im klassischen Sinn, sondern ein von Magentos Bootstrap direkt eingebundenes PHP-Array. Die Verwechslung beider Konzepte ist häufig, aber folgenreich: Wer eine generische .env-Datei mit einem Package wie vlucas/phpdotenv parst und annimmt, das decke Magentos Konfiguration ab, übersieht, dass die eigentlichen kritischen Werte, Datenbank-Zugangsdaten, der Crypt-Key und Cache-Backend-Konfiguration, ausschließlich in env.php liegen.

Der Crypt-Key ist dabei besonders kritisch, weil er zur Verschlüsselung sensibler Datenbank-Spalten dient, etwa gespeicherter API-Zugangsdaten von Zahlungs-Modulen oder Integrationstoken. Wer den Crypt-Key kompromittiert, kann sämtliche mit ihm verschlüsselten Werte in der Datenbank entschlüsseln, auch rückwirkend, falls ein Datenbank-Dump zusätzlich abgegriffen wurde. Redis- oder Valkey-Zugangsdaten für Cache und Session-Backend liegen ebenfalls im Klartext in dieser Datei.

env.php muss deshalb mit restriktiven Dateirechten (üblich sind 640) und einem Besitzer versehen sein, der nicht dem Webserver-Prozess-User entspricht, sofern die Trennung im jeweiligen Deployment-Modell möglich ist. Backup-Dateien wie env.php.bak oder env.php.old, die manche Deployment-Skripte versehentlich im Web-Root hinterlassen, sind ein unterschätzter Leak-Vektor, weil eine Fehlkonfiguration im Webserver sie als Klartext ausliefern kann, statt sie als PHP zu interpretieren.

<?php
// app/etc/env.php (excerpt) - generated by bin/magento setup:install
// Must never be committed to version control or served as a static file.
return [
    'backend' => [
        'frontName' => 'admin',
    ],
    'crypt' => [
        // Encrypts sensitive DB columns (payment tokens, integration secrets).
        // Compromise of this value allows decrypting all affected data.
        'key' => 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
    ],
    'db' => [
        'connection' => [
            'default' => [
                'host' => 'db',
                'dbname' => 'magento',
                'username' => 'magento',
                'password' => 'REPLACE_WITH_STRONG_GENERATED_SECRET',
                'engine' => 'innodb',
            ],
        ],
    ],
    'cache' => [
        'frontend' => [
            'default' => [
                'backend' => 'Cm_Cache_Backend_Redis',
                'backend_options' => [
                    'server' => 'redis',
                    'port' => '6379',
                    'password' => 'REPLACE_WITH_STRONG_GENERATED_SECRET',
                ],
            ],
        ],
    ],
    'MAGE_MODE' => 'production',
];

6. Secrets zur Laufzeit injizieren statt ins Image zu backen

Ein Secret, das über ARG oder ENV im Dockerfile ins Image gebacken wird, bleibt dort dauerhaft erhalten, selbst wenn eine spätere Layer-Instruktion den Wert scheinbar überschreibt oder löscht. Jeder, der Zugriff auf die Image-Registry hat oder ein geleaktes Image in die Hände bekommt, kann über docker history oder ein simples Layer-Extraktions-Tool die vollständige Build-Historie inklusive aller jemals gesetzten Secrets auslesen. Das gilt auch für ein per COPY .env . ins Image kopiertes File.

Der sichere Ansatz injiziert Secrets erst beim Start des Containers oder beim Deployment, nie beim Bau des Images. Praktisch heißt das: --env-file beim docker run-Aufruf, Compose- oder Swarm-native secrets:, oder orchestrator-eigene Secret-Stores wie Kubernetes Secrets, die als tmpfs-Mounts bereitgestellt werden. In CI/CD-Pipelines übernimmt ein dedizierter Deploy-Schritt diese Aufgabe, indem er Werte unmittelbar vor dem Rollout aus einem Vault wie HashiCorp Vault oder AWS Secrets Manager zieht und injiziert, statt sie im Pipeline-Code selbst zu hinterlegen.

Für dieses Projekt bedeutet das konkret: Das Deployment-Skript liest Secrets aus einem außerhalb des Repositories liegenden Passwort-Manager oder Secrets-File erst unmittelbar vor docker compose up und schreibt sie in die env/-Dateien auf dem Zielserver, nie in den Build-Kontext des Images. Multi-Stage-Builds stellen zusätzlich sicher, dass Secrets, die im Build-Stage benötigt werden, etwa für einen privaten Composer-Repository-Token, nicht versehentlich in die finale Runtime-Layer durchsickern.

# .github/workflows/deploy.yml - inject secrets at deploy time, never bake them in
name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.1

      # Build the image WITHOUT any secrets in the build context.
      - name: Build application image
        run: docker build -t registry.example.com/magento-app:${{ github.sha }} .

      - name: Push image to registry
        run: docker push registry.example.com/magento-app:${{ github.sha }}

      # Secrets are pulled from the CI secret store and injected only now,
      # at deploy time, directly into the target host's env/ directory.
      - name: Inject secrets and deploy
        env:
          DB_PASSWORD: ${{ secrets.PROD_DB_PASSWORD }}
          CRYPT_KEY: ${{ secrets.PROD_CRYPT_KEY }}
          REDIS_PASSWORD: ${{ secrets.PROD_REDIS_PASSWORD }}
        run: |
          ssh deploy@production "cat > /srv/app/env/db.env" <<EOF
          MYSQL_PASSWORD=${DB_PASSWORD}
          EOF
          ssh deploy@production "docker compose -f compose.yaml up -d"

7. environment, env_file und secrets in docker-compose.yaml

Docker Compose bietet drei unterschiedliche Mechanismen, Werte in einen Container zu bringen, und sie unterscheiden sich deutlich in ihrer Sicherheitswirkung. Der environment:-Block trägt Schlüssel-Wert-Paare direkt in die YAML-Datei ein, sichtbar für jeden mit Lesezugriff auf die Compose-Datei und zusätzlich über docker inspect jederzeit auslesbar, auch von Monitoring-Agenten, die Container-Metadaten sammeln. Für hochsensible Werte ist das ungeeignet.

env_file: lädt Werte aus einer externen Datei in die Container-Umgebung, hat zur Laufzeit dieselbe Sichtbarkeit über docker inspect und Prozess-Environment wie environment:, hält die Werte aber wenigstens aus der Compose-Datei selbst heraus, was Versionskontrolle und Reviews erleichtert, solange die Datei korrekt ignoriert wird. Der native secrets:-Mechanismus, seit Compose v2 auch ohne Swarm-Modus über dateibasierte Secrets nutzbar, mountet Werte als Dateien unter /run/secrets/, nicht als Prozess-Environment-Variable, und ist damit weder über docker inspect noch über ps im Container einsehbar.

Die praktische Faustregel: environment: für unkritische Konfiguration wie APP_ENV oder Zeitzonen-Einstellungen, env_file: für entwicklerfreundliche, konsequent gitignorierte Dateien, und secrets: für alles, was ein Angreifer mit Container-Inspektionszugriff, aber ohne direkten Dateisystem-Zugriff nicht sehen sollte, etwa Datenbank-Passwörter oder den Magento-Crypt-Key.

# compose.yaml - environment vs. env_file vs. secrets, side by side
services:
  phpfpm:
    image: mironsoft/magento-phpfpm:8.4
    environment:
      # Non-sensitive: safe to keep inline, visible in docker inspect.
      APP_ENV: production
      TZ: Europe/Berlin
    env_file:
      # Convenience layer for developer-oriented config, must be gitignored.
      - env/magento.env
    secrets:
      # Only referenced by name here, actual value never touches this file.
      - db_password
      - crypt_key

  db:
    image: mysql:8.0
    env_file:
      - env/db.env
    secrets:
      - db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt
  crypt_key:
    file: ./secrets/crypt_key.txt

8. .gitignore-Disziplin für Environment-Dateien

Die Grundausstattung eines wirksamen .gitignore für dieses Setup umfasst mindestens .env, .env.* mit einer expliziten Ausnahme für !.env.example, das gesamte env/*.env-Muster für das Mark-Shust-Layout sowie app/etc/env.php. Bei Letzterem herrscht in vielen Teams Unsicherheit: Die gängige Praxis ist, env.php pro Umgebung über setup:install oder eine Deployment-Pipeline neu zu generieren und nur eine dokumentierte env.php.example mit Platzhaltern zu versionieren, während versionierbare, nicht-sensitive Konfiguration über bin/magento app:config:import und app/etc/config.php läuft.

.gitignore allein verhindert nur zukünftige, versehentliche Commits, es schützt nicht vor menschlichem Fehler bei einem expliziten git add -f. Deshalb gehören Pre-Commit-Hooks mit Tools wie gitleaks oder git-secrets in jede ernstzunehmende Pipeline, die jeden Staged Diff gegen bekannte Credential-Muster prüfen, bevor der Commit überhaupt entsteht. Da lokale Hooks mit --no-verify umgangen werden können, sollte derselbe Scan zusätzlich als verpflichtender CI-Schritt bei jedem Push laufen.

Landet trotz aller Vorsicht ein Secret in der Git-Historie, reicht das Löschen der Datei im nächsten Commit nicht aus, der Wert bleibt in jedem geklonten Repository und jedem Fork abrufbar. Werkzeuge wie BFG Repo-Cleaner oder git filter-repo entfernen den Wert nachträglich aus der Historie, ersetzen aber niemals die sofortige Rotation des betroffenen Secrets, denn eine History-Rewrite macht bereits erfolgte Zugriffe nicht ungeschehen. Eine gepflegte .env.example beziehungsweise env.php.example mit sprechenden Platzhaltern dokumentiert außerdem, welche Variablen ein neues Teammitglied überhaupt benötigt, ohne echte Werte preiszugeben.

9. Environment-Variablen-Sicherheit im Vergleich

Die folgende Übersicht stellt fünf typische Fehlkonfigurationen im Umgang mit Environment-Variablen den jeweils sicheren Gegenmaßnahmen gegenüber, wie sie in Docker-, CI/CD- und Magento-Kontexten regelmäßig auftreten.

Kein einzelner Punkt in dieser Tabelle löst das Problem allein. Erst die Kombination aus Laufzeit-Injection, konsequenter .gitignore-Disziplin, restriktiven Dateirechten für env.php, deaktivierten Debug-Endpunkten und sauber getrennten Umgebungen reduziert die Angriffsfläche auf ein realistisches Minimum.

10. Zusammenfassung

Environment-Variablen sind kein automatisch sicherer Ersatz für Config-Dateien, sondern ein Werkzeug mit eigenen, spezifischen Schwächen. Erreichbare phpinfo()-Aufrufe, Debug-Ausgaben und vergessene Diagnose-Endpunkte gehören zu den häufigsten realen Leak-Vektoren, weil sie den kompletten Environment-Inhalt unverschlüsselt preisgeben. Magentos app/etc/env.php ist strukturell etwas anderes als eine generische .env-Datei und verdient wegen Crypt-Key und Datenbank-Zugangsdaten besonderen Schutz durch restriktive Dateirechte und konsequenten Ausschluss aus der Versionskontrolle.

Die technisch wirksamste Einzelmaßnahme bleibt, Secrets ausschließlich zur Laufzeit zu injizieren statt sie ins Docker-Image zu backen, kombiniert mit dem korrekten Einsatz von Docker Composes secrets:-Mechanismus für hochsensible Werte. Präzedenzregeln zwischen Shell, .env, env_file und environment: sollten nie aus dem Gedächtnis rekonstruiert, sondern vor jedem Deployment mit docker compose config sichtbar gemacht werden. Konsequente .gitignore-Disziplin, ergänzt um automatisiertes Secret-Scanning, schließt die verbleibende Lücke zwischen Theorie und tatsächlichem Team-Verhalten.

11. FAQ: Environment-Variablen sicher verwalten