CLI e inyección de secretos
La CLI de Passwork es la herramienta principal para la inyección de secretos en scripts de shell y canalizaciones de CI/CD. Recupera los secretos de Passwork, los descifra localmente (gestionando el CSE de forma transparente) y los pone a disposición como variables de entorno o salida estándar, sin que el secreto aparezca nunca en el historial del shell ni en los archivos de script.
Instalación
- 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
Requisitos:
- Python 3.10+
- requests>=2.31.0,
- python-dotenv>=1.0.0
- cryptography>=42.0.0
- pbkdf2>=1.3
Imagen de Docker
Para entornos en contenedores y ejecutores de CI/CD, utilice la imagen oficial de Docker:
docker pull passwork/passwork-cli:latest
Variables de entorno de autenticación
Todos los modos de la CLI leen las credenciales de las variables de entorno. Defínalas antes de ejecutar cualquier comando de passwork-cli:
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
Como alternativa, páselas como marcadores: --host, --token, --refresh-token, --master-key.
Si el cifrado del lado del cliente está desactivado en su instancia de Passwork, omita PASSWORK_MASTER_KEY y --master-key. La CLI funciona sin ellos.
Modo exec: inyectar secretos en un proceso
exec es el modo principal para la inyección de secretos. Obtiene los registros especificados, los descifra, los establece como variables de entorno y ejecuta el comando que usted especifique con esas variables en su ámbito. Las variables existen solo durante la duración del proceso: nunca se escriben en el disco ni en el historial del shell.
Sintaxis
passwork-cli exec [selection parameters] command_to_execute
Parámetros de selección
| Parámetro | Descripción |
|---|---|
--password-id <id> | ID de un único elemento (o varios separados por comas) |
--folder-id <id> | Todos los elementos de una carpeta (o de varias carpetas separadas por comas) |
--vault-id <id> | Todos los elementos de una bóveda |
--tags <tag1,tag2> | Todos los elementos que coinciden con las etiquetas indicadas |
Nomenclatura de las variables
El nombre del elemento se convierte en el nombre de la variable de entorno. Los espacios y los caracteres especiales se sustituyen por guiones bajos _. Los nombres de los campos personalizados se convierten en sus propias variables.
Un registro llamado POSTGRES_PASSWORD con el campo personalizado DB_HOST → inyecta POSTGRES_PASSWORD y DB_HOST.
Ejemplos
Ejecutar una migración de base de datos con credenciales de una carpeta:
- shell
passwork-cli exec --folder-id "prod-databases-folder-id" \
./migrate.sh
Ejecutar un comando que necesita credenciales de BD específicas por ID de elemento:
- shell
passwork-cli exec --password-id "postgres-order-svc-id" \
psql -h "$DB_HOST" -U "$DB_USER" -d orders
Ejecutar un comando complejo con tuberías (utilice --cmd):
- shell
passwork-cli exec --password-id "server-creds-id" \
--cmd "ssh user@server 'journalctl -u app | tail -100' > errors.log"
Obtener todas las credenciales de API de producción por etiqueta:
- shell
passwork-cli exec --tags "production,external-api" \
./sync-integrations.sh
Modo get: recuperar un valor específico
get descifra un único campo de un elemento y lo escribe en stdout. Utilícelo cuando un script necesite capturar el valor de un secreto en una variable.
passwork-cli get --password-id "<item_id>" [--field <field_name>]
Sin --field, get devuelve el campo de contraseña. Con --field, devuelve el campo personalizado indicado.
- 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")
Nunca ejecute echo $DB_PASS en los scripts. Utilice el valor directamente en el comando que lo necesita. El historial del shell y los registros de CI/CD capturan los argumentos de los comandos, no los valores de las variables de entorno.
Modo update: rotar el valor de un secreto
update escribe un nuevo valor en un campo especificado de un elemento existente de Passwork. Utilícelo en los scripts de rotación después de actualizar el secreto en el sistema de destino.
passwork-cli update --password-id "<item_id>" --password "<new_value>"
Para los campos personalizados:
passwork-cli update --password-id "<item_id>" \
--field "AWS_SECRET_ACCESS_KEY" --value "<new_key>"
Consulte Rotación de secretos para conocer los flujos de trabajo de rotación completos.
Modo api: llamadas directas a la API
api envía una solicitud arbitraria a la API y devuelve la respuesta JSON. Utilícelo para operaciones no cubiertas por los otros modos, o para inspeccionar los datos de Passwork desde los scripts.
- 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>"
Imagen de Docker
Utilice passwork/passwork-cli:latest en entornos donde no sea práctico instalar paquetes de Python.
- 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
La imagen de Docker se ejecuta como un usuario sin privilegios de root. Para el uso en canalizaciones de CI/CD, consulte Patrones de CI/CD.
Para consultar la documentación completa de la CLI, consulte Utilidad CLI y Contenedor de Docker para la CLI.