Управление секретами через passwork-cli

Что такое passwork-cli

passwork-cli — консольная утилита для работы с секретами Пассворка. Основные возможности:

Возможность	Описание
Получение секретов	Чтение пароля, полей, TOTP-кодов по ID записи
Подстановка в окружение	Запуск команд с секретами в переменных окружения
Обновление секретов	Изменение значения пароля и других полей — для ротации и автоматизации
Прямой доступ к API	Выполнение любых HTTP-запросов к Пассворку

Zero-Knowledge

passwork-cli реализует клиентское шифрование: сервер Пассворка хранит только зашифрованные данные, а расшифровка и шифрование происходят локально на стороне CLI. Это означает, что даже при перехвате трафика или компрометации сервера злоумышленник не получит доступ к секретам.

Установка

Python-пакет (pip)

passwork-cli входит в пакет pw-connector — устанавливать нужно именно его. Проще всего через pip install pw-connector из PyPI; если нужны исходники или отдельная ветка, ставьте с gitVerse по SSH или HTTPS:

# PyPI
pip install pw-connector

# SSH
pip install git+ssh://git@gitverse.ru:2222/passwork-ru/passwork-python.git

# HTTPS
pip install git+https://gitverse.ru/passwork-ru/passwork-python.git

После установки в системе появляется команда passwork-cli.

Docker-образ

Для CI/CD и серверов без Python используйте Docker-образ:

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

Подробнее: Docker-контейнер для CLI.

Конфигурация

passwork-cli настраивается через переменные окружения:

Переменная	Описание	Обязательная
PASSWORK_HOST	URL сервера Пассворка	✅
PASSWORK_TOKEN	Access token для аутентификации	✅
PASSWORK_MASTER_KEY	Мастер-ключ для расшифровки (если используется)	Зависит от настроек

подсказка

Для CI/CD храните PASSWORK_TOKEN и PASSWORK_MASTER_KEY в защищённых переменных CI-системы (GitLab CI Variables, GitHub Secrets и т.д.), а не в коде репозитория.

Режимы работы

passwork-cli поддерживает четыре режима. Выбор режима зависит от задачи:

Режим	Назначение	Криптография	Типичный сценарий
exec	Запуск команды с секретами в ENV	✅ На клиенте	CI/CD, деплой-скрипты
get	Получение одного значения в STDOUT	✅ На клиенте	Bash-скрипты, точечные запросы
update	Обновление полей записи	✅ На клиенте	Ротация паролей
api	Прямые HTTP-запросы к API	❌ Вручную	Сложная автоматизация, отчёты

к сведению

Режимы exec, get и update автоматически расшифровывают и шифруют данные на клиенте. Режим api возвращает «сырой» ответ API — работа с шифрованием остаётся на вашей стороне.

Подробная документация по каждому режиму: CLI-утилита.

exec — запуск команд с секретами

Извлекает секреты, превращает их в переменные окружения и запускает указанную команду. Секреты доступны только на время выполнения команды.

# Запустить деплой-скрипт с секретами из папки
passwork-cli exec --folder-id "<folder-id>" ./deploy.sh

# Запустить с секретами из конкретной записи
passwork-cli exec --password-id "<item-id>" ./app

Когда использовать: CI/CD-пайплайны, деплой-скрипты, запуск приложений с секретами.

Подробнее: Режим exec.

get — получение одного значения

Возвращает расшифрованное значение в STDOUT. Удобно для точечных запросов в скриптах.

# Получить пароль
passwork-cli get --password-id "<item-id>"

# Получить пользовательское поле
passwork-cli get --password-id "<item-id>" --field API_KEY

# Получить TOTP-код
passwork-cli get --password-id "<item-id>" --totp

Когда использовать: bash-скрипты, где нужно одно конкретное значение; генерация TOTP-кодов.

Подробнее: Режим get.

update — обновление секретов

Изменяет поля записи: пароль, логин, URL, описание, теги, пользовательские поля.

# Обновить пароль
passwork-cli update --password-id "<item-id>" --password "new-password"

# Обновить пользовательское поле
passwork-cli update --password-id "<item-id>" --custom-field "API_KEY=new-api-key"

Когда использовать: ротация паролей, обновление ключей после перегенерации, массовые изменения.

Подробнее: Режим update.

api — прямые HTTP-запросы

Выполняет произвольные запросы к API Пассворка и возвращает JSON-ответ.

# Получить список сейфов
passwork-cli api --method GET --endpoint "v1/vaults"

# Поиск по тегам
passwork-cli api --method GET --endpoint "v1/items/search" \
  --params '{"tags":["secrets","prod"]}'

Когда использовать: сложная автоматизация, отчёты, операции, не покрытые другими режимами.

Подробнее: Режим api.

Практические сценарии

CI/CD: деплой с секретами

Самый частый сценарий — запуск деплой-скрипта с секретами из Пассворка.

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

Ротация пароля БД

Сценарий: сгенерировать новый пароль, обновить его в БД и записать в Пассворк.

#!/bin/bash
set -e

# Генерируем новый пароль
NEW_PASS=$(openssl rand -base64 32)

# Обновляем пароль в PostgreSQL
psql -h db.example.com -U admin -c \
  "ALTER ROLE app_user WITH PASSWORD '${NEW_PASS}';"

# Записываем новый пароль в Пассворк
passwork-cli update \
  --password-id "<item-id>" \
  --password "${NEW_PASS}"

echo "Password rotated successfully"

Получение секрета в bash-скрипте

Когда нужно одно конкретное значение:

# Получить пароль БД и использовать в команде
DB_PASS=$(passwork-cli get --password-id "<item-id>")
psql -h localhost -U app -W "$DB_PASS" -d mydb -c "SELECT 1"

# Получить API-ключ из пользовательского поля
API_KEY=$(passwork-cli get --password-id "<item-id>" --field API_KEY)
curl -H "Authorization: Bearer $API_KEY" https://api.example.com/data

Docker Compose с секретами

Запуск контейнеров с секретами через exec:

# Запустить docker compose с секретами в окружении
passwork-cli exec --folder-id "<folder-id>" docker compose up -d

Внутри docker-compose.yml секреты будут доступны как переменные окружения:

services:
  app:
    image: myapp:latest
    environment:
      - DB_HOST=${DB_HOST}
      - DB_USER=${DB_USER}
      - DB_PASSWORD=${DB_PASSWORD}

Версия для LLM