feature/233: Added User-specific audit for mailitems accessed

[juliusperez1695]

Pull Request Template

Description

Created new function Get-HawkMailItemsAccessed to be call during user-specific investigations. When calling this function, the user is able to utilize the $UserIDs parameter to either obtain an audit for a single user or multiple users. This function was also added to the Start-HawkUserInvestigation function.

Fixes # (issue)

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration

• Test A
• Test B
• Individually tested Get-HawkMailItemsAccessed and confirmed expected output

Checklist:

• My code follows the style guidelines of Hawk
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules
• I have checked my code and corrected any misspellings

[jonnybottles]

Hey @juliuis, I just reviewed your changes and have some feedback:

1. Re-name function
   This is my bad when I assigned you the ticket, but all user investigation functions should start with: "Get-HawkUser*"
   So you will need to re-name this function to "Get-HawkUserMailItemsAccessed" as well as its associated file
2. Publicly export function
   Whenever creating a Tenant or User function (but not internal functions), the expectation is that the user can run it via it's respective investigation type by running "Start-HawkTenantInvestigation" or "Start-HawkUserInvestigation", but also they should be able to run it as a standalone function. For a user to run it as a standalone function once hawk is imported, you have to make that function public by adding it to the Functons to export list in Hawk.psd1
3. Changelog Update:
   I have never mentioned this to you before, so no biggy here, but after your ticket is complete and ready to merge, you will need to update the changelog.md file with high level changes. Don't put eveyr single granular chnage in the log, just the big changes that a user would care about.
4. $UserIDs paramater
   To keep consistency with all of our "User" functions, pleae change your [string[]]$UserIDs parameter to [array]$UserPrincipalName. All other user functions use [array]$UserPrincipalNam as their paramter
5. Test-EXOConnection
   When I ran Get-HawkUserAdminAudit by itself and not in start-HawkUserInvestigation, it failed. Reason for this is in every Hawk User function that calls out to exchange online and or calls Search-Unified Audit log, you need to first add "Test-EXOConneciton" to the beginning of that function. This tests to make sure your connected to exchagne online, if not it prompts you to connect.
6. Files written to incorrect folder
   You wrote your logs to the tenant folder, which is the incorrect location. This is a user function and should be written to an appropraite user folder, to do so pass the -User parameter to the Out-MultipleFileType function
7. File names require user name appended
   All user logs written to disk should be written to disk and appended with users name, for excample: "InboxRules_navarropj.json".
8. Implement Get-SimpleUnifiedAuditLog
   Since we are parsing the UAL, you will also need to pass your results from the call to Get-AllUnifiedAuditLog entry into Get-SimpleUnifiedAuditLog, this function will flatten the nested array that is the audit log into a more simplistic few. Using this function you will need to write two additonal files to disk:

• Simple_MailItemsAccessed[USER_NAME].json
• Simple_MailItemsAccessed[USER_NAME].json

9. Error Handling
   Wrap your calls yo GetAllUnifiedAuditLog, Out-MultipleFileType and also Get-SimpleUnifiedAuditLog (once implemented) all inside try catch blocks to identify and inform the user of any errors.
   Lastly, to help you I recommend taking a look at Get-HawkUserAdminAuditLog, Get-HawkTenantAdminInboxRuleCreation and any other functions that call Get-SimpleUnifiedAudit log for examples and ideas for your ticket. If you have any questions feel free to hit me up any time as usual! Also, I didnt get a chance to view the actual log output, once you implement the changes above and you submit for your next merge request, ill take a look at the output.