OpenShip-Schlüsselverwaltung: Plattform oder Server?

Die Anwendung läuft, aber ein API-Schlüssel wurde trotzdem in eine Docker-Image-Schicht übernommen.

Die schnellste Lösung: Für normale Anwendungsschlüssel verwenden Sie die umgebungsgebundene, zugriffsbeschränkte und nachvollziehbare Schlüsselverwaltung von OpenShip; Infrastrukturzugänge bleiben nur dann auf dem Server, wenn sie dort zwingend benötigt werden. Für sensible Produktionssysteme kombinieren Sie beide Ebenen mit einem Secrets Vault und prüfen jede Rotation durch einen echten Wiederherstellungstest.

Wer sollte weiterlesen?
Dieser Leitfaden richtet sich an Einzelentwickler, die den ersten Modell-API-Schlüssel mit OpenShip bereitstellen, an kleine Teams mit getrennten Preview-, Test- und Produktionsumgebungen sowie an technische Verantwortliche, die Rotation, Berechtigungen und Notfallwiederherstellung belastbar organisieren müssen.

OpenShip-Schlüsselverwaltung beginnt nicht mit dem Speicherort

Die wichtigste Sicherheitsfrage lautet nicht „Plattform oder Server?“, sondern: An welcher Stelle kann der Schlüssel sichtbar, kopiert, protokolliert oder mit einer falschen Umgebung verbunden werden?

OpenShip trennt grundsätzlich zwischen der Steuerungsebene und dem Ziel, auf dem die Anwendung läuft. Die offizielle Architekturbeschreibung unterscheidet lokale Ausführung, einen über SSH verbundenen Server und verwaltete Cloud-Ausführung. Projekte, Deployments, Domains, Backups, Umgebungsvariablen und Berechtigungen werden dabei über die API-Steuerungsebene verwaltet. Die offizielle Architekturübersicht von OpenShip beschreibt diese Zuständigkeiten ausführlich.

Das bedeutet jedoch nicht automatisch, dass ein in der Plattform gespeicherter Wert niemals in einem Build, Container oder Log auftauchen kann. Ob ein Schlüssel zur Laufzeit injiziert, während des Builds verfügbar gemacht oder in eine Client-Datei übernommen wird, hängt von Ihrer Konfiguration und dem Framework ab. Deshalb müssen Sie die tatsächlichen Artefakte prüfen, nicht nur das Eingabefeld im Dashboard.

Besonders gefährlich sind vier Ablageorte:

• Git-Historie: Ein später gelöschter Schlüssel bleibt möglicherweise in alten Commits, Forks oder lokalen Klonen erhalten.
• Dockerfile und Build-Argumente: Ein als Build-Argument übergebener Wert kann in einer Image-Historie oder Zwischenebene sichtbar werden.
• Build- und Deployment-Logs: Debug-Ausgaben, fehlgeschlagene Installationsskripte und Shell-Kommandos können Variablenwerte ausgeben.
• Client-Bundle: Variablen mit einem öffentlich gedachten Präfix werden bei vielen Web-Frameworks in JavaScript eingebettet und an jeden Browser ausgeliefert.

Ein Server-Schlüssel darf daher niemals in eine Datei gelangen, die der Quellcodeverwaltung, dem Build-System oder dem Browser zugänglich ist. Eine lokale .env-Datei ist nur dann ein vertretbarer Ort, wenn sie ausschließlich auf dem Zielsystem liegt, ihre Dateirechte begrenzt sind und kein automatischer Build sie einliest oder kopiert.

Erster Schritt: Prüfen Sie die vier Leckpfade

Bevor Sie die Ablage neu organisieren, untersuchen Sie das bestehende Deployment. Die Reihenfolge ist wichtig, weil ein neuer Speicherort einen bereits kopierten Schlüssel nicht zurückholt.

