Перейти к содержимому

// Engineering Log

Секреты и zero trust: Часть 3 — Bitwarden CLI на Linux: bw, сессия и безопасная работа

Опубликовано 20.11.2026 · Автор:

// Быстрый маршрут

Эта статья относится к теме Безопасность и защита.

Bitwarden CLI (bw) — официальный клиент Bitwarden для командной строки. С его помощью можно искать, читать, создавать, изменять и удалять записи, работать с организациями и коллекциями. С ним секреты из хранилища можно подставлять в скрипты и команды администрирования вместо того, чтобы держать их в .env, в истории оболочки или в заметках. bw работает и с облаком Bitwarden, и с собственным сервером Vaultwarden. Ниже разобрано, как установить bw на Linux, подключить его к Vaultwarden и пользоваться им так, чтобы секреты не оседали на диске, в журналах и в списке процессов. Сведения проверены по документации Bitwarden и исходникам CLI версии 2026.10.0.

Установка

Есть три способа.

npm. Нужны Node.js 22 или новее и npm 10 или новее:

bash
node --version    # v22.x или выше
npm install -g @bitwarden/cli
bw --version

Документация предупреждает: на Linux для установки через npm может понадобиться build-essential (sudo apt install build-essential) или его аналог в вашем дистрибутиве. На arm64 (например, на Raspberry Pi) документация рекомендует именно npm: готовые бинарники выпускаются только для x64.

snap:

bash
sudo snap install bw

Нативный бинарник для Linux x64 работает без Node.js:

bash
curl -fsSL -o bw.zip 'https://bitwarden.com/download/?app=cli&platform=linux'
unzip bw.zip && chmod +x bw && sudo mv bw /usr/local/bin/

Для сборок на GitHub публикуются файлы с контрольными суммами SHA-256, перед установкой сверьте сумму архива: файл с суммой берите на странице релиза на GitHub (точное имя файла проверьте там) и сверяйте командой sha256sum -c. Там же лежат два варианта: обычный и OSS. В OSS-сборке нет функций под закрытой лицензией, например команд одобрения устройств; для работы с Vaultwarden хватает любой.

Подключение к Vaultwarden

По умолчанию bw подключается к облаку Bitwarden. Для своего сервера адрес задают до входа:

bash
bw config server https://vault.example.ru
bw config server          # без аргумента показывает текущий адрес

Если сервер отдаёт самоподписанный сертификат или сертификат вашего внутреннего центра сертификации, укажите Node.js файл с корневым сертификатом:

bash
export NODE_EXTRA_CA_CERTS="$HOME/.config/bw/example-ca.pem"

Отключать проверку сертификатов не нужно: CLI передаёт серверу хеш мастер-пароля и получает токены доступа. Как развернуть сам сервер за обратным прокси, описано в части о Vaultwarden.

Вход и разблокировка — разные шаги

У CLI три состояния, их показывает bw status:

bash
bw status | jq -r .status
# unauthenticated — вход не выполнен
# locked          — вход выполнен, хранилище заблокировано
# unlocked        — хранилище разблокировано

Вход (bw login) связывает CLI с учётной записью: сервер проверяет вас, выдаёт токены, и CLI скачивает зашифрованное хранилище. Разблокировка (bw unlock) расшифровывает хранилище на вашей машине мастер-паролем и создаёт ключ сессии. Вход выполняют один раз, разблокируют при каждой работе.

bash
bw login you@example.ru     # спросит мастер-пароль и, если включён, второй фактор
bw unlock                   # спросит мастер-пароль и выдаст ключ сессии

Вход по e-mail и паролю сразу создаёт и ключ сессии. При входе по API-ключу или через SSO bw unlock потом обязателен: расшифровать данные можно только мастер-паролем. Команды config, encode, generate, update и status работают без разблокировки.

Двухэтапный вход в CLI

CLI поддерживает три способа второго фактора: приложение-аутентификатор (TOTP), код на e-mail и YubiKey OTP. Номер способа передают в --method:

Способ--method
Authenticator (TOTP)0
Email1
YubiKey OTP3
bash
bw login you@example.ru --method 0 --code 123456

