keepass_kpscript 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4d8c2308abfd17cef4c6c0c52c2ecefd0a499bf8cc7d451c9e53b50b98d53702
+  data.tar.gz: ae4cc14f37d7de8ed8a2003017c33503e8e686ec1a10ed2ef91ff5174dc77cb5
+SHA512:
+  metadata.gz: 8bcdd547d96ea071093859910a4042ed0c129856b8999ed59d24f53893afe8f4821f1fa7506186a12ea6f89300dabb2ee724ea6e29401be8708a4ba49dd4d8cb
+  data.tar.gz: 3821acb14d910905dba791592d70e951db2a5f9a7bb67de4c471d0d84d9a4bcb96890a2b2057c73c233a1cdc772ad39152ff6d864372dd3f0997bb7614b055be

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# [v0.0.1](https://github.com/Muriel-Salvan/keepass_kpscript/compare/...v0.0.1) (2021-06-30 10:50:35)
+
+### Patches
+
+* [Added semantic releasing](https://github.com/Muriel-Salvan/keepass_kpscript/commit/836b38f193a9bce29c1092490805a592a450c214)
+* [Typo](https://github.com/Muriel-Salvan/keepass_kpscript/commit/c5e3ae4c359228d1d1bea8cef7ac80f86539aecc)

data/README.md

@@ -0,0 +1,180 @@
+[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
+
+# keepass_kpscript - Ruby API to handle Keepass databases using KPScript
+
+## Description
+
+This Rubygem gives you ways to handle [KeePass databases](https://keepass.info/) using the [KPScript KeePass plugin](https://keepass.info/plugins.html#kpscript).
+
+Other Rubygems handling KeePass databases usually handle the databases format themselves and can get obsolete if not kept up-to-date with the new file specifications.
+
+`keepass_kpscript` uses the official KPScript plugin installed with a KeePass installation to handle databases, so that the risk of specifications' obsolescence is low (unless KPScript changes its command-line interface). However the cons of this approach is that `keepass_kpscript` needs a local installation of KeePass and KPScript to run.
+
+Works for both Windows and Linux installations of KPScript.
+
+## Requirements
+
+* [KeePass](https://keepass.info/) - To be installed locally.
+* [KPScript KeePass plugin](https://keepass.info/plugins.html#kpscript) - To be installed in your KeePass installation (follow the install instructions from the KPScript documentation).
+
+## Install
+
+Via gem command line:
+
+```bash
+gem install keepass_kpscript
+```
+
+If using `bundler`, add this in your `Gemfile`:
+
+```ruby
+gem 'keepass_kpscript'
+```
+
+## Usage
+
+Basically you just need to tell `keepass_kpscript` the KPScript command-line to be used (with `KeepassKpscript.use`), and the API will give you access to KPScript API to handle KeePass databases.
+
+```ruby
+require 'keepass_kpscript'
+
+# Let's use the system KeePass (under Windows, enclose it within "" for paths containing spaces like 'Program Files')
+kpscript = KeepassKpscript.use('"C:\Program Files\KeePass\KPScript.exe"')
+
+# Open a database with a simple password
+database = kpscript.open('C:\Data\MyDatabase.kdbx', password: 'MyP4$sW0rD')
+
+# Read a password for an entry
+google_password = database.password_for 'Google Account'
+puts "Password for 'Google Account' is #{google_password}"
+```
+
+Now that you get the basic usage, you can see the following sections for more features.
+
+### Using key files, passwords and encrypted passwords to open databases
+
+The [`Kpscript#open`](lib/keepass_kpscript/kpscript.rb) method accepts the following parameters while opening a database:
+* `password`: The password to be used.
+* `password_enc`: The encrypted password to be used (can be used in place of the password). You can use the [`Kpscript#encrypt_password`](lib/keepass_kpscript/kpscript.rb) method to generates an encrypted password from a password.
+* `key_file`: Path to the key file to be used.
+
+Example: open a database protected both by a password and a key file, and use an encrypted version of the password to open it.
+
+```ruby
+encrypted_password = kpscript.encrypt_password('MyP4$sW0rD')
+
+# This will not use the real password on KPScript command-line, which is better security wise.
+database = kpscript.open('C:\Data\MyDatabase.kdbx', password_enc: encrypted_password, key_file: 'C:\Data\Database.key')
+```
+
+### Read entries from a database
+
+The most versatile method to read database content is [`Database#entries_string`](lib/keepass_kpscript/database.rb), which maps directly the [`GetEntryString` KPScript method](https://keepass.info/help/v2_dev/scr_sc_index.html#getentrystring).
+
+It uses chainable selectors to select the entries to be read, based on field names, uuids...
+
+Example: read the URL field of all entries tagged `production` belonging to the group `Azure`
+```ruby
+database.entries_string(kpscript.select.tags('production').group('Azure'), 'URL').each do |url|
+  puts "Found URL: #{url}"
+end
+```
+
+A more secure way to read secrets from a database is by using [`Database#with_entries_string`](lib/keepass_kpscript/database.rb) that works with a code block and the same parameters as [`Database#entries_string`](lib/keepass_kpscript/database.rb). The benefits are:
+* Any variable that would have been read will be erased from memory at the end of the code execution, so that no attacker can eventually read it from memory, code injection, or memory dump on disk.
+* The secret strings given to the code will be [`SecretString`](https://github.com/Muriel-Salvan/secret_string) instead of a String, that will guard the secret from being revealed in common Ruby operations (logging, screen output...), unless the `to_unprotected` method is used on it. Better way to control accessibility of your secrets!
+
+Example: read all the passwords of entries belonging to Google's URL, and make sure those passwords are removed from memory after usage (and even try to leak the password in memory_)
+```ruby
+# Try to leak the password (simulating a security vulnerability here)
+leaked_password = nil
+
+database.with_entries_string(kpscript.select.fields(URL: '//google.com//'), 'Password').each do |password|
+  puts "Displayed password: #{password}"
+  # => Displayed password: XXXXX
+  puts "Now we REALLY want to display the password: #{password.to_unprotected}"
+  # => Now we REALLY want to display the password: MyP4$sW0rD
+  leaked_password = password
+end
+
+# Now that we are out of the code block, let's try to use the password again, hehe }:->
+puts "Displayed leaked password: #{leaked_password.to_unprotected}"
+# => Displayed leaked password:
+```
+
+To know more:
+* The possible field references are documented in [KeePass documentation](https://keepass.info/help/base/fieldrefs.html).
+* The possible selectors that can be used on the `Kpscript#select` call are methods defined in [the `Select` class](lib/keepass_kpscript/select.rb).
+
+### Edit entries in a database
+
+[`Database#edit_entries`](lib/keepass_kpscript/database.rb) can be used to edit entries. It maps the [`EditEntry` KPScript method](https://keepass.info/help/v2_dev/scr_sc_index.html#editentry) functionality.
+
+The API uses the same selectors' logic as [`Database#entries_string`](lib/keepass_kpscript/database.rb).
+
+Example: add notes and set the icon index 5 to all entries having a Google URL
+```ruby
+database.edit_entries(
+  kpscript.select.fields(URL: '//google.com//'),
+  fields: { Notes: 'It\'s for Google' },
+  icon_idx: 5
+)
+```
+
+### Export a database
+
+[`Database#export`](lib/keepass_kpscript/database.rb) maps the [`Export` KPScript method](https://keepass.info/help/v2_dev/scr_sc_index.html#export) to export databases.
+
+```ruby
+database.export('KeePass XML (2.x)', 'my_export.xml')
+```
+
+### Detach binaries (attachments) from a database
+
+[`Database#detach_bins`](lib/keepass_kpscript/database.rb) maps the [`DetachBins` KPScript method](https://keepass.info/help/v2_dev/scr_sc_index.html#detachbins) to extract files from databases.
+
+Be careful that by default this method modifies your database by removing the attached files from it and writing them next to it.
+If you want to keep your database intact, you can use the `copy_to_dir` option and it will extract files without removing them to antoher directory.
+
+```ruby
+# Extract all files from database into the ./my_files sub-folder.
+database.detach_bins(copy_to_dir: 'my_files')
+
+# Extract and remove all files from database next to the database file.
+database.detach_bins
+```
+
+## Change log
+
+Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
+
+## Testing
+
+Automated tests are done using rspec.
+
+To execute them, first install development dependencies:
+
+```bash
+bundle install
+```
+
+Then execute rspec
+
+```bash
+bundle exec rspec
+```
+
+## Contributing
+
+Any contribution is welcome:
+* Fork the github project and create pull requests.
+* Report bugs by creating tickets.
+* Suggest improvements and new features by creating tickets.
+
+## Credits
+
+- [Muriel Salvan](https://x-aeon.com/muriel)
+
+## License
+
+The BSD License. Please see [License File](LICENSE.md) for more information.

data/lib/keepass_kpscript.rb

@@ -0,0 +1,22 @@
+require 'keepass_kpscript/kpscript'
+
+# Ruby API wrapping the KPScript CLI
+module KeepassKpscript
+
+  class << self
+
+    # Get a KPScript instance from a given KPScript command line
+    #
+    # Parameters::
+    # * *cmd* (String): KPScript command line
+    # * *debug* (Boolean): Do we activate debugging logs? [default: false]
+    #     Warning: Those logs can contain passwords and secrets from your database. Only use it in a local environment.
+    # Result::
+    # * Kpscript: A KPScript instance
+    def use(cmd, debug: false)
+      Kpscript.new(cmd, debug: debug)
+    end
+
+  end
+
+end

data/lib/keepass_kpscript/database.rb

@@ -0,0 +1,186 @@
+require 'fileutils'
+require 'open3'
+require 'secret_string'
+require 'time'
+require 'keepass_kpscript/select'
+
+module KeepassKpscript
+
+  # KPScript API handling a KeePass database
+  class Database
+
+    # Constructor
+    #
+    # Parameters::
+    # * *kpscript* (Kpscript): The KPScript instance handling this database
+    # * *database_file* (String): Database file path
+    # * *password* (String or nil): Password opening the database, or nil if none [default: nil].
+    # * *password_enc* (String or nil): Encrypted password opening the database, or nil if none [default: nil].
+    # * *key_file* (String or nil): Key file path opening the database, or nil if none [default: nil].
+    def initialize(kpscript, database_file, password: nil, password_enc: nil, key_file: nil)
+      @kpscript = kpscript
+      @database_file = database_file
+      @password = password
+      @password_enc = password_enc
+      @key_file = key_file
+    end
+
+    # Securely select field values from entries.
+    # Using this will make sure the entries' values are then erased from memory for security when exiting client code.
+    # Try to not clone or extrapolate those values in other String variables, or if you have to call SecretString.erase on those variables to also erase their content.
+    #
+    # Parameters::
+    # * Same parameters as #entries_string
+    # * Proc: Code called with the entries retrieved
+    #   * Parameters::
+    #     * *values* (Array<String>)
+    def with_entries_string(*args, **kwargs)
+      values = []
+      begin
+        values = entries_string(*args, **kwargs).map { |str| SecretString.new(str) }
+        yield values
+      ensure
+        values.each(&:erase)
+      end
+    end
+
+    # Get field string values from entries.
+    #
+    # Parameters::
+    # * *select* (Select): The entries selector
+    # * *field* (String): Field to be selected
+    # * *fail_if_not_exists* (Boolean): Do we fail if the field does not exist? [default: false]
+    # * *fail_if_no_entry* (Boolean): Do we fail if no entry was found? [default: false]
+    # * *spr* (Boolean): So we Spr-compile the value of the retrieved field? [default: false]
+    # Result::
+    # * Array<String>: List of retrieved field values
+    def entries_string(
+      select,
+      field,
+      fail_if_not_exists: false,
+      fail_if_no_entry: false,
+      spr: false
+    )
+      args = [
+        '-c:GetEntryString',
+        select.to_s,
+        "-Field:\"#{field}\""
+      ]
+      args << '-FailIfNotExists' if fail_if_not_exists
+      args << '-FailIfNoEntry' if fail_if_no_entry
+      args << '-Spr' if spr
+      execute_kpscript(*args).split("\n")
+    end
+
+    # Edit field values from entries.
+    #
+    # Parameters::
+    # * *select* (Select): The entries selector
+    # * *fields* (Hash<String or Symbol, String>): Set of { field name => field value } to be set [default: {}]
+    # * *icon_idx* (Integer or nil): Set the icon index, or nil if none [default: nil]
+    # * *custom_icon_idx* (Integer or nil): Set the custom icon index, or nil if none [default: nil]
+    # * *expires* (Boolean or nil): Edit the expires flag, or nil to leave it untouched [default: nil]
+    # * *expiry_time* (Time or nil): Expiry time or nil to leave it untouched [default: nil]
+    # * *create_backup* (Boolean): Should we create backup of entries before modifying them? [default: false]
+    def edit_entries(
+      select,
+      fields: {},
+      icon_idx: nil,
+      custom_icon_idx: nil,
+      expires: nil,
+      expiry_time: nil,
+      create_backup: false
+    )
+      args = [
+        '-c:EditEntry',
+        select.to_s
+      ] + fields.map { |field_name, field_value| "-set-#{field_name}:\"#{field_value}\"" }
+      args << "-setx-Icon:#{icon_idx}" if icon_idx
+      args << "-setx-CustomIcon:#{custom_icon_idx}" if custom_icon_idx
+      args << "-setx-Expires:#{expires ? 'true' : 'false'}" unless expires.nil?
+      args << "-setx-ExpiryTime:\"#{expiry_time.strftime('%FT%T')}\"" if expiry_time
+      args << '-CreateBackup' if create_backup
+      execute_kpscript(*args)
+    end
+
+    # Retrieve a password for a given entry title
+    #
+    # Parameters::
+    # * *title* (String): Entry title
+    # Result::
+    # * String: Corresponding password
+    def password_for(title)
+      entries_string(@kpscript.select.fields(Title: title), 'Password').first
+    end
+
+    # Detach binaries.
+    #
+    # Parameters::
+    # * *copy_to_dir* (String or nil): Specify a directory in which binaries are extracted, or nil to extract next to the database file. [default: nil]
+    #     If copy_to_dir is specified, then the directory will be created and a copy of the original database will be used to detach bins, leaving the original database untouched.
+    def detach_bins(copy_to_dir: nil)
+      if copy_to_dir.nil?
+        execute_kpscript('-c:DetachBins')
+      else
+        # Make a temporary copy of the database (as the KPScript extraction is destructive)
+        FileUtils.mkdir_p copy_to_dir
+        # Make a copy of the database in the directory first
+        tmp_database = "#{copy_to_dir}/#{File.basename(@database_file)}.tmp.kdbx"
+        FileUtils.cp @database_file, tmp_database
+        begin
+          @kpscript.open(tmp_database, password: @password, password_enc: @password_enc, key_file: @key_file).detach_bins
+        ensure
+          # Remove temporary database
+          File.unlink tmp_database
+        end
+      end
+    end
+
+    # Export the database
+    #
+    # Parameters::
+    # * *format* (String): Format to export to (see the KeePass Export dialog for possible values).
+    # * *file* (String): File path to export to.
+    # * *group_path* (Array<String> or nil): Group path to export, or nil for all [default: nil]
+    # * *xsl_file* (String or nil): In case of transforming using XSL, this specifies the XSL file path to be used, or nil for none. [default: nil]
+    def export(format, file, group_path: nil, xsl_file: nil)
+      args = [
+        '-c:Export',
+        "-Format:\"#{format}\"",
+        "-OutFile:\"#{file}\""
+      ]
+      args << "-GroupPath:\"#{group_path.join('/')}\"" if group_path
+      args << "-XslFile:\"#{xsl_file}\"" if xsl_file
+      case execute_kpscript(*args)
+      when /E: Unknown format!/
+        raise "Unknown format: #{format}"
+      end
+    end
+
+    private
+
+    # Execute KPScript on our database with a given list of arguments.
+    # Handle internally all arguments needed to open the database with the correct secrets.
+    #
+    # Parameters::
+    # * *args* (Array<String>): List of arguments
+    # Result::
+    # * String: stdout
+    def execute_kpscript(*args)
+      resulting_stdout = nil
+      begin
+        kdbx_args = ["\"#{@database_file}\""]
+        kdbx_args << SecretString.new("-pw:\"#{@password}\"", silenced_str: '-pw:"XXXXX"') if @password
+        kdbx_args << SecretString.new("-pw-enc:\"#{@password_enc}\"", silenced_str: '-pw-env:"XXXXX"') if @password_enc
+        kdbx_args << SecretString.new("-keyfile:\"#{@key_file}\"", silenced_str: '-keyfile:"XXXXX"') if @key_file
+        resulting_stdout = @kpscript.run(kdbx_args + args.flatten)
+      ensure
+        # Make sure we erase secrets
+        kdbx_args.each(&:erase)
+      end
+      resulting_stdout
+    end
+
+  end
+
+end

data/lib/keepass_kpscript/kpscript.rb

@@ -0,0 +1,111 @@
+require 'fileutils'
+require 'tmpdir'
+require 'keepass_kpscript/select'
+require 'keepass_kpscript/database'
+
+module KeepassKpscript
+
+  # Drives an instance of KPScript
+  class Kpscript
+
+    # Constructor
+    #
+    # Parameters::
+    # * *cmd* (String): The KPScript command line
+    # * *debug* (Boolean): Do we activate debugging logs? [default: false]
+    #     Warning: Those logs can contain passwords and secrets from your database. Only use it in a local environment.
+    def initialize(cmd, debug: false)
+      @cmd = cmd
+      @debug = debug
+    end
+
+    # Open a database using this KPScript instance
+    #
+    # Parameters::
+    # * *database_file* (String): Path to the database file
+    # * *password* (String or nil): Password opening the database, or nil if none [default: nil].
+    # * *password_enc* (String or nil): Encrypted password opening the database, or nil if none [default: nil].
+    # * *key_file* (String or nil): Key file path opening the database, or nil if none [default: nil].
+    # Result::
+    # * Database: The database
+    def open(database_file, password: nil, password_enc: nil, key_file: nil)
+      Database.new(self, database_file, password: password, password_enc: password_enc, key_file: key_file)
+    end
+
+    # Shortcut to get easily access to selectors
+    #
+    # Result::
+    # * Select: A new entries selector
+    def select
+      Select.new
+    end
+
+    # Encrypt a password so that it can be used to open databases without using the real password
+    #
+    # Parameters:
+    # * *password* (String or SecretString): Password to be encrypted
+    # Result::
+    # * String: The encrypted password
+    def encrypt_password(password)
+      password_enc = nil
+      # We use a temporary database to encypt the password
+      tmp_database_file = "#{Dir.tmpdir}/keepass_kpscript.tmp.kdbx"
+      FileUtils.cp "#{__dir__}/pass_encryptor.kdbx", tmp_database_file
+      begin
+        tmp_database = self.open(tmp_database_file, password: 'pass_encryptor')
+        selector = select.fields(Title: 'pass_encryptor')
+        tmp_database.edit_entries(selector, fields: { Password: password.to_unprotected })
+        password_enc = tmp_database.entries_string(selector, 'URL', spr: true).first
+      ensure
+        File.unlink tmp_database_file
+      end
+      password_enc
+    end
+
+    # Run KPScript with a given list of arguments
+    #
+    # Parameters::
+    # * *args* (Array<String or SecretString>): List of arguments that are given to the KPScript command-line
+    # Result::
+    # * String: The stdout of the command (without the last status line)
+    def run(*args)
+      args.flatten!
+      resulting_stdout = nil
+      SecretString.protect(
+        "#{@cmd} #{args.map(&:to_unprotected).join(' ')}",
+        silenced_str: "#{@cmd} #{args.join(' ')}"
+      ) do |cmd|
+        Open3.popen3(cmd.to_unprotected) do |_stdin, stdout, _stderr, wait_thr|
+          exit_status = wait_thr.value.exitstatus
+          stdout_lines = stdout.read.split("\n")
+          log_debug do
+            <<~EO_LOGDEBUG
+              Execute #{cmd.to_unprotected} =>
+              Exit status: #{exit_status}
+              STDOUT:
+              #{stdout_lines.join("\n")}
+            EO_LOGDEBUG
+          end
+          raise "Error while executing #{cmd} (exit status: #{exit_status})" unless exit_status.zero?
+          raise "Error returned by #{cmd}: #{stdout_lines.last}" unless stdout_lines.last == 'OK: Operation completed successfully.'
+
+          resulting_stdout = stdout_lines[0..-2].join("\n")
+        end
+      end
+      resulting_stdout
+    end
+
+    # Issue some debugging logs, if debug is activated.
+    # Secret strings will be displayed unprotected by those logs.
+    #
+    # Parameters::
+    # * Proc: Code giving the message to be displayed
+    #   * Result::
+    #     * String: Message to display
+    def log_debug
+      puts "[ DEBUG ] - #{yield.to_unprotected}" if @debug
+    end
+
+  end
+
+end