{"id":15021146,"url":"https://github.com/powershell/secretmanagement","last_synced_at":"2025-05-15T03:08:07.543Z","repository":{"id":37893725,"uuid":"261261981","full_name":"PowerShell/SecretManagement","owner":"PowerShell","description":"PowerShell module to consistent usage of secrets through different extension vaults","archived":false,"fork":false,"pushed_at":"2025-05-05T16:35:37.000Z","size":378,"stargazers_count":353,"open_issues_count":48,"forks_count":51,"subscribers_count":23,"default_branch":"main","last_synced_at":"2025-05-15T03:07:57.509Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PowerShell.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-05-04T18:17:32.000Z","updated_at":"2025-05-06T21:44:24.000Z","dependencies_parsed_at":"2024-06-14T01:25:53.494Z","dependency_job_id":"7e29c9bc-bf50-4f8f-9839-5a6123fa1d6f","html_url":"https://github.com/PowerShell/SecretManagement","commit_stats":{"total_commits":105,"total_committers":7,"mean_commits":15.0,"dds":0.3047619047619048,"last_synced_commit":"90f7a10127fef576c28d09c4b8ee357018653a65"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerShell%2FSecretManagement","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerShell%2FSecretManagement/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerShell%2FSecretManagement/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerShell%2FSecretManagement/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PowerShell","download_url":"https://codeload.github.com/PowerShell/SecretManagement/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254264769,"owners_count":22041794,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T19:56:11.557Z","updated_at":"2025-05-15T03:08:02.532Z","avatar_url":"https://github.com/PowerShell.png","language":"C#","readme":"# PowerShell SecretManagement module\n\nPowerShell SecretManagement module provides a convenient way for a user to store and retrieve secrets.\nThe secrets are stored in SecretManagement extension vaults.\nAn extension vault is a PowerShell module that has been registered to SecretManagement, and exports five module functions required by SecretManagement.\nAn extension vault can store secrets locally or remotely.\nExtension vaults are registered to the current logged in user context, and will be available only to that user (unless also registered to other users).  \n\nIn addition to implementing the five required SecretManagement functions, extension vaults are responsible for any authentication, including prompting the user for passphrases, and providing error and informational messages specific to the vault implementation.\nError and informational messages common to all extension vaults are provided by SecretManagement.  \n\nPowerShell SecretManagement module is essentially an orchestrator for extension vaults which perform the actual secret storage and encryption.\nThe extension vault may implement its own store, or wrap an existing secure store solution, such as Azure KeyVault, KeePass, Keyring, etc.  \n\nPowerShell SecretManagement supports the following secret data types:\n\n- byte[]\n- string\n- SecureString\n- PSCredential\n- Hashtable  \n\nAll extension vault implementations must also support these data types.  \n\nPowerShell SecretManagement module provides cmdlets for for accessing and manipulating secrets, and also cmdlets for registering and manipulating vault extensions.  \n\n## Installation\n\nYou can install the `Microsoft.PowerShell.SecretManagement` module from the [PowerShell Gallery](https://www.powershellgallery.com/packages/Microsoft.PowerShell.SecretManagement).  \n\n```powershell\nInstall-Module -Name Microsoft.PowerShell.SecretManagement -Repository PSGallery\n```\n\n## Secret metadata\n\nExtension vaults can optionally support storing and retrieving additional secret metadata, that is data associated with the secret.  \nSecret metadata is not security sensitive and does not need to be stored securely in the extension vault.  \n\nSecret metadata can be included by using the `-Metadata` parameter: `Set-Secret -Metadata @{ Name=Value }`.\nThe `-Metadata` parameter takes a `Hashtable` type argument consisting of name/value pairs.  \nExtension vaults should at minimum support the following value types:  \n\n- string\n\n- int\n\n- DateTime\n\nThe secret metadata is included in the `SecretInformation` type object returned by `Get-SecretInfo`, in a `Metadata` property.  \nThe `Metadata` property is a `ReadonlyDictionary\u003cstring, object\u003e` type.  \n\n## Vault extension registration cmdlets\n\n### Register-SecretVault\n\nRegisters a single extension vault to the current user\n\n### Get-SecretVault\n\nRetrieves information about one or more registered extension vaults\n\n### Unregister-SecretVault\n\nUnregisters a single extension vault\n\n### Set-SecretVaultDefault\n\nSets one registered extension vault as the default vault\n\n### Test-SecretVault\n\nRuns the Test-SecretVault function provided by the extension vault\n\n### Unlock-SecretVault\n\nUnlocks the extension vault through a passed in SecureString password\n\n## Accessing secrets cmdlets\n\n### Set-Secret\n\nAdds a secret to a specific extension vault, or to the default vault if no vault is specified\n\n### Set-SecretInfo\n\nAdds or replaces additional secret metadata to an existing secret in the vault.\nMetadata is not stored securely.\n\n### Get-Secret\n\nRetrieves a secret from a specific extension vault, or first found over all vaults\n\n### Get-SecretInfo\n\nRetrieves information about one or more secrets, but not the secret itself\n\n### Remove-Secret\n\nRemoves a secret from a specific vault\n\n## Vault extension registration\n\nVault extensions are registered to the current user context.\nThey are registered as PowerShell modules that expose required functions used by SecretManagement to manipulate secrets.\nThe required functions are provided as PowerShell cmdlets, and can be implemented as script or binary cmdlets.  \n\nSince each extension vault module exports the same five cmdlets, the module must conform to a directory structure that hides cmdlets from the user and PowerShell command discovery.\nTherefore the extension vault module itself does not export the five required cmdlets directly, but are instead exported from a nested module that resides within the extension vault module directory.\nThis nested module must have a name that is the parent module name with '.Extension' appended to it.  \n\nIt is recommended that the parent module manifest file (.psd1) include the 'SecretManagement' tag in its PrivateData section.\nThis allows [PowerShellGallery](https://www.powershellgallery.com) to associate it with the SecretManagement module.  \n\n### Example: Script module vault extension\n\nThis is a minimal vault extension example to demonstrate the directory structure and functional requirements of an extension vault module.\nThe extension vault module name is 'TestVault'.  \n\n#### Module directory structure\n\n./TestVault  \n./TestVault/TestVault.psd1  \n./TestVault/TestStoreImplementation.dll  \n./TestVault/TestVault.Extension  \n./TestVault/TestVault.Extension/TestVault.Extension.psd1  \n./TestVault/TestVault.Extension/TestVault.Extension.psm1  \n\n#### TestVault.psd1 file\n\n```powershell\n@{\n    ModuleVersion = '1.0'\n    RootModule = '.\\TestStoreImplementation.dll'\n    NestedModules = @('.\\TestVault.Extension')\n    CmdletsToExport = @('Set-TestStoreConfiguration','Get-TestStoreConfiguration')\n    PrivateData = @{\n        PSData = @{\n            Tags = @('SecretManagement')\n        }\n    }\n}\n```\n\nThe TestVault extension module has a binary component (TestStoreImplementation.dll) which implements the vault.  It publicly exports two cmdlets that are used to configure the store.\nIt also declares the required nested module (TestVault.Extension) that exports the five functions required by SecretManagement registration.  \n\nNote that the nested module conforms to the required naming format:  \n'[ModuleName].Extension'  \n\nNote that only the 'NestedModules' entry is required because it loads 'TestVault.Extension' into the module scope, and allows SecretManagement access to the required five functions.\nThe 'RootModule' and 'CmdletsToExport' entries are only for configuring the TestStore in this specific case, and are not needed in general.  \n\n#### TestVault.Extension.psd1 file\n\n```powershell\n@{\n    ModuleVersion = '1.0'\n    RootModule = '.\\TestVault.Extension.psm1'\n    RequiredAssemblies = '..\\TestStoreImplementation.dll'\n    FunctionsToExport = @('Set-Secret','Get-Secret','Remove-Secret','Get-SecretInfo','Test-SecretVault')\n}\n```\n\nThis nested module implements and exports the five functions required by SecretManagement.\nIt also specifies the TestStoreImplementation.dll binary as a 'RequiredAssemblies' because the five exported functions depend on it.  \n\n#### TestVault.Extension.psm1 file\n\n```powershell\nfunction Get-Secret\n{\n    [CmdletBinding()]\n    param (\n        [string] $Name,\n        [string] $VaultName,\n        [hashtable] $AdditionalParameters\n    )\n\n    return [TestStore]::GetItem($Name, $AdditionalParameters)\n}\n\nfunction Get-SecretInfo\n{\n    [CmdletBinding()]\n    param (\n        [string] $Filter,\n        [string] $VaultName,\n        [hashtable] $AdditionalParameters\n    )\n\n    return @(,[Microsoft.PowerShell.SecretManagement.SecretInformation]::new(\n        \"Name\",        # Name of secret\n        \"String\",      # Secret data type [Microsoft.PowerShell.SecretManagement.SecretType]\n        $VaultName,    # Name of vault\n        $Metadata))    # Optional Metadata parameter\n}\n\nfunction Set-Secret\n{\n    [CmdletBinding()]\n    param (\n        [string] $Name,\n        [object] $Secret,\n        [string] $VaultName,\n        [hashtable] $AdditionalParameters\n    )\n\n    [TestStore]::SetItem($Name, $Secret)\n}\n\n# Optional function\nfunction Set-SecretInfo\n{\n    [CmdletBinding()]\n    param (\n        [string] $Name,\n        [hashtable] $Metadata,\n        [string] $VaultName,\n        [hashtable] $AdditionalParameters\n    )\n\n    [TestStore]::SetItemMetadata($Name, $Metadata)\n}\n\nfunction Remove-Secret\n{\n    [CmdletBinding()]\n    param (\n        [string] $Name,\n        [string] $VaultName,\n        [hashtable] $AdditionalParameters\n    )\n\n    [TestStore]::RemoveItem($Name)\n}\n\nfunction Test-SecretVault\n{\n    [CmdletBinding()]\n    param (\n        [string] $VaultName,\n        [hashtable] $AdditionalParameters\n    )\n\n    return [TestStore]::TestVault()\n}\n\n# Optional function\nfunction Unregister-SecretVault\n{\n    [CmdletBinding()]\n    param (\n        [string] $VaultName,\n        [hashtable] $AdditionalParameters\n    )\n\n    [TestStore]::RunUnregisterCleanup()\n}\n\n# Optional function\nfunction Unlock-SecretVault\n{\n    [CmdletBinding()]\n    param (\n        [SecureString] $Password,\n        [string] $VaultName,\n        [hashtable] $AdditionalParameters\n    )\n\n    [TestStore]::UnlockVault($Password)\n}\n```\n\nThis module script implements the five functions, as cmdlets, required by SecretManagement, plus some optional functions.\nIt also implements an optional `Unregister-SecretVault` function that is called during vault extension un-registration.\nIt also implements an optional `Set-SecretInfo` function that sets secret metadata to a specific secret in the vault.\nIt also implements an optional `Unlock-SecretVault` function that unlocks the vault for the current session based on a provided password.  \n\nThe `Set-Secret`, `Set-SecretInfo`, `Remove-Secret`, `Unregister-SecretVault` functions do not write any data to the pipeline, i.e., they do not return any data.  \n\nThe `Get-Secret` cmdlet writes the retrieved secret value to the output pipeline on return, or null if no secret was found.\nIt should write an error only if an abnormal condition occurs.  \n\nThe `Get-SecretInfo` cmdlet writes an array of `Microsoft.PowerShell.SecretManagement.SecretInformation` type objects to the output pipeline or an empty array if no matches were found.  \n\nThe `Test-SecretVault` cmdlet should write all errors that occur during the test.\nBut only a single true/false boolean should be written the the output pipeline indicating success.  \n\nThe `Unregister-SecretVault` cmdlet is optional and will be called on the extension vault if available.\nIt is called before the extension vault is unregistered to allow it to perform any needed clean up work.  \n\nThe `Unlock-SecretVault` cmdlet is optional and will be called on the extension vault if available.\nIt's purpose is to unlock an extension vault for use without having to prompt the user, and is useful for unattended scripts where user interaction is not possible.  \n\nIn general, these cmdlets should write to the error stream only for abnormal conditions that prevent successful completion.\nAnd write to the output stream only the data as indicated above, and expected by SecretManagement.  \n\nIn addition, these cmdlets should perform proper authentication and provide errors, and instructions to authenticate, as appropriate.\nOr prompt the user if needed, for example if a passphrase is required.  \n\nA vault extension doesn't need to provide full implementation of all required functions.\nFor example, a vault extension does not need to provide a way to add or remove a secret through the SecretManagement cmdlets, and can just provide retrieval services.\nIf a vault extension doesn't support some functionality, then it should write an appropriate error with a meaningful message.  \n\nBe careful with module implementation with scripts, because any data returned by function or method calls are automatically written to the output pipeline (if not assigned to a variable).\nSecretManagement expects only specific data to appear in the output pipeline, and if other data is inadvertently written, that will cause SecretManagement to not function properly.  \n\n### Registering the vault\n\nOnce the TestVault module is created, it is registered as follows:\n\n```powershell\nRegister-SecretVault -Name LocalStore -ModuleName ./TestVault -VaultParameters @{ None=\"ReallyNeeded\" } -DefaultVault\n\nGet-SecretVault\n\nVaultName  ModuleName  IsDefaultVault\n---------  ----------  --------------\nLocalStore TestVault   True\n\n```\n\n## Extension vault registry file location\n\nSecretManagement is designed to be installed and run within a user account on both Windows and non-Windows platforms.\nThe extension vault registry file is located in a user account protected directory.  \n\nFor Windows platforms the location is: `%LOCALAPPDATA%\\Microsoft\\PowerShell\\secretmanagement`\n\nFor non-Windows platforms the location: `$HOME/.secretmanagement`\n\n## Windows Managed Accounts\n\nSecretManagement does not currently work for Windows managed accounts.  \n\nSecretManagement depends on both `%LOCALAPPDATA%` folders to store registry information, and Data Protection APIs for safely handling secrets with the .Net `SecureString` type.  \nHowever, Windows managed accounts do not have profiles or `%LOCALAPPDATA%` folders, and Windows Data Protection APIs do not work for managed accounts.  \nConsequently, SecretManagement will not run under managed accounts.\n\n## Code of Conduct\n\nPlease see our [Code of Conduct](.github/CODE_OF_CONDUCT.md) before participating in this project.\n\n## Security Policy\n\nFor any security issues, please see our [Security Policy](.github/SECURITY.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpowershell%2Fsecretmanagement","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpowershell%2Fsecretmanagement","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpowershell%2Fsecretmanagement/lists"}