CLI утилита

Описание

Интерфейс командной строки для получения паролей из менеджера паролей Пассворк и безопасного использования в скриптах и командах.

Пассворк CLI работает в двух основных режимах:

• exec — извлекает пароли из Пассворк, добавляет в переменные окружения и запускает указанную команду с доступом к этим переменным;
• api — предоставляет прямой доступ к API Пассворка, позволяя выполнять любые методы API и получать ответы в формате JSON.

Требования

• Python 3.10+
• requests>=2.31.0
• python-dotenv>=1.0.0
• cryptography>=42.0.0
• pbkdf2>=1.3

Установка

Можно установить пакет прямо из Github:

shell

pip install git+ssh://git@github.com:passwork-me/passwork-python.git

Или через HTTPS:

shell

pip install git+https://github.com/passwork-me/passwork-python.git

Общие параметры

Все команды поддерживают следующие параметры:

Параметр	Переменная окружения	Описание
--host	PASSWORK_HOST	URL сервера Пассворк
--token	PASSWORK_TOKEN	Токен доступа к API
--refresh-token	PASSWORK_REFRESH_TOKEN	Токен обновления (необязательно)
--master-key	PASSWORK_MASTER_KEY	Мастер-ключ для расшифровки
--no-ssl-verify		Отключение проверки SSL-сертификата

1. Режим выполнения (exec)

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

Синтаксис

shell

passwork-cli exec [опции] команда_для_выполнения

Или с использованием параметра --cmd:

shell

passwork-cli exec [опции] --cmd "команда_для_выполнения"

Идентификация паролей

Для команды exec необходимо указать хотя бы один из следующих параметров:

Параметр	Описание
--password-id	ID одного или нескольких паролей (через запятую)
--vault-id	ID одного или нескольких хранилищ (через запятую)
--folder-id	ID одной или нескольких папок (через запятую)
--tags	Теги для поиска паролей (через запятую)

Как это работает

1. Аутентификация: Подключение к серверу Пассворка с использованием указанных учетных данных;
2. Получение паролей: Поиск паролей по заданным критериям (ID, хранилище, папка, теги);
3. Расшифровка: Расшифровка найденных паролей с помощью мастер-ключа;
4. Создание окружения: Формирование переменных окружения из:
   • Основного значения пароля (имя переменной соответствует названию пароля);
   • Всех пользовательских полей записи.
5. Выполнение команды: Запуск указанной команды в новом процессе с доступом к переменным окружения.

Возможности

• Поддержка нескольких паролей: Возможность использовать несколько паролей одновременно;
• Доступ к пользовательским полям: Все кастомные поля доступны как переменные окружения;
• Именование переменных: Пробелы и символы заменяются на _;
• Синтаксис как у Docker: Команда может быть указана сразу после параметров CLI;
• Сохранение кода выхода: Возвращается код завершения выполненной команды.

Сценарии использования

• Доступ к базам данных: Подключение без хранения паролей в конфигурации;
• Аутентификация в API: Запуск скриптов, требующих токенов;
• Деплой: Выполнение скриптов с учётом доступа к паролям разных сервисов;
• Администрирование серверов: Выполнение задач с привилегиями;
• CI/CD пайплайны: Безопасная передача паролей в автоматические процессы.

Примеры использования

Получение пароля и выполнение команды:

shell

# Экспорт переменных окружения
export PASSWORK_HOST="https://passwork.example.com"
export PASSWORK_TOKEN="your_token"
export PASSWORK_MASTER_KEY="your_master_key"

# Получение пароля по ID и запуск MySQL-клиента
passwork-cli exec --password-id "db_password_id" mysql -u admin -h localhost -p $DB_PASSWORD database_name

Получение нескольких паролей из папки:

shell

# Получение всех паролей из папки проекта и запуск скрипта деплоя
passwork-cli exec --folder-id "project_folder_id" ./deploy.sh

Использование разных идентификаторов:

shell

# Получение паролей по ID, тегам и из папки
passwork-cli exec \
  --password-id "specific_password_id" \
  --tags "production,database" \
  --folder-id "api_credentials" \
  ./complex_deployment.sh

Команды shell:

shell

# Для shell-команд нужно использовать --cmd
passwork-cli exec --password-id "server_creds" --cmd "ssh user@server 'cat /var/log/app.log | grep ERROR' > local_errors.log"

Подключение к серверу с самоподписанным сертификатом:

shell

# Отключение проверки SSL
passwork-cli exec --no-ssl-verify --password-id "test_server_password" ssh user@test-server.local

2. Режим API (api)

Позволяет выполнять прямые вызовы к API Пассворка с получением ответов в формате JSON.

Синтаксис

shell

passwork-cli api [опции]

Параметры API

Команде api необходимы следующие параметры:

Параметр	Описание
--method	HTTP-метод (GET, POST, PUT, DELETE, PATCH)
--endpoint	Путь API (например, v1/vaults)
--params	JSON-строка с параметрами (необязательно)
--field	Имя поля для извлечения из ответа (необязательно)

Как это работает

1. Аутентификация: Подключение к серверу Пассворка;
2. Формирование запроса: Создание HTTP-запроса по указанному пути и методу;
3. Отправка запроса: Отправка запроса с нужными заголовками авторизации;
4. Обработка ответа: Получение и разбор ответа от API;
5. Фильтрация (опционально): Извлечение указанного поля с помощью --field;
6. Вывод: Результат выводится в формате JSON.

Примеры использования

Получение списка всех хранилищ:

shell

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

Получение определённого пароля и извлечение только имени:

shell

passwork-cli api --method GET --endpoint "v1/items/password_id" --field "name"

Поиск паролей по тегам и получение их имён:

shell

passwork-cli api \
  --method GET \
  --endpoint "v1/items/search" \
  --params '{"tags":["api","production"]}' \
  --field "name"

Обновление access-токена:

shell

passwork-cli api \
  --host "https://passwork.example.com" \
  --token "your_expired_token" \
  --refresh-token "your_refresh_token" \
  --method POST \
  --endpoint "v1/auth/refresh-token" \
  --field "token"

Использование с самоподписанным сертификатом:

shell

passwork-cli api --no-ssl-verify --method GET --endpoint "v1/user/profile"

Безопасность

• Учетные данные не сохраняются на диск;
• Команды с паролями не попадают в историю оболочки;
• Пароли доступны только внутри запущенного процесса;
• Рекомендуется использовать переменные окружения для хранения учетных данных.

Примеры

Примеры дополнительных сценариев расположены в examples_cli директории.