devblackops/passwordstate

PowerShell module for interacting with ClickStudio's PasswordState password management application

PasswordState

Passwordstate is a PowerShell module used to interface with ClickStudio's PasswordState application via the REST API.

This module supports creating, retrieving, and updating PasswordState entries using simple PowerShell cmdlets that you can integrate into your existing processes.

Getting Started

You start off by running Initialize-PasswordStateRepository, which will initialize some base variables used in the PasswordState PowerShell module. It takes 2 parameters: -APIEndpoint is the URL to where your current PasswordState installation resides, and the -CredentialRepository is where you can store "Credentials" or API keys in this case. If you do not specify -CredentialRepository it will be created under your %UserProfile% folder.

Then you want to store some "credentials" on disk (Not really credentials, but API keys, PowerShell credential objects are used as a method of storing credentials in a secure way)

First you create a credential object using PowerShells Get-Credential cmdlet. You will be prompted to input a username/password, in username put in the name you want to call the credential file (Usually something that refers to, what the actual API key is giving you access to, a password list for instance), and in the password field enter your APIkey. If you do not specify a location, the credentials will be stored in the location you specified when you ran Initialize-PasswordStateRepository

$Initialize-PasswordStateRepository -ApiEndpoint 'https://passwordstate.local/api' -CredentialRepository 'C:\PasswordStateCreds'
$Cred = Get-Credential
Export-PasswordStateApiKey -ApiKey $cred

Lets say you entered "ADUserList" as Username and "52e7c9d84hb7fa33f6b123dac823e956" as password, this will result in a file called ADUserList.cred under the directory C:\PasswordStateCreds

If you at a later time want to use that credential you just call: Import-PasswordStateApiKey

$ADUserListCred = Import-PasswordStateApiKey -Name 'ADUserList'

Now you can use that credential object (API key) to connect to PasswordState In the below example, the API key is read from the $ADUserListCred variable, and URL to PasswordState is read from the URL you typed in when you ran Initialize-PasswordStateRepository

Get-PasswordStateListPasswords -ApiKey $ADUserListCred -PasswordListId 42

Examples

• Initialize-PasswordStateRepository

  Initialize-PasswordStateRepository -ApiEndpoint 'https://passwordstate.local/api' -CredentialRepository 'C:\PasswordStateCreds'

• Export-PasswordStateApiKey

  $Cred = Get-Credential
  Export-PasswordStateApiKey -ApiKey $cred -Repository c:\users\joe\data\.customrepo

• Get-PasswordStateApiKey

   Get-PasswordStateApiKey -Name 'system' -Repository c:\users\joe\data\.customrepo

• Import-PasswordStateApiKey

   $cred = Import-PasswordStateApiKey -Name personal -Repository c:\users\joe\data\.customrepo

• Find-PasswordStatePassword

   $allPasswords = Get-PasswordStateAllPasswords -SystemApiKey $sysKey -Endpoint 'https://passwordstate.local'

• Get-PasswordStateAllLists

   $lists = Get-PasswordStateList -SystemApiKey $sysKey -Endpoint 'https://passwordstate.local'

• Get-PasswordStateAllPasswords

   $allPasswords = Get-PasswordStateAllPasswords -SystemApiKey $sysKey -Endpoint 'https://passwordstate.local'

• Get-PasswordStateList

   $lists = Get-PasswordStateList -SystemApiKey $sysKey -Endpoint 'https://passwordstate.local'

• Get-PasswordStateListPasswords

   $passwords = Get-PasswordStateListPasswords -ApiKey $key -PasswordListId 1234 -Endpoint 'https://passwordstate.local'

• Get-PasswordStatePasswordHistory

   $history = Get-PasswordStatePasswordHistory -ApiKey $key -PasswordId 1234 -Endpoint 'https://passwordstate.local'

• New-PasswordStatePassword

   New-PasswordStatePassword -ApiKey $key -PasswordListId 1 -Title 'testPassword' -Username 'testPassword' -Description 'this is a test' -GeneratePassword

• New-PasswordStatePassword

   New-PasswordStatePassword -ApiKey $key -PasswordListId 1 -Title "TestDocument" -Username "testDoc" -GeneratePassword -DocumentPath "C:\temp\SecureDoc.txt" -DocumentName SecureDoc.txt -DocumentDescription 'My Very Secure Document'

• New-PasswordStateRandomPassword

   New-PasswordStateRandomPassword -Quantity 10 -WordPhrases $false -MinLength 20

• Set-PasswordStatePassword

   Set-PasswordStatePassword -ApiKey $key -PasswordId 1234 -Username 'mypassword'

