search

Callidus2000 / SecretManagement.NetwrixPasswordSecure

GNU General Public License v3.0
3 stars 0 forks source link

readme

<!-- Thanks for checking out the Best-README-Template. If you have a suggestion that would make this better, please fork the repo and create a pull request or simply open an issue with the tag "enhancement". Thanks again! Now go create something AMAZING! :D

-->

Contributors Forks Stargazers Issues GPLv3 License


SecretManagement PowerShell Extension for Netwrix PasswordSecure

This Powershell Module is an extension to the Microsoft Secret Management Module
Explore the docs »

Report Bug · Request Feature

Table of Contents
  1. About The Project
  2. Getting Started
  3. Usage
  4. Use-Cases - Why was this module created?
  5. Roadmap
  6. Contributing
  7. License
  8. Contact
  9. Acknowledgements

About The Project

This Powershell Module is an extension to the Microsoft Secret Management Module for accessing secrets stored within the Netwrix Password Secure Server. It is a wrapper for the API which is only accessible by using a C# SDK provided by NetWrix only to enterprise customers. The module is useless if you are no enterprise customer (regarding the license modell you are using).

The usage of the SDK is documented in the Netwrix Helpcenter filed under the keyword 'SDK'. You have to sideload/copy the SDK *.DLL files to a given location in order to get the module up to work (see Installation).

Since v2.0.0 it supports

Built With

Getting Started

To get a local copy up and running follow these simple steps.

Prerequisites

Installation

The releases are published in the Powershell Gallery, therefor it is quite simple:

  install-module SecretManagement.NetwrixPasswordSecure -Scope CurrentUser

As the module 100% depends on the C# SDK API DLL Files you have to request them from the vendor. After acquiring the zipped files please extract them into the subdirectory SecretManagement.NetwrixPasswordSecure.Extension\bin. The local path is hinted by an error message if you try to import the module while the DLLs are missing:

Import-Module SecretManagement.NetwrixPasswordSecure
WARNING: [15:47:39][<Unknown>] Required Assemblies (like PsrAPI.dll) are missing in the folder 'C:\Users\root\Documents\PowerShell\Modules\SecretManagement.NetwrixPasswordSecure\1.0.0\SecretManagement.NetwrixPasswordSecure.Extension\bin'. They are provided for *Enterprise* cutomers by the product vendor on request. Please unzip all provided *.DLL within this folder

Register a Secret Vault

To interact with a password server you have to register it as a SecretVault. For this task you've got multiple possibilities, ordered from "Simple, but non customizable" to "You have to know what you are doing, but then you may configure the weirdest scenarios".

Use an interactive assistant

If you are using this module on a computer which has the Netwrix client software installed, you can invoke an interactive register service.

Register-NetwrixSecureVault -InterActive

Out GridView Example After choosing an entry you will be asked which username should be used for connection.

Overwrite the vaultname

If you do not want to use the existing Database Name as a vault name you can overwrite it with the VaultName parameter:

Register-NetwrixSecureVault -VaultName SomeThingElse -InterActive

Use the interactive part to create a manual command

If you add a -WhatIf to the interactive part the vault will not be registered but you get the instructions for manual registration:

Register-NetwrixSecureVault -InterActive -WhatIf
# shortened for user input
You may register the chosen vault later with the following command:
$registerParam=@{
  VaultParameters = @{
    Port = '11016'
    Database = 'PWS8_I'
    Server = 'integration.domain.com'
    UserName = 'maxmuster'
    version = '2.0.0'
  }
  ModuleName = 'SecretManagement.NetwrixPasswordSecure'
  Name = 'PWS_Integration'
}
Register-SecureVault @registerParam

Of course you can define the necessary parameter completely manual.

Use Register-SecretVault

$registerParam=@{
  VaultParameters = @{
    Database = 'PWS8_I'
    Server = 'integration.domain.com'
    UserName = 'maxmuster'
    #Port = '11016'
  }
  ModuleName = 'SecretManagement.NetwrixPasswordSecure'
  Name = 'PWS_Integration'
}
Register-SecureVault @registerParam

The port is optional.

Query secrets

Lets pretend you've got just three entries stored in your server: foo, hubba and hubba (yes, a dupe regarding the name within different containers).

Get-Secret -Name foo

UserName                     Password
--------                     --------
foo      System.Security.SecureString

Get-Secret -Vault $Vaultname -Name hubba
[Error] Multiple credentials found; Search with Get-SecretInfo and require the correct one by *.MetaData.id
Get-Secret: Unable to get secret hubba from vault PWSafeInt
Get-Secret: The secret hubba was not found.

Seen it? The SecretManagement Framework does not allow to query duplicate entries, in the concept (off-world) there rule uniqueness regarding the name attribute. As duplicate names can be used you have to acquire the GUID of the correct entry and query this record in particular

