Public/Phishing/Get-KB4PhishingSecurityTest.ps1
|
<# .SYNOPSIS Gets KnowBe4 phishing security tests. .DESCRIPTION Retrieves phishing security tests from the KnowBe4 Reporting API. The command can list all security tests, list tests for a specific phishing campaign, or get a specific security test by ID. Normal output unwraps KnowBe4 page data and returns security test objects. Use Raw to inspect the full response envelope and page wrapper. .PARAMETER Id The KnowBe4 phishing security test ID. This parameter also accepts the alias PstId. .PARAMETER CampaignId The phishing campaign ID used to list security tests for a specific campaign. .PARAMETER CampaignType Filters for a phishing campaign type. The current supported value is Callback. .PARAMETER All Retrieves all available pages for list requests. .PARAMETER PageSize The number of security tests to request per page. Valid range is 1 through 500. .PARAMETER Page The page number to request when using page-based pagination. .PARAMETER Cursor The cursor value to request. Use 'true' to start cursor pagination manually. .PARAMETER UsePagePagination Uses page-based pagination when All is specified. Cursor pagination is preferred. .PARAMETER Raw Returns the full PSKB4Reporting response envelope instead of unwrapped security test objects. .EXAMPLE Get-KB4PhishingSecurityTest -PageSize 50 Gets the first page of phishing security tests. .EXAMPLE Get-KB4PhishingSecurityTest -CampaignId 12345 Gets phishing security tests for campaign 12345. .EXAMPLE Get-KB4PhishingSecurityTest -Id 67890 Gets a specific phishing security test. .OUTPUTS PSCustomObject. #> function Get-KB4PhishingSecurityTest { [CmdletBinding(DefaultParameterSetName = 'List')] param( [Parameter(Mandatory, ParameterSetName = 'ById', ValueFromPipelineByPropertyName)] [Alias('PstId')] [int] $Id, [Parameter(Mandatory, ParameterSetName = 'ByCampaign')] [int] $CampaignId, [Parameter()] [ValidateSet('Callback')] [string] $CampaignType, [Parameter(ParameterSetName = 'List')] [Parameter(ParameterSetName = 'ByCampaign')] [switch] $All, [Parameter(ParameterSetName = 'List')] [Parameter(ParameterSetName = 'ByCampaign')] [ValidateRange(1, 500)] [int] $PageSize = 100, [Parameter(ParameterSetName = 'List')] [Parameter(ParameterSetName = 'ByCampaign')] [ValidateRange(1, [int]::MaxValue)] [int] $Page, [Parameter(ParameterSetName = 'List')] [Parameter(ParameterSetName = 'ByCampaign')] [string] $Cursor, [Parameter(ParameterSetName = 'List')] [Parameter(ParameterSetName = 'ByCampaign')] [switch] $UsePagePagination, [Parameter()] [switch] $Raw ) process { $query = @{} if ($CampaignType) { $query['campaign_type'] = $CampaignType.ToLowerInvariant() } if ($PSCmdlet.ParameterSetName -eq 'ById') { $path = '/v1/phishing/security_tests/{0}' -f (Format-KB4PathValue -Value $Id) return Get-KB4ResponseBody -Response (Invoke-KB4Request -Path $path -Query $query) -Raw:$Raw } $path = if ($PSCmdlet.ParameterSetName -eq 'ByCampaign') { '/v1/phishing/campaigns/{0}/security_tests' -f (Format-KB4PathValue -Value $CampaignId) } else { '/v1/phishing/security_tests' } $pagedParameters = @{ Path = $path Query = $query All = $All PageSize = $PageSize UsePagePagination = $UsePagePagination Raw = $Raw } if ($PSBoundParameters.ContainsKey('Page')) { $pagedParameters['Page'] = $Page } if ($PSBoundParameters.ContainsKey('Cursor')) { $pagedParameters['Cursor'] = $Cursor } Invoke-KB4PagedRequest @pagedParameters } } |