FIDO2 WebAuthn и Duo в CLI не поддерживаются. Если на учётной записи включены только они, войти можно только по API-ключу (о нём ниже). Пароль вводите интерактивно, чтобы он не попал в историю оболочки; одноразовый код в аргументе команды на время её работы виден в списке процессов.

Ключ сессии: BW_SESSION и –raw

bw unlock печатает готовую команду export BW_SESSION="…". С глобальной опцией --raw выводится только сам ключ, без пояснений, поэтому его удобно сразу записать в переменную:

bash
export BW_SESSION="$(bw unlock --raw)"

Запрос пароля CLI выводит в stderr, поэтому при перехвате stdout подсказка «Master password:» остаётся на экране, а в переменную попадает только ключ. Вместо переменной окружения ключ можно передать опцией --session <ключ>, но тогда он виден в списке процессов.

Ключ сессии действует до bw lock или bw logout и не переходит в новое окно терминала сам. Закончив работу, заблокируйте хранилище:

bash
bw lock
unset BW_SESSION

bw lock блокирует хранилище и сбрасывает сохранённое состояние; после него ключ сессии больше не открывает данные.

Пароль не в аргументе командной строки

bw unlock принимает пароль и позиционным аргументом: bw unlock <пароль>. Так делать нельзя:

  • аргументы любого процесса видны всем пользователям системы в ps aux и в /proc/<pid>/cmdline, пока процесс работает (если /proc не смонтирован с hidepid);
  • команда с паролем попадает в историю оболочки (~/.bash_history, ~/.zsh_history);
  • она же может уйти в журнал аудита, если на сервере включён auditd с записью execve.

Для неинтерактивной разблокировки есть две безопасные опции.

--passwordenv <имя> — CLI читает пароль из переменной окружения с указанным именем. Имя любое, BW_PASSWORD в документации — только пример. Переменные окружения процесса через /proc/<pid>/environ может прочитать только владелец процесса и root, а не все пользователи:

bash
# bash; в zsh: read -rs '?Мастер-пароль: ' BW_PW
read -rs -p 'Мастер-пароль: ' BW_PW; echo
BW_SESSION="$(BW_PW="$BW_PW" bw unlock --passwordenv BW_PW --raw)"
export BW_SESSION
unset BW_PW

Запись BW_PW="$BW_PW" bw … передаёт переменную только этому процессу, не экспортируя её в оболочку.

--passwordfile <файл> — CLI берёт пароль из первой строки файла. Документация советует ограничить доступ к такому файлу; CLI права не проверяет. Создавайте файл сразу с нужными правами, а не меняйте их после:

bash
mkdir -p -m 700 ~/.config/bw
( umask 077; read -rs -p 'Мастер-пароль: ' P; printf '%s\n' "$P" > ~/.config/bw/master ); unset P; echo
bw unlock --passwordfile ~/.config/bw/master --raw

Мастер-пароль в файле на диске — это мастер-пароль открытым текстом: его найдёт любой, кто получит копию диска или резервную копию домашнего каталога. Используйте этот вариант только на сервере, где без автоматической разблокировки не обойтись, и учитывайте это в модели угроз. Как убрать пароль с диска и разблокировать хранилище касанием аппаратного ключа, описано в части о разблокировке через FIDO2.

Где хранить ключ сессии

Ключ сессии вместе с локальной копией хранилища даёт доступ ко всем записям, поэтому обращайтесь с ним как с паролем. Чтобы не разблокировать хранилище в каждом новом терминале, ключ можно положить в $XDG_RUNTIME_DIR. На системах с systemd это каталог /run/user/<uid> в tmpfs с правами 0700: он хранится в памяти, доступен только вам и очищается при выходе из всех сеансов (если для пользователя не включён loginctl enable-linger) или перезагрузке.

bash
# разблокировать и сохранить ключ
umask 077
( umask 077; bw unlock --raw > "$XDG_RUNTIME_DIR/bw-session" )   # если разблокировка не удалась, удалите пустой файл

# в ~/.bashrc: подхватить ключ в новых оболочках
[ -r "$XDG_RUNTIME_DIR/bw-session" ] && export BW_SESSION="$(cat "$XDG_RUNTIME_DIR/bw-session")"