Get-SecretInfo -Name hubba |fl

Name      : Hubba [5dd937c4-b0a0-ed11-a876-005056bce948]
Type      : PSCredential
VaultName : PWS
Metadata  : {[userName, Foo], [id, 5dd937c4-b0a0-ed11-a876-005056bce948], [Beschreibung, Hubba], [memo, ]…}

Name      : Hubba [ef2fe11d-b0a0-ed11-a876-005056bce948]
Type      : PSCredential
VaultName : PWS
Metadata  : {[userName, hubba], [id, ef2fe11d-b0a0-ed11-a876-005056bce948], [Beschreibung, Hubba], [memo, ]…}

# Query the one with the username 'hubba'
Get-Secret ef2fe11d-b0a0-ed11-a876-005056bce948

UserName                     Password
--------                     --------
hubba    System.Security.SecureString

Updating existing secret

For updating use Set-Secret:

Set-Secret -Secret (Get-Credential) -Name foo

Attention: If you use a SecureString secret only the password is updated, using a PSCredential secret updates the username, too.

Creating a new Secret

For adding a new secret you also use Set-Secret - Sometimes in the future, as it's currently under development.

# Create an entry under the default OU with the default form
Set-Secret -Verbose -Vault $Vaultname -Secret $myNewSecret -Name "Cheeata"
# Create an entry under the OU 'API' with the default form
Set-Secret -Verbose -Vault $Vaultname -Secret $myNewSecret -Name "API\Cheeata 2"
# Create an entry under the default OU with the form 'Password'
Set-Secret -Verbose -Vault $Vaultname -Secret $myNewSecret -Name "API\Cheeata 3|Password"

Setting additional entry fields

If the password form contain additional information/fields they can be set by using Set-SecretInfo.

Forms? OU? See Internal concepts.

Internal Concepts

The solution is not only focused on security but also on customizability. For understanding some configuration/usage scenarios you need to know the basics.

Password Forms

The administrator of the server can configure multiple password forms which can be used by the regular user to store secrets in a standardized manner. Each named form defines named fields of different types. E.g. a regular credential form may consist of 'username' and 'password' fields while a form for a physical server adds information about the 'root ssh key' and the password for the BIOS or ILO interface. For the secret management extension it's necessary to know which fields belong directly to the secret itself or are just additional (meta) information which do not have to be kept secret.

You can configure which form should be used by default just by adding -DefaultFormName parameter to Register-NetwrixSecureVault. If this is omitted the form with the least amount of fields (and as second sorting level with the shortest name) will be used as default.

Password Container

Every password entry is a container. Each password container can be derived from a password form or be built from ground up without any standard. The password container has child items which represent the named fields (see Password Container).

Organizational Units (OU)

All password containers are grouped in hierarchical groups called organizations. Each organization has a type: 'Group' (for sharing information between users) and 'User' (most times only permissions for the named user himself.)

You can configure which OU should be used by default just by adding -DefaultOUName parameter to Register-NetwrixSecureVault. If this is omitted the first OU sorted by name ascending will be used as default, 'Group' types preferred.

Combining all together

If the user wants to store a secret in to this solution he has to choose to which OU the new entry should belong (if no default is configured), which form to use and then he has to fill out all the necessary fields. If a secret is queried the extensions searches for an entry with the given name, tries to identify the base form of the container and them maps the field to the queried information type (credential, secret information, ..).

Roadmap

New features will be added if any of my scripts need it ;-)

v1 - Released

Further development/documentation - RoadMap behind the scenes

The main focus of this module is to get access to our internal Password Servers. As the system is quite easy to customize (see Internal Concepts) it might not be usable for your installation. If running into problems open a new issue, I try to look into it.

Regarding missing documentation like 'Mapping password form fields to secret information' (includes storing HashTables) I'll add it if asked for. Currently I'm the only user of this module, I don't know how many Enterprise Customers may be interested in it and therefor currently no one needs more examples/docs. Feel free to comment as an issue or reach out to me directly.

I cannot guarantee that no breaking change will occur as the development follows my internal DevOps need completely. Likewise I will not insert full documentation of all parameters as I don't have time for this copy&paste. Sorry. But major changes which classify as breaking changes will result in an increment of the major version. See Changelog for information regarding breaking changes.

See the open issues for a list of proposed features (and known issues).

If you need a special function feel free to contribute to the project.

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated. For more details please take a look at the CONTRIBUTE document

Short stop:

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Limitations

License

Distributed under the GNU GENERAL PUBLIC LICENSE version 3. See LICENSE.md for more information.

Contact

Project Link: https://github.com/Callidus2000/SecretManagement.NetwrixPasswordSecure

Acknowledgements