// 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 или новее:
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:
sudo snap install bwНативный бинарник для Linux x64 работает без Node.js:
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. Для своего сервера адрес задают до входа:
bw config server https://vault.example.ru
bw config server # без аргумента показывает текущий адресЕсли сервер отдаёт самоподписанный сертификат или сертификат вашего внутреннего центра сертификации, укажите Node.js файл с корневым сертификатом:
export NODE_EXTRA_CA_CERTS="$HOME/.config/bw/example-ca.pem"Отключать проверку сертификатов не нужно: CLI передаёт серверу хеш мастер-пароля и получает токены доступа. Как развернуть сам сервер за обратным прокси, описано в части о Vaultwarden.
Вход и разблокировка — разные шаги
У CLI три состояния, их показывает bw status:
bw status | jq -r .status
# unauthenticated — вход не выполнен
# locked — вход выполнен, хранилище заблокировано
# unlocked — хранилище разблокированоВход (bw login) связывает CLI с учётной записью: сервер проверяет вас, выдаёт токены, и CLI скачивает зашифрованное хранилище. Разблокировка (bw unlock) расшифровывает хранилище на вашей машине мастер-паролем и создаёт ключ сессии. Вход выполняют один раз, разблокируют при каждой работе.
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 |
| 1 | |
| YubiKey OTP | 3 |
bw login you@example.ru --method 0 --code 123456FIDO2 WebAuthn и Duo в CLI не поддерживаются. Если на учётной записи включены только они, войти можно только по API-ключу (о нём ниже). Пароль вводите интерактивно, чтобы он не попал в историю оболочки; одноразовый код в аргументе команды на время её работы виден в списке процессов.
Ключ сессии: BW_SESSION и –raw
bw unlock печатает готовую команду export BW_SESSION="…". С глобальной опцией --raw выводится только сам ключ, без пояснений, поэтому его удобно сразу записать в переменную:
export BW_SESSION="$(bw unlock --raw)"Запрос пароля CLI выводит в stderr, поэтому при перехвате stdout подсказка «Master password:» остаётся на экране, а в переменную попадает только ключ. Вместо переменной окружения ключ можно передать опцией --session <ключ>, но тогда он виден в списке процессов.
Ключ сессии действует до bw lock или bw logout и не переходит в новое окно терминала сам. Закончив работу, заблокируйте хранилище:
bw lock
unset BW_SESSIONbw 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; в 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 права не проверяет. Создавайте файл сразу с нужными правами, а не меняйте их после:
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) или перезагрузке.
# разблокировать и сохранить ключ
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 или по строке поиска:
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:
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:
bw get item 0f4c9a2e-1b7d-4c8e-9a3f-5d6e7f8a9b0c \
| jq -r '.fields[]? | select(.name == "api_token") | .value'Секрет не нужно показывать на экране, чтобы им воспользоваться. Передавайте его сразу в команду через переменную окружения или стандартный ввод:
# переменная окружения только для одного процесса
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):
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-ключ.
Правка заменяет запись целиком, поэтому берут текущую версию, меняют нужное поле и отправляют обратно:
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 запись удаляется безвозвратно:
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. В исходниках клиента все три указаны как обязательные:
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 не поддерживает, и для автоматизации, где нельзя ответить на запрос кода:
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:
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, проверьте в его интерфейсе. Для автоматизации заведите отдельного пользователя с доступом только к нужной коллекции, а не используйте свою учётную запись с доступом ко всему.
Скрипт-обёртка
Скрипт, который берёт секрет из хранилища, передаёт его одной команде, не записывая секрет в файлы на диске и не передавая его в аргументах командной строки:
#!/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 "$@"with-secret db.example.ru PGPASSWORD -- psql -h db.example.ru -U app appdb--nointeraction не даёт CLI запросить пароль посреди скрипта: если хранилище заблокировано, команда сразу завершится с ошибкой «Vault is locked.». Значение секрета не попадает в аргументы, вывод и историю; оно остаётся в окружении запущенной команды, и его может прочитать процесс того же пользователя или root. Ключ сессии BW_SESSION скрипт перед запуском команды удаляет из окружения.
Если всё же приходится вводить команду с секретом вручную, не сохраняйте её в истории. В 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)
Или оставьте заявку здесь:
// Related