# закончить работу
bw lock; rm -f "$XDG_RUNTIME_DIR/bw-session"; unset BW_SESSION

Чего делать нельзя:

  • писать ключ сессии в ~/.bashrc, ~/.profile, .env и любой другой файл на диске;
  • выводить его в журнал скрипта: set -x в bash печатает раскрытые команды вместе со значениями в аргументах (например, export VAR=значение), поэтому вокруг работы с секретами трассировку отключают (set +x);
  • вставлять в чаты, тикеты, задания CI;
  • держать хранилище разблокированным на общем сервере, где под вашей учётной записью работают другие люди или сервисы.

Помните, что любой процесс, запущенный от вашего пользователя, может прочитать и $XDG_RUNTIME_DIR, и переменные окружения ваших процессов. Tmpfs защищает от кражи диска и от других пользователей, но не от вредоносной программы в вашем же сеансе.

Чтение секретов

bw get возвращает один объект по ID или по строке поиска:

bash
bw get password db.example.ru        # только пароль
bw get username db.example.ru
bw get totp db.example.ru            # текущий TOTP-код
bw get notes deploy-key
bw get item db.example.ru | jq .     # запись целиком в JSON

Если под строку подходят несколько записей, CLI выдаёт ошибку «More than one result was found» и печатает их ID. Найдите нужную через bw list и дальше обращайтесь по ID:

bash
bw list items --search db | jq -r '.[] | [.id, .name, .login.username] | @tsv'
bw get password 0f4c9a2e-1b7d-4c8e-9a3f-5d6e7f8a9b0c

Фильтры --folderid, --collectionid, --organizationid, --url объединяются между собой через ИЛИ, а с --search — через И. Поле из пользовательских полей записи достают через jq:

bash
bw get item 0f4c9a2e-1b7d-4c8e-9a3f-5d6e7f8a9b0c \
  | jq -r '.fields[]? | select(.name == "api_token") | .value'

Секрет не нужно показывать на экране, чтобы им воспользоваться. Передавайте его сразу в команду через переменную окружения или стандартный ввод:

bash
# переменная окружения только для одного процесса
PGPASSWORD="$(bw get password db.example.ru)" psql -h db.example.ru -U app appdb

# стандартный ввод
bw get password registry.example.ru | docker login registry.example.ru -u deploy --password-stdin

Если вы изменили запись в другом клиенте, выполните bw sync: эта команда только скачивает хранилище с сервера. Изменения, сделанные в CLI (create, edit, delete), отправляются на сервер сразу. Время последней синхронизации показывает bw sync --last.

Создание, правка и удаление записей

bw create и bw edit принимают JSON в base64. Порядок такой: взять шаблон, заполнить его через jq, закодировать bw encode, передать в bw create. Пароль не нужно подставлять в текст фильтра jq: он окажется в аргументах процесса и в истории. Безопаснее сгенерировать пароль в переменную и отдать его jq через окружение (env.PW):

bash
PW="$(bw generate -ulns --length 32)"
bw get template item | PW="$PW" jq '
    .type = 1
  | .name = "db.example.ru"
  | .notes = null
  | .login = {
      username: "app",
      password: env.PW,
      uris: [{match: null, uri: "https://db.example.ru"}]
    }' \
  | bw encode | bw create item | jq -r .id
unset PW

Типы записей: 1 — логин, 2 — защищённая заметка, 3 — карта, 4 — личные данные, 5 — SSH-ключ.

Правка заменяет запись целиком, поэтому берут текущую версию, меняют нужное поле и отправляют обратно:

bash
ID=0f4c9a2e-1b7d-4c8e-9a3f-5d6e7f8a9b0c
NEW="$(bw generate -ulns --length 32)"
bw get item "$ID" | NEW="$NEW" jq '.login.password = env.NEW' | bw encode | bw edit item "$ID"
unset NEW

Удаление по умолчанию переносит запись в корзину, откуда её можно вернуть. В облаке Bitwarden запись хранится в корзине 30 дней; в Vaultwarden срок задаёт TRASH_AUTO_DELETE_DAYS (по умолчанию записи автоматически не удаляются). С --permanent запись удаляется безвозвратно:

bash
bw delete item "$ID"
bw list items --trash | jq -r '.[] | [.id, .name] | @tsv'
bw restore item "$ID"

Запись SSH-ключа

Для записей типа 5 готового шаблона в списке документации нет (item.sshKey среди шаблонов не значится). JSON собирают из шаблона item и объекта sshKey с тремя полями: privateKey, publicKey и keyFingerprint. В исходниках клиента все три указаны как обязательные:

bash
KEY=~/.ssh/id_ed25519
bw get template item | jq \
    --rawfile priv "$KEY" \
    --rawfile pub "$KEY.pub" \
    --arg fp "$(ssh-keygen -lf "$KEY.pub" | awk '{print $2}')" '
    .type = 5
  | .name = "ssh: deploy@example.ru"
  | .login = null
  | .notes = null
  | .sshKey = {privateKey: $priv, publicKey: ($pub | rtrimstr("\n")), keyFingerprint: $fp}' \
  | bw encode | bw create item | jq -r .id

Закрытый ключ jq читает из файла (--rawfile), а не из аргумента; отпечаток публичный, его можно передать через --arg. Поддержка этого типа зависит от версии сервера, поэтому сначала создайте тестовую запись и откройте её в веб-интерфейсе Vaultwarden. Встроенный SSH-агент, который отдаёт такие ключи программе ssh, есть в десктопном приложении Bitwarden.

Вход по API-ключу

Персональный API-ключ (client_id и client_secret) берут в веб-интерфейсе в настройках безопасности учётной записи. Он нужен, если на учётной записи включён второй фактор, который CLI не поддерживает, и для автоматизации, где нельзя ответить на запрос кода:

bash
export BW_CLIENTID='<client_id>'
export BW_CLIENTSECRET='<client_secret>'
bw login --apikey
# BW_PW задайте так же, как в разделе про --passwordenv
bw unlock --passwordenv BW_PW --raw

Вход по API-ключу рассчитан на случаи, когда код второго фактора ввести нельзя, поэтому не храните client_secret и мастер-пароль вместе без необходимости. Документация говорит прямо: API-ключ не заменяет мастер-пароль. Он только выполняет вход, а для чтения данных всё равно нужен bw unlock с мастер-паролем. Утечка API-ключа без мастер-пароля не раскрывает содержимое хранилища, но позволяет войти от вашего имени и скачать зашифрованные данные, поэтому храните ключ так же аккуратно, как пароль, и перевыпускайте его при подозрении на утечку.

Организации, коллекции и права

Общие секреты команды хранят в организации и раскладывают по коллекциям. В CLI:

bash
bw list organizations | jq -r '.[] | [.id, .name] | @tsv'
bw list collections | jq -r '.[] | [.id, .name] | @tsv'
bw list items --collectionid <id_коллекции>
# перенести личную запись в организацию и коллекцию
echo '["<id_коллекции>"]' | bw encode | bw move "$ID" <id_организации>

Роли участников организации: Owner, Admin, User; пользовательские роли (Custom) в Bitwarden есть только в тарифе Enterprise. На уровне коллекции документация Bitwarden описывает права «View items», «View items, hidden passwords», «Edit items», «Edit items, hidden passwords» и «Manage collection». Скрытые пароли не защищают полностью: автозаполнение продолжает работать, и Bitwarden советует считать такой пароль переданным пользователю. Какие из этих уровней реализованы в вашей версии Vaultwarden, проверьте в его интерфейсе. Для автоматизации заведите отдельного пользователя с доступом только к нужной коллекции, а не используйте свою учётную запись с доступом ко всему.

Скрипт-обёртка

Скрипт, который берёт секрет из хранилища, передаёт его одной команде, не записывая секрет в файлы на диске и не передавая его в аргументах командной строки:

bash
#!/usr/bin/env bash
# with-secret: with-secret <запись> <ПЕРЕМЕННАЯ> -- команда [аргументы]
set -euo pipefail
set +x

item="$1"; var="$2"; shift 2
[ "${1:-}" = "--" ] && shift

: "${BW_SESSION:?Хранилище не разблокировано: export BW_SESSION=\"\$(bw unlock --raw)\"}"

value="$(bw get password "$item" --nointeraction)" || {
  echo "Не удалось получить $item" >&2; exit 1
}

