events.psm1
|
# Helper function Resolve-Event { [CmdletBinding()] Param( [Parameter(Mandatory=$false)] [string]$Appliance, [Parameter(Mandatory=$false)] [object]$AccessToken, [Parameter(Mandatory=$false)] [switch]$Insecure, [Parameter(Mandatory=$true,Position=0)] [object]$EventObj ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } while (-not $local:FoundEvent) { Write-Host "Searching for events with '$EventObj'" try { $local:FoundEvent = (Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core GET ` "Events/$EventObj") } catch {} if (-not $local:FoundEvent) { $local:Events = ((Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core GET Events ` -Parameters @{ fields = "Name,Category,Description" }) | Where-Object { $_.Name -match "$EventObj" }) if (($local:Events).Count -eq 0) { $local:Events = ((Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core GET Events ` -Parameters @{ fields = "Name,Category,Description" }) | Where-Object { $_.Category -match "$EventObj" }) } if (($local:Events).Count -eq 0) { try { $local:Events = (Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core GET Events ` -Parameters @{ filter = "Description icontains '$EventObj'"; fields = "Name,Category,Description" }) } catch { Write-Verbose $_ Write-Verbose "Caught exception with icontains filter, trying with contains filter" $local:Events = (Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core GET Events ` -Parameters @{ filter = "Description contains '$EventObj'"; fields = "Name,Category,Description" }) } } $local:Events = ($local:Events | Sort-Object -Property Name) if (($local:Events).Count -eq 0) { throw "Unable to find event matching '$EventObj'..." } if (($local:Events).Count -ne 1) { $local:Longest = (($local:Events).Name | Measure-Object -Maximum -Property Length).Maximum Write-Host "Found $($local:Events.Count) events matching '$EventObj':" Write-Host "[" $local:Events | ForEach-Object { Write-Host (" {0,$($local:Longest)} - {1}" -f $_.Name,$_.Description) } Write-Host "]" $EventObj = (Read-Host "Enter event name or search string") } else { $local:FoundEvent = (Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core GET ` "Events/$($local:Events[0].Name)") } } } $local:FoundEvent } function Resolve-SubscriptionEvent { [CmdletBinding()] Param( [Parameter(Mandatory=$false)] [string]$Appliance, [Parameter(Mandatory=$false)] [object]$AccessToken, [Parameter(Mandatory=$false)] [switch]$Insecure, [Parameter(Mandatory=$false)] [object]$TypeOfEvent, [Parameter(Mandatory=$true)] [string[]]$EventsToValidate ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } [string[]]$InvalidEvents = $null [object[]]$SubscriptionEvents = $null if ($TypeOfEvent) { [string[]]$EventNames = (Get-SafeguardEventName -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure -TypeOfEvent $TypeOfEvent) } else { [string[]]$EventNames = (Get-SafeguardEventName -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure) } foreach ($IndividualEvent in $EventsToValidate) { if (-not $EventNames.Contains($IndividualEvent)) { $InvalidEvents += $IndividualEvent } $local:SubscriptionEvent = @{ Name = $IndividualEvent } $SubscriptionEvents += $local:SubscriptionEvent } if ($null -ne $InvalidEvents) { $InvalidEventsList = $InvalidEvents -join "," Write-Error -Message "The following are not valid $TypeOfEvent events: $InvalidEventsList." -Category InvalidArgument -ErrorAction Stop } return $SubscriptionEvents } <# .SYNOPSIS Get information on events in Safeguard via the Web API. .DESCRIPTION Safeguard events occur as a result of or access request or administrative activity. Administrative activity includes creation and deletion of assets or accounts. This cmdlet helps you get information about events. This cmdlet tries to get a single event by matching name, if that doesn't work it tries category, and finally description. .PARAMETER Appliance IP address or hostname of a Safeguard appliance. .PARAMETER AccessToken A string containing the bearer token to be used with Safeguard Web API. .PARAMETER Insecure Ignore verification of Safeguard appliance SSL certificate. .PARAMETER EventToGet A string containing the name of the event to get. .PARAMETER Fields An array of the event property names to return. .INPUTS None. .OUTPUTS JSON response from Safeguard Web API. .EXAMPLE Get-SafeguardEvent -AccessToken $token -Appliance 10.5.32.54 -Insecure .EXAMPLE Get-SafeguardEvent AssetCreated #> function Get-SafeguardEvent { [CmdletBinding()] Param( [Parameter(Mandatory=$false)] [string]$Appliance, [Parameter(Mandatory=$false)] [object]$AccessToken, [Parameter(Mandatory=$false)] [switch]$Insecure, [Parameter(Mandatory=$false,Position=0)] [object]$EventToGet, [Parameter(Mandatory=$false)] [string[]]$Fields ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } $local:Parameters = $null if ($Fields) { $local:Parameters = @{ fields = ($Fields -join ",")} } if ($PSBoundParameters.ContainsKey("EventToGet")) { Resolve-Event -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure $EventToGet } else { Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core GET Events -Parameters $local:Parameters } } <# .SYNOPSIS Get the names of subscribable events in Safeguard by their type via the Web API. .DESCRIPTION Get the list of names of subscribable events in Safeguard. .PARAMETER Appliance IP address or hostname of a Safeguard appliance. .PARAMETER AccessToken A string containing the bearer token to be used with Safeguard Web API. .PARAMETER Insecure Ignore verification of Safeguard appliance SSL certificate. .PARAMETER TypeofEvent A string containing the type of events for which to return the names of the events that belong to this type. .INPUTS None. .OUTPUTS JSON response from Safeguard Web API. .EXAMPLE Get-SafeguardEventName -AccessToken $token -Appliance 10.5.32.54 -Insecure .EXAMPLE Get-SafeguardEventName AssetAccount #> function Get-SafeguardEventName { [CmdletBinding(DefaultParameterSetName="Category")] Param( [Parameter(Mandatory=$false)] [string]$Appliance, [Parameter(Mandatory=$false)] [object]$AccessToken, [Parameter(Mandatory=$false)] [switch]$Insecure, [Parameter(Mandatory=$false, ParameterSetName="Category")] [string]$Category, [Parameter(Mandatory=$false, ParameterSetName="TypeOfObject", Position=0)] [ValidateSet('A2AService','AccessPolicy','AccountDiscoverySchedule','AccountGroup','ArchiveServer', 'Asset','AssetAccount','AssetGroup','AssetPartition','AuthenticationProvider','IdentityProvider', 'PartitionProfile','PartitionProfileChangeSchedule','PartitionProfileCheckSchedule', 'PartitionProfileSyncGroup','PartitionTag','PersonalAccount','ReasonCode','Registration','Role', 'SessionModuleConnection','SshKeySyncGroup','StarlingRegisteredConnector','StarlingSubscription', 'TicketSystem','User','UserGroup', IgnoreCase=$true)] [object]$TypeofEvent ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } [object[]]$local:Names = $null $local:Events = (Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure ` Core GET Events -Parameters @{ fields = "Name,Category,ObjectType" }) foreach ($local:IndividualEvent in $local:Events) { if ($PSBoundParameters.ContainsKey("TypeofEvent") -and $TypeofEvent) { if (($local:IndividualEvent).ObjectType -ieq $TypeofEvent) { $local:Names += $(($local:IndividualEvent).Name) } } elseif ($PSBoundParameters.ContainsKey("Category") -and $Category) { if (($local:IndividualEvent).Category -ieq $Category) { $local:Names += $(($local:IndividualEvent).Name) } } else { $local:Names += $(($local:IndividualEvent).Name) } } $local:Names | Sort-Object } <# .SYNOPSIS Get the names of subscribable events in Safeguard by their type via the Web API. .DESCRIPTION Get the list of names of subscribable events in Safeguard. .PARAMETER Appliance IP address or hostname of a Safeguard appliance. .PARAMETER AccessToken A string containing the bearer token to be used with Safeguard Web API. .PARAMETER Insecure Ignore verification of Safeguard appliance SSL certificate. .PARAMETER TypeofEvent A string containing the type of events for which to return the names of the events that belong to this type. .INPUTS None. .OUTPUTS JSON response from Safeguard Web API. .EXAMPLE Get-SafeguardEventCategory -AccessToken $token -Appliance 10.5.32.54 -Insecure .EXAMPLE Get-SafeguardEventCategory AssetAccount #> function Get-SafeguardEventCategory { [CmdletBinding()] Param( [Parameter(Mandatory=$false)] [string]$Appliance, [Parameter(Mandatory=$false)] [object]$AccessToken, [Parameter(Mandatory=$false)] [switch]$Insecure, [Parameter(Mandatory=$false, Position=0)] [ValidateSet('A2AService','AccessPolicy','AccountDiscoverySchedule','AccountGroup','ArchiveServer', 'Asset','AssetAccount','AssetGroup','AssetPartition','AuthenticationProvider','IdentityProvider', 'PartitionProfile','PartitionProfileChangeSchedule','PartitionProfileCheckSchedule', 'PartitionProfileSyncGroup','PartitionTag','PersonalAccount','ReasonCode','Registration','Role', 'SessionModuleConnection','SshKeySyncGroup','StarlingRegisteredConnector','StarlingSubscription', 'TicketSystem','User','UserGroup', IgnoreCase=$true)] [object]$TypeofEvent ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } [object[]]$local:Names = $null $local:Events = (Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure ` Core GET Events -Parameters @{ fields = "Name,Category,ObjectType" }) foreach ($local:IndividualEvent in $local:Events) { if ($PSBoundParameters.ContainsKey("TypeofEvent")) { if (($local:IndividualEvent).ObjectType -eq $TypeofEvent) { $local:Names += $(($local:IndividualEvent).Category) } } else { $local:Names += $(($local:IndividualEvent).Category) } } $local:Names | Sort-Object | Get-Unique } <# .SYNOPSIS Get information on events in Safeguard via the Web API. .DESCRIPTION Safeguard events occur as a result of or access request or administrative activity. Administrative activity includes creation and deletion of assets or accounts. This cmdlet helps you get information about events. This cmdlet gets the properties that will be sent to subscribers of an event. This cmdlet uses Get-SafeguardEvent to locate a single event. .PARAMETER Appliance IP address or hostname of a Safeguard appliance. .PARAMETER AccessToken A string containing the bearer token to be used with Safeguard Web API. .PARAMETER Insecure Ignore verification of Safeguard appliance SSL certificate. .PARAMETER EventToGet A string containing the name of the event to get. .INPUTS None. .OUTPUTS JSON response from Safeguard Web API. .EXAMPLE Get-SafeguardEventProperty AssetCreated #> function Get-SafeguardEventProperty { [CmdletBinding()] Param( [Parameter(Mandatory=$false)] [string]$Appliance, [Parameter(Mandatory=$false)] [object]$AccessToken, [Parameter(Mandatory=$false)] [switch]$Insecure, [Parameter(Mandatory=$true,Position=0)] [object]$EventToGet ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } (Get-SafeguardEvent -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure $EventToGet).Properties ` | Sort-Object -Property Name | Format-Table Name,Description } <# .SYNOPSIS Find information on events in Safeguard via the Web API. .DESCRIPTION Safeguard events are events that occur as a result of an administrative activity such as created and deletion of an asset or an account. .PARAMETER Appliance IP address or hostname of a Safeguard appliance. .PARAMETER AccessToken A string containing the bearer token to be used with Safeguard Web API. .PARAMETER Insecure Ignore verification of Safeguard appliance SSL certificate. .PARAMETER SearchString A string to search for in the event information. .PARAMETER QueryFilter A string to pass to the -filter query parameter in the Safeguard Web API. .PARAMETER Fields An array of the event property names to return. .INPUTS None. .OUTPUTS JSON response from Safeguard Web API. .EXAMPLE Find-SafeguardEvent -AccessToken $token -Appliance 10.5.32.54 -Insecure AssetCreated .EXAMPLE Find-SafeguardEvent -QueryFilter -Fields #> function Find-SafeguardEvent { [CmdletBinding(DefaultParameterSetName="Search")] Param( [Parameter(Mandatory=$false)] [string]$Appliance, [Parameter(Mandatory=$false)] [object]$AccessToken, [Parameter(Mandatory=$false)] [switch]$Insecure, [Parameter(Mandatory=$true,Position=0,ParameterSetName="Search")] [string]$SearchString, [Parameter(Mandatory=$true,Position=0,ParameterSetName="Query")] [string]$QueryFilter, [Parameter(Mandatory=$false)] [string[]]$Fields ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } if ($PSCmdlet.ParameterSetName -eq "Search") { $local:Parameters = @{ q = $SearchString } if ($Fields) { $local:Parameters["fields"] = ($Fields -join ",") } Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core GET Events ` -Parameters $local:Parameters } else { $local:Parameters = @{ filter = $QueryFilter } if ($Fields) { $local:Parameters["fields"] = ($Fields -join ",") } Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core GET Events ` -Parameters $local:Parameters } } <# .SYNOPSIS Get event subscription in Safeguard via the Web API. .DESCRIPTION Event subscription is a subscription to receive notifications when an event occurs. Event subscription can be created for all type of users but can only be created by an administrative user. One event subscriber can subscribe to multiple events. .PARAMETER Appliance IP address or hostname of a Safeguard appliance. .PARAMETER AccessToken A string containing the bearer token to be used with Safeguard Web API. .PARAMETER Insecure Ignore verification of Safeguard appliance SSL certificate. .PARAMETER SubscriptionId An integer containing ID of the event subscription to get. .PARAMETER ShowSystemOwned Whether to show system owned subscriptions or not (Default: false) .INPUTS None. .OUTPUTS JSON response from Safeguard Web API. .EXAMPLE Get-SafeguardEventSubscription -AccessToken $token -Appliance 10.5.32.54 -Insecure .EXAMPLE Get-SafeguardEventSubscription 123 #> function Get-SafeguardEventSubscription { [CmdletBinding()] Param( [Parameter(Mandatory=$false)] [string]$Appliance, [Parameter(Mandatory=$false)] [object]$AccessToken, [Parameter(Mandatory=$false)] [switch]$Insecure, [Parameter(Mandatory=$false, Position=0)] [string]$SubscriptionId, [Parameter(Mandatory=$false)] [switch]$ShowSystemOwned ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } if ($PSBoundParameters.ContainsKey("SubscriptionId")) { Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core GET "EventSubscribers/$SubscriptionId" } else { if ($ShowSystemOwned) { Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core GET EventSubscribers } else { Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core GET EventSubscribers ` -Parameters @{ filter = "IsSystemOwned eq false" } } } } <# .SYNOPSIS Search for an event subscription in Safeguard via the Web API. .DESCRIPTION Search for an event subscription in Safeguard for any string fields containing the SearchString. .PARAMETER Appliance IP address or hostname of a Safeguard appliance. .PARAMETER AccessToken A string containing the bearer token to be used with Safeguard Web API. .PARAMETER Insecure Ignore verification of Safeguard appliance SSL certificate. .PARAMETER SearchString A string to search for in the event subscription. .PARAMETER QueryFilter A string to pass to the -filter query parameter in the Safeguard Web API. .PARAMETER Fields An array of the event property names to return. .INPUTS None. .OUTPUTS JSON response from Safeguard Web API. .EXAMPLE Find-SafeguardEventSubscription -AccessToken $token -Appliance 10.5.32.54 -Insecure .EXAMPLE Find-SafeguardEventSubscription "test" .EXAMPLE Find-SafeguardEventSubscription -QueryFilter "PartitionOwnerIsSubscribed eq True" -Fields Id,Type,Description .EXAMPLE Find-SafeguardEventSubscription -QueryFilter "AdminRoles contains 'ApplianceAdmin'" -Fields Id,Type,Description #> function Find-SafeguardEventSubscription { [CmdletBinding(DefaultParameterSetName="Search")] Param( [Parameter(Mandatory=$false)] [string]$Appliance, [Parameter(Mandatory=$false)] [object]$AccessToken, [Parameter(Mandatory=$false)] [switch]$Insecure, [Parameter(Mandatory=$true,Position=0,ParameterSetName="Search")] [string]$SearchString, [Parameter(Mandatory=$true,Position=0,ParameterSetName="Query")] [string]$QueryFilter, [Parameter(Mandatory=$false)] [string[]]$Fields ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } if ($PSCmdlet.ParameterSetName -eq "Search") { $local:Parameters = @{ q = $SearchString } if ($Fields) { $local:Parameters["fields"] = ($Fields -join ",") } Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core GET EventSubscribers ` -Parameters $local:Parameters } else { $local:Parameters = @{ filter = $QueryFilter } if ($Fields) { $local:Parameters["fields"] = ($Fields -join ",") } Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core GET EventSubscribers ` -Parameters $local:Parameters } } <# .SYNOPSIS Create a new event subscription in Safeguard via the Web API. .DESCRIPTION An event subscription is a configuration to receive notifications via a subscriber mechanism when an event occurs. The subscriber mechanisms are Email, Snmp, Signalr, and Syslog. Snmp and Syslog subscriptions will send notifications using those protocols. Email subscriptions can be created for all types of users but can only be created by an administrative user. Email subscriptions can be for a user or an email address. Use an email address to send notifications to a distribution group. SignalR mechanisms only support a user. The user must connect to SignalR to receive notifications. For certain subscriptions, you may specify an object type to subscribe, e.g. Asset or AssetAccount, and an object ID to only receive SignalR or Email notifications for that particular object. .PARAMETER Appliance IP address or hostname of a Safeguard appliance. .PARAMETER AccessToken A string containing the bearer token to be used with Safeguard Web API. .PARAMETER Insecure Ignore verification of Safeguard appliance SSL certificate. .PARAMETER ObjectTypeToSubscribe A string containing the type of object to be subscribed. .PARAMETER ObjectIdToSubscribe A string containing the Id or name of the object to be subscribed. .PARAMETER SubscriptionEvent Array of name of events to be subscribed. .PARAMETER UserToSubscribe A string containing the name or Id of the user to be subscribed to events in Safeguard. .PARAMETER Description A string containing the description of the event subscription. .PARAMETER IsEmailEvent A switch to specify if the type of subscription to create is Email subscription. Default subscription type is SignalR. .PARAMETER EmailAddress A string containing the email address if the user to be subscribed. If the type of subscription is Email subscription. Either an email address or UserId is to be provided. .PARAMETER IsSnmpEvent A switch to specify if the type of subscription to create is SNMP subscription. Default subscription type is SignalR. .PARAMETER SnmpNetworkAddress A string containing network address of the SNMP server. This parameter is mandatory if -IsSnmpEvent parameter is switched ON. .PARAMETER SnmpPort An integer containing port of the SNMP server. The default port is 162. .PARAMETER SnmpCommunity A string containing the Community name of the SNMP server. THe default name of the SNMP community is "public" .PARAMETER SnmpVersion An integer containing the version of SNMP protocol. The default version is 2. .PARAMETER IsSyslogEvent A switch to specify if the type of subscription to create is Syslog subscription. Default subscription type is SignalR. .PARAMETER SyslogNetworkAddress A string containing network address of the Syslog server. This parameter is mandatory if -IsSyslogEvent parameter is switched ON. .PARAMETER SyslogPort An integer containing port of the Syslog server. The default port is 514. .PARAMETER SyslogFacility A string containing the Facility name of the Syslog server. THe default name of the Syslog Facility is "User" .INPUTS None. .OUTPUTS JSON response from Safeguard Web API. .EXAMPLE New-SafeguardEventSubscription -IsEmailEvent -EmailAddress "login-notification@work.domain" -SubscriptionEvent (Get-SafeguardEventName -Category UserAuthentication) .EXAMPLE New-SafeguardEventSubscription -ObjectTypeToSubscribe AssetAccount -ObjectIdToSubscribe 123 -SubscriptionEvent PasswordChangeFailed .EXAMPLE New-SafeguardEventSubscription -ObjectTypeToSubscribe AssetAccount -ObjectIdToSubscribe 1 -SubscriptionEvent PasswordChangeFailed -UserToSubscribe dan@petrsnd.org .EXAMPLE New-SafeguardEventSubscription -IsSyslogEvent -SyslogNetworkAddress "11.22.33.44" -SubscriptionEvent AssetAccountCreated #> function New-SafeguardEventSubscription { [CmdletBinding(DefaultParametersetName='Default')] Param( [Parameter(Mandatory=$false)] [string]$Appliance, [Parameter(Mandatory=$false)] [object]$AccessToken, [Parameter(Mandatory=$false)] [switch]$Insecure, [Parameter(Mandatory=$false, Position=0)] [ValidateSet('Asset','AssetAccount',IgnoreCase=$true)] [string]$ObjectTypeToSubscribe, [Parameter(Mandatory=$false, Position=1)] [string]$ObjectIdToSubscribe, [Parameter(Mandatory=$false, Position=2)] [string[]]$SubscriptionEvent, [Parameter(Mandatory=$false)] [object]$UserToSubscribe, [Parameter(Mandatory=$false)] [string]$Description, [Parameter(Mandatory=$false)] [switch]$IsSignalrEvent, [Parameter(ParameterSetName='EmailEvent')][switch]$IsEmailEvent, [Parameter(ParameterSetName='EmailEvent', Mandatory=$false)][string]$EmailAddress, [Parameter(ParameterSetName='SnmpEvent')][switch]$IsSnmpEvent, [Parameter(ParameterSetName='SnmpEvent', Mandatory=$true)][string]$SnmpNetworkAddress, [Parameter(ParameterSetName='SnmpEvent', Mandatory=$false)][Int]$SnmpPort, [Parameter(ParameterSetName='SnmpEvent', Mandatory=$false)][string]$SnmpCommunity, [Parameter(ParameterSetName='SnmpEvent', Mandatory=$false)][Int]$SnmpVersion, [Parameter(ParameterSetName='SyslogEvent')][switch]$IsSyslogEvent, [Parameter(ParameterSetName='SyslogEvent', Mandatory=$true)][string]$SyslogNetworkAddress, [Parameter(ParameterSetName='SyslogEvent', Mandatory=$false)][Int]$SyslogPort, [ValidateSet('Kernel', 'User', 'Mail', 'Daemons', 'Authorization', 'Syslog', 'Printer', 'News', 'Uucp', 'Clock', 'Authorization2', 'Ftp', 'Ntp', 'Audit','Alert', 'Clock2', 'Local0', 'Local1', 'Local2', 'Local3', 'Local4', 'Local5', 'Local6', 'Local7', IgnoreCase=$true)] [Parameter(ParameterSetName='SyslogEvent', Mandatory=$false)][object]$SyslogFacility ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } #Resolve events to be subscribed [object[]]$SubscriptionEvents = (Resolve-SubscriptionEvent -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure ` -TypeOfEvent $ObjectTypeToSubscribe -EventsToValidate $SubscriptionEvent) #Resolve the object to be subscribed switch ($ObjectTypeToSubscribe) { "Asset"{ $ObjectIdToSubscribe = (Get-SafeguardAsset -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure -AssetToGet $ObjectIdToSubscribe).Id; break } "AssetAccount"{ $ObjectIdToSubscribe = (Get-SafeguardAssetAccount -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure -AccountToGet $ObjectIdToSubscribe).Id; break } } #Initialize the body of the API call. Default type of subscription is set as SignalR $local:Body = @{ Type = "SignalR"; ObjectType = $ObjectTypeToSubscribe; ObjectId = $ObjectIdToSubscribe; Subscriptions = $SubscriptionEvents } #Common parameters if ($PSBoundParameters.ContainsKey("UserToSubscribe")) { $local:User = (Get-SafeguardUser -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure -UserToGet $UserToSubscribe) $local:Body.UserId = $($local:User).Id } if ($PSBoundParameters.ContainsKey("Description")) {$local:Body.Description = $Description} if ($PSBoundParameters.ContainsKey("EmailAddress")) {$local:Body.EmailAddress = $EmailAddress} #If the type of subscription is SNMP if ($PSBoundParameters.ContainsKey("IsSnmpEvent")) {$local:Body.Type = "SNMP"} #SNMP properties if ($PSBoundParameters.ContainsKey("SnmpNetworkAddress")) {$local:Body.SnmpNetworkAddress = $SnmpNetworkAddress} if ($PSBoundParameters.ContainsKey("SnmpPort")) {$local:Body.SnmpPort = $SnmpPort} if ($PSBoundParameters.ContainsKey("SnmpCommunity")) {$local:Body.SnmpCommunity = $SnmpCommunity} if ($PSBoundParameters.ContainsKey("SnmpVersion")) {$local:Body.SnmpVersion = $SnmpVersion} #If the type of subscription is Syslog if ($PSBoundParameters.ContainsKey("IsSyslogEvent")) {$local:Body.Type = "Syslog"} #Syslog Properties $local:SyslogProperties = @{ NetworkAddress = $null } if ($PSBoundParameters.ContainsKey("SyslogNetworkAddress")) {$local:SyslogProperties.NetworkAddress = $SyslogNetworkAddress} if ($PSBoundParameters.ContainsKey("SyslogPort")) {$local:SyslogProperties.Port = $SyslogPort} if ($PSBoundParameters.ContainsKey("SyslogFacility")) {$local:SyslogProperties.Facility = $SyslogFacility} $local:Body.SyslogProperties = $local:SyslogProperties #If the type of subscription is Email if ($PSBoundParameters.ContainsKey("IsEmailEvent")) { $local:Body.Type = "Email" if ($PSBoundParameters.ContainsKey("UserToSubscribe")) { If([string]::IsNullOrWhitespace($local:User.EmailAddress)) { Write-Error -Message "An email address or a user with an email address must be specified." -Category InvalidArgument -ErrorAction Stop } } if($PSBoundParameters.ContainsKey("UserToSubscribe") -and $PSBoundParameters.ContainsKey("EmailAddress")) { Write-Error -Message "You cannot specify both the UserID and an EmailAddress properties simultaneously." -Category InvalidArgument -ErrorAction Stop } } Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core POST EventSubscribers -Body $local:Body } <# .SYNOPSIS Update an existing event subscription in Safeguard via the Web API. .DESCRIPTION An event subscription is a configuration to receive notifications via a subscriber mechanism when an event occurs. The subscriber mechanisms are Email, Snmp, Signalr, and Syslog. Snmp and Syslog subscriptions will send notifications using those protocols. Email subscriptions can be created for all types of users but can only be created by an administrative user. Email subscriptions can be for a user or an email address. Use an email address to send notifications to a distribution group. SignalR mechanisms only support a user. The user must connect to SignalR to receive notifications. For certain subscriptions, you may specify an object type to subscribe, e.g. Asset or AssetAccount, and an object ID to only receive SignalR or Email notifications for that particular object. .PARAMETER Appliance IP address or hostname of a Safeguard appliance. .PARAMETER AccessToken A string containing the bearer token to be used with Safeguard Web API. .PARAMETER Insecure Ignore verification of Safeguard appliance SSL certificate. .PARAMETER SubscriptonId An integer containg the ID of an event subscription to be updated. .PARAMETER SubscriptionObject An object containing the existing event subscription with desired properties set. .PARAMETER ObjectTypeToSubscribe A string containing the type of object to be subscribed. .PARAMETER ObjectIdToSubscribe A string containing the Id or name of the object to be subscribed. .PARAMETER SubscriptionEvent Array of name of events to be subscribed. .PARAMETER UserToSubscribe A string containing the name or Id of the user to be subscribed to events in Safeguard. .PARAMETER Description A string containing the description of the event subscription. .PARAMETER IsSignalrEvent A switch to update the type of subscription to Signal. .PARAMETER IsEmailEvent A switch to update the type of subscription to Email. .PARAMETER EmailAddress A string containing the email address if the user to be subscribed. If the type of subscription is Email subscription. Either an email address or UserId is to be provided. .PARAMETER IsSnmpEvent A switch to update the type of subscription to SNMP. .PARAMETER SnmpNetworkAddress A string containing network address of the SNMP server. This parameter is mandatory if -IsSnmpEvent parameter is switched ON. .PARAMETER SnmpPort An integer containing port of the SNMP server. The default port is 162. .PARAMETER SnmpCommunity A string containing the Community name of the SNMP server. THe default name of the SNMP community is "public" .PARAMETER SnmpVersion An integer containing the version of SNMP protocol. The default version is 2. .PARAMETER IsSyslogEvent A switch to update the type of subscription to Syslog. .PARAMETER SyslogNetworkAddress A string containing network address of the Syslog server. This parameter is mandatory if -IsSyslogEvent parameter is switched ON. .PARAMETER SyslogPort An integer containing port of the Syslog server. The default port is 514. .PARAMETER SyslogFacility A string containing the Facility name of the Syslog server. THe default name of the Syslog Facility is "User" .INPUTS None. .OUTPUTS JSON response from Safeguard Web API. .EXAMPLE Edit-SafeguardEventSubscription -SubscriptionObject $obj .EXAMPLE Edit-SafeguardEventSubscription -SubscriptionId 123 -IsEmailEvent -EmailAddress "name@company.com" #> function Edit-SafeguardEventSubscription { [CmdletBinding(DefaultParametersetName='Default')] Param( [Parameter(Mandatory=$false)] [string]$Appliance, [Parameter(Mandatory=$false)] [object]$AccessToken, [Parameter(Mandatory=$false)] [switch]$Insecure, [Parameter(Mandatory=$false, Position=0)] [Int]$SubscriptionId, [Parameter(Mandatory=$false, Position=1)] [ValidateSet('Asset','AssetAccount',IgnoreCase=$true)] [string]$ObjectTypeToSubscribe, [Parameter(Mandatory=$false, Position=2)] [string]$ObjectIdToSubscribe, [Parameter(Mandatory=$false, Position=3)] [object[]]$SubscriptionEvent, [Parameter(Mandatory=$false)] [object]$UserToSubscribe, [Parameter(Mandatory=$false)] [string]$Description, [Parameter(Mandatory=$false)] [switch]$IsSignalrEvent, [Parameter(ParameterSetName='Object', Mandatory=$false)] [object]$SubscriptionObject, [Parameter(ParameterSetName='EmailEvent')][switch]$IsEmailEvent, [Parameter(ParameterSetName='EmailEvent', Mandatory=$false)][string]$EmailAddress, [Parameter(ParameterSetName='SnmpEvent')][switch]$IsSnmpEvent, [Parameter(ParameterSetName='SnmpEvent', Mandatory=$true)][string]$SnmpNetworkAddress, [Parameter(ParameterSetName='SnmpEvent', Mandatory=$false)][Int]$SnmpPort, [Parameter(ParameterSetName='SnmpEvent', Mandatory=$false)][string]$SnmpCommunity, [Parameter(ParameterSetName='SnmpEvent', Mandatory=$false)][Int]$SnmpVersion, [Parameter(ParameterSetName='SyslogEvent')][switch]$IsSyslogEvent, [Parameter(ParameterSetName='SyslogEvent', Mandatory=$true)][string]$SyslogNetworkAddress, [Parameter(ParameterSetName='SyslogEvent', Mandatory=$false)][Int]$SyslogPort, [ValidateSet('Kernel', 'User', 'Mail', 'Daemons', 'Authorization', 'Syslog', 'Printer', 'News', 'Uucp', 'Clock', 'Authorization2', 'Ftp', 'Ntp', 'Audit','Alert', 'Clock2', 'Local0', 'Local1', 'Local2', 'Local3', 'Local4', 'Local5', 'Local6', 'Local7', IgnoreCase=$true)] [Parameter(ParameterSetName='SyslogEvent', Mandatory=$false)][object]$SyslogFacility ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } if ($PSBoundParameters.ContainsKey("SubscriptionObject")) { #Resolve events contained in the SubscriptionObject ForEach($IndividualEvent in $SubscriptionObject.Subscriptions) { [string[]]$local:Events += $IndividualEvent.Name } [object[]]$SubscriptionEvents = (Resolve-SubscriptionEvent -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure ` -TypeOfEvent $SubscriptionObject.ObjectType -EventsToValidate $Events) $SubscriptionObject.Subscriptions = $SubscriptionEvents Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core PUT "EventSubscribers/$($SubscriptionObject.Id)" -Body $SubscriptionObject return } if (-not $PSBoundParameters.ContainsKey("SubscriptionId")) { $SubscriptionId = (Read-Host "SubscriptionId") } $local:Body = (Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core GET "EventSubscribers/$SubscriptionId") if ($PSBoundParameters.ContainsKey("ObjectTypeToSubscribe")) {$local:Body.ObjectType = $ObjectTypeToSubscribe} #Resolve events to be subscribed if ($PSBoundParameters.ContainsKey("SubscriptionEvent")) { [object[]]$SubscriptionEvents = (Resolve-SubscriptionEvent -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure ` -TypeOfEvent $local:Body.ObjectType -EventsToValidate $SubscriptionEvent) } else { ForEach($IndividualEvent in $local:Body.Subscriptions) { [string[]]$local:Events += $IndividualEvent.Name } [object[]]$SubscriptionEvents = (Resolve-SubscriptionEvent -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure ` -TypeOfEvent $local:Body.ObjectType -EventsToValidate $Events) } $local:Body.Subscriptions = $SubscriptionEvents #Resolve the object to be subscribed if ($PSBoundParameters.ContainsKey("ObjectIdToSubscribe")) { switch ($local:Body.ObjectType) { "Asset"{ $ObjectIdToSubscribe = (Get-SafeguardAsset -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure -AssetToGet $ObjectIdToSubscribe).Id; break } "AssetAccount"{ $ObjectIdToSubscribe = (Get-SafeguardAssetAccount -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure -AccountToGet $ObjectIdToSubscribe).Id; break } } } if ($PSBoundParameters.ContainsKey("IsSignalrEvent")) {$local:Body.Type = "SignalR"} #Common parameters if ($PSBoundParameters.ContainsKey("UserToSubscribe")) { $local:User = Get-SafeguardUser -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure -UserToGet $UserToSubscribe $local:Body.UserId = $($local:User).Id } if ($PSBoundParameters.ContainsKey("Description")) {$local:Body.Description = $Description} if ($PSBoundParameters.ContainsKey("EmailAddress")) {$local:Body.EmailAddress = $EmailAddress} #If the type of subscription is SNMP if ($PSBoundParameters.ContainsKey("IsSnmpEvent")) {$local:Body.Type = "SNMP"} #SNMP properties if ($PSBoundParameters.ContainsKey("SnmpNetworkAddress")) {$local:Body.SnmpNetworkAddress = $SnmpNetworkAddress} if ($PSBoundParameters.ContainsKey("SnmpPort")) {$local:Body.SnmpPort = $SnmpPort} if ($PSBoundParameters.ContainsKey("SnmpCommunity")) {$local:Body.SnmpCommunity = $SnmpCommunity} if ($PSBoundParameters.ContainsKey("SnmpVersion")) {$local:Body.SnmpVersion = $SnmpVersion} #If the type of subscription is Syslog if ($PSBoundParameters.ContainsKey("IsSyslogEvent")) {$local:Body.Type = "Syslog"} #Syslog Properties $local:SyslogProperties = @{ NetworkAddress = $null } if ($PSBoundParameters.ContainsKey("SyslogNetworkAddress")) {$local:SyslogProperties.NetworkAddress = $SyslogNetworkAddress} if ($PSBoundParameters.ContainsKey("SyslogPort")) {$local:SyslogProperties.Port = $SyslogPort} if ($PSBoundParameters.ContainsKey("SyslogFacility")) {$local:SyslogProperties.Facility = $SyslogFacility} $local:Body.SyslogProperties = $local:SyslogProperties #If the type of subscription is Email if ($PSBoundParameters.ContainsKey("IsEmailEvent")) { $local:Body.Type = "Email" if($PSBoundParameters.ContainsKey("EmailAddress") -and (-Not $PSBoundParameters.ContainsKey("UserToSubscribe"))) { $local:Body.UserId = $null } if ($local:Body.UserId -ne $null) { $local:UserEmailAddress = (Get-SafeguardUser -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure -UserToGet $local:Body.UserId).EmailAddress If([string]::IsNullOrWhitespace($local:UserEmailAddress)) { Write-Error -Message "An email address or a user with an email address must be specified." -Category InvalidArgument -ErrorAction Stop } } if(($local:Body.UserId -ne $null) -and $PSBoundParameters.ContainsKey("EmailAddress")) { Write-Error -Message "You cannot specify both the UserID and an EmailAddress properties simultaneously." -Category InvalidArgument -ErrorAction Stop } } Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core PUT "EventSubscribers/$($local:Body.Id)" -Body $local:Body } <# .SYNOPSIS Remove an event subscription in Safeguard via the Web API. .DESCRIPTION An event subscription is a configuration to receive notifications via a subscriber mechanism when an event occurs. The subscriber mechanisms are Email, Snmp, Signalr, and Syslog. Snmp and Syslog subscriptions will send notifications using those protocols. Email subscriptions can be created for all types of users but can only be created by an administrative user. Email subscriptions can be for a user or an email address. Use an email address to send notifications to a distribution group. SignalR mechanisms only support a user. The user must connect to SignalR to receive notifications. For certain subscriptions, you may specify an object type to subscribe, e.g. Asset or AssetAccount, and an object ID to only receive SignalR or Email notifications for that particular object. .PARAMETER Appliance IP address or hostname of a Safeguard appliance. .PARAMETER AccessToken A string containing the bearer token to be used with Safeguard Web API. .PARAMETER Insecure Ignore verification of Safeguard appliance SSL certificate. .PARAMETER SubscriptionId An integer containing ID of the event subscription to get. .INPUTS None. .OUTPUTS JSON response from Safeguard Web API. .EXAMPLE Remove-SafeguardEventSubscription 123 #> function Remove-SafeguardEventSubscription { [CmdletBinding()] Param( [Parameter(Mandatory=$false)] [string]$Appliance, [Parameter(Mandatory=$false)] [object]$AccessToken, [Parameter(Mandatory=$false)] [switch]$Insecure, [Parameter(Mandatory=$true, Position=0)] [string]$SubscriptionId ) if (-not $PSBoundParameters.ContainsKey("ErrorAction")) { $ErrorActionPreference = "Stop" } if (-not $PSBoundParameters.ContainsKey("Verbose")) { $VerbosePreference = $PSCmdlet.GetVariableValue("VerbosePreference") } Invoke-SafeguardMethod -AccessToken $AccessToken -Appliance $Appliance -Insecure:$Insecure Core DELETE "EventSubscribers/$SubscriptionId" } |