• Set-PasswordStateDocument (On PasswordList)

    Set-PasswordStateDocument -ApiKey $key -PasswordListId 1 -DocumentPath "C:\temp\Secure.txt" -DocumentName SecureDoc.txt -DocumentDescription 'My Very Secure Document'

• Set-PasswordStateDocument (On Password)

    Set-PasswordStateDocument -ApiKey $key -PasswordId 4242 -DocumentPath "C:\temp\Secure.txt" -DocumentName SecureDoc.txt -DocumentDescription 'My Very Secure Document'

For more information, see http://devblackops.io

passwordstate's Issues

Some special characters in Passwords will result in an error

Expected Behavior

If you use special chars like ¤$ in your password, Invoke-Webrequest will give you an error, this is because powershell uses UniCode wheres as the web request expects UTF8

Current Behavior

Possible Solution

$result = Invoke-RestMethod -Uri $uri -Method Post -ContentType "application/$Format" -Headers $headers -Body ([System.Text.Encoding]::UTF8.GetBytes($json))

Force the json to be loaded as UTF8.

Steps to Reproduce (for bugs)

1. New-PasswordStatePassword -ApiKey $ADUserListCred -PasswordListId 49 -Username ctn -Password ('1dsdsdsdfsdsd¤234' | ConvertTo-SecureString -AsPlainText -Force) -ExpiryDate '15-10-2020 14:37:30' -Title test1234 -Verbose
   2.
   3.
   4.

Context

I am adding some extra stuff, so will do a PR when I get that worked out.

Your Environment

• Module version used:
• Operating System and PowerShell version:

Add support for v8 winapi

the winapi is an extension on the existing api, but auditing is based on whoever does the actual call, not a generic api key.

Expected Behavior

By using the /winapi uri and the Invoke-RestMethod UseDefaultCredentials parameter we can do the same as with the normal api.

Current Behavior

New feature, currently not implemented.

Possible Solution

Context

Our company does not allow 'normal' api calls and forces us to use the winapi.

Provide a basic test file for every module

With the new test layout, a file per function can be created, containing all tests for any given function. I have created a first draft for these test files.

Expected Behavior

N/A

Current Behavior

N/A

Possible Solution

N/A

Steps to Reproduce (for bugs)

N/A

Context

N/A

Your Environment

N/A

Module Support for PasswordState 8 Active Directory Authentication

Module Support for PasswordState 8 Active Directory Authentication

Topic

Hello -
I wanted to start a discussion topic on support for AD auth now that it is a feature that PasswordState 8 supports.

I would imagine there would need to be support for both methods (both API keys and the newer AD auth) as some organizations might use them side by side, or opt to stick with API keys possibly in an environment without AD. I wasn't sure if there was any plans to add the new functionality to this module but it seems to be the most popular one for PasswordState (and my favorite as well :) ).

High Level Solution

Unless I'm over simplifying it I would think this could be accomplished with parameter sets on the functions. One that takes the API key still and another that would take -Credential, and possibly a 3rd that would take -UseDefaultCredentials.

In the past for other Invoke-RestMethod based API wrappers I've built a splat based on the parameter sets to feed a single command and could maybe leverage that design.

Overall just wanted to start a convorsation on the idea!

Find-PasswordStatePassword does not map username for search

Expected Behavior

When you use Find-PasswordStatePassword I would expext to be able to search for Username, but it seems that it is not possible, if you supply it, it will return everything from a list.

It seems as if you have accidentally omitted Username as a search parameter (Missing when you build the URI string)

Current Behavior

Possible Solution

if ($PSBoundParameters.ContainsKey('Username')) {
        $params += "&Username=$Username"
    }

Steps to Reproduce (for bugs)

1. Find-PasswordStatePassword -ApiKey $ADUserListCred -PasswordListId 49 -Username 'gris'
   2.
   3.
   4.

Context

I am trying to check if password allready exists before creating new one

I allready have an outstanding Pull request, where I have added some more functionality, I have allready fixed this in my current branch, I can do a pull request as well if you prefer that.

Your Environment

• Module version used: 1.1.(1) (Branch that is not merged yet)
• Operating System and PowerShell version: Windows 10 ,5.1.14393.0

New functions to add

Create new functions to implement the following tasks in from the PasswordState API:

1. Folders
   • Create new folder
   • Search for folder(s)
2. Lists
   • Create list
3. Passwords
   • Add password reset dependency
   • Delete a password
4. Hosts
   • Add a new host
   • Delete a host
   • Search for host(s)