# exec заменяет скрипт командой: переменная есть только в её окружении
export "$var=$value"
unset value BW_SESSION
exec "$@"
bash
with-secret db.example.ru PGPASSWORD -- psql -h db.example.ru -U app appdb

--nointeraction не даёт CLI запросить пароль посреди скрипта: если хранилище заблокировано, команда сразу завершится с ошибкой «Vault is locked.». Значение секрета не попадает в аргументы, вывод и историю; оно остаётся в окружении запущенной команды, и его может прочитать процесс того же пользователя или root. Ключ сессии BW_SESSION скрипт перед запуском команды удаляет из окружения.

Если всё же приходится вводить команду с секретом вручную, не сохраняйте её в истории. В bash:

bash
export HISTCONTROL=ignoreboth   # строки, начинающиеся с пробела, не сохраняются
 export MYSQL_PWD='<пароль>'    # пробел в начале строки: команда не сохранится
set +o history                  # выключить историю в текущем сеансе
set -o history                  # включить обратно

Опция history есть только в bash; в zsh строки с пробелом в начале не сохраняет setopt HIST_IGNORE_SPACE. Пример кладёт пароль в окружение, а не в аргумент: HISTCONTROL скрывает команду только от истории, а аргумент командной строки остаётся виден в списке процессов. Но надёжнее не вводить секреты в командную строку вовсе. Как не допустить утечки секретов в Git, разобрано в статье «Безопасная разработка: Часть 2 — Секреты в коде».

Типичные ошибки

«You are not logged in.» — вход не выполнен или выполнен с другим BITWARDENCLI_APPDATA_DIR. Проверьте bw status, при необходимости bw config server и bw login.

«Vault is locked.» — хранилище заблокировано, а CLI запущен с --nointeraction; без этой опции он спросит мастер-пароль. Выполните bw unlock --raw и экспортируйте BW_SESSION.

Неверный или устаревший BW_SESSION. После bw lock, bw logout или повторной разблокировки старый ключ недействителен: команды сообщают, что хранилище заблокировано, или не могут расшифровать данные. Разблокируйте заново и обновите сохранённый ключ в $XDG_RUNTIME_DIR.

«More than one result was found». Строка поиска подходит к нескольким записям. Используйте ID из bw list items --search.

«Not found.» — запись не существует или CLI её ещё не видит: она создана в другом клиенте после последней синхронизации. Выполните bw sync.

Ошибка сертификата при bw login — у сервера сертификат внутреннего центра сертификации. Укажите NODE_EXTRA_CA_CERTS, проверку не отключайте.

Предупреждение «Warning: Provided passwordenv … is not set» — переменная, имя которой передано в --passwordenv, пуста или не передана процессу; CLI в этом случае спросит пароль, а с --nointeraction затем следует ошибка «Master password is required. Try again in interactive mode or provide a password file or environment variable.». Передавайте имя переменной, а не её значение: --passwordenv BW_PW, а не --passwordenv "$BW_PW".

Для отладки соединения с сервером CLI выводит подробный журнал при BITWARDENCLI_DEBUG=true. Перед тем как пересылать такой журнал кому-то, проверьте, что в нём нет токенов.

// Похожая задача

Если у вас похожая ситуация

Эта статья относится к одной из рабочих тем. Можно продолжить чтение по теме, перейти на главную, чтобы понять, чем я занимаюсь, или сразу открыть услуги.

Тема статьи

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

SSL, hardening, доступы, защита сервисов и безопасные конфигурации.

Часто с этим приходят

  • Настроить SSL, сертификаты и безопасные подключения
  • Ограничить доступы и закрыть лишние точки входа
  • Усилить конфигурацию сервера и сервисов

// Следующий шаг

Если вам нужна не только статья, а помощь по этой теме, удобнее сразу перейти в услугу. Главная и подборка материалов остаются рядом.

Открыть услуги

// Contact

Нужна помощь?

Свяжись со мной и я помогу решить проблему

Написать в Telegram

Отвечаю в течение рабочего дня (03:00–13:00 GMT)

Или оставьте заявку здесь:

Подтвердите, что вы не бот.

Написать и получить быстрый ответ