A Python implementation and CLI for bitwarden
Project description
Cross Platform Bitwarden library and CLI with sudolikeaboss functionality.
This repo houses both python and rust versions.
STATUS: python version works, rust version does not fully work yet (pull
requests, patches, etc welcome)
patches, bug reports and code welcome.
source repo lives @ https://fossil.birl.ca/bitwarden-cli/home
But is mirrored to github:
https://github.com/birlorg/bitwarden-cli
Historic fun fact: all crypto code had to be stored outside
of the USA at one time.
------------------------------------------------------------
EXAMPLE USAGE:
ALIAS bw=bitwarden
GET HELP:
---------
$ bitwarden --help
Usage: bitwarden [OPTIONS] COMMAND [ARGS]...
Bitwarden CLI program.
Options:
--url TEXT
--identurl TEXT
--debug / --no-debug
--db TEXT
--help Show this message and exit.
Commands:
deletedb ***THIS ERASES DATA*** Flush and empty the...
fetch_name fetch by name.
fetch_uuid fetch by UUID.
find find query in username,uri this does a simpe...
login login to server.
logout logout from server, stop agent and forget all...
pull pull all records from server, updating local...
register register a new account on server.
slab run in slab mode.
sql query the local data store using SQL.
status Show various statistics.
$ bitwarden find --help
Usage: bitwarden find [OPTIONS] QUERY
find query in username,uri
this does a simpe python string find i.e.:
if query in username:
but searches against username and first url
You can export it in almost any format you wish with -f
to get the password once you found an entry use fetch_uuid
complicated example:
bw find example.com -f tsv --no-headers | fzf | cut -f 1 | xargs bitwarden fetch_uuid -p
which means: find all entries with example.com in them, use fzf to select
a record and return only the password.
Options:
-f, --format [csv|tsv|json|yaml|html|xls|xlsx|dbf|latex|ods]
--headers / --no-headers
--help Show this message and exit.
---- USAGE:
login:
bw login nobody@example.com
it will prompt you for a password. if you are
a moron, you can specify it with --password <MY PASSWORD HERE> but don't be a
moron.
SLAB mode: "sudolikeaboss is a simple application that aims to make your life as
a dev, ops, or just a random person who likes to ssh and sudo into boxes much,
much easier by allowing you to access your bitwarden passwords on the terminal.
All you need is iterm2, bitwarden, a mac, and a dream." - from:
https://github.com/ravenac95/sudolikeaboss
We support self-hosted installations just pass --url and --identurl The url will
be saved indefinitely, you do not need to set it every time (not even when you
login again, it will be remembered) see bw login --help for details.
-----------------------------------------------------------------------
SECURITY:
Bitwarden works by having a "master key" that is computed from your email and
password. This needs to be kept "safe", but this is a CLI program. We could
store the master key on disk somewhere, but that's a bad idea.
The way we do this is with an in-memory 'agent' that listens on a 127.0.0.1 port
(configurable, but defaults to 6277) see: python/bitwarden/agent.py for all the
details. Bonus if you figure out why that port # :). Ideally on POSIX platforms
it would use a socket on disk somewhere to communicate, but I wanted this to
work on Windows, so this is what we can do.. :) patches welcoome to fix this up
on POSIX.
when you login, it starts up the agent, with a timeout set to the login
access_token timeout in seconds, since we do not currently support re-freshing
the token. At the end of the token lease, the agent will kill itself and stop
running. (this is configurable, but not exported to the CLI yet -- patches
welcome)
The agent requires a token to get the master key from it's in-memory store.
This is currently 16 bytes of os.urandom() on startup and is stored on disk, but
changes every time a new agent runs.details are in python/bitwarden/db.py
This should mostly function fine on Windows, but is currently untested. bug
reports and patches welcome.
-----------------------------------------------------------------------
INSTALLATION
NOTE: the rust and python are 2 different implementations that are not
(currently) tied together. you need not install both, just install one (the
pythone one currently if you want it to work)..
rust installation:
clone the repo (either fossil or git)
cd rust cargo build --release
cp target/release/bitwarden /usr/local/bin/bitwarden
then follow DB setup instructions below.
python installation:
clone the repo (either fossil or git)
cd python
python3 setup.py install
then follow DB setup instructions below.
or better yet, use pipenv.
Common to both, the DB setup:
If you have liquibase and the sqlite JDBC driver,
run tools/lb.sh Otherwise copy over the blank DB (with schema installed) I
include in the tools/ dir the directory it belongs in is platform dependent, run
bitwarden and it will tell you. Alternatively you can put the DB wherever you
like and always prepend --db to your commands (not recommended)
-------------------------------------------------------------------
TROUBLESHOOTING:
export DEBUG=true and then run bitwarden. or bitwarden --debug <cmd>
It will output LOTS
of stuff, some of it is security sensitive, so be careful when you copy/paste
the logs.
--------------------------------
TODO planned(code welcome):
* finish off minimal implementation of the python version (search, add, etc)
* build and release executables for mac and windows. build Makefile to automate
this.
* finish off rust crypto and agent, port python version to use rust crypto and
agent
* add server support (i.e. can also act like a server, so you could for
instance have your local browser and desktop talk locally and work 100%
off-line)
* fix up documentation in
HTML(http://fossil-scm.org/index.html/doc/trunk/www/embeddeddoc.wiki) and
make prettier.
Goals:
* be a useful bitwarden tool that works on openBSD, debian, macOS and windows
since these are the platforms I spend most of my time on. UI is abysmal,
thanks to @kspearrin for doing that slog, go pay him.
* be able to work off-line completely if you wish. (slab mode already does
this..mostly)
Non-Goals:
* GUI's because writing them is misery. @kspearrin has this well-handled! YAY!
-----------
email: bitwarden <at> birl.ca
This repo houses both python and rust versions.
STATUS: python version works, rust version does not fully work yet (pull
requests, patches, etc welcome)
patches, bug reports and code welcome.
source repo lives @ https://fossil.birl.ca/bitwarden-cli/home
But is mirrored to github:
https://github.com/birlorg/bitwarden-cli
Historic fun fact: all crypto code had to be stored outside
of the USA at one time.
------------------------------------------------------------
EXAMPLE USAGE:
ALIAS bw=bitwarden
GET HELP:
---------
$ bitwarden --help
Usage: bitwarden [OPTIONS] COMMAND [ARGS]...
Bitwarden CLI program.
Options:
--url TEXT
--identurl TEXT
--debug / --no-debug
--db TEXT
--help Show this message and exit.
Commands:
deletedb ***THIS ERASES DATA*** Flush and empty the...
fetch_name fetch by name.
fetch_uuid fetch by UUID.
find find query in username,uri this does a simpe...
login login to server.
logout logout from server, stop agent and forget all...
pull pull all records from server, updating local...
register register a new account on server.
slab run in slab mode.
sql query the local data store using SQL.
status Show various statistics.
$ bitwarden find --help
Usage: bitwarden find [OPTIONS] QUERY
find query in username,uri
this does a simpe python string find i.e.:
if query in username:
but searches against username and first url
You can export it in almost any format you wish with -f
to get the password once you found an entry use fetch_uuid
complicated example:
bw find example.com -f tsv --no-headers | fzf | cut -f 1 | xargs bitwarden fetch_uuid -p
which means: find all entries with example.com in them, use fzf to select
a record and return only the password.
Options:
-f, --format [csv|tsv|json|yaml|html|xls|xlsx|dbf|latex|ods]
--headers / --no-headers
--help Show this message and exit.
---- USAGE:
login:
bw login nobody@example.com
it will prompt you for a password. if you are
a moron, you can specify it with --password <MY PASSWORD HERE> but don't be a
moron.
SLAB mode: "sudolikeaboss is a simple application that aims to make your life as
a dev, ops, or just a random person who likes to ssh and sudo into boxes much,
much easier by allowing you to access your bitwarden passwords on the terminal.
All you need is iterm2, bitwarden, a mac, and a dream." - from:
https://github.com/ravenac95/sudolikeaboss
We support self-hosted installations just pass --url and --identurl The url will
be saved indefinitely, you do not need to set it every time (not even when you
login again, it will be remembered) see bw login --help for details.
-----------------------------------------------------------------------
SECURITY:
Bitwarden works by having a "master key" that is computed from your email and
password. This needs to be kept "safe", but this is a CLI program. We could
store the master key on disk somewhere, but that's a bad idea.
The way we do this is with an in-memory 'agent' that listens on a 127.0.0.1 port
(configurable, but defaults to 6277) see: python/bitwarden/agent.py for all the
details. Bonus if you figure out why that port # :). Ideally on POSIX platforms
it would use a socket on disk somewhere to communicate, but I wanted this to
work on Windows, so this is what we can do.. :) patches welcoome to fix this up
on POSIX.
when you login, it starts up the agent, with a timeout set to the login
access_token timeout in seconds, since we do not currently support re-freshing
the token. At the end of the token lease, the agent will kill itself and stop
running. (this is configurable, but not exported to the CLI yet -- patches
welcome)
The agent requires a token to get the master key from it's in-memory store.
This is currently 16 bytes of os.urandom() on startup and is stored on disk, but
changes every time a new agent runs.details are in python/bitwarden/db.py
This should mostly function fine on Windows, but is currently untested. bug
reports and patches welcome.
-----------------------------------------------------------------------
INSTALLATION
NOTE: the rust and python are 2 different implementations that are not
(currently) tied together. you need not install both, just install one (the
pythone one currently if you want it to work)..
rust installation:
clone the repo (either fossil or git)
cd rust cargo build --release
cp target/release/bitwarden /usr/local/bin/bitwarden
then follow DB setup instructions below.
python installation:
clone the repo (either fossil or git)
cd python
python3 setup.py install
then follow DB setup instructions below.
or better yet, use pipenv.
Common to both, the DB setup:
If you have liquibase and the sqlite JDBC driver,
run tools/lb.sh Otherwise copy over the blank DB (with schema installed) I
include in the tools/ dir the directory it belongs in is platform dependent, run
bitwarden and it will tell you. Alternatively you can put the DB wherever you
like and always prepend --db to your commands (not recommended)
-------------------------------------------------------------------
TROUBLESHOOTING:
export DEBUG=true and then run bitwarden. or bitwarden --debug <cmd>
It will output LOTS
of stuff, some of it is security sensitive, so be careful when you copy/paste
the logs.
--------------------------------
TODO planned(code welcome):
* finish off minimal implementation of the python version (search, add, etc)
* build and release executables for mac and windows. build Makefile to automate
this.
* finish off rust crypto and agent, port python version to use rust crypto and
agent
* add server support (i.e. can also act like a server, so you could for
instance have your local browser and desktop talk locally and work 100%
off-line)
* fix up documentation in
HTML(http://fossil-scm.org/index.html/doc/trunk/www/embeddeddoc.wiki) and
make prettier.
Goals:
* be a useful bitwarden tool that works on openBSD, debian, macOS and windows
since these are the platforms I spend most of my time on. UI is abysmal,
thanks to @kspearrin for doing that slog, go pay him.
* be able to work off-line completely if you wish. (slab mode already does
this..mostly)
Non-Goals:
* GUI's because writing them is misery. @kspearrin has this well-handled! YAY!
-----------
email: bitwarden <at> birl.ca
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
bitwarden-0.2.1.tar.gz
(18.9 kB
view hashes)
Built Distributions
bitwarden-0.2.1-py3-none-any.whl
(18.7 kB
view hashes)
Close
Hashes for bitwarden-0.2.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fedd5d17ffa1ccaab31d07d396e34858e5de9280ee792ff61bbf3aef7fb68d84 |
|
MD5 | afcde0e4f7b88085548deb4e81edaedf |
|
BLAKE2b-256 | c883ba7aecc9a99a05e2ef08e88596a80128288bd20f005afbb9ea1615c4791d |
Close
Hashes for bitwarden-0.2.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fa0a3c8463ea9a803c95628400d5eed8c7dfe64fda6a7aaa7062fd274eaa0b88 |
|
MD5 | f7a3ee5b6351c8338bdc66d48f53b2f3 |
|
BLAKE2b-256 | d51fadd092bac53f4ea73bc17ae7e37fd07da08bc51363e977108366a7f83d4d |