1. Repository-Historie durchsuchen: Prüfen Sie aktuelle Dateien, frühere Commits, Tags, Pull Requests und Beispielkonfigurationen. Suchen Sie nicht nur nach bekannten Variablennamen, sondern auch nach typischen Präfixen, langen zufälligen Zeichenketten und Verbindungs-URLs.
2. Image-Historie kontrollieren: Untersuchen Sie Dockerfile, Build-Argumente, Zwischenebenen und die Metadaten des veröffentlichten Images. Ein Schlüssel, der nur während eines einzelnen Build-Schritts verwendet wurde, kann trotzdem in einer Schicht verbleiben.
3. Build-Ausgabe lesen: Suchen Sie nach Shell-Echo, Debug-Modus, fehlgeschlagenen Befehlen und automatisch ausgegebenen Konfigurationen. Maskierung in der Oberfläche ist kein Beweis, dass der Wert nie im Log stand.
4. Client-Dateien prüfen: Entpacken Sie das erzeugte JavaScript-Bundle und suchen Sie nach Modellschlüsseln, Datenbankpasswörtern, SMTP-Zugangsdaten und privaten Endpunkten.
5. Bei einem Fund sofort widerrufen: Ein gefundener Schlüssel gilt als kompromittiert. Erst danach legen Sie einen neuen Wert an und testen die Anwendung mit dem neuen Schlüssel.

Der relevante Prüfpunkt ist nicht „Der Schlüssel steht nicht in meiner aktuellen Quelldatei“. Der relevante Prüfpunkt lautet: Kann ein Entwickler, ein Build-Prozess, ein Container-Leser oder ein Browser den Wert aus einem Artefakt rekonstruieren?

Für Docker-Builds sollten Sie außerdem prüfen, ob Ihre Build-Methode ausdrücklich für geheime Werte vorgesehene Mechanismen verwendet. Docker beschreibt Build-Secrets und deren Verwendung in Builds getrennt von normalen Build-Argumenten und Umgebungsvariablen. Das ist keine automatische Absicherung Ihres OpenShip-Projekts, liefert aber einen geeigneten Prüfmaßstab für Dockerfile und CI/CD-Konfiguration.

Zweiter Schritt: Preview, Test und Produktion strikt trennen

Werden OpenShip-Umgebungsvariablen in das Build-Image übernommen?

Nicht jede Umgebungsvariable wird automatisch Teil des Images. Das Risiko entsteht, sobald Sie sie als Build-Argument verwenden, in Dateien schreiben, während des Builds ausgeben oder ein Framework sie als öffentliche Client-Variable behandelt. Die OpenShip-Architektur beschreibt Docker als einen möglichen Runtime-Typ; daraus folgt aber keine pauschale Aussage darüber, wie Ihre konkrete Anwendung einzelne Variablen verarbeitet. Die Dokumentation zum Architekturmodell sollten Sie deshalb mit dem Verhalten Ihres Frameworks und Ihrer Build-Datei abgleichen.

Für jede Umgebung benötigen Sie eine eigene Konfigurationsmenge:

Die häufigste Fehlkonfiguration ist kein spektakulärer Angriff, sondern ein kopierter Variablensatz: Ein Entwickler erstellt ein Preview-Projekt, übernimmt die Produktionswerte, ändert nur die Datenbank-URL und vergisst den Modell- oder Webhook-Schlüssel. Der Dienst läuft scheinbar korrekt, aber Tests verbrauchen Produktionskontingent, schreiben in echte Daten oder erzeugen externe Aktionen.

Dokumentieren Sie deshalb pro Projekt nicht nur den Variablennamen, sondern auch Besitzer, Umgebung, Zweck, Zielsystem und Rotationsweg. Werte selbst gehören nicht in dieses Dokument.

Was unterscheidet eine Server-.env von Plattformschlüsseln?

Eine .env auf dem Server liegt näher am Runtime-Prozess und kann für Infrastrukturwerte sinnvoll sein. Plattformvariablen liegen dagegen in der zentralen Steuerungsebene und können dem Projekt oder einer bestimmten Umgebung zugeordnet werden. Der Unterschied ist somit weniger „verschlüsselt gegen unverschlüsselt“, sondern vor allem Verantwortung, Sichtbarkeit und Wiederherstellung.

OpenShip beschreibt Organisationen, Rollen, Ressourcenfreigaben und ein Audit-Log als Bestandteile seines Berechtigungsmodells. Die Dokumentation weist zugleich darauf hin, dass Standardrollen wie „member“ und „admin“ relativ weitreichend sind und feinere Einschränkungen über eingeschränkte Mitglieder oder bereichsbezogene Tokens erfolgen. Das ist eine dokumentierte Plattformfunktion, aber noch kein Nachweis, dass Ihre konkrete Installation sie korrekt konfiguriert hat. Details zu Rollen und Berechtigungen in OpenShip

Dritter Schritt: Schlüsselrotation ohne ungeplanten Ausfall

Müssen Sie für einen neuen Modell-API-Schlüssel neu deployen?

