Public/Phishing/Get-KB4PhishingCampaign.ps1
|
<# .SYNOPSIS Gets KnowBe4 phishing campaigns. .DESCRIPTION Retrieves phishing campaigns from the KnowBe4 Reporting API. Without Id, the command returns a page of campaigns or all campaigns when All is specified. With Id, the command returns a specific phishing campaign. Normal output unwraps KnowBe4 page data and returns campaign objects. Use Raw to inspect the full response envelope and page wrapper. .PARAMETER Id The KnowBe4 phishing campaign ID. This parameter also accepts the alias CampaignId. .PARAMETER CampaignType Filters for a phishing campaign type. The current supported value is Callback. .PARAMETER All Retrieves all available pages. .PARAMETER PageSize The number of phishing campaigns 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 campaign objects. .EXAMPLE Get-KB4PhishingCampaign -PageSize 50 Gets the first page of phishing campaigns. .EXAMPLE Get-KB4PhishingCampaign -Id 12345 Gets a specific phishing campaign. .OUTPUTS PSCustomObject. #> function Get-KB4PhishingCampaign { [CmdletBinding(DefaultParameterSetName = 'List')] param( [Parameter(Mandatory, ParameterSetName = 'ById', ValueFromPipelineByPropertyName)] [Alias('CampaignId')] [int] $Id, [Parameter()] [ValidateSet('Callback')] [string] $CampaignType, [Parameter(ParameterSetName = 'List')] [switch] $All, [Parameter(ParameterSetName = 'List')] [ValidateRange(1, 500)] [int] $PageSize = 100, [Parameter(ParameterSetName = 'List')] [ValidateRange(1, [int]::MaxValue)] [int] $Page, [Parameter(ParameterSetName = 'List')] [string] $Cursor, [Parameter(ParameterSetName = 'List')] [switch] $UsePagePagination, [Parameter()] [switch] $Raw ) process { $query = @{} if ($CampaignType) { $query['campaign_type'] = $CampaignType.ToLowerInvariant() } if ($PSCmdlet.ParameterSetName -eq 'ById') { $path = '/v1/phishing/campaigns/{0}' -f (Format-KB4PathValue -Value $Id) return Get-KB4ResponseBody -Response (Invoke-KB4Request -Path $path -Query $query) -Raw:$Raw } $pagedParameters = @{ Path = '/v1/phishing/campaigns' 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 } } |