4. More Examples

This is a list of examples to get you started on how to leverage the MCAS Powershell module to the fullest.

Note: Most of these examples assume you have a credential loaded in the session.

Example: Finding the available MCAS cmdlets

We can create a table for the module and look at the ExportedCommands property.

$a = @(Get-Module -Name MCAS); $a.ExportedCommands.Keys

Example: Creating a reusable credential file

We use the -PassThru switch to pipe the credential to Export-CliXml and specify a full path with filename.credential

Get-MCASCredential -PassThru | Export-CliXml $home\MyCASDemoCred.credential -Force

We can then append our PS Profile to auto-import our credentials at the start of the session. Needs to be stored in:

$CASCredential
$CASCredential = Import-Clixml "$home\MyCASDemoCred.credential"

Example: Creating a hash table to store a file object

First, we will take a look at a single file.

Get-MCASFile -Identity 573e0d91669abb4caf445d82

We see a property called 'boxItem' that contains a lot of info. Let's instantiate this as a hash table.

$b = @(Get-MCASFile -Identity 573e0d91669abb4caf445d8)

Now we can look at the boxItem properties easily.

$b.boxItem

And we can even dig deeper to see information about the File Owner and login.

$b.boxItem.owned_by
$b.boxItem.owned_by.login

Example: Pulling back nested properties without variablizing

Instead of storing in a variable, we wrap in parentheses.

(Get-MCASFile -ResultSetSize 1).boxItem.owned_by.login

Example: Formatting columns

Here we pull back 10 alert records and display only a few parameters in a table.

Get-MCASAlert -ResultSetSize 10 | select status, resolutionStatus, Identity, date | 
Format-Table

What if we want to edit the format a bit for date. We can customize the date parameter by specifying a new property name and expression where we split the date on T and select only the first part of the split. This shows us just the date. (N=Name; E=Expression)

Get-MCASAlert -ResultSetSize 10 | select status, resolutionStatus, Identity, `
@{N="Date"; E={($_.date -split 'T')[0]}} | Format-Table

Example: Getting a list of violators for a particular policy

We grab the last 100 alerts with a General Anomlay Detection violation

$violators = (Get-MCASAlert -ResultSetSize 100 -SortBy Date -SortDirection Descending) | 
where {$_.entities.label -eq 'General anomaly detection'}

We can now extract the usernames of these violators.

$violators = ($violators.entities | where {$_.type -eq 'user'} | select id -Unique)

Now we can use this list to punish the violators!

$violators

Example: Integrating with on-prem Active Directory for remediation

We can disable any AD accounts of users associated to high severity alerts (requires ActiveDirectory module for Powershell)

(Get-MCASAlert -Credential $cred -Severity High).entities | Where-Object {$_.type -eq 'user'} | 
select id -Unique | ForEach-Object {Disable-ADAccount -Identity $_.id}

Example: Setting alert status for multiple alerts

First, we will pull a list of alerts that are 'read'. We will see nothing.

Get-MCASAlert -Read | select Identity

Next, we will pull the last 5 unread alerts and see that we received 5.

Get-MCASAlert -ResultSetSize 5 -Unread -SortBy Date -SortDirection Descending | select Identity

We will now pipe those unread alerts into Set-MCASAlert and mark them as read.

Get-MCASAlert -ResultSetSize 5 -Unread -SortBy Date -SortDirection Descending | Set-MCASAlert -MarkAs Read

To verify, we can run the original command and see that we now have 5 read alerts.

Get-MCASAlert -Read | select Identity

We can migrate these back to unread just as easily.

Get-MCASAlert -Read | Set-MCASAlert -MarkAs Unread

And again to verify, we now see we are back to 0 read alerts.

Get-MCASAlert -Read

Example: Upload single log file

We will use Send-MCASDiscoveryLog to upload a single log.

Send-MCASDiscoveryLog -LogFile "C:\logs\file.log" -LogType `
CISCO_IRONPORT_PROXY -DiscoveryDataSource MYDATASOURCENAME -Verbose

Example: Upload multiple log files

We do a Get-ChildItem (dir) to get a path to a folder with many logs. Select just the items ending in .log. For each log item, we pass it to Send-MCASDiscoveryLog.

Get-ChildItem -Path "C:\logs" | 
Where-Object{$_.name -match '\.log'} |
ForEach-Object {Send-MCASDiscoveryLog -LogFile $_.FullName -LogType CISCO_IRONPORT_PROXY -DiscoveryDataSource MYDATASOURCENAME -Verbose}

Example: Get all activities for files that violate a specific policy

This is more advanced Powershell, so it is complex, but also very powerful. Once we have a policy id number for a specific policy (which can be found in the URL when viewing the policy in the MCAS web console), which is '676a280df4709649d395f92c' in this example, we can see all activities related to files that are in violation of that policy.

 ((((Get-MCASAlert -Policy 5786981acb60c65dfc0fb4b6).entities | 
 Where-Object {($_.type -eq 'file')}).label) | Select -Unique | 
 ForEach {Get-MCASFile -Name $_}).name | Where-Object {$_ -ne $null} |  
 ForEach {Get-MCASActivity -Text $_} | 
 Select appName,description,user