Geheimnisse über passwork-cli verwalten

Was ist passwork-cli

passwork-cli ist ein Befehlszeilentool zur Interaktion mit Passwork-Geheimnissen. Hauptfunktionen:

Funktion	Beschreibung
Geheimnis abrufen	Passwörter, Felder und TOTP-Codes per Eintrags-ID abrufen
Umgebungsinjektion	Befehle mit in Umgebungsvariablen geladenen Geheimnissen ausführen
Geheimnisse aktualisieren	Passwörter und Felder ändern — nützlich für Rotation und Automatisierung
Direkter API-Zugriff	Beliebige HTTP-Anfragen an Passwork senden

Zero-Knowledge

passwork-cli übernimmt die Verschlüsselung lokal: Der Passwork-Server speichert nur verschlüsselte Daten, während die Ent- und Verschlüsselung auf Ihrem Rechner stattfindet. Selbst wenn der Netzwerkverkehr abgefangen oder der Server kompromittiert wird, können Angreifer nicht auf Ihre Geheimnisse zugreifen.

Installation

Python-Paket (pip)

passwork-cli wird als Teil des Python-Connectors ausgeliefert. Installation mit pip:

# PyPI
pip install passwork-python

# Or from GitHub via SSH
pip install git+ssh://[email protected]:passwork-me/passwork-python.git

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

Nach der Installation steht der Befehl passwork-cli in Ihrem Terminal zur Verfügung.

Docker-Image

Für CI/CD-Umgebungen oder Server ohne Python verwenden Sie das Docker-Image:

docker run --rm \
  -e PASSWORK_HOST="https://passwork.example.com" \
  -e PASSWORK_TOKEN="your_access_token" \
  -e PASSWORK_MASTER_KEY="your_master_key" \
  passwork/passwork-cli exec --password-id "<item-id>" ./deploy.sh

Siehe auch: Docker-Container für CLI.

Konfiguration

Konfigurieren Sie passwork-cli über Umgebungsvariablen:

Variable	Beschreibung	Erforderlich
PASSWORK_HOST	Passwork-Server-URL	Ja
PASSWORK_TOKEN	Zugriffstoken für die Authentifizierung	Ja
PASSWORK_MASTER_KEY	Masterschlüssel für die Entschlüsselung (falls zutreffend)	Abhängig von der Einrichtung

tipp

Speichern Sie in CI/CD PASSWORK_TOKEN und PASSWORK_MASTER_KEY als geschützte Variablen (GitLab CI Variables, GitHub Secrets usw.) — committen Sie sie niemals in Ihr Repository.

Betriebsmodi

passwork-cli bietet vier Modi. Wählen Sie basierend auf Ihrer Aufgabe:

Modus	Zweck	Verschlüsselung	Typischer Anwendungsfall
exec	Befehl mit Geheimnissen in ENV ausführen	Clientseitig	CI/CD, Deploy-Skripte
get	Einzelnen Wert an STDOUT ausgeben	Clientseitig	Bash-Skripte, Ad-hoc-Abfragen
update	Eintragsfelder ändern	Clientseitig	Passwortrotation
api	Rohe HTTP-Anfragen an die API senden	Manuell	Komplexe Automatisierung, Berichte

info

Die Modi exec, get und update übernehmen die Verschlüsselung automatisch. Der Modus api gibt rohe API-Antworten zurück — Sie verwalten die Verschlüsselung selbst.

Vollständige Dokumentation für jeden Modus: CLI-Tool.

exec — Befehle mit Geheimnissen ausführen

Ruft Geheimnisse ab, wandelt sie in Umgebungsvariablen um und führt den angegebenen Befehl aus. Geheimnisse existieren nur für die Dauer dieses Befehls.

# Run deploy script using secrets from a folder
passwork-cli exec --folder-id "<folder-id>" ./deploy.sh

# Run using secrets from a specific record
passwork-cli exec --password-id "<item-id>" ./app

Verwenden Sie dies, wenn: Sie CI/CD-Pipelines, Deploy-Skripte oder Anwendungen ausführen, die Geheimnisse benötigen.

Details: exec-Modus.

get — einzelnen Wert abrufen

Gibt einen entschlüsselten Wert an STDOUT aus. Ideal für schnelle Abfragen in Skripten.

# Retrieve password
passwork-cli get --password-id "<item-id>"

