FAQ und Best Practices

Sicherheit und Architektur

Was passiert, wenn ich den Masterpasswort verliere?

Ohne das Masterpasswort ist die Entschlüsselung von Geheimnissen unmöglich — eine direkte Folge der Zero-Knowledge-Architektur. Der Server speichert keine Schlüssel und kann bei der Wiederherstellung nicht helfen.

Was Sie tun können:

• Speichern Sie bei Dienstkonten das Masterpasswort in geschützten CI-Variablen und an einem separaten sicheren Ort (Tresor oder HSM).
• Stellen Sie bei Benutzern sicher, dass Ihr Administrator das Passwort zurücksetzen und neuen Tresorzugang gewähren kann.

Was kann der Passwork-Serveradministrator sehen?

Ein Administrator, der die Passwork-Infrastruktur verwaltet, kann Folgendes einsehen:

Sichtbar	Nicht sichtbar
Tresor- und Ordnerstruktur	Entschlüsselte Passwörter
Datensatznamen	Feldwerte
Metadaten (Tags, Daten)	Inhalte von Anhängen
Audit-Protokoll	Verschlüsselungsschlüssel der Benutzer

Selbst mit vollem Server- und Datenbankzugriff kann der Administrator keine Geheimnisse lesen.

Kann Zero-Knowledge deaktiviert werden?

In der selbst gehosteten Version von Passwork ist die clientseitige Verschlüsselung (Zero-Knowledge) das Grundprinzip der Architektur. In einer bereits installierten Instanz ist es unmöglich, sie ein- oder auszuschalten: Die Wahl des Modus wird im Einrichtungsassistenten festgelegt.

Was tun, wenn ein CI-Token kompromittiert wurde?

1. Widerrufen Sie das Token sofort — über die Einstellungen des Dienstkontos.
2. Überprüfen Sie das Audit-Protokoll — identifizieren Sie, welche Operationen das Token durchgeführt hat.
3. Rotieren Sie betroffene Geheimnisse — jedes Geheimnis, auf das das kompromittierte Konto zugreifen konnte.
4. Erstellen Sie ein neues Token — aktualisieren Sie es in Ihrem CI-System.

tipp

Verwenden Sie separate Dienstkonten pro CI-Pipeline. So werden bei einem kompromittierten Token nicht alle Geheimnisse offengelegt.

Arbeiten mit CLI und SDK

Warum benötigt die CLI sowohl ein Zugriffstoken als auch ein Masterpasswort?

• Zugriffstoken — authentifiziert Sie bei der Passwork-API.
• Masterpasswort — entschlüsselt Daten lokal (Zero-Knowledge).

Ohne das Zugriffstoken können Sie keine verschlüsselten Daten abrufen. Ohne das Masterpasswort können Sie sie nicht entschlüsseln.

Wie ruft die CLI Daten ab?

Wenn Sie passwork-cli ausführen, geschieht Folgendes:

1. Authentifizierung beim Server.
2. Herunterladen verschlüsselter Datensätze aus dem angegebenen Ordner.
3. Lokale Entschlüsselung.
4. Einfügen der Werte in Umgebungsvariablen oder Ausgabe auf STDOUT.

Es gibt kein Caching zwischen den Aufrufen — jeder Aufruf ruft aktuelle Daten vom Server ab.

Wie werden Aktualisierungskonflikte behandelt?

Passwork verwendet optimistisches Sperren. Wenn zwei Clients gleichzeitig denselben Datensatz aktualisieren:

1. Der erste Vorgang ist erfolgreich.
2. Der zweite erhält einen Konfliktfehler.
3. Der zweite Client muss den Datensatz neu laden und es erneut versuchen.

Im Python SDK:

try:
    client.update_password(item)
except ConflictError:
    # Reload and try again
    item = client.get_password(item_id=item.id)
    item.password = new_password
    client.update_password(item)

Kann ich die CLI ohne Docker verwenden?

Selbstverständlich. passwork-cli ist ein Python-Paket, das Sie über pip installieren können:

pip install passwork-python

