Functions/Set-MCASAlert.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
<#
.Synopsis
   Sets the status of alerts in Cloud App Security.
 
.DESCRIPTION
   Sets the status of alerts in Cloud App Security and requires a credential be provided.
 
   There are two parameter sets:
 
   MarkAs: Used for marking an alert as 'Read' or 'Unread'.
   Dismiss: Used for marking an alert as 'Dismissed'.
 
   An alert identity is always required to be specified either explicity or implicitly from the pipeline.
 
.EXAMPLE
    PS C:\> Set-MCASAlert -Identity cac1d0ec5734e596e6d785cc -MarkAs Read
 
    This marks a single specified alert as 'Read'.
 
.EXAMPLE
    PS C:\> Set-MCASAlert -Identity cac1d0ec5734e596e6d785cc -Dismiss
 
    This will set the status of the specified alert as "Dismissed".
 
.FUNCTIONALITY
   Set-MCASAlert is intended to function as a mechanism for setting the status of alerts Cloud App Security.
#>

function Set-MCASAlert {
    [CmdletBinding()]
    param
    (
        # Fetches an alert object by its unique identifier.
        [Parameter(ParameterSetName='Fetch', Mandatory=$true, ValueFromPipeline=$true, ValueFromPipelineByPropertyName=$true, Position=0)]
        [ValidateNotNullOrEmpty()]
        [ValidatePattern({^[A-Fa-f0-9]{24}$})]
        [Alias("_id")]
        [string]$Identity,

        # Specifies the credential object containing tenant as username (e.g. 'contoso.us.portal.cloudappsecurity.com') and the 64-character hexadecimal Oauth token as the password.
        [Parameter(Mandatory=$false)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.PSCredential]$Credential = $CASCredential,

        # Specifies how to mark the alert. Possible Values: 'Read', 'Unread'.
        [Parameter(Mandatory=$false)]
        [ValidateSet('Read','Unread')]
        [string]$MarkAs,

        # Specifies that the alert should be dismissed.
        [Parameter(Mandatory=$false)]
        [switch]$Dismiss,

        [Parameter(Mandatory=$false)]
        [Switch]$Quiet
    )
    process
    {
        if (!($MarkAs -or $Dismiss)) {
            throw "You must specify one or both of the -MarkAs and -Dismiss parameters"
        }

        if ($Dismiss) {
            $Action = 'dismiss'
            try {
                # Set the alert's state by its id
                $response = Invoke-MCASRestMethod -Credential $Credential -Path "/api/v1/alerts/$Identity/$Action/" -Method Post
            }
            catch {
                throw "Error calling MCAS API. The exception was: $_"
            }
        }
        if ($MarkAs)  {
            $Action = $MarkAs.ToLower() # Convert -MarkAs to lower case, as expected by the CAS API
            try {
                # Set the alert's state by its id
                $response = Invoke-MCASRestMethod -Credential $Credential -Path "/api/v1/alerts/$Identity/$Action/" -Method Post
            }
            catch {
                throw "Error calling MCAS API. The exception was: $_"
            }
        }

        if (!$Quiet) {
            $Success
        }
    }
}