Nicht zwingend, aber Sie müssen den tatsächlichen Ladezeitpunkt Ihrer Anwendung kennen. Manche Prozesse lesen Umgebungsvariablen nur beim Start. Andere Konfigurationen werden von einem laufenden Prozess zwischengespeichert. Eine Änderung im Dashboard kann daher erfolgreich gespeichert sein, während der alte Wert weiterhin im Speicher verwendet wird.

Behandeln Sie eine Rotation als kontrollierten Ablauf mit drei möglichen Zuständen:

1. Alten und neuen Schlüssel parallel vorbereiten: Der neue Schlüssel wird angelegt und mit einem eindeutigen Namen oder einer Version dokumentiert. Der alte Schlüssel bleibt zunächst aktiv.
2. Anwendung auf den neuen Wert umstellen: Ändern Sie die Plattformvariable oder den Vault-Eintrag. Starten Sie den betroffenen Prozess neu, falls die Anwendung Variablen nur beim Start liest.
3. Nachweis erbringen: Senden Sie eine echte, ungefährliche Testanfrage. Prüfen Sie dabei nicht nur den HTTP-Status, sondern auch, ob der neue Schlüssel beim Zielanbieter verwendet wird, ob keine unerwarteten Fehler in Logs erscheinen und ob Preview sowie Produktion weiterhin getrennt sind.
4. Alten Wert widerrufen: Erst wenn der neue Wert bestätigt ist, deaktivieren Sie den alten Schlüssel.
5. Rückfall testen: Dokumentieren Sie, wie Sie bei einem fehlerhaften neuen Schlüssel zurück auf den vorherigen gültigen Wert wechseln, ohne den kompromittierten Schlüssel erneut zu aktivieren.

Die drei häufigsten Fehler sind das direkte Überschreiben ohne Rückfalloption, das Widerrufen des alten Werts vor dem Neustart und die Annahme, dass „gespeichert“ automatisch „aktiv verwendet“ bedeutet. Ihre Abnahme sollte deshalb folgende Fragen beantworten:

• Verwendet eine neue Anfrage tatsächlich den neuen Schlüssel?
• Ist der alte Schlüssel widerrufbar und nach dem Test nicht mehr gültig?
• Wissen Sie, welcher Prozess neu gestartet werden muss?
• Können Sie bei einem fehlerhaften Anbieterwechsel kontrolliert zurückrollen?
• Enthält kein Log den geheimen Wert oder eine vollständige Authentifizierungs-URL?

Für den CLI- und CI-Betrieb sollten Sie persönliche Zugriffstokens nicht gemeinsam im Team verwenden. OpenShip dokumentiert persönliche Tokens, die einmalig angezeigt, lokal in einer Konfigurationsdatei gespeichert und für Skripte verwendet werden können. Für Automatisierung sind lesende oder eingeschränkt gültige Tokens vorzuziehen, statt den persönlichen Vollzugriff eines Administrators zu kopieren. Die OpenShip-CLI-Dokumentation zu Personal Access Tokens erläutert diesen Ablauf.

Vierter Schritt: Berechtigungen nach Aufgabe statt nach Vertrauen vergeben

Welche Schlüsselrechte sollte ein Teammitglied erhalten?

Ordnen Sie nicht „Personen“ pauschal Zugriff auf alle Geheimnisse zu, sondern Aufgaben und Ressourcen.

Entwicklung

• darf Preview-Variablen verwenden und ändern;
• darf keine Produktionsschlüssel lesen;
• darf Testdaten und isolierte Modellkonten nutzen;
• erhält keinen persönlichen Administratortoken für lokale Skripte.

Release-Verantwortliche

• darf Deployments starten und Produktionsvariablen aktualisieren;
• sollte Werte möglichst setzen oder rotieren, aber nicht unnötig anzeigen können;
• benötigt Zugriff auf die relevanten Projekte, nicht auf alle Server und Backups;
• muss Änderungen mit Ticket, Zeit und Rückfallplan dokumentieren.

Administration

• verwaltet Teammitgliedschaften, Ressourcen und Audit-Zugriff;
• kann Notfallwiederherstellung autorisieren;
• sollte nicht automatisch jede Anwendung im Tagesgeschäft betreiben;
• benötigt einen getrennten Notfallzugang mit dokumentierter Nutzung.

CI/CD oder Agent

• verwendet ein eigenes, widerrufbares Token;
• erhält nur die für Build oder Deployment benötigten Aktionen;
• bekommt keine interaktive Shell und keinen Zugriff auf nicht benötigte Projekte;
• darf niemals den persönlichen Token eines Owners verwenden.

