ewjoachim / bitwarden-keyring

Implementation of Bitwarden as keyring backend

Bitwarden Keyring

Implementation of the Keyring backend code reading secrets from Bitwarden using Bitwarden-cli

Overview

The Keyring python package provides a handy single point of entry for any secret holding system, allowing for seemless integration of those systems into applications needing secrets, like twine.

This projects implement Keyring to be able to read secrets from Bitwarden, an open source multiplatform cloud/self-hostable password manager.

This backend assumes that it will be used in the context of a CLI application, and that it can communicate with the user using sdtin, stdout and stderr. We could implement an additional backend for use in a library assuming that everything is already unlocked, or another one using pinentry to ask the user.

Requirements

This project uses the official bitwarden CLI under the hood, because there's no simple official Python bitwarden lib. Here are the installation instructions as of October 2018 and the link to the up to date instructions

You can install the Bitwarden CLI multiple different ways:

NPM

If you already have the Node.js runtime installed on your system, you can install the CLI using NPM. NPM makes it easy to keep your installation updated and should be the preferred installation method if you are already using Node.js.

npm install -g @bitwarden/cli

Native Executable

Natively packaged versions of the CLI are provided for each platform which have no requirements on installing the Node.js runtime. You can obtain these from the downloads section in the Bitwarden documentation.

Other Package Managers

• Chocolatey

  choco install bitwarden-cli

• Homebrew

  brew install bitwarden-cli

• Snap

  sudo snap install bw

Installation and configuration

pip install bitwarden-keyring

The Python packaging ecosystem can be quite a mess.

Because of this, it's likely that your setup and my setup are nothing alike. Keyring supports a configuration file with an option allowing to explicitely define the path to a backend. You may need that for your installation, or maybe not.

Usage

Use as a normal keyring backend. It is installed with priority 10 so it's likely going to be selected first.

If you want to use it with twine, good news, you're already set. Just make sure that this package is installed in the same location as twine.

bitwarden-keyring will automatically ask for credentials when needed. If you don't want to unlock your vault every time, export the vault session to your environment (use bw unlock and follow the instructions, or launch export BW_SESSION=$(bw unlock --raw)).

Caveats

bitwarden-keyring was only tested with:

• macOS, using the bitwarden-cli from brew
• ubuntu, using the bw from snap

As mentionned, bitwarden-keyring only works in the context of a CLI application with access to standard inputs and output. If you need something that either reads silently or using another method of communication, the best is probably to make another backend and most of the functions can be reused.

Licensing

bitwarden-keyring is published under the terms of the MIT License. The name Bitwarden is most probably the property of 8bit Solutions LLC.

Contributions and Code of Conduct

Contributions are welcome, please refer to the Contributing guide. Please keep in mind that all interactions with the project are required to follow the Code of Conduct.

bitwarden-keyring's Issues

ImportError: cannot import name ‘properties’ from ‘keyring.util’

I'm not using bitwarden, but on the computer of a friend, there is

  File “/usr/local/lib/python3.11/site-packages/bitwarden_keyring/__init__.py”, line 8, in <module> from keyring.util import properties
ImportError: cannot import name ‘properties’ from ‘keyring.util’

This module was indeed removed

jaraco/keyring@b8ee1bd

I don't know what it does, so I cannot recommand anything to fix this, but according to the deprecation warning that this commit removed

warnings.warn(
    "Properties from keyring.util are no longer supported. "
    "Use jaraco.classes.properties instead.",
    DeprecationWarning,
)

I don't know what jaraco is, but I assume you can simply replace the problematic import with from jaraco.classes import properties

Feature Request: Add session passing to functions

Hey Joachim,

Thanks for the module, I have been using it to build out a utility to allow me to easily search and copy my bitwarden passwords to clipboard with fzf for search.

I ran into a small issue while using the module where I want to built a username/password cache using the bw() function, then using those results I call the get_password() func. The issue I am having is it is repeatedly calling for a new session on each function call (which asks me for password each time to unlock), and there doesn't seem to be a way to pass the session to the get_password, set_password, or del_password functions.

I am proposing the following, add a function input session=None, then add a small check inside the function. If session == None, it will grab the session from users password, else it will use the session passed to it.

I have created #4 with the additions, tests, and minor version bump. Wanted to write my thoughts out here as well.

Let me know if you know a better way.

• Sam

RFE: how to use bitwarden-keyring ?

Sorry for asking this.

Can you provide an python example that utilize this module ?

test_bitwarden_keyring.py failing the test

• This is centos 7.6 with python36.

[me@centos7 tests]$ /usr/local/bin/pytest
======================================================================== test session starts =========================================================================
platform linux -- Python 3.6.8, pytest-5.1.1, py-1.8.0, pluggy-0.12.0 -- /usr/bin/python3.6
cachedir: .pytest_cache
rootdir: /home/tjyang/github/bitwarden-keyring, inifile: setup.cfg
plugins: cov-2.7.1
collected 0 items / 1 errors
Coverage.py warning: Module bitwarden_keyring was never imported. (module-not-imported)
Coverage.py warning: No data was collected. (no-data-collected)
WARNING: Failed to generate report: No data to report.

/usr/local/lib/python3.6/site-packages/pytest_cov/plugin.py:229: PytestWarning: Failed to generate report: No data to report.

  self.cov_controller.finish()

=============================================================================== ERRORS ===============================================================================
__________________________________________________________ ERROR collecting tests/test_bitwarden_keyring.py __________________________________________________________
ImportError while importing test module '/home/tjyang/github/bitwarden-keyring/tests/test_bitwarden_keyring.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
/usr/local/lib/python3.6/site-packages/_pytest/python.py:501: in _importtestmodule
    mod = self.fspath.pyimport(ensuresyspath=importmode)
/usr/local/lib/python3.6/site-packages/py/_path/local.py:701: in pyimport
    __import__(modname)
/usr/local/lib/python3.6/site-packages/_pytest/assertion/rewrite.py:140: in exec_module
    exec(co, module.__dict__)
test_bitwarden_keyring.py:8: in <module>
    import bitwarden_keyring as bwkr
E   ModuleNotFoundError: No module named 'bitwarden_keyring'

----------- coverage: platform linux, python 3.6.8-final-0 -----------
Name    Stmts   Miss Branch BrPart  Cover   Missing
---------------------------------------------------

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Interrupted: 1 errors during collection !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
========================================================================== 1 error in 0.34s ==========================================================================
[me@centos7 tests]$
/home/me/github/bitwarden-keyring/tests
[me@centos7 tests]$

Get password

I can create a new item:

$ keyring set hello world
Password for 'world' in 'hello':
Created.

The bitwarden-cli shows the new item as expected: $ bw get item hello

But keyring get hello world doesn't return anything. (It doesn't raise an error either.)

I'm on Win10 with bitwarden-cli version 2023.5.0. Could you help me to troubleshoot the issue? I don't know where to start.

Who to setup bw to be used by python keyring?

Because of this, it's likely that your setup and my setup are nothing alike. Keyring supports a configuration file with an option allowing to explicitely define the path to a backend. You may need that for your installation, or maybe not.

What exactly should I to write in config to specified keyring backend in python keyrign?

TypeError: a bytes-like object is required, not 'str'

I was getting the following error when trying to run it. I noticed the issue was caused by line 93-95 in init.py. Could be due to me using Windows/Python3.7.

I was able to fix the issue by setting encoding for subprocess and removing encoding for stdout.

rashed-c@11d624e

However, I am still a bit confused about how to pull credentials properly. Can you please give me an example on how you would use bitwarden-keyring?

Thanks.