Giter Club home page Giter Club logo

poshkeepass's Introduction

PowerShell KeePass

PoShKeePass is a PowerShell module that combines the ease of the PowerShell cli and the extensibility of the KeePassLib API to provide a powerful and easy to use management and automating platform for KeePass databases.

psgallery psgallery

Features

  1. Database Configuration Profiles - Supports mutliple databases and authentication options.
  2. Getting, Creating, Updating, and Removing KeePass Entries and Groups - All of these perform as much automatic database authentication as possible using the database configuration profile. For databases that use a masterkey (password) it will prompt for it.
  3. Generating KeePass Passwords - Supports most character sets and advanced keepass options. Also supports creating password profiles that can be specified to create a new password with the same rule set.

Getting Started

Install

Install-Module -Name PoShKeePass

Documentation

Please check out our Getting Started documentation on our wiki.

Important Notes & Reminders

  1. Please always keep up to date backups of your KeePass database files .kdbx and .key files.
  2. The module uses the KeePassLib 2.39.1 which is included in the module.
  3. This module was built and tested in PowerShell 5.1 on Windows 10 but should work in PowerShell 4 and Windows 8.1 and Server 2012 R2 and up. It may work in some earlier versions but is currently untested and not supported. If you come across issues create an issue and I will look into fixing it or create a pull request.

Changelog

Please review the changelog document for a full history.

v.2.1.3.0

  • Added #160 - Default Database Configuration Profile.

    • When set, the -DatabaseProfileName parameter is optional, and if not passed it will grab the default profile from the config.
    • To Set it up on an existing profile simply use the update command:
      Update-KeePassDatabaseConfigurationProfile -DatabaseProfileName 'name' -Default
    • To Create a new profile as default use the new command:
      New-KeePassDatabaseConfigurationProfile -DatabaseProfileName 'name' -Default -DatabasePath '' other options
    • This allows for calls to the main module functions without the -DatabaseProfileName parameter such as:
      Get-KeePassEntry -UserName 'aUser'

v.2.1.2.8

  • Added - #84 - Manage Notes properties on KPGroup Objects.

  • v.2.1.2.6 - Added - #158 - Added Update-KeePassDatabaseConfiguration function and tests.

  • v.2.1.2.5 - Fix - #157 - Set New-KPConnection function back to internal function and no longer exports.

v.2.1.2.4

  • Added Feature #29 - Can now manage the Expiration Time/Enabled State of groups and entry.

  • v.2.1.2.3 - Fix #64 - Review Message for grammar, clarified some messages as well.

  • v.2.1.2.2 - Fix #156 - New-KeePassDatabase will now error out if kdbx file already exists, instead of silently overwriting an existing file.

  • v.2.1.2.1 - Fix #149 - Breaking Change New-KeePassGroup and Update-KeePassGroup now return a KeePass PSObject via the ConvertTo-KPPsObject function.

v.2.1.2.0

  • Fix #148 - Can now update an entry multiple times, while retaining history and not through internal lib exception
  • Changes to build script

v2.1.1.8

Many fixes, features and improvements, please note the Breaking Changes Below

  • Fix #129 - Can now pass Credential Object to -MasterKey Parameter
  • Fix/Implemented #69 - All primary Functions return a Powershell object rather than a KeePass Object This Includes Breaking changes!.
    • Breaking:
      • Since a powershell object is now returned, in order to access the keepass object a child property has been added to the ps object, .KPEntry and .KPGroup.
      • Deprecated the -AsPlainText parameter on the Get-KeePassGroup function, the call will still work but it will present a warning message. This is being removed as it is no longer necessary.
    • Non-Breaking:
      • Moved how database profile name was being added to the ps object for better performance on conversion.
  • Implemented #93 - Get-KeePassEntry Now supports -Title and -UserName parameters also via pipeline.
  • Normalized Error handling to remove repetitive code
  • Converted extraneous logic to parameter splatting
  • Code formatting and removed explict parameter attributes where not necessary.
  • Updated Object creation to use the hashtable method for performance over the New-Object + Add-Memeber.
  • Fix #44 - Pipeline now Works for Remove-KeePassDatabaseConfiguration.
  • Implemented #141 - Much stronger Pipeline support.
    • -DatabaseProfileName no longer needs to be specified to a KPPSObject pipeline recieving function.
      • Example: Get-KeePassEntry -Title 'test' -DatabaseProfileName 'profile' | Remove-KeePassEntry
    • All parent and object paths now are recieved by the pipeline which of course can be overridden by specifing the parameter.
  • Fixed #140 and #138 - by removing the EncodeKeePassLib.ps1 script file as it is no longer in use.
  • Fixed #144 - Removed Faultly logic which allowed for the KeePass Icon to get set to blank while updating an object.
  • Implemented #143 There are no more dynamic parameters! So all of the gitches have left with them. They still support tab completion by using Register-ArgumentCompleter.
    • Breaking Change as this is only supported in powershell v5 and up, auto complete will not work in older versions.
  • Implemented #118 - by adding support for keepasslib version 2.39.1
    • The new file format version between the previous version of 2.34 and the latest apears to be much slower on some operations.
    • Testing the new Lib version against the previously suported version 2.34 all worked and appears to be backwards compatible. Also it does not upgrade the file format version.
    • Version can easily flipped back by modifying the global variable in the .psm1 file.
    • This fixes #131.
  • Fix #145 - Updating a KeePass Entry now updates the modification time in UTC.
    • Breaking Change - Renamed the LastAccessTime and LastModificationTime properties to LastAccessTimeUtc and LastModificationTimeUtc to reflect that they are in UTC.
  • Addressed #88 - Get-KeePassEntry
    • Since a Ps object is now always returned, all fields but the password are in plaintext. Now specifying the -AsPlainText will decode the password to plaintext.
      • This gives the user better control over when they expose the password as plaintext if need be.
    • Another improvement is there is now a -WithCredential parameter which adds a .Credential property to the return Entry PS Object.
      • This is not done by default as it has overhead.
      • This gives the user better options and does not require manual creation of the credential.
      • Breaking Change Since this has been implemeneted the -AsPsCredential parameter has been removed. The new method is better as it allows for multiple entries to be returned with thier cred objects instead of limiting it to 1 entry.
  • Breaking Change - ConvertTo-KPPSObject and all returned objects the .FullPath property now returns the true full path of the object. The ParentGroup property still exists and can be used as an alteranative data source for any lost functionality.