# Retrieve a custom field
passwork-cli get --password-id "<item-id>" --field API_KEY

# Retrieve a TOTP code
passwork-cli get --password-id "<item-id>" --totp

Verwenden Sie dies, wenn: Sie einen einzelnen Wert in einem Bash-Skript benötigen oder einen TOTP-Code generieren möchten.

Details: get-Modus.

update — Geheimnisse ändern

Ändert Eintragsfelder: Passwort, Login, URL, Beschreibung, Tags oder benutzerdefinierte Felder.

# Update password
passwork-cli update --password-id "<item-id>" --password "new-password"

# Update a custom field
passwork-cli update --password-id "<item-id>" --custom-field "API_KEY=new-api-key"

Verwenden Sie dies, wenn: Sie Passwörter rotieren, Schlüssel nach Neugenerierung aktualisieren oder Massenaktualisierungen durchführen.

Details: update-Modus.

api — direkte HTTP-Anfragen

Sendet beliebige Anfragen an die Passwork API und gibt JSON zurück.

# List vaults
passwork-cli api --method GET --endpoint "v1/vaults"

# Search by tags
passwork-cli api --method GET --endpoint "v1/items/search" \
  --params '{"tags":["infrastructure","production"]}'

Verwenden Sie dies, wenn: Sie komplexe Automatisierung erstellen, Berichte generieren oder Operationen durchführen, die von anderen Modi nicht abgedeckt werden.

Details: api-Modus.

Praktische Beispiele

CI/CD: Bereitstellung mit Geheimnissen

Ein häufiges Szenario — ein Bereitstellungsskript ausführen, das Geheimnisse aus Passwork abruft.

GitLab CI:

deploy:
  image: passwork/passwork-cli
  variables:
    PASSWORK_HOST: $PASSWORK_HOST
    PASSWORK_TOKEN: $PASSWORK_TOKEN
    PASSWORK_MASTER_KEY: $PASSWORK_MASTER_KEY
  script:
    - passwork-cli exec --folder-id "$SECRETS_FOLDER_ID" ./deploy.sh

GitHub Actions:

- name: Deploy with secrets
  run: |
    docker run --rm \
      -e PASSWORK_HOST="${{ secrets.PASSWORK_HOST }}" \
      -e PASSWORK_TOKEN="${{ secrets.PASSWORK_TOKEN }}" \
      -e PASSWORK_MASTER_KEY="${{ secrets.PASSWORK_MASTER_KEY }}" \
      -v $(pwd):/app -w /app \
      passwork/passwork-cli exec --folder-id "${{ vars.SECRETS_FOLDER_ID }}" ./deploy.sh

Rotation eines Datenbankpassworts

Ein neues Passwort generieren, auf die Datenbank anwenden und in Passwork speichern.

#!/bin/bash
set -e

# Generate a fresh password
NEW_PASS=$(openssl rand -base64 32)

# Apply to PostgreSQL
psql -h db.prod.internal -U postgres -c \
  "ALTER ROLE backend_svc WITH PASSWORD '${NEW_PASS}';"

# Store in Passwork
passwork-cli update \
  --password-id "<item-id>" \
  --password "${NEW_PASS}"

echo "Password rotated successfully"

Geheimnis in einem Bash-Skript abrufen

Wenn Sie nur einen einzelnen Wert benötigen:

# Grab the DB password and use it immediately
DB_PASS=$(passwork-cli get --password-id "<item-id>")
psql -h db.internal -U webapp -W "$DB_PASS" -d orders -c "SELECT 1"

# Get an API key from a custom field
STRIPE_KEY=$(passwork-cli get --password-id "<item-id>" --field STRIPE_SECRET)
curl -H "Authorization: Bearer $STRIPE_KEY" https://api.stripe.com/v1/charges

Docker Compose mit Geheimnissen

Container mit über exec injizierten Geheimnissen starten:

# Start docker compose with secrets in the environment
passwork-cli exec --folder-id "<folder-id>" docker compose up -d

In docker-compose.yml sind Geheimnisse als Umgebungsvariablen verfügbar:

services:
  api:
    image: order-service:latest
    environment:
      - MYSQL_HOST=${MYSQL_HOST}
      - MYSQL_USER=${MYSQL_USER}
      - MYSQL_PASSWORD=${MYSQL_PASSWORD}