Package: pwsync
A Password synchronization toolNobody can be held liable for any damages cause by this tool.
Always make a backup before using this tool.pwsyncis a low level command line tool that synchronizespassword databases.pwsyncgrew from a personal need to simplify credential usage for online services
(e.g. for web shops, banks, cloud services, ...)
on different platforms (Ubuntu, iPad, Android mobile, ...).
Keepass feels outdated for such use-cases.
Bitwarden (and alikes) simplify authentication thanks to itsbrowser extension.
Due to the personal use case,pwsynconly supportsKeepassdatabase files
andBitwardenonline database.
But anybody can add support for other cloud password services
if their (public) REST API is known with a Pull Request.These properties of the password database features are handled (thelowest common denominator):a hierarchical classification withfolder/groupa credential'stitle/descriptionausername(an empty username is not supported)apassword(per credential)notesoneurl(without the matching capabilities of Bitwarden)a one time pass code (TOTPwhich Keepass stores in itsattributesproperty aspws_totp)afavoriteflag (Keepass stores this in its attributes property aspws_fav)an organization (required when using collections, which Keepass stores aspws_orgin its attributes property)multiple collections (which Keepass keeps in its attributes property aspws_col)a specificsyncflag that, if missing, will ignore a password database entry during synchronization
(Keepass keeps this in its attributes property aspws_sync)Support for fields, icons, expiration date, the automatic creation of organizations,
changes on a credential's collection set, Bitwarden's reprompt,
Bitwarden's multiple urls and matching patterns, privately hosted Bitwarden etc.is currently missing!UsageIt is important to familarize oneself withpwsyncfirst!
Use the toy Keepass password database files in thedemodirectory (passphrase ispw).
Read this documentation to its very end.# main use-case: synchronize changes from a local Keepass database to an online Bitwarden database.# for all entries that have their _pws_sync_ flag set.pwsync--fromdemo/from.kdbx--tobitwarden# Similar but use the 2 toy Keepass password database files# make a backup into a "to.kdbx.backup" first!# see below for an example of typical output.pwsync--fromdemo/from.kdbx--todemo/to.kdbx# Do a dry-run (-d) for syncing all (-a) items that match the selection (-s)# Item's are matched based on the concatenation of their <folder-value> '/' <title-value>python-mpwsync.main-d-fdemo/from.kdbx-tdemo/to.kdbx-a\-s".*/folder 1.1/.*"-s"folder 2/.*"\--from-master-password=pw--to-master-password=pw# a description of all optionspwsync-hInstallationpwsyncdepends on theBitwarden command line clienttool.
This tool and its installation description can be foundhere.npminstall-g@bitwarden/cli# get git, python (here version 3.8) and build toolssudoaptinstall-y--upgradegitbuild-essentialpython3.8-venvpython3.8-dev# clone the pwsync repo locallygitclonehttps://github.com/aptly-io/pwsync.gitcdpwsync# prepare a virtual env. to avoid conflicts with existing python installation(s)python3.8-mvenv.venv
..venv/bin/activate# upgrade pip and setuptoolspython-mpipinstall--upgradepipsetuptoolsbuildAs userInstall the script and try-out the installation with the command command shown in Usage.python-mpipinstall--upgrade.As developer# use an "editable" install together with tools for source code formatting, linting and testingpython-mpipinstall--upgrade-e.[dev]# and/or with tools for building a distributionpython-mpipinstall--upgrade.[build]# install a git pre-commit hooks according to .pre-commit-config.yamlpre-commitinstallDevelopment# format the source code (configuration in pyproject.toml) (done by pre-commit hook)python-mblackpwsync/*.pytests/*.py# linting and source code analysis (ran in pre-commit hook)python-mpylintpwsynctests||echo"FAILED"python-mpylamapwsync/*.py# tests with an xml coverage report for pwsync# the test_bwc requires an online account; provide the credentials in env. vars.exportTEST_BW_CLIENT_ID=exportTEST_BW_CLIENT_SECRET=exportTEST_BW_MASTER_PASSWORD=python-mpytest-s-vvv--cov=pwsync--cov-report=xml:cov.xmltests||echo"FAILED"# or run a specific individual testpython-mpytest-s-vvvtests/test_bwc.py-ktest_create_one_collection# for distribution# for the proper version to be generated, use the main branch with a tag like v0.1b5python-mbuild# upload on testpypitwinecheck--strictdist/*# basic check# do a minimal test of the package in a new venvdeactivate
python3.8-mvenv.venv_install
..venv_install/bin/activate
python-mpipinstalldist/pwsync-0.1b5-py3-none-any.whl
whichpwsync
pwsync--fromdemo/from.kdbx--todemo/to.kdbx
deactivate
rm-rf.venv_install# finally uploadpython-mtwineupload--repositorytestpypidist/*Technical detailsThe supported password databases use different technology and implementation:
Keepass is file based while Bitwarden is a cloud service.
To recognize equivalent password entries between the databases,pwsyncidentifies entries by certain property value(s).
By default thefolderandtitleproperty values are used.
(this can be customized with the--idcommand line option).The synchronization goes in 1 direction:
only thetodatabase could get modified due to differences with thefromdatabase.
There are 3 modification types:create: adds a new password entry in thetodatabase because it exists only in thefromdatabase.delete: removes an entry from thetodatabase because it does not exist in thefromdatabase.update: changes an entry in thetodatabase because it is different for the equivalent entry in thefromdatabase.Aconflictis when thetopassword entry has a more recent modification time than
its equivalent entry in thefromdatabase.
Conflicts are skipped bypwsync; one has to manually address these.Changing the property value used for password entry identification (e.g. thetitle) in one database,
causes a create/delete modification!To synchronize,pwsyncdepends on:The pythondiffsyncmodule: determines the differences between two password databases.The pythonpykeepassmodule: modifies a Keepass_ file.The pythonprompt-toolkitmoduleBitwarden's official(?)command line client: modifies a Bitwarden online password database.An curated dump of the console output is shown below:The passphrase to open the Keepass file is prompted.Since the output would be too large, parts arecut out.There are no conflicts in this example.There are 7 updates (7 entries infrom.kdbxare different and more recent thanto.kdbx).For easier interpretation, differences are highlighted in red and green.in the first example, theusernamechanged fromnametoName updated.secrets are obviously hiddenThere are 11 new and removed entries (only 1 of each is shown).
What exactly is added and removed in the entry is show (again in green and red respectively).
The 1 create and delete entry shown, are very similar; in fact these differ only in theirtitle.
This is the reasonpwsynmcsees these as different entries (as explained higher)!Licensepwsyncis necessarily GPL3 since it (currently) depends upon the GPL3 python modulepykeepass.Copyright 2022, 2023 Francis Meyvis (pwsync@mikmak.fun)