Known Issues

See the Known-Issue tag to get a list of known issues and their status.

Contributing

  • If you are insterested in fixing issues and contributing directly to the code base, please see the documentation on How to Contribute.
  • If you come across a bug or have a feature request feel free to create an issue with the appropriate label.

Shout-Outs

  • PSKeePass would like to thank Jason Fossen for his initial work with KeePass in PowerShell.
  • PSKeePass would like to thank Christian Lehrer for his powershell keepass work and contributions.
  • PSKeePass would like to thank Ninjigen for his powershell keepass work and contributions.
  • PSKeePass would like to thank Andrzej Pilacik (aka @cypisek77) for his review and feedback on documentation and over all rubber ducking.

License

Copyright (c) 2019 John Klann. All rights reserved.

Licensed under the MIT License.

poshkeepass's People

Contributors

chritea avatar colaloc avatar jkdba avatar jmk-foofus avatar ninjigen avatar skons avatar thomasschoeller avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

poshkeepass's Issues

Include DLL in to Module

Self contained,
Always using the right version.

Todo:

  • Embed KeePassLib
  • Perform Version Checks
  • Consider and Protect against security risks of embedding the KeePassLib

Get all entries and use standard where-object/select-object cmdlets to filter

What do you think of the idea to change the Get-KeePassEntry cmdlet so it does not require group and title? Then I can use standard PS cmdlets for filtering after I have got all entries. This would enable me to search databases for entries without expiries, weak passwords, e.g.

Get-KeePassEntry | Where-Object { $_.Expiry -eq $null }

Am happy to submit PR for this if you think it would be beneficial to the project.

Allow for Database and Composite Key Management

Functions like...

  • Get-KeePassDatabase
  • Set-KeePassDatabase
  • New-KeePassDatabase
  • Remove-KeePassDatabase
  • Get-KeePassCompositeKey
  • Set-KeePassCompositeKey
  • New-KeePassCompositeKey
  • Remove-KeePassCompositeKey

Question: Consider Merging Projects

Hi I just found your project, I have also been working on a PowerShell KeePass module with the same basic intentions.

I noticed some strengths in your code versus mine and vice-versa. Potentially we could consider working on the same project and bring the best of both worlds together.

Check out my project here and let me know.

Allow for User Specified API Version

Potentially this could be saved in the config, as well as a parameter to Import-KPLibrary.

This will require that the function Import-KPLibrary to be exposed to the user.

Remove the -AsPlainText switch in Get-KeePassEntry and provide a function to convert a secure string into plain text from the pipeline

It's more of a suggestion than a question, but how about instead of having a Get-KeePassEntry function having a switch to provide the password as plain text, we should provide the with a consistent PSObject having a secure string for a password, and a function which would convert the secure string as plain text ?

The syntax would be something like

$KeePassEntry.Password | ConvertFrom-KeepassPassword

plain password

Integrate PowerKeePass and PSKeePass code

As discussed we will integrate these two projects using the PowerKeePass module code as a backend framework for the frontend module code from original PSKeePass project.

Todo's:

  • Go through PSKeePass cmdlets and see what backend cmdlets need to be created to support these cmdlets.
  • See what backend cmdlets need to be updated or modified to support features of the frontend.
  • Update frontend code to use backend
  • Update frontend to support extra features that the backend already supports.