OpenShip beschreibt vier Organisationsrollen und zusätzlich eingeschränkte Mitglieder mit konkreten Ressourcenzuweisungen. Wichtig ist die Vererbungslogik: Eine Freigabe auf Projektebene kann auch Deployments, Domains, Services und Umgebungsvariablen dieses Projekts einschließen. Prüfen Sie daher vor dem Erteilen einer Projektfreigabe, ob damit unabsichtlich auch der Zugriff auf sensible Variablen entsteht.

Führen Sie einen echten Berechtigungstest mit einem Testkonto durch. Melden Sie sich nicht als Administrator an und schließen daraus, dass die Einschränkung funktioniert. Prüfen Sie mit einem eingeschränkten Mitglied:

• Kann es die Variable nur setzen oder auch ihren Wert lesen?
• Kann es ein Produktionsdeployment starten?
• Kann es Serverterminals, Logs oder Backups öffnen?
• Erscheint die Aktion im Audit-Log?
• Bleibt der Zugriff nach Entzug der Projektfreigabe tatsächlich gesperrt?

Die offizielle Dokumentation ist hierbei eine Prüfgrundlage, nicht Ihre Abnahme. Besonders bei selbst gehosteten, Cloud- und gemischten Installationen müssen Sie die tatsächlich sichtbaren Menüs, API-Antworten und Rollenrechte der eingesetzten Version testen.

Fünfter Schritt: Wiederherstellung nach Serverausfall planen

Ein Server-Backup ist nicht automatisch eine vollständige Wiederherstellungsstrategie. Sie müssen drei Dinge getrennt betrachten:

1. Anwendungsdaten: Datenbank, Uploads, Konfiguration und Deployments.
2. Plattformkonfiguration: Projektdefinitionen, Zielserver, Domains, Umgebungsvariablen, Rollen und Backup-Ziele.
3. Externe Schlüsselquelle: Secrets Vault, Anbieterportal oder kontrollierte Notfallkopie.

Wenn Sie nur die Anwendung sichern, kann der neue Server zwar Dateien enthalten, aber keine gültigen Zugangsdaten besitzen. Wenn Sie nur eine .env kopieren, fehlt möglicherweise die Plattformkonfiguration für Domain, Container, Netzwerk oder Deployment. Wenn Sie nur die Plattformdaten sichern, aber den Zugang zum externen Vault oder zur zentralen Identität verlieren, bleibt die Anwendung ebenfalls stehen.

Erstellen Sie deshalb vor dem Produktivstart einen Wiederherstellungsablauf:

1. Einen neuen oder leeren Zielserver bereitstellen.
2. OpenShip in der vorgesehenen Betriebsform installieren.
3. Plattform- und Anwendungsdaten aus einer verschlüsselten Sicherung wiederherstellen.
4. Die Berechtigung der verantwortlichen Person oder des Notfallkontos erneut herstellen.
5. Geheimnisse aus der vorgesehenen Quelle injizieren, ohne sie in Klartextdateien abzulegen.
6. Die Anwendung in einer isolierten Wiederherstellungsumgebung starten.
7. Gesundheitsprüfung, Modellanfrage, Datenbankverbindung und Webhook-Verhalten testen.
8. Erst danach DNS oder produktiven Verkehr umschalten.

Die Sicherung darf keine unverschlüsselte Produktions-.env in einem allgemein zugänglichen Cloud-Speicher enthalten. Verschlüsseln Sie die Datei vor der Ablage, beschränken Sie den Zugriff auf wenige berechtigte Personen und dokumentieren Sie, wer im Notfall die Entschlüsselung oder erneute Autorisierung durchführen darf.

OpenShip beschreibt Backups als Teil der von der API verwalteten Plattformdaten und unterscheidet lokale, serverbasierte und Cloud-Ziele. Für die Planung ist entscheidend, wo Ihre Daten kanonisch liegen und welche Komponenten bei einem Wechsel des Zielsystems neu autorisiert werden müssen. Die Architektur- und Datenverantwortungsdokumentation sollte deshalb gemeinsam mit Ihrer eigenen Wiederherstellungsanleitung geprüft werden.

Die passende Ablage nach Geheimnistyp auswählen

Eine pauschale Entscheidung „alles in OpenShip“ oder „alles auf den Server“ ist für produktive AI-Systeme zu grob. Teilen Sie die Werte nach ihrer Aufgabe auf:

• Anwendungsschlüssel: Modellanbieter, E-Mail-Dienst, Zahlungs- oder Such-API gehören normalerweise in projekt- und umgebungsgebundene Plattformvariablen.
• Infrastrukturzugänge: SSH-Schlüssel, lokale Dienstkonten und Betriebssystemwerte bleiben auf dem Zielsystem, wenn nur der Serverprozess sie benötigt.
• Kurzlebige Tokens: CI/CD- oder Agent-Tokens sollten separat, eingeschränkt und widerrufbar sein.
• Hochsensible Produktionswerte: Für Datenbanken mit weitreichenden Rechten, Signaturschlüssel und zentrale Identitäten ist ein Secrets Vault sinnvoll, sofern Sie Betrieb, Zugriff und Wiederherstellung tatsächlich leisten können.

Verwenden Sie einen Secrets Vault nicht als Sicherheitsdekoration. Ein zusätzlicher Dienst erhöht die Zahl der Abhängigkeiten: Ihre Anwendung braucht eine Identität, Netzwerkzugriff, eine Autorisierung und einen funktionierenden Wiederherstellungsweg. Für ein kleines Preview-Projekt kann eine gut getrennte Plattformvariable sicherer und leichter prüfbar sein als ein unvollständig betriebener Vault. Für ein wachsendes Produktionssystem mit mehreren Anwendungen und häufigen Rotationen kann die zusätzliche Zentralisierung dagegen gerechtfertigt sein. Die OWASP-Empfehlungen für Secrets Management eignen sich als unabhängige Prüfbasis für Lebenszyklus, Zugriff und Rotation.

Nutzen Sie diese Entscheidungsliste vor jedem produktiven Deployment:

• [ ] Kein Produktionsschlüssel befindet sich in Git, Dockerfile, Build-Argumenten oder Client-Bundles.
• [ ] Preview, Test und Produktion besitzen getrennte Modell-, Datenbank- und Webhook-Zugänge.
• [ ] Jede Variable hat einen Besitzer, einen Zweck und einen dokumentierten Rotationsweg.
• [ ] Der neue Schlüssel wird mit einer echten Anfrage geprüft, bevor der alte widerrufen wird.
• [ ] Der Prozessneustart nach einer Änderung ist bekannt und getestet.
• [ ] CI/CD und Agenten verwenden eigene, eingeschränkte Tokens.
• [ ] Entwickler können keine Produktionswerte lesen, wenn sie diese nicht benötigen.
• [ ] Audit-Einträge zeigen, wer Variablen oder Berechtigungen geändert hat.
• [ ] Plattformkonfiguration, Anwendungsdaten und externe Schlüsselquelle sind getrennt gesichert.
• [ ] Eine Wiederherstellung wurde auf einem isolierten Zielsystem vollständig durchgeführt.
• [ ] Die Notfallrolle kann ohne persönliche Dauerzugänge neu autorisieren.
• [ ] Nach dem Entzug einer Berechtigung ist der alte Zugriff tatsächlich nicht mehr möglich.

Entscheidung für die Praxis

Für die meisten Teams lautet die belastbare Standardentscheidung daher: Anwendungsschlüssel in die getrennte OpenShip-Umgebung, Infrastrukturwerte auf den Zielserver, besonders kritische Produktionswerte in einen Secrets Vault – aber nur mit nachgewiesener Rotation und Wiederherstellung.

Wenn Sie OpenShip auf einem eigenen Server betreiben, müssen Sie außerdem den Rechner berücksichtigen, von dem aus Sie deployen. Ein gemeinsam genutztes Notebook, ein dauerhaft eingeloggter CLI-Kontext oder ein ungeschützter Remote-Build-Rechner kann die beste Plattformkonfiguration wieder aushebeln. Prüfen Sie vor dem nächsten Release, ob Ihre Build-Umgebung dauerhaft erreichbar ist, ob Teammitglieder persönliche Zugangsdaten teilen und ob die Übergabe zwischen Mac, CI/CD und Zielserver getrennte Berechtigungen besitzt.

Für temporäre Entwicklungs- oder Build-Umgebungen kann eine konfigurierbare Mac-Arbeitsumgebung sinnvoller sein als ein gemeinsam genutztes Gerät mit dauerhaft gespeicherten Tokens. Bei Fragen zur sicheren Übergabe und Betriebsorganisation finden Sie außerdem konkrete Unterstützung im Hilfezentrum von Macstripe.