5. Documents
   • Add document to existing password
   • Add document to existing list
   • Get a password document
   • Get a password list document

Documentation - readme not correct

in the examples you have
Find-PasswordStatePassword

Current Behavior

but you show an example for
Get-PasswordStateAllPasswords

Improve the module by adding the PSScriptAnalyzer Test Suite

The available tests are good, but do not provide an easy way to add own (custom tests). I would like to add the full PSScriptAnalyzer test suite to the project.

Expected Behavior

Add own pester tests.

Current Behavior

Hard to add own tests

Possible Solution

N/A

Steps to Reproduce (for bugs)

N/A

Context

N/A

Your Environment

N/A

PowerShell Core Support Discussion

On import of the module in PowerShell Core (PowerShell-6.0.0-beta.4-win10-win2016-x64 as of now) the private function _SetCertPolicy throws an exception since the 'ICertificatePolicy' namespace doesn't exist in .Net Core 2.x.

This issue was addressed by a PR which added a parameter -SkipCertificateCheck to Invoke-RestMethod and Invoke-WebRequest. Currently setting this globally for PS needs to be done with $PSDefaultParameterValues for the two cmdlets. It looks like there may be support for a $SkipCertificateCheckPreference in the future.

PowerShell Core\6 Issue 1945
PowerShell Core\6 PR 2006

I just wanted to start a topic on support for the changes.

Expected Behavior / Possible Solution

My immediate thinking would be to modify the private function to do a version check against PowerShell and then continue to use the ICertificatePolicy method for Windows PowerShell 5 and before and then if its core for the time being set the default parameter value with $PSDefaultParameterValues.

In my example I check on the PSEdition property but it could check the version too, I admittedly don't know the best long term option for the check but this seems to work for the time being.

function _SetCertPolicy
{
    # Allow untrusted SSL certs
    if ($PSVersionTable.PSEdition -eq 'Core')
    {
        $PSDefaultParameterValues.Add("Invoke-RestMethod:SkipCertificateCheck", $true)
        $PSDefaultParameterValues.Add("Invoke-WebRequest:SkipCertificateCheck", $true)
    }
    else
    {
        Add-Type -TypeDefinition @"
        using System.Net;
        using System.Security.Cryptography.X509Certificates;
        public class TrustAllCertsPolicy : ICertificatePolicy {
            public bool CheckValidationResult(
                ServicePoint srvPoint, X509Certificate certificate,
                WebRequest request, int certificateProblem) {
                return true;
            }
        }
"@
        [System.Net.ServicePointManager]::CertificatePolicy = New-Object -TypeName TrustAllCertsPolicy
    }#ifelse
}#function

Current Behavior

As stated above for the time being it will allow the module to support both Core and Desktop editions of PowerShell with a fairly minimal change.

Steps to Reproduce (for bugs)

1. Install a PowerShell Core beta.
2. Launch PowerShell Core Beta.
3. Find-Module -Name PasswordState | Install-Module -Scope CurrentUser
4. Import-Module -Name PasswordState

Context

I know PowerShell core is still in beta and this issue isn't specific to this module as I've seen many others approach API certificates the same way but as I use the PasswordState module daily and it would be nice to start using it from core as we start to expand into running PowerShell Core on Linux OS's.

Your Environment

• Module version used:
  • 1.2.1
• Operating System and PowerShell version:
  • Microsoft Windows 10 Enterprise
  • PowerShell v6.0.0-beta.4

Get-PasswordStateListPasswords Timeout

We have a very large password list with 15000+ passwords in it. When trying to run Get-PasswordStateListPasswords I receive a Invoke-RestMethod: The operation has timed out error. Line 47

Can we extend the timeout settings somehow?

Prevent Access to insecure TLS sites

The module modifies the default powershell session behavior to prevent access to tls sites that have selfsigned or untrusted certificates. Having the possibility to modify the session is not part of the module and should be removed.
People (unwillingly) update their security settings

Expected Behavior

Connecting to untrusted TLS sites is not possible.

Current Behavior

Connecting to untrusted TLS sites is possible

Possible Solution

I am building a PR to correct this.

Steps to Reproduce (for bugs)

N/A

Context

N/A

Your Environment

N/A

Prevent strict mode for tests

The module enforces the powershell strict mode 3. Since pester has evolved a bit further, strict mode should be turned off for tests

Expected Behavior

N/A

Current Behavior

N/A

Possible Solution

N/A

Steps to Reproduce (for bugs)

N/A

Context

N/A

Your Environment

N/A