Include Pester test

Pester Tests will use a sample keepass databases.

  • Create Sample Databases for different authentication testing.
  • Create Pester tests

Merge the two different Connection Functions

Currently there are two functions that perform different steps in getting a KeePass database Connection.

Get-KPConnection
Invoke-KPConnection

As discussed this needs to be merged into one function called New-KPConnection.

This function will handle both steps of the connection process.

Always Return a PowerShell Object

Currently Get-KeePassEntry and Get-KeePassGroup return keepasslib objects except when the -asplaintext option is specified.

As Discussed the functions should always return a powershell object, as the user will not know how to interact with a keepass object.

Fix `Get-Help ConvertTo-KPPSObject -examples` entry

I believe there is some antiquated code that needs updating here:

Get-Help ConvertTo-KPPSObject -examples

Under the second example:

Example #2

    PS>Get-KeePassEntry -KeePassonnection $DB -UserName "AUserName" | ConvertTo-KeePassPsObject

The flags -KeePassonnection and -UserName do not exist (although a -UserName may be nice to implement)

Add Parameter MasterKey to Core Functions

Added Dynamic Parameter MasterKey

Added optional Parameter -MasterKey to core functions.

This parameter was added to allow for easier scripting with databases that use a masterkey password.

Previously if a masterkey password was used the updated functions would prompt the user of the masterkey after the funciton was called. This is still the behaviour if the masterkey is required but not specified.

Strictly Typed Parameters in Cmdlets

I could add this to wiki for discussion, but currently the code I added from my project has "Strictly Typed" parameters meaning they are typed as something specific to the KeePass SDK.

Ex: ([KeePassLib.PwDatabase])

    [CmdletBinding()]
    param
    (
        [Parameter(Position=0, Mandatory)]
        [ValidateNotNullOrEmpty()]
        [KeePassLib.PwDatabase] $Connection
    )

This means that the SDK must be loaded before the majority of cmdlets will function. I do not think this will be an issue going forward once issue #2 is complete however, in the meantime I solved this issue in my previous project by loading the DLL at the bottom of the module (where you export the various cmdlets in the module).

Alternatively I could remove the strong typing and set all of these parameters to a custom powershell object type, however this will reduce parameter validation and make the code more ambiguous.

Thoughts?

Add Ability to display an entry's `notes`

It would be quite useful to display the notes field from an entry. It could be a flag on -plaintext or a setting for the database's profile. But beyond username and password , the notes field is absolutely critical (at least for me).

Also, this module is MUCH appreciated. Thanks!

Future of *-KeePassConfiguration?

What is the future of {Get,Set}-KeePassConfiguration? You are embedding the KeePass binary, leaves only the DB and Key File properties.

Will you remove these functions? I'm asking because replace it with something like https://github.com/PoshCode/Configuration. This would also make it possible to have per user settings, even the module is installed in the host module directory.

Adding to PSGallery

@chritea, So I started looking into the powershell gallery and I saw no requirements for pester. I was wondering where you saw or heard about this requirement. I still intend to create pester tests, just curious if I am missing something.

Need to Change all GetFullPath Call to Return with Database Path

This needs to happen and documentation needs to be updated.

Since the uuid of a group changes per call, it is not a valid look up method.

Since this is the case and a user can return -asplaintext or not from the Get-KeePassGroup function then Pipe it to the Update-KeePassGroup function. There is no great way of determining the actual group to update.

By changing this option to Return the path with the database name I will be able to remove the anonymity of the group that is getting passed.

Unfortunately this is a bigger change as a poor design decision was made early on.

Show Cmdlets

Cmdlets to show different keepass objects.

Example:

Show-KeePassGroups: would show all groups on the top layer and would have a recurse option... etc.

Additional Methods to Generating a Password

Additional Methods to Generating a Password:

Currently Supported

  1. User Selected Character Sets with advanced rules.
  2. None... use Default Character Sets with advanced rules.

To Be Supported

  • Generate Using Pattern (with options)
  • Generate Using Custom Algorithm
  • Derive from Previous Password
  • Use Built In Profiles, such as:
  • 40-Bit hex Key
  • 128-Bit Hex Key
  • 256-Bit Hex Key
  • Random MAC Address
  • Allow for Collect additional entropy options
  • Smaller Subset Character sets.
  • Custom Character Sets
  • User Entered Password

SupportShouldProcess Design

Both user facing and base functions/cmdlets that do dangerous operations (set,update,remove,etc) should use the Cmdlet Option of SupportShouldProcess.

When the top level code makes a call to the base code it can then use the -confirm:$false flag to bypass its ShouldProcessing logic.

This way no matter if you are scripting using the base functions or simply using the cli stuff you will always be prompted.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.