Geheimnisse über das Python SDK verwalten

Was ist das Python SDK

Das Python SDK ist eine Bibliothek für die programmatische Interaktion mit Passwork. Es ist für erweiterte Automatisierung konzipiert, bei der die CLI-Funktionen nicht ausreichen.

Funktion	Beschreibung
Geheimnisse lesen	Passwörter, Felder und Anhänge per ID oder Suche abrufen
Geheimnisse ändern	Passwörter, Felder, Tags und Beschreibungen aktualisieren
Geheimnisse erstellen	Einträge programmatisch in bestimmten Ordnern erstellen
Struktur verwalten	Mit Ordnern und Tresoren arbeiten, Einträge verschieben

Wann SDK vs. CLI verwenden

Szenario	Empfehlung
CI/CD-Pipeline, Deploy-Skript	passwork-cli — einfacher, kein Code erforderlich
Passwortrotation mit benutzerdefinierter Logik	Python SDK — mehr Flexibilität, bessere Fehlerbehandlung
Migration von einem anderen System	Python SDK — Daten nach Bedarf transformieren
Prüfung der Geheimnis-Integrität	Python SDK — komplexe Validierung implementieren
Einzelnes Geheimnis in Bash abrufen	passwork-cli get — nur ein Befehl

Installation

Installation mit pip von GitHub:

# 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

Siehe auch: Python-Connector.

Client initialisieren

from passwork import Client

client = Client(
    url="https://passwork.example.com",
    token="your_access_token",
)

tipp

Vermeiden Sie die Hardcodierung von Token in Ihrem Code. Verwenden Sie stattdessen Umgebungsvariablen:

import os
from passwork import Client

client = Client(
    url=os.environ["PASSWORK_HOST"],
    token=os.environ["PASSWORK_TOKEN"],
)

Geheimnisse lesen

Per Eintrags-ID

item = client.get_password(item_id="<item-id>")

# Standard fields
print(item.login)
print(item.password)

# Custom fields
db_host = item.fields["MYSQL_HOST"]
stripe_key = item.fields["STRIPE_SECRET"]

Per Ordner

# Fetch all records from a folder
items = client.list_folder_items(folder_id="<folder-id>")

for item in items:
    print(f"{item.title}: {item.login}")

Per Suchbegriff

# Find records matching a query
items = client.search("mysql production")

for item in items:
    print(f"{item.id}: {item.title}")

Geheimnisse ändern

Bestehenden Eintrag aktualisieren

# Load the record
item = client.get_password(item_id="<item-id>")

# Change fields
item.password = "Jk8$mNp#2xLq!9Wz"
item.fields["STRIPE_SECRET"] = "sk_live_abc123xyz"

# Persist changes
client.update_password(item)

Neuen Eintrag erstellen

client.create_password(
    folder_id="<folder-id>",
    title="MySQL Primary",
    login="backend_svc",
    password="Tm4#kL9$pQ2!xZ7",
    fields={
        "MYSQL_HOST": "mysql.prod.internal",
        "MYSQL_PORT": "3306",
    },
    tags=["production", "db"],
)

Massenoperationen

Das SDK ermöglicht Automatisierung wie:

• Einträge zwischen Ordnern verschieben;
• Tags in großen Mengen hinzufügen oder entfernen;
• Felder basierend auf einer Vorlage aktualisieren;
• die secrets/*-Hierarchie migrieren.

# Add a tag to all records in a folder
items = client.list_folder_items(folder_id="<folder-id>")

for item in items:
    if "legacy" not in item.tags:
        item.tags.append("legacy")
        client.update_password(item)

Praktische Beispiele

Rotation eines Datenbankpassworts

Vollständiges Beispiel mit Fehlerbehandlung für PostgreSQL-Passwortrotation:

import os
import secrets
import psycopg2
from passwork import Client

def rotate_db_password(item_id: str, db_user: str):
    """Rotate the password for a PostgreSQL user."""
    
    # Set up the client
    client = Client(
        url=os.environ["PASSWORK_HOST"],
        token=os.environ["PASSWORK_TOKEN"],
    )
    
    # Create a fresh password
    new_password = secrets.token_urlsafe(32)
    
    # Retrieve admin credentials for the DB connection
    admin_item = client.get_password(item_id=os.environ["PG_ADMIN_ITEM_ID"])
    
    try:
        # Apply the new password in PostgreSQL
        conn = psycopg2.connect(
            host=admin_item.fields["PG_HOST"],
            dbname="postgres",
            user=admin_item.login,
            password=admin_item.password,
        )
        conn.autocommit = True
        
        with conn.cursor() as cur:
            cur.execute(
                "ALTER ROLE %s WITH PASSWORD %s",
                (db_user, new_password)
            )
        
        conn.close()
        
        # Store the updated password in Passwork
        item = client.get_password(item_id=item_id)
        item.password = new_password
        client.update_password(item)
        
        print(f"Password rotated for {db_user}")
        return True
        
    except Exception as e:
        print(f"Rotation failed: {e}")
        return False

# Usage
rotate_db_password(
    item_id="<item-id>",
    db_user="order_service"
)

Prüfung der Geheimnisgültigkeit

Skript, das gespeicherte Anmeldedaten regelmäßig auf Funktionsfähigkeit überprüft:

import os
import psycopg2
from passwork import Client

def check_db_credentials(folder_id: str):
    """Verify that database credentials in Passwork are valid."""
    
    client = Client(
        url=os.environ["PASSWORK_HOST"],
        token=os.environ["PASSWORK_TOKEN"],
    )
    
    items = client.list_folder_items(folder_id=folder_id)
    broken = []
    
    for item in items:
        if "db" not in item.tags:
            continue
            
        try:
            conn = psycopg2.connect(
                host=item.fields.get("PG_HOST"),
                dbname=item.fields.get("PG_DATABASE", "postgres"),
                user=item.login,
                password=item.password,
                connect_timeout=5,
            )
            conn.close()
            print(f"[OK] {item.title}")
            
        except Exception as e:
            print(f"[FAIL] {item.title}: {e}")
            broken.append(item)
            
            # Flag the record for review
            if "stale" not in item.tags:
                item.tags.append("stale")
                client.update_password(item)
    
    return broken

# Usage
broken = check_db_credentials(folder_id="<infrastructure/production/databases>")
if broken:
    print(f"\n{len(broken)} secrets need review")

Geheimnisse aus Dateien importieren

Geheimnisse aus .env-Dateien in Passwork migrieren:

import os
from pathlib import Path
from passwork import Client

def migrate_env_file(env_path: str, folder_id: str, tags: list):
    """Import secrets from a .env file into Passwork."""
    
    client = Client(
        url=os.environ["PASSWORK_HOST"],
        token=os.environ["PASSWORK_TOKEN"],
    )
    
    env_file = Path(env_path)
    secrets_dict = {}
    
    # Parse the .env file
    for line in env_file.read_text().splitlines():
        line = line.strip()
        if not line or line.startswith("#"):
            continue
        if "=" in line:
            key, value = line.split("=", 1)
            secrets_dict[key.strip()] = value.strip().strip('"\'')
    
    # Store in Passwork
    client.create_password(
        folder_id=folder_id,
        title=env_file.stem,
        fields=secrets_dict,
        tags=tags,
    )
    
    print(f"Imported {len(secrets_dict)} secrets from {env_path}")

# Usage
migrate_env_file(
    env_path="./legacy/.env.production",
    folder_id="<infrastructure/production/backend>",
    tags=["production", "imported"],
)