FAQ и лучшие практики

Безопасность и архитектура

Что произойдёт, если потерять мастер-ключ?

Без мастер-ключа расшифровать секреты невозможно — это следствие Zero-Knowledge архитектуры. Сервер не хранит ключи и не может помочь с восстановлением.

Что делать:

• Для сервисных учёток храните мастер-ключ в защищённых переменных CI-системы и в отдельном безопасном месте (сейф, HSM).
• Для пользователей — убедитесь, что администратор может сбросить пароль и выдать новый доступ к сейфам.

Что видит администратор сервера Пассворка?

Администратор сервера (тот, кто управляет инфраструктурой Пассворка) видит:

Видит	Не видит
Структуру сейфов и папок	Расшифрованные пароли
Названия записей	Значения полей
Метаданные (теги, даты)	Содержимое вложений
Журнал операций	Ключи шифрования пользователей

Это означает, что даже при полном доступе к серверу и БД администратор не может прочитать секреты.

Можно ли отключить Zero-Knowledge?

В коробочной версии Пассворка клиентское шифрование (Zero-Knowledge) — базовый принцип архитектуры. В уже установленной инстанс‑коробке включить или выключить его невозможно: выбор режима определяется на этапе мастер установки.

Что делать, если токен CI утёк?

1. Немедленно отзовите токен — в настройках сервисной учётки.
2. Проверьте журнал аудита — какие операции выполнялись с этим токеном.
3. Ротируйте секреты, к которым был доступ у скомпрометированной учётки.
4. Выпустите новый токен и обновите его в CI-системе.

подсказка

Используйте отдельные сервисные учётки для разных CI-пайплайнов. Тогда компрометация одного токена не затронет все секреты.

Работа с CLI и SDK

Почему CLI требует и access token, и master key?

• Access token — для аутентификации в API Пассворка (доказывает, что вы — это вы).
• Master key — для расшифровки данных на клиенте (Zero-Knowledge).

Без access token вы не получите зашифрованные данные с сервера. Без master key вы не сможете их расшифровать.

Как CLI получает данные?

passwork-cli при запуске:

1. Аутентифицируется на сервере.
2. Загружает зашифрованные записи из указанной папки.
3. Расшифровывает их локально.
4. Подставляет в переменные окружения или выводит в STDOUT.

Кэширование между запусками не происходит — каждый вызов получает свежие данные с сервера.

Как обрабатываются конфликты при одновременном обновлении?

Пассворк использует optimistic locking. Если два клиента одновременно обновляют одну запись:

1. Первый клиент успешно сохраняет изменения.
2. Второй клиент получает ошибку конфликта.
3. Второй клиент должен перечитать запись и повторить операцию.

В Python SDK это выглядит так:

try:
    client.update_password(item)
except ConflictError:
    # Перечитываем и пробуем снова
    item = client.get_password(item_id=item.id)
    item.password = new_password
    client.update_password(item)

Можно ли использовать CLI без Docker?

Да. passwork-cli входит в пакет pw-connector, который ставится одной командой:

pip install pw-connector

Docker-образ нужен только там, где не хочется разворачивать Python-окружение.

Организация секретов

Как структурировать папки для нескольких команд?

Пример для организации с несколькими продуктами:

secrets/
├── platform/           # Общая инфраструктура
│   ├── prod/
│   └── stage/
├── product-a/          # Команда продукта A
│   ├── prod/
│   ├── stage/
│   └── dev/
└── product-b/          # Команда продукта B
    ├── prod/
    └── stage/

Права доступа:

• Команда A → доступ только к product-a/*
• Команда B → доступ только к product-b/*
• DevOps → доступ ко всем папкам
• CI/CD сервисные учётки → read-only к конкретным папкам

Как именовать записи для автоматизации?

Используйте предсказуемые имена, которые легко понять:

# Хорошо — понятно что внутри
postgres-main-prod
redis-session-cache
stripe-api-key

# Плохо — непонятно без открытия
password-1
new-secret
test

Если используете exec с папкой, имена записей становятся именами переменных окружения. Используйте UPPER_SNAKE_CASE:

DB_PASSWORD
REDIS_URL
STRIPE_SECRET_KEY

Хранить ли в одной записи несколько связанных секретов?

Да, если секреты логически связаны и используются вместе:

Запись: postgres-main-prod
├── login: app_user
├── password: ...
├── DB_HOST: db.example.com
├── DB_PORT: 5432
└── DB_NAME: production

Нет, если секреты независимы или имеют разные политики ротации.

Ротация и жизненный цикл

Почему Пассворк не ротирует секреты автоматически?

Zero-Knowledge архитектура означает, что сервер не имеет доступа к расшифрованным данным. Чтобы ротировать секрет, нужно:

1. Расшифровать старое значение (требует ключей клиента).
2. Сгенерировать новое.
3. Обновить целевую систему (БД, сервис).
4. Зашифровать и сохранить новое значение.

Шаги 1, 3, 4 требуют клиента с ключами и доступом к целевой системе. Сервер Пассворка этого не имеет.

Можно ли восстановить удалённый секрет?

Если запись удалена, восстановление зависит от настроек сервера (корзина, soft delete). Уточните у администратора.

warning

Всегда делайте бэкап перед массовыми операциями. Используйте staging-окружение для тестирования скриптов.

Миграция и интеграция

Как мигрировать с другого secrets manager?

Общий подход:

1. Экспортируйте секреты из старой системы (обычно в JSON/YAML).
2. Напишите скрипт преобразования в структуру Пассворка.
3. Импортируйте через Python SDK (create_password).

Пример для миграции из .env файлов есть в разделе Python SDK.

Как интегрировать Пассворк с Terraform?

Пассворк не имеет официального Terraform provider, но можно:

1. Использовать external data source с passwork-cli get.
2. Написать wrapper-скрипт, который читает секреты и передаёт в Terraform.

data "external" "db_password" {
  program = ["bash", "-c", "passwork-cli get --password-id $ID --json"]
}

resource "aws_db_instance" "main" {
  password = data.external.db_password.result.password
}

Версия для LLM