# Or from GitHub
pip install git+https://github.com/passwork-me/passwork-python.git

Docker ist praktisch für CI/CD, wenn Sie keine Python-Umgebung verwalten möchten.

Organisation von Geheimnissen

Wie sollte ich Ordner für mehrere Teams strukturieren?

Ein Beispiel für eine Organisation mit mehreren Produkten:

infrastructure/
├── shared/             # Shared infrastructure
│   ├── production/
│   └── staging/
├── orders-team/        # Orders service team
│   ├── production/
│   ├── staging/
│   └── development/
└── payments-team/      # Payments service team
    ├── production/
    └── staging/

Zugriffsrechte:

• Orders-Team → nur orders-team/*
• Payments-Team → nur payments-team/*
• Plattform-Ingenieure → alle Ordner
• CI/CD-Dienstkonten → schreibgeschützter Zugriff auf bestimmte Ordner

Wie sollte ich Datensätze für die Automatisierung benennen?

Verwenden Sie vorhersehbare, beschreibende Namen:

# Good — purpose is obvious
mysql-orders-prod
elasticsearch-logs
sendgrid-api-key

# Avoid — requires opening to understand
creds-1
temp-secret
abc123

Bei Verwendung von exec mit einem Ordner werden Datensatznamen zu Umgebungsvariablen. Verwenden Sie UPPER_SNAKE_CASE:

MYSQL_PASSWORD
ELASTIC_AUTH
SENDGRID_API_KEY

Sollte ich mehrere zusammengehörige Geheimnisse in einem Datensatz speichern?

Ja, wenn die Geheimnisse logisch zusammengehören und gemeinsam verwendet werden:

Record: mysql-orders-prod
├── login: order_service
├── password: ...
├── MYSQL_HOST: mysql.prod.internal
├── MYSQL_PORT: 3306
└── MYSQL_DATABASE: orders

Nein, wenn die Geheimnisse unabhängig sind oder nach unterschiedlichen Zeitplänen rotiert werden.

Rotation und Lebenszyklus

Warum rotiert Passwork Geheimnisse nicht automatisch?

Zero-Knowledge bedeutet, dass der Server keinen Zugriff auf entschlüsselte Daten hat. Die Rotation erfordert:

1. Entschlüsselung des aktuellen Werts (benötigt Client-Schlüssel).
2. Generierung eines neuen Werts.
3. Aktualisierung des Zielsystems (Datenbank, Dienst).
4. Verschlüsselung und Speicherung des neuen Werts.

Die Schritte 1, 3 und 4 erfordern einen Client mit Schlüsseln und Zugriff auf das Zielsystem. Der Server verfügt nicht darüber.

Kann ich ein gelöschtes Geheimnis wiederherstellen?

Die Wiederherstellung hängt von den Servereinstellungen ab (Papierkorb, vorläufiges Löschen). Wenden Sie sich an Ihren Administrator.

warnung

Erstellen Sie immer eine Sicherungskopie vor Massenoperationen und testen Sie Skripte zunächst in einer Staging-Umgebung.

Migration und Integration

Wie migriere ich von einem anderen Secrets-Manager?

Allgemeiner Ansatz:

1. Exportieren Sie Geheimnisse aus dem alten System (üblicherweise JSON oder YAML).
2. Schreiben Sie ein Skript, um die Daten in die Passwork-Struktur umzuwandeln.
3. Importieren Sie über das Python SDK (create_password).

Siehe den Abschnitt Python SDK für ein Migrationsbeispiel mit .env-Dateien.

Wie integriere ich Passwork mit Terraform?

Es gibt keinen offiziellen Terraform-Provider, aber Sie können:

1. Eine external-Datenquelle mit passwork-cli get verwenden.
2. Ein Wrapper-Skript schreiben, das Geheimnisse liest und an Terraform weitergibt.

data "external" "db_password" {
  program = ["bash", "-c", "passwork-cli get --password-id $ID --json"]
}

resource "aws_db_instance" "main" {
  password = data.external.db_password.result.password
}