CLI und Secret-Injection
Passwork CLI ist das primäre Werkzeug für die Secret-Injection in Shell-Skripten und CI/CD-Pipelines. Es ruft Secrets aus Passwork ab, entschlüsselt sie lokal (wobei CSE transparent verarbeitet wird) und stellt sie als Umgebungsvariablen oder in der Standardausgabe bereit — ohne dass das Secret jemals in der Shell-Historie oder in Skriptdateien erscheint.
Installation
- PyPI
- GitHub (SSH)
- GitHub (HTTPS)
pip install passwork-python
pip install git+ssh://[email protected]:passwork-me/passwork-python.git
pip install git+https://github.com/passwork-me/passwork-python.git
Voraussetzungen:
- Python 3.10+
- requests>=2.31.0,
- python-dotenv>=1.0.0
- cryptography>=42.0.0
- pbkdf2>=1.3
Docker-Image
Für containerisierte Umgebungen und CI/CD-Runner verwenden Sie das offizielle Docker-Image:
docker pull passwork/passwork-cli:latest
Umgebungsvariablen für die Authentifizierung
Alle CLI-Modi lesen die Anmeldedaten aus Umgebungsvariablen. Setzen Sie diese, bevor Sie einen passwork-cli-Befehl aufrufen:
export PASSWORK_HOST="https://passwork.example.com"
export PASSWORK_TOKEN="<access_token>"
export PASSWORK_REFRESH_TOKEN="<refresh_token>" # optional, enables auto-renewal
export PASSWORK_MASTER_KEY="<master_key>" # required only if CSE is enabled
Alternativ können Sie sie als Flags übergeben: --host, --token, --refresh-token, --master-key.
Wenn die client-seitige Verschlüsselung in Ihrer Passwork-Instanz deaktiviert ist, lassen Sie PASSWORK_MASTER_KEY und --master-key weg. Die CLI funktioniert auch ohne diese.
Exec-Modus — Secrets in einen Prozess einschleusen
exec ist der Kernmodus für die Secret-Injection. Es ruft die angegebenen Datensätze ab, entschlüsselt sie, setzt sie als Umgebungsvariablen und führt den von Ihnen angegebenen Befehl mit diesen Variablen im Geltungsbereich aus. Die Variablen existieren nur für die Dauer des Prozesses — sie werden niemals auf die Festplatte oder in die Shell-Historie geschrieben.
Syntax
passwork-cli exec [selection parameters] command_to_execute
Auswahlparameter
| Parameter | Beschreibung |
|---|---|
--password-id <id> | Einzelne Element-ID (oder mehrere durch Komma getrennt) |
--folder-id <id> | Alle Elemente aus einem Ordner (oder mehrere durch Komma getrennte Ordner) |
--vault-id <id> | Alle Elemente aus einem Tresor |
--tags <tag1,tag2> | Alle Elemente, die den angegebenen Tags entsprechen |
Benennung von Variablen
Der Name des Elements wird zum Namen der Umgebungsvariable. Leerzeichen und Sonderzeichen werden durch einen Unterstrich _ ersetzt. Benutzerdefinierte Feldnamen werden zu eigenen Variablen.
Ein Datensatz mit dem Namen POSTGRES_PASSWORD und dem benutzerdefinierten Feld DB_HOST → schleust POSTGRES_PASSWORD und DB_HOST ein.
Beispiele
Eine Datenbankmigration mit Anmeldedaten aus einem Ordner ausführen:
- shell
passwork-cli exec --folder-id "prod-databases-folder-id" \
./migrate.sh
Einen Befehl ausführen, der bestimmte DB-Anmeldedaten per Element-ID benötigt:
- shell
passwork-cli exec --password-id "postgres-order-svc-id" \
psql -h "$DB_HOST" -U "$DB_USER" -d orders
Einen komplexen Befehl mit Pipes ausführen (verwenden Sie --cmd):
- shell
passwork-cli exec --password-id "server-creds-id" \
--cmd "ssh user@server 'journalctl -u app | tail -100' > errors.log"
Alle Produktions-API-Anmeldedaten per Tag abrufen:
- shell
passwork-cli exec --tags "production,external-api" \
./sync-integrations.sh
Get-Modus — einen bestimmten Wert abrufen
get entschlüsselt ein einzelnes Feld eines Elements und schreibt es in stdout. Verwenden Sie dies, wenn ein Skript einen Secret-Wert in eine Variable erfassen muss.
passwork-cli get --password-id "<item_id>" [--field <field_name>]
Ohne --field gibt get das Passwortfeld zurück. Mit --field gibt es das benannte benutzerdefinierte Feld zurück.
- shell
# Store the value in a variable (does not appear in process list)
DB_PASS=$(passwork-cli get --password-id "postgres-prod-id")
# Get a specific custom field
AWS_KEY=$(passwork-cli get --password-id "aws-creds-id" --field "AWS_SECRET_ACCESS_KEY")
Verwenden Sie in Skripten niemals echo $DB_PASS. Nutzen Sie den Wert direkt in dem Befehl, der ihn benötigt. Shell-Historie und CI/CD-Logs erfassen die Befehlsargumente — nicht die Werte der Umgebungsvariablen.
Update-Modus — einen Secret-Wert rotieren
update schreibt einen neuen Wert in ein angegebenes Feld eines bestehenden Passwork-Elements. Verwenden Sie dies in Rotationsskripten, nachdem Sie das Secret im Zielsystem aktualisiert haben.
passwork-cli update --password-id "<item_id>" --password "<new_value>"
Für benutzerdefinierte Felder:
passwork-cli update --password-id "<item_id>" \
--field "AWS_SECRET_ACCESS_KEY" --value "<new_key>"
Vollständige Rotations-Workflows finden Sie unter Secret-Rotation.
API-Modus — rohe API-Aufrufe
api sendet einen beliebigen API-Request und gibt die JSON-Antwort zurück. Verwenden Sie es für Operationen, die von den anderen Modi nicht abgedeckt werden, oder um Passwork-Daten aus Skripten zu inspizieren.
- shell
# List all vaults
passwork-cli api --method GET --endpoint "v1/vaults"
# Get a specific item
passwork-cli api --method GET --endpoint "v1/items/<item_id>"
Docker-Image
Verwenden Sie passwork/passwork-cli:latest in Umgebungen, in denen die Installation von Python-Paketen nicht praktikabel ist.
- One-shot
- Docker Compose
docker run --rm \
-e PASSWORK_HOST="https://passwork.example.com" \
-e PASSWORK_TOKEN="$PASSWORK_TOKEN" \
-e PASSWORK_MASTER_KEY="$PASSWORK_MASTER_KEY" \
-v "$(pwd)":/app -w /app \
passwork/passwork-cli:latest \
exec --folder-id "$SECRETS_FOLDER_ID" ./deploy.sh
services:
deploy:
image: passwork/passwork-cli:latest
environment:
PASSWORK_HOST: ${PASSWORK_HOST}
PASSWORK_TOKEN: ${PASSWORK_TOKEN}
PASSWORK_MASTER_KEY: ${PASSWORK_MASTER_KEY}
volumes:
- .:/app
working_dir: /app
command: exec --folder-id "${SECRETS_FOLDER_ID}" ./deploy.sh
Das Docker-Image läuft als Non-Root-Benutzer. Zur Nutzung in CI/CD-Pipelines siehe CI/CD-Muster.
Die vollständige CLI-Dokumentation finden Sie unter CLI-Werkzeug und Docker-Container für die CLI.