plugins.psm1
|
<#
.SYNOPSIS Get a list of all registered plugins or a specific plugin by name. .DESCRIPTION The Secrets Broker uses individualized plugins that are capable of pushing credential information to a specific third-party vault. Each plugin must be installed and configured individually. This cmdlet lists all of the plugins that have been installed if invoked with no parameters along with the specific configuration parameters. If a plugin name is provided, it will return the configuration parameters for the specific plugin. .PARAMETER PluginName The name of an installed plugin. .EXAMPLE Get-SgDevOpsPlugin .EXAMPLE Get-SgDevOpsPlugin -PluginName HashiCorpVault #> function Get-SgDevOpsPlugin { [CmdletBinding()] Param( [Parameter(Mandatory=$false, Position=0)] [string]$PluginName ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } if ($PluginName) { Invoke-SgDevOpsMethod GET "Plugins/$PluginName" } else { Invoke-SgDevOpsMethod GET "Plugins" } } <# .SYNOPSIS Upload and install a new plugin. .DESCRIPTION The Secrets Broker uses individualized plugins that are capable of pushing credential information to a specific third-party vault. Each plugin must be installed and configured individually. The plugin must be a zip compressed file. The plugin is installed into the \ProgramData\SafeguardDevOpsService\ExternalPlugins folder. If a new plugin is being installed, restarting the service may not be necessary. However, if an existing plugin is being upgraded, the service does not have the ability to unload a loaded plugin. Therefore all plugin updates will be installed to a staging folder. The next time that the Secrets Broker service is restarted, all staged plugins will be moved to the external plugin folder and loaded. To restart automatically after installing a plugin, set the restart flag to true. .PARAMETER PluginZipFile The full path and file name of the plugin to be installed. .PARAMETER Restart A boolean that indicates whether the Secrets Broker should be restarted after installing the plugin. .EXAMPLE Install-SgDevOpsPlugin c:\my\plugin\path\pluginfile.zip #> function Install-SgDevOpsPlugin { [CmdletBinding()] Param( [Parameter(Mandatory=$true, Position=0)] [string]$PluginZipFile, [Parameter(Mandatory=$false)] [switch]$Restart ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } try { $PluginZipFile = (Resolve-Path $PluginZipFile) $local:Bytes = [System.IO.File]::ReadAllBytes($PluginZipFile) } catch { Write-Host -ForegroundColor Magenta "Unable to read plugin zip file." Write-Host -ForegroundColor Red $_ throw "Invalid plugin zip file specified" } $local:Base64PluginData = [System.Convert]::ToBase64String($local:Bytes) Invoke-SgDevOpsMethod POST "Plugins" -Parameters @{ restart = [bool]$Restart } -Body @{ Base64PluginData = $local:Base64PluginData } Write-Host "Plugin has been installed. Call Get-SgDevOpsPlugin to see installed plugins." if ($Restart) { Write-Host "The Secrets Broker will restart, you must reconnect using Connect-SgDevOps." } } <# .SYNOPSIS Delete the configuration for a specific plugin. .DESCRIPTION The Secrets Broker uses individualized plugins that are capable of pushing credential information to a specific third-party vault. Each plugin must be installed and configured individually. This cmdlet removes the configuration for a specific plugin by name and unregisters the plugin from the Secrets Broker. However, it does not remove the plugin from the \ProgramData\SafeguardDevOpsService\ExternalPlugins folder. The plugin files must be manually removed from the ExternalPlugins folder once Secrets Broker service has been stopped. .PARAMETER PluginName The name of an installed plugin. .EXAMPLE Remove-SgDevOpsPlugin .EXAMPLE Remove-SgDevOpsPlugin -PluginName HashiCorpVault #> function Remove-SgDevOpsPlugin { [CmdletBinding()] Param( [Parameter(Mandatory=$true, Position=0)] [string]$PluginName ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } Invoke-SgDevOpsMethod DELETE "Plugins/$PluginName" } <# .SYNOPSIS Get a list of accounts that are mapped to a vault plugin. .DESCRIPTION Secrets Broker uses individualized plugins that are capable of pushing credential information to a specific third-party vault. Accounts must be mapped to each plugin so that the corresponding credential can be pushed to the third-party vault. By mapping an account to a plugin, the Secrets Broker monitor will detect a password change for the mapped account and push the new credential to the plugin. .PARAMETER PluginName The name of an installed plugin. .EXAMPLE Get-SgDevOpsPluginVaultAccount #> function Get-SgDevOpsPluginVaultAccount { [CmdletBinding()] Param( [Parameter(Mandatory=$true, Position=0)] [string]$PluginName ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } Invoke-SgDevOpsMethod GET "Plugins/$PluginName/VaultAccount" } <# .SYNOPSIS Map an account with the vault credential to a plugin. .DESCRIPTION The Secrets Broker uses individualized plugins that are capable of pushing credentials to a specific third-party vault. Each plugin usually has a credential that is used to authenticate to the third-party vault. This credential must be stored in the Safeguard appliance and fetched at the time when Safeguard Secrets Broker for DevOps needs to authenticate to the third-party vault. The Asset and Account parameters will be used to resolve an asset-account that should be used by the plugin to authenticate to the third-party valult. This asset-account will be mapped to the plugin and the credential that is associated with the asset-account will be pulled from Safeguard at the time when the plugin needs to authenticate to the third-party vault. (See get-SgDevOpsAvailableAssetAccount) .PARAMETER PluginName The name of an installed plugin. .PARAMETER Asset The name of an asset. .PARAMETER Account The name of an account. .EXAMPLE Set-SgDevOpsPluginVaultAccount -PluginName HashiCorpVault -Asset MyVaultAsset -Account MyVaultAccount #> function Set-SgDevOpsPluginVaultAccount { [CmdletBinding()] Param( [Parameter(Mandatory=$true, Position=0)] [string]$PluginName, [Parameter(Mandatory=$true, Position=1)] [object]$Asset, [Parameter(Mandatory=$true, Position=2)] [object]$Account ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } Import-Module -Name "$PSScriptRoot\ps-utilities.psm1" -Scope Local $local:AssetAccount = (Resolve-SgDevOpsAvailableAccount $Asset $Account -Domain $Domain)[0] Invoke-SgDevOpsMethod PUT "Plugins/$PluginName/VaultAccount" -Body $local:AssetAccount } <# .SYNOPSIS Get the settings for a specific plugin. .DESCRIPTION The Secrets Broker uses individualized plugins that are capable of pushing credentials to a specific third-party vault. Each plugin must be installed and configured individually. .PARAMETER PluginName The name of an installed plugin. .PARAMETER SettingName The name of an plugin setting. .EXAMPLE Get-SgDevOpsPluginSetting -PluginName HashiCorpVault .EXAMPLE Get-SgDevOpsPluginSetting -PluginName HashiCorpVault -SettingName NetworkAddress #> function Get-SgDevOpsPluginSetting { [CmdletBinding()] Param( [Parameter(Mandatory=$true, Position=0)] [string]$PluginName, [Parameter(Mandatory=$false, Position=1)] [string]$SettingName ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } $local:Plugin = (Get-SgDevOpsPlugin $PluginName) if ($SettingName) { $local:Plugin.Configuration[$SettingName] } else { $local:Plugin.Configuration } } <# .SYNOPSIS Update a setting for a plugin. .DESCRIPTION The Secrets Broker uses individualized plugins that are capable of pushing credentials to a specific third-party vault. Each plugin must be installed and configured individually. .PARAMETER PluginName The name of an installed plugin. .PARAMETER SettingName The name of an plugin setting. .PARAMETER SettingValue New value for the plugin setting. .EXAMPLE Set-SgDevOpsPluginSetting -PluginName HashiCorpVault -SettingName NetworkAddress -SettingValue 192.168.1.1 #> function Set-SgDevOpsPluginSetting { [CmdletBinding()] Param( [Parameter(Mandatory=$true, Position=0)] [string]$PluginName, [Parameter(Mandatory=$true, Position=1)] [string]$SettingName, [Parameter(Mandatory=$true, Position=2)] [string]$SettingValue ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } $local:Plugin = (Get-SgDevOpsPlugin $PluginName) $local:Plugin.Configuration.$SettingName = $SettingValue Invoke-SgDevOpsMethod PUT "Plugins/$PluginName" -Body $local:Plugin } <# .SYNOPSIS Get the list of accounts that are mapped to a vault plugin. .DESCRIPTION The Secrets Broker uses individualized plugins that are capable of pushing credentials to a specific third-party vault. Accounts must be mapped to each plugin so that the corresponding credential can be pushed to the third-party vault. By mapping an account to a plugin, the Secrets Broker monitor will detect a password change for the mapped account and push the new credential to the plugin. .PARAMETER PluginName The name of an installed plugin. .EXAMPLE Get-SgDevOpsMappedAssetAccount -PluginName HashiCorpVault #> function Get-SgDevOpsMappedAssetAccount { [CmdletBinding()] Param( [Parameter(Mandatory=$true, Position=0)] [string]$PluginName ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } Invoke-SgDevOpsMethod GET "Plugins/$PluginName/Accounts" } <# .SYNOPSIS Map an account or an array of accounts to a vault plugin. .DESCRIPTION The Secrets Broker uses individualized plugins that are capable of pushing credentials to a specific third-party vault. Accounts must be mapped to each plugin so that the corresponding credential can be pushed to the third-party vault. By mapping an account to a plugin, the Secrets Broker monitor will detect a password change for the mapped account and push the new credential to the plugin. The Asset, Account and Domain parameters will be used to resolve an asset-account that will be added to the A2A registration. If an array of asset-accounts is provided, the Asset, Account and Domain parameters should omitted. .PARAMETER PluginName The name of an installed plugin. .PARAMETER Asset The name of an asset. .PARAMETER Account The name of an account. .PARAMETER Domain The name of a domain that the asset-account belong to. .PARAMETER AccountObjects An array of account objects to map to the plugin. (see Get-SgDevOpsRegisteredAssetAccount). .EXAMPLE Add-SgDevOpsMappedAssetAccount -PluginName HashiCorpVault -Asset MyServer -Account MyAccount .EXAMPLE Add-SgDevOpsMappedAssetAccount -PluginName HashiCorpVault -AccountObjects $MyAccounts #> function Add-SgDevOpsMappedAssetAccount { [CmdletBinding(DefaultParameterSetName="Attributes")] Param( [Parameter(Mandatory=$true, Position=0)] [string]$PluginName, [Parameter(ParameterSetName="Attributes", Mandatory=$true, Position=1)] [string]$Asset, [Parameter(ParameterSetName="Attributes", Mandatory=$true, Position=2)] [string]$Account, [Parameter(ParameterSetName="Attributes", Mandatory=$false)] [string]$Domain, [Parameter(ParameterSetName="Objects", Mandatory=$true)] [object[]]$AccountObjects ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } Import-Module -Name "$PSScriptRoot\ps-utilities.psm1" -Scope Local [object[]]$local:NewList = @() if ($PsCmdlet.ParameterSetName -eq "Attributes") { $local:NewList += (Resolve-SgDevOpsRegisteredAccount $Asset $Account -Domain $Domain) } else { $AccountObjects | ForEach-Object { $local:NewList += (Resolve-SgDevOpsRegisteredAccount -Account $_) } } Invoke-SgDevOpsMethod PUT "Plugins/$PluginName/Accounts" -Body $local:NewList } <# .SYNOPSIS Remove an account or an array of accounts from a vault plugin. .DESCRIPTION The Secrets Broker uses individualized plugins that are capable of pushing credentials to a specific third-party vault. Accounts must be mapped to each plugin so that the corresponding credential can be pushed to the third-party vault. By mapping an account to a plugin, the Secrets Broker monitor will detect a password change for the mapped account and push the new credential to the plugin. The Asset, Account and Domain parameters will be used to resolve an asset-account that will be added to the A2A registration. If an array of asset-accounts is provided, the Asset, Account and Domain parameters should omitted. .PARAMETER PluginName The name of an installed plugin. .PARAMETER Asset The name of an asset. .PARAMETER Account The name of an account. .PARAMETER Domain The name of a domain that the asset-account belong to. .PARAMETER AccountObjects An array of account objects to unmap from the plugin. (see Get-SgDevOpsMappedAssetAccount). .EXAMPLE Remove-SgDevOpsMappedAssetAccount -PluginName HashiCorpVault -Asset MyServer -Account MyAccount .EXAMPLE Remove-SgDevOpsMappedAssetAccount -PluginName HashiCorpVault -AccountObjects $MyAccounts #> function Remove-SgDevOpsMappedAssetAccount { [CmdletBinding(DefaultParameterSetName="Attributes")] Param( [Parameter(Mandatory=$true, Position=0)] [string]$PluginName, [Parameter(ParameterSetName="Attributes", Mandatory=$true, Position=1)] [string]$Asset, [Parameter(ParameterSetName="Attributes", Mandatory=$true, Position=2)] [string]$Account, [Parameter(ParameterSetName="Attributes", Mandatory=$false)] [string]$Domain, [Parameter(ParameterSetName="Objects")] [object[]]$AccountObjects ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } $local:MappedAccounts = (Get-SgDevOpsMappedAssetAccount $PluginName) [object[]]$local:RemoveList = @() if ($PsCmdlet.ParameterSetName -eq "Attributes") { if ($Domain) { $local:RemoveList += ($local:MappedAccounts | Where-Object { $_.AssetName -ieq $Asset -and $_.AccountName -ieq $Account -and $_.DomainName -ieq $Domain}) } else { $local:RemoveList += ($local:MappedAccounts | Where-Object { $_.AssetName -ieq $Asset -and $_.AccountName -ieq $Account }) } } else { $AccountObjects | ForEach-Object { $local:Object = $_ if ($local:Object.AccountId) { $local:RemoveList += ($local:MappedAccounts | Where-Object { $_.AccountId -eq $local:Object.AccountId }) } else { # try to match available asset accounts (they have an Id rather than an AccountId) $local:RemoveList += ($local:MappedAccounts | Where-Object { $_.AccountId -eq $local:Object.Id }) } } } if (-not $local:RemoveList) { throw "Unable to find specified mapped asset accounts to remove." } Invoke-SgDevOpsMethod DELETE "Plugins/$PluginName/Accounts" -Body $local:RemoveList # return the current list Get-SgDevOpsMappedAssetAccount $PluginName } <# .SYNOPSIS Get all of the instances of a plugin by name. .DESCRIPTION The Secrets Broker uses individualized plugins that are capable of pushing credentials to a specific third-party vault. Secrets Broker is capable of creating and managing mutliple instances of each plugin. This cmdlet gets all of the instances of a plugin given the plugin name. .PARAMETER PluginName The name of an existing plugin. .PARAMETER IncludeDeleted Include any plugins that are marked to be deleted on the next restart. .EXAMPLE Get-SgDevOpsPluginInstances -PluginName HashiCorpVault -IncludeDeleted #> function Get-SgDevOpsPluginInstances { [CmdletBinding()] Param( [Parameter(Mandatory=$true, Position=0)] [string]$PluginName, [Parameter(Mandatory=$false)] [switch]$IncludeDeleted ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } Invoke-SgDevOpsMethod GET "Plugins/$PluginName/Instances" -Parameters @{ includeDeleted = [bool]$IncludeDeleted } } <# .SYNOPSIS Add a new instance of a plugin by name. .DESCRIPTION The Secrets Broker uses individualized plugins that are capable of pushing credentials to a specific third-party vault. Secrets Broker is capable of creating and managing mutliple instances of each plugin. This cmdlet creates a new instance of an existing plugin and optionally copies the configuration of the original plugin to the new plugin instance. .PARAMETER PluginName The name of an exiting plugin. .PARAMETER CopyConfig Copy the configuration of the exiting plugin to the new plugin instance. .EXAMPLE Add-SgDevOpsPluginInstances -PluginName HashiCorpVault -CopyConfig #> function Add-SgDevOpsPluginInstances { [CmdletBinding()] Param( [Parameter(Mandatory=$true, Position=0)] [string]$PluginName, [Parameter(Mandatory=$false)] [switch]$CopyConfig ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } Invoke-SgDevOpsMethod POST "Plugins/$PluginName/Instances" -Parameters @{ copyConfig = [bool]$CopyConfig } } <# .SYNOPSIS Remove all instances of a plugin by name. .DESCRIPTION The Secrets Broker uses individualized plugins that are capable of pushing credentials to a specific third-party vault. Secrets Broker is capable of creating and managing mutliple instances of each plugin. This cmdlet deletes all instances of a plugin by name and removes the plugin from Secrets Broker. .PARAMETER PluginName The name of an installed plugin. .PARAMETER Restart A boolean that indicates whether the Secrets Broker should be restarted after deleting all instances of the plugin. .EXAMPLE Delete-SgDevOpsPluginInstances .EXAMPLE Remove-SgDevOpsPluginInstances -PluginName HashiCorpVault -Restart #> function Remove-SgDevOpsPluginInstances { [CmdletBinding()] Param( [Parameter(Mandatory=$true, Position=0)] [string]$PluginName, [Parameter(Mandatory=$false)] [switch]$Restart ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } Invoke-SgDevOpsMethod DELETE "Plugins/$PluginName/Instances" -Parameters @{ restart = [bool]$Restart } } |