From 5113b7c05bb889ae4cfbb4e88206d9312196f0c3 Mon Sep 17 00:00:00 2001 From: Shawn Melton <11204251+wsmelton@users.noreply.github.com> Date: Mon, 4 Oct 2021 19:58:26 -0500 Subject: [PATCH] Search-TssDistributedEngine - new command to search for Engines --- .../Search-TssDistributedEngine.md | 153 ++++++++++++++++++ src/Thycotic.SecretServer.Format.ps1xml | 42 +++++ .../distributed-engines/EngineSummary.cs | 20 +++ .../EngineActivationStatus.cs | 15 ++ .../EngineConnectionStatus.cs | 15 ++ .../Search-TssDistributedEngine.ps1 | 108 +++++++++++++ .../Search-TssDistributedEngineSite.ps1 | 1 - 7 files changed, 353 insertions(+), 1 deletion(-) create mode 100644 docs/commands/distributed-engines/Search-TssDistributedEngine.md create mode 100644 src/Thycotic.SecretServer/classes/distributed-engines/EngineSummary.cs create mode 100644 src/Thycotic.SecretServer/enums/distributed-engines/EngineActivationStatus.cs create mode 100644 src/Thycotic.SecretServer/enums/distributed-engines/EngineConnectionStatus.cs create mode 100644 src/functions/distributed-engines/Search-TssDistributedEngine.ps1 diff --git a/docs/commands/distributed-engines/Search-TssDistributedEngine.md b/docs/commands/distributed-engines/Search-TssDistributedEngine.md new file mode 100644 index 00000000..756b8f2e --- /dev/null +++ b/docs/commands/distributed-engines/Search-TssDistributedEngine.md @@ -0,0 +1,153 @@ +# Search-TssDistributedEngine + +## SYNOPSIS +Search Distributed Engines + +## SYNTAX + +``` +Search-TssDistributedEngine [-TssSession] [-SiteId ] + [-ActivationStatus ] [-ConnectionStatus ] + [-SearchText ] [-RequireActivation] [-SortBy ] [] +``` + +## DESCRIPTION +Search Distributed Engines + +## EXAMPLES + +### EXAMPLE 1 +``` +$session = New-TssSession -SecretServer https://alpha -Credential $ssCred +Search-TssDistributedEngine -TssSession $session -SiteId 1 +``` + +Return list of engines assigned to Site ID 1 + +## PARAMETERS + +### -TssSession +TssSession object created by New-TssSession for authentication + +```yaml +Type: Session +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -SiteId +Site ID + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -ActivationStatus +Only return engines with this activation status + +```yaml +Type: EngineActivationStatus +Parameter Sets: (All) +Aliases: +Accepted values: Pending, Activated, Inactive, Deleted + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ConnectionStatus +Only return engines with this connection status + +```yaml +Type: EngineConnectionStatus +Parameter Sets: (All) +Aliases: +Accepted values: Offline, Online, Invalid, OldVersion + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SearchText +Only return engines with a friendly name that contains this text + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RequireActivation +Only include engines that require action. +For example, pending but not deleted or no site assigned. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SortBy +Sort by specific property, default EngineId + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: EngineId +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +### Thycotic.PowerShell.DistributedEngines.EngineSummary +## NOTES +Requires TssSession object returned by New-TssSession + +## RELATED LINKS + +[https://thycotic-ps.github.io/thycotic.secretserver/commands/distributed-engines/Search-TssDistributedEngine](https://thycotic-ps.github.io/thycotic.secretserver/commands/distributed-engines/Search-TssDistributedEngine) + +[https://github.com/thycotic-ps/thycotic.secretserver/blob/main/src/functions/distributed-engines/Search-TssDistributedEngine.ps1](https://github.com/thycotic-ps/thycotic.secretserver/blob/main/src/functions/distributed-engines/Search-TssDistributedEngine.ps1) + diff --git a/src/Thycotic.SecretServer.Format.ps1xml b/src/Thycotic.SecretServer.Format.ps1xml index 75d05377..80bdaf0c 100644 --- a/src/Thycotic.SecretServer.Format.ps1xml +++ b/src/Thycotic.SecretServer.Format.ps1xml @@ -3420,5 +3420,47 @@ + + + DistributedEngines.EngineSummary + + Thycotic.PowerShell.DistributedEngines.EngineSummary + + + + + + + + + + + + + + + EngineId + + + ActivationStatus + + + ConnectionStatus + + + FriendlyName + + + Hostname + + + LastConnected + + + + + + + diff --git a/src/Thycotic.SecretServer/classes/distributed-engines/EngineSummary.cs b/src/Thycotic.SecretServer/classes/distributed-engines/EngineSummary.cs new file mode 100644 index 00000000..99110524 --- /dev/null +++ b/src/Thycotic.SecretServer/classes/distributed-engines/EngineSummary.cs @@ -0,0 +1,20 @@ +using System; +using System.Threading.Tasks; +using System.Management.Automation; +using System.Management.Automation.Runspaces; +using Thycotic.PowerShell.Enums; + +namespace Thycotic.PowerShell.DistributedEngines +{ + public class EngineSummary + { + public EngineActivationStatus ActivationStatus { get; set; } + public string BindAddress { get; set; } + public EngineConnectionStatus ConnectionStatus { get; set; } + public int EngineId { get; set; } + public string FriendlyName { get; set; } + public string Hostname { get; set; } + public bool IsBlockedByNet48 { get; set; } + public DateTime? LastConnected { get; set; } + } +} \ No newline at end of file diff --git a/src/Thycotic.SecretServer/enums/distributed-engines/EngineActivationStatus.cs b/src/Thycotic.SecretServer/enums/distributed-engines/EngineActivationStatus.cs new file mode 100644 index 00000000..47c0c998 --- /dev/null +++ b/src/Thycotic.SecretServer/enums/distributed-engines/EngineActivationStatus.cs @@ -0,0 +1,15 @@ +using System; +using System.Threading.Tasks; +using System.Management.Automation; +using System.Management.Automation.Runspaces; + +namespace Thycotic.PowerShell.Enums +{ + public enum EngineActivationStatus + { + Pending, + Activated, + Inactive, + Deleted + } +} \ No newline at end of file diff --git a/src/Thycotic.SecretServer/enums/distributed-engines/EngineConnectionStatus.cs b/src/Thycotic.SecretServer/enums/distributed-engines/EngineConnectionStatus.cs new file mode 100644 index 00000000..208cf7c4 --- /dev/null +++ b/src/Thycotic.SecretServer/enums/distributed-engines/EngineConnectionStatus.cs @@ -0,0 +1,15 @@ +using System; +using System.Threading.Tasks; +using System.Management.Automation; +using System.Management.Automation.Runspaces; + +namespace Thycotic.PowerShell.Enums +{ + public enum EngineConnectionStatus + { + Offline, + Online, + Invalid, + OldVersion + } +} \ No newline at end of file diff --git a/src/functions/distributed-engines/Search-TssDistributedEngine.ps1 b/src/functions/distributed-engines/Search-TssDistributedEngine.ps1 new file mode 100644 index 00000000..30680f00 --- /dev/null +++ b/src/functions/distributed-engines/Search-TssDistributedEngine.ps1 @@ -0,0 +1,108 @@ +function Search-TssDistributedEngine { + <# + .SYNOPSIS + Search Distributed Engines + + .DESCRIPTION + Search Distributed Engines + + .LINK + https://thycotic-ps.github.io/thycotic.secretserver/commands/distributed-engines/Search-TssDistributedEngine + + .LINK + https://github.com/thycotic-ps/thycotic.secretserver/blob/main/src/functions/distributed-engines/Search-TssDistributedEngine.ps1 + + .EXAMPLE + $session = New-TssSession -SecretServer https://alpha -Credential $ssCred + Search-TssDistributedEngine -TssSession $session -SiteId 1 + + Return list of engines assigned to Site ID 1 + + .NOTES + Requires TssSession object returned by New-TssSession + #> + [CmdletBinding()] + [OutputType('Thycotic.PowerShell.DistributedEngines.EngineSummary')] + param ( + # TssSession object created by New-TssSession for authentication + [Parameter(Mandatory,ValueFromPipeline,Position = 0)] + [Thycotic.PowerShell.Authentication.Session] + $TssSession, + + # Site ID + [Parameter(ValueFromPipelineByPropertyName)] + [int] + $SiteId, + + # Only return engines with this activation status + [Thycotic.PowerShell.Enums.EngineActivationStatus] + $ActivationStatus, + + # Only return engines with this connection status + [Thycotic.PowerShell.Enums.EngineConnectionStatus] + $ConnectionStatus, + + # Only return engines with a friendly name that contains this text + [string] + $SearchText, + + # Only include engines that require action. For example, pending but not deleted or no site assigned. + [switch] + $RequireActivation, + + # Sort by specific property, default EngineId + [string] + $SortBy = 'EngineId' + ) + begin { + $tssParams = $PSBoundParameters + $invokeParams = . $GetInvokeApiParams $TssSession + } + process { + Get-TssInvocation $PSCmdlet.MyInvocation + if ($tssParams.ContainsKey('TssSession') -and $TssSession.IsValidSession()) { + Compare-TssVersion $TssSession '10.9.000064' $PSCmdlet.MyInvocation + $uri = $TssSession.ApiUrl, 'distributed-engine', 'engines' -join '/' + $uri = $uri, "sortBy[0].direction=asc&sortBy[0].name=$SortBy&take=$($TssSession.Take)" -join '?' + $invokeParams.Method = 'GET' + + $filters = @() + switch ($tssParams.Keys) { + 'SiteId' { $filters += "filter.siteId=$SiteId" } + 'ActivationStatus' { $filters += "filter.activationStatus = $([string]$ActivationStatus)" } + 'ConnectionStatus' { filters += "filter.connectionStatus = $([string]$ConnectionStatus)" } + 'SearchText' { $filters += "filter.friendlyName = $SearchText" } + 'RequireActivation' { $filters += "filter.onlyIncludeRequiringAction=$([boolean]$RequireActivation)" } + default { + Write-Error "[-SiteId] or [-RequiredActivation] parameter must be provided!" + return + } + } + if ($filters) { + $uriFilter = $filters -join '&' + Write-Verbose "Filters: $uriFilter" + $uri = $uri, $uriFilter -join '&' + } + $invokeParams.Uri = $uri + + Write-Verbose "Performing the operation $($invokeParams.Method) $($invokeParams.Uri)" + try { + $apiResponse = Invoke-TssApi @invokeParams + $restResponse = . $ProcessResponse $apiResponse + } catch { + Write-Warning "Issue on search request" + $err = $_ + . $ErrorHandling $err + } + + if ($restResponse.records.Count -le 0 -and $restResponse.records.Length -eq 0) { + Write-Warning "No records found" + } + if ($restResponse.records) { + [Thycotic.PowerShell.DistributedEngines.EngineSummary[]]$restResponse.records + } + } else { + Write-Warning "No valid session found" + } + } +} \ No newline at end of file diff --git a/src/functions/distributed-engines/Search-TssDistributedEngineSite.ps1 b/src/functions/distributed-engines/Search-TssDistributedEngineSite.ps1 index 540996a2..293d50a8 100644 --- a/src/functions/distributed-engines/Search-TssDistributedEngineSite.ps1 +++ b/src/functions/distributed-engines/Search-TssDistributedEngineSite.ps1 @@ -63,7 +63,6 @@ function Search-TssDistributedEngineSite { $tssParams = $PSBoundParameters $invokeParams = . $GetInvokeApiParams $TssSession } - process { Get-TssInvocation $PSCmdlet.MyInvocation if ($tssParams.ContainsKey('TssSession') -and $TssSession.IsValidSession()) {