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

Report Bug · Request Feature

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

• multiple organizational units for storing new secrets
• automatic analysis of configured password forms
• storage of SecureString, PSCredential and HashTable secrets
  (yet undocumented as if no one is using my module I spare my free time somewhere else than in documenting the most complex part)
• usage of pre-deployed configurations (e.g. by GPO) (undocumented as of the same reason)

• PSModuleDevelopment
• psframework

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

• Powershell 7.x (Core) (If possible get the latest version)
  Maybe it's working under 5.1, just did not test it
• A Password Secure Server with a user account

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

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".

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

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

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

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.

$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.

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

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.

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"

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

Forms? OU? See 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.

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.

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).

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.

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, ..).

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

• Get Access to stored secrets by best guess approach which data is stored where

The vaults are as customizable as the password storage. Therefor a system was developed which allows the configuration of provided password forms and field associations. To keep the effort for team/company usage as low as possible it will be possible to distribute this mapping information e.g. by GPO and registry settings.

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.

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

• Maybe there are some inconsistencies in the docs, which may result in a mere copy/paste marathon from my other projects

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

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

• Friedrich Weinmann for his marvelous PSModuleDevelopment and psframework