Package: saltext.bitwarden
bitwardenSalt Extension Modules for BitwardenIntroductionThis extension forSaltenables Salt to access and administer aBitwardenvault/instance.This project aims to eventually have 100% coverage of theBitwarden Vault Management APIand theBitwarden Public (Organization Management) API. This extension
is changing quickly, and while attempts will be made to not make breaking changes, the current
focus is on functionality rather than syntax/API stability.RequirementsThis extension requires thebwBitwarden CLI utility to be installed for functions that depend
on theBitwarden Vault Management API. Installation instructions are availablehere. It also has dependencies on thepyhumps,requests, andvalidatorspython packages, which are automatically installed.InstallationAn example state file for installing and configuring this extension on EL8 (RHEL, AlmaLinux, Rocky
Linux, Oracle Linux, Scientific Linux, etc.):# Install the NodeSource EL8 repo to get Node.jscmd_nodesource-el8.repo:cmd.run:-name:curl -fsSL https://rpm.nodesource.com/setup_18.x | bash --creates:-/etc/yum.repos.d/nodesource-el8.repo# Bitwarden CLI depends on Node.jspkg_nodejs:pkg.installed:-name:nodejs-require:-cmd_nodesource-el8.repo# Install the Bitwarden CLI client (which includes the Vault Management REST API# server)npm_bitwarden_cli:npm.installed:-name:'@bitwarden/cli'-require:-pkg_nodejs# Install the Bitwarden Salt Extensionpip_saltext.bitwarden:pip.installed:-name:saltext.bitwarden-require:-npm_bitwarden_cli# Configure server options for Bitwarden REST API Serverfile_/etc/sysconfig/bw-api:file.managed:-name:/etc/sysconfig/bw-api-user:root-group:root-mode:"0644"-contents:|# Command-line options for bw serveBITWARDENCLI_APPDATA_DIR=/etc/salt/.bitwardenOPTIONS="--hostname localhost --port 8087"-require:-pip_saltext.bitwarden-watch_in:-service_bw-api# Create a systemd service unit file since one is not included in the package.# Reloads systemctl if the file changes.file_/etc/systemd/system/bw-api.service:file.managed:-name:/etc/systemd/system/bw-api.service-user:root-group:root-mode:"0644"-contents:|[Unit]Description=Bitwarden Vault Management APIDocumentation=https://bitwarden.com/help/cli/After=network.target[Service]EnvironmentFile=-/etc/sysconfig/bw-apiUser=saltGroup=saltType=simpleWorkingDirectory=~ExecStart=/bin/bw serve $OPTIONSRestart=always[Install]WantedBy=multi-user.target-require:-file_/etc/sysconfig/bw-api-watch_in:-service_bw-api# You must manually create files in /etc/salt/master.d/bitwarden.conf or# /etc/salt/minion.d/bitwarden.conf (or both) depending on the context, with the following contents# (substituting values as appropriate):##  bitwarden:#    driver: bitwarden#    cli_path: /bin/bw#    cli_conf_dir: /etc/salt/.bitwarden#    cli_runas: salt#    vault_url: https://bitwarden.com#    email: user@example.com#    password: CorrectHorseBatteryStaple#    vault_api_url: http://localhost:8087#    public_api_url: https://api.bitwarden.com#    client_id: 25fa6fc6-deeb-4b42-a279-5e680b51aa58#    client_secret: AofieD0oexiex1mie3eigi9oojooF3#    org_client_id: organization.d0e19db4-38aa-4284-be3d-e80cff306e6c#    org_client_secret: aWMk2MBf4NWXfaevrKyxa3uqNXYVQy# Used for runner and SDB modulesfile_/etc/salt/master.d/bitwarden.conf:file.exists:-name:/etc/salt/master.d/bitwarden.conf-require:-pip_saltext.bitwarden# Used for execution, SDB and state modulesfile_/etc/salt/minion.d/bitwarden.conf:file.exists:-name:/etc/salt/minion.d/bitwarden.conf-require:-pip_saltext.bitwarden# Make sure the Bitwarden vault is logged in before we start the REST API server# service otherwise the service will refuse to startbitwarden_logged_in:bitwarden.logged_in:-name:logged_in-use_cli:True-profile:bitwarden# Run the Bitwarden Vault Management REST API server `bw serve`service_bw-api:service.running:-name:bw-api-enable:True-init_delay:10-require:-bitwarden_logged_in# State to reload systemctlservice_systemctl_reload:module.run:-name:service.systemctl_reload-onchanges:-file_/etc/systemd/system/bw-api.service# Use firewalld to protect the Bitwarden Vault Management REST API serverservice_firewalld:service.running:-name:firewalld-enable:True-reload:True# Lock down access to the Bitwarden Vault Management REST API to only the root user (uid 0) using# firewalld because once the vault is unlocked, access is completely unauthenticated.## See https://github.com/bitwarden/clients/issues/3932## We directly manage the direct rules configuration file because the Salt firewalld state module# doesn't support direct rules.file_/etc/firewalld/direct.xml:file.managed:-name:/etc/firewalld/direct.xml-user:root-group:root-mode:"0644"-contents:|<?xml version="1.0" encoding="utf-8"?><!--#########################################################################                                                                      ##              THIS FILE IS MANAGED BY SALT - DO NOT EDIT              ##                                                                      ## The contents of this file are managed by Salt. Any changes to this   ## file may be overwritten automatically and without warning.           #########################################################################--><direct><rule ipv="ipv4" table="filter" chain="OUTPUT" priority="0">-o lo -p tcp --dport 8087 -m owner --uid-owner root -j ACCEPT</rule><rule ipv="ipv4" table="filter" chain="OUTPUT" priority="0">-o lo -p tcp --dport 8087 -m owner --uid-owner salt -j ACCEPT</rule><rule ipv="ipv4" table="filter" chain="OUTPUT" priority="1">-o lo -p tcp --dport 8087 -j REJECT</rule><rule ipv="ipv6" table="filter" chain="OUTPUT" priority="0">-o lo -p tcp --dport 8087 -m owner --uid-owner root -j ACCEPT</rule><rule ipv="ipv6" table="filter" chain="OUTPUT" priority="0">-o lo -p tcp --dport 8087 -m owner --uid-owner salt -j ACCEPT</rule><rule ipv="ipv6" table="filter" chain="OUTPUT" priority="1">-o lo -p tcp --dport 8087 -j REJECT</rule></direct>-watch_in:-service_firewalldThe configuration files required vary depending on which module you wish to use:module typefile typeexecutionminionrunnermastersdbmaster, minionstateminionUsageThis extension currently provides only read-only access to Bitwarden vaults using thesdbmodule,
with other modules primarily for vault management such as logging in and unlocking the vault.# SDB via runner modulesalt-runsdb.get'sdb://bitwarden/by-uuid/2fcd790a-70f7-43a2-b265-08a763873980/password'CorrectHorseBatteryStaple# SDB via execution modulesalt-callsdb.get'sdb://bitwarden/by-uuid/2fcd790a-70f7-43a2-b265-08a763873980/password'local:CorrectHorseBatteryStapleAs always, you can also reference SDB modules in your pillar files:example_pillar:some_password:{{salt['sdb.get']('sdb://bitwarden/by-uuid/2fcd790a-70f7-43a2-b265-08a763873980/password')}}The format of the SDB URI is as follows:sdb://<profile>/by-uuid/<uuid>/<object>Where<profile>is the profile defined in the master or minion configuration
file,<uuid>is the UUID of the item, and<object>is one of:nameusernamepasswordtotpnotescreation_daterevision_datedeleted_datepassword_revision_dateAdditionally, password history can be retrieved with the following SDB URI
format:sdb://<profile>/by-uuid/<uuid>/password_history/by-index/<index>Where<profile>is the profile defined in the master or minion configuration
file,<uuid>is the UUID of the item, andindexis a non-negative
integer specifying which password to retrieve from the history (0 being the
current password, 1 being the previous password, and so forth).Lastly, custom fields can be retrieved with the following SDB URI format:sdb://<profile>/by-uuid/<uuid>/fields/by-name/<field_name>/<object>Where<profile>is the profile defined in the master or minion configuration
file,<uuid>is the UUID of the item,<field_name>is the name of
custom field, and object is one of:valuetypelinked_idNote that the custom field name must be unique within an item.
Bitwarden does not enforce unique custom field names, so that is left up to the
user.The UUID of an item can be found using the Bitwarden CLI:bwlistitems--search"Google Account"--pretty[{"object":"item","id":"2fa63ad5-e4e4-43d4-a089-3fadcf455be2","organizationId":null,"folderId":null,"type":1,"reprompt":0,"name":"Google Account","notes":null,"favorite":false,"login":{"uris":[{"match":null,"uri":"https://accounts.google.com"}],"username":"user@example.com","password":"aTjSsJvhQY5E24","totp":"AEM1HEESIEV8YAED8THUBEHOOW","passwordRevisionDate":null},"collectionIds":[],"revisionDate":"1970-01-01T00:00:00.000Z"}]DocsModule documentation is available athttps://ggiesen.gitlab.io/salt-ext-bitwarden.BugsBugs can be reported using theIssue Tracker.ContributingAll contributions are welcome and very much appreciated. Contributing guide coming soon.
Contributing can take many forms, including:Reporting bugsFeature requestsCode submissions (bug fixes/new features/improve code quality)Writing testsWriting documentationDetailing use casesWriting blog postsLicenseThis project is licensed under the Apache Software License. SeeLICENSEfor the licence text.