Merge pull request #139 from CriticalSolutionsNetwork/138-add-hash-computation-to-file-output-of-export-function-and-compress-into-archive

138 add hash computation to file output of export function and compress into archive

CHANGELOG.md

@@ -4,6 +4,12 @@ The format is based on and uses the types of changes according to [Keep a Change
 
 ## [Unreleased]
 
+### Added
+
+- Added hash and compress steps to `Export-M365SecurityAuditTable` function.
+
+## [0.1.21] - 2024-07-01
+
 ### Fixed
 
 - Formatting for MgGraph tests.

help/Export-M365SecurityAuditTable.md

@@ -190,10 +190,11 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## INPUTS
 
-### [CISAuditResult[]], [string]
+### [CISAuditResult[]] - An array of CISAuditResult objects.
+### [string] - A path to a CSV file.
 ## OUTPUTS
 
-### [PSCustomObject]
+### [PSCustomObject] - A custom object containing the path to the zip file and its hash.
 ## NOTES
 
 ## RELATED LINKS

helpers/Build-Help.ps1

@@ -4,7 +4,7 @@ Import-Module .\output\module\M365FoundationsCISReport\*\*.psd1
 
 
 <#
-    $ver = "v0.1.18"
+    $ver = "v0.1.22"
     git checkout main
     git pull origin main
     git tag -a $ver -m "Release version $ver refactor Update"
@@ -59,6 +59,5 @@ Set-Secret -Name "GitHubToken" -Vault ModuleBuildCreds
 $GalleryApiToken = Get-Secret -Name "GalleryApiToken" -Vault ModuleBuildCreds -AsPlainText
 $GitHubToken = Get-Secret -Name "GitHubToken" -Vault ModuleBuildCreds -AsPlainText
 
-
 $GalleryApiToken
 $GitHubToken

source/Public/Export-M365SecurityAuditTable.ps1

@@ -1,45 +1,50 @@
 <#
     .SYNOPSIS
-    Exports M365 security audit results to a CSV file or outputs a specific test result as an object.
+        Exports Microsoft 365 security audit results to CSV or Excel files and supports outputting specific test results as objects.
     .DESCRIPTION
-    This function exports M365 security audit results from either an array of CISAuditResult objects or a CSV file.
+        The Export-M365SecurityAuditTable function exports Microsoft 365 security audit results from an array of CISAuditResult objects or a CSV file.
-    It can export all results to a specified path or output a specific test result as an object.
+        It can export all results to a specified path, output a specific test result as an object, and includes options for exporting results to Excel.
+        Additionally, it computes hashes for the exported files and includes them in the zip archive for verification purposes.
     .PARAMETER AuditResults
-    An array of CISAuditResult objects containing the audit results.
+        An array of CISAuditResult objects containing the audit results. This parameter is mandatory when exporting from audit results.
     .PARAMETER CsvPath
-    The path to a CSV file containing the audit results.
+        The path to a CSV file containing the audit results. This parameter is mandatory when exporting from a CSV file.
     .PARAMETER OutputTestNumber
-    The test number to output as an object. Valid values are "1.1.1", "1.3.1", "6.1.2", "6.1.3", "7.3.4".
+        The test number to output as an object. Valid values are "1.1.1", "1.3.1", "6.1.2", "6.1.3", "7.3.4". This parameter is used to output a specific test result.
     .PARAMETER ExportAllTests
-    Switch to export all test results.
+        Switch to export all test results. When specified, all test results are exported to the specified path.
     .PARAMETER ExportPath
-    The path where the CSV files will be exported.
+        The path where the CSV or Excel files will be exported. This parameter is mandatory when exporting all tests.
     .PARAMETER ExportOriginalTests
-    Switch to export the original audit results to a CSV file.
+        Switch to export the original audit results to a CSV file. When specified, the original test results are exported along with the processed results.
     .PARAMETER ExportToExcel
-    Switch to export the results to an Excel file.
+        Switch to export the results to an Excel file. When specified, results are exported in Excel format.
     .INPUTS
-    [CISAuditResult[]], [string]
+        [CISAuditResult[]] - An array of CISAuditResult objects.
+        [string] - A path to a CSV file.
     .OUTPUTS
-    [PSCustomObject]
+        [PSCustomObject] - A custom object containing the path to the zip file and its hash.
     .EXAMPLE
         Export-M365SecurityAuditTable -AuditResults $object -OutputTestNumber 6.1.2
-    # Output object for a single test number from audit results
+        # Outputs the result of test number 6.1.2 from the provided audit results as an object.
     .EXAMPLE
         Export-M365SecurityAuditTable -ExportAllTests -AuditResults $object -ExportPath "C:\temp"
-    # Export all results from audit results to the specified path
+        # Exports all audit results to the specified path in CSV format.
     .EXAMPLE
         Export-M365SecurityAuditTable -CsvPath "C:\temp\auditresultstoday1.csv" -OutputTestNumber 6.1.2
-    # Output object for a single test number from CSV
+        # Outputs the result of test number 6.1.2 from the CSV file as an object.
     .EXAMPLE
         Export-M365SecurityAuditTable -ExportAllTests -CsvPath "C:\temp\auditresultstoday1.csv" -ExportPath "C:\temp"
-    # Export all results from CSV to the specified path
+        # Exports all audit results from the CSV file to the specified path in CSV format.
     .EXAMPLE
         Export-M365SecurityAuditTable -ExportAllTests -AuditResults $object -ExportPath "C:\temp" -ExportOriginalTests
-    # Export all results from audit results to the specified path along with the original tests
+        # Exports all audit results along with the original test results to the specified path in CSV format.
     .EXAMPLE
         Export-M365SecurityAuditTable -ExportAllTests -CsvPath "C:\temp\auditresultstoday1.csv" -ExportPath "C:\temp" -ExportOriginalTests
-    # Export all results from CSV to the specified path along with the original tests
+        # Exports all audit results from the CSV file along with the original test results to the specified path in CSV format.
+    .EXAMPLE
+        Export-M365SecurityAuditTable -ExportAllTests -AuditResults $object -ExportPath "C:\temp" -ExportToExcel
+        # Exports all audit results to the specified path in Excel format.
     .LINK
         https://criticalsolutionsnetwork.github.io/M365FoundationsCISReport/#Export-M365SecurityAuditTable
 #>
@@ -50,33 +55,29 @@ function Export-M365SecurityAuditTable {
         [Parameter(Mandatory = $true, Position = 1, ParameterSetName = "ExportAllResultsFromAuditResults")]
         [Parameter(Mandatory = $true, Position = 2, ParameterSetName = "OutputObjectFromAuditResultsSingle")]
         [CISAuditResult[]]$AuditResults,
-
         [Parameter(Mandatory = $true, Position = 1, ParameterSetName = "ExportAllResultsFromCsv")]
         [Parameter(Mandatory = $true, Position = 2, ParameterSetName = "OutputObjectFromCsvSingle")]
         [ValidateScript({ (Test-Path $_) -and ((Get-Item $_).PSIsContainer -eq $false) })]
         [string]$CsvPath,
-
         [Parameter(Mandatory = $true, Position = 1, ParameterSetName = "OutputObjectFromAuditResultsSingle")]
         [Parameter(Mandatory = $true, Position = 1, ParameterSetName = "OutputObjectFromCsvSingle")]
         [ValidateSet("1.1.1", "1.3.1", "6.1.2", "6.1.3", "7.3.4")]
         [string]$OutputTestNumber,
-
         [Parameter(Mandatory = $false, Position = 0, ParameterSetName = "ExportAllResultsFromAuditResults")]
         [Parameter(Mandatory = $false, Position = 0, ParameterSetName = "ExportAllResultsFromCsv")]
         [switch]$ExportAllTests,
-
         [Parameter(Mandatory = $true, ParameterSetName = "ExportAllResultsFromAuditResults")]
         [Parameter(Mandatory = $true, ParameterSetName = "ExportAllResultsFromCsv")]
         [string]$ExportPath,
-
         [Parameter(Mandatory = $true, ParameterSetName = "ExportAllResultsFromAuditResults")]
         [Parameter(Mandatory = $true, ParameterSetName = "ExportAllResultsFromCsv")]
         [switch]$ExportOriginalTests,
-
         [Parameter(Mandatory = $false, ParameterSetName = "ExportAllResultsFromAuditResults")]
         [Parameter(Mandatory = $false, ParameterSetName = "ExportAllResultsFromCsv")]
         [switch]$ExportToExcel
     )
+    Begin {
+        $createdFiles = @() # Initialize an array to keep track of created files
         if ($ExportToExcel) {
             Assert-ModuleAvailability -ModuleName ImportExcel -RequiredVersion "7.8.9"
         }
@@ -92,22 +93,19 @@ function Export-M365SecurityAuditTable {
                 Initialize-CISAuditResult @params
             }
         }
-
         if ($ExportAllTests) {
             $TestNumbers = "1.1.1", "1.3.1", "6.1.2", "6.1.3", "7.3.4"
         }
-
         $results = @()
-
         $testsToProcess = if ($OutputTestNumber) { @($OutputTestNumber) } else { $TestNumbers }
-
+    }
+    Process {
         foreach ($test in $testsToProcess) {
             $auditResult = $AuditResults | Where-Object { $_.Rec -eq $test }
             if (-not $auditResult) {
                 Write-Information "No audit results found for the test number $test."
                 continue
             }
-
             switch ($test) {
                 "6.1.2" {
                     $details = $auditResult.Details
@@ -117,7 +115,6 @@ function Export-M365SecurityAuditTable {
                     else {
                         $csv = $null
                     }
-
                     if ($null -ne $csv) {
                         foreach ($row in $csv) {
                             $row.AdminActionsMissing = (Get-Action -AbbreviatedActions $row.AdminActionsMissing.Split(',') -ReverseActionType Admin | Where-Object { $_ -notin @("MailItemsAccessed", "Send") }) -join ','
@@ -139,7 +136,6 @@ function Export-M365SecurityAuditTable {
                     else {
                         $csv = $null
                     }
-
                     if ($null -ne $csv) {
                         foreach ($row in $csv) {
                             $row.AdminActionsMissing = (Get-Action -AbbreviatedActions $row.AdminActionsMissing.Split(',') -ReverseActionType Admin) -join ','
@@ -160,11 +156,11 @@ function Export-M365SecurityAuditTable {
                 }
             }
         }
-
+    }
+    End {
         if ($ExportPath) {
             $timestamp = (Get-Date).ToString("yyyy.MM.dd_HH.mm.ss")
             $exportedTests = @()
-
             foreach ($result in $results) {
                 $testDef = $script:TestDefinitionsObject | Where-Object { $_.Rec -eq $result.TestNumber }
                 if ($testDef) {
@@ -177,9 +173,11 @@ function Export-M365SecurityAuditTable {
                             if ($ExportToExcel) {
                                 $xlsxPath = [System.IO.Path]::ChangeExtension($fileName, '.xlsx')
                                 $result.Details | Export-Excel -Path $xlsxPath -WorksheetName Table -TableName Table -AutoSize -TableStyle Medium2
+                                $createdFiles += $xlsxPath # Add the created file to the array
                             }
                             else {
                                 $result.Details | Export-Csv -Path $fileName -NoTypeInformation
+                                $createdFiles += $fileName # Add the created file to the array
                             }
                             $exportedTests += $result.TestNumber
                         }
@@ -197,23 +195,52 @@ function Export-M365SecurityAuditTable {
                     Write-Information "No specified tests were included in the export." -InformationAction Continue
                 }
             }
-
             if ($ExportOriginalTests) {
                 # Define the test numbers to check
                 $TestNumbersToCheck = "1.1.1", "1.3.1", "6.1.2", "6.1.3", "7.3.4"
-
                 # Check for large details and update the AuditResults array
                 $updatedAuditResults = Get-ExceededLengthResultDetail -AuditResults $AuditResults -TestNumbersToCheck $TestNumbersToCheck -ExportedTests $exportedTests -DetailsLengthLimit 30000 -PreviewLineCount 25
                 $originalFileName = "$ExportPath\$timestamp`_M365FoundationsAudit.csv"
                 if ($ExportToExcel) {
                     $xlsxPath = [System.IO.Path]::ChangeExtension($originalFileName, '.xlsx')
                     $updatedAuditResults | Export-Excel -Path $xlsxPath -WorksheetName Table -TableName Table -AutoSize -TableStyle Medium2
+                    $createdFiles += $xlsxPath # Add the created file to the array
                 }
                 else {
                     $updatedAuditResults | Export-Csv -Path $originalFileName -NoTypeInformation
+                    $createdFiles += $originalFileName # Add the created file to the array
                 }
             }
+            # Hash each file and add it to a dictionary
+            # Hash each file and save the hashes to a text file
+            $hashFilePath = "$ExportPath\$timestamp`_Hashes.txt"
+            $fileHashes = @()
+            foreach ($file in $createdFiles) {
+                $hash = Get-FileHash -Path $file -Algorithm SHA256
+                $fileHashes += "$($file): $($hash.Hash)"
             }
+            $fileHashes | Set-Content -Path $hashFilePath
+            $createdFiles += $hashFilePath # Add the hash file to the array
+
+            # Create a zip file and add all the created files
+            $zipFilePath = "$ExportPath\$timestamp`_M365FoundationsAudit.zip"
+            Compress-Archive -Path $createdFiles -DestinationPath $zipFilePath
+
+            # Remove the original files after they have been added to the zip
+            foreach ($file in $createdFiles) {
+                Remove-Item -Path $file -Force
+            }
+
+            # Compute the hash for the zip file and rename it
+            $zipHash = Get-FileHash -Path $zipFilePath -Algorithm SHA256
+            $newZipFilePath = "$ExportPath\$timestamp`_M365FoundationsAudit_$($zipHash.Hash.Substring(0, 8)).zip"
+            Rename-Item -Path $zipFilePath -NewName $newZipFilePath
+
+            # Output the zip file path with hash
+            [PSCustomObject]@{
+                ZipFilePath = $newZipFilePath
+            }
+        } # End of ExportPath
         elseif ($OutputTestNumber) {
             if ($results[0].Details) {
                 return $results[0].Details
@@ -225,4 +252,9 @@ function Export-M365SecurityAuditTable {
         else {
             Write-Error "No valid operation specified. Please provide valid parameters."
         }
+        # Output the created files at the end
+        #if ($createdFiles.Count -gt 0) {
+        ###########    $createdFiles
+        #}
+    }
 }

source/en-US/M365FoundationsCISReport-help.xml

@@ -277,7 +277,15 @@
     <command:inputTypes>
       <command:inputType>
         <dev:type>
-          <maml:name>[CISAuditResult[]], [string]</maml:name>
+          <maml:name>[CISAuditResult[]] - An array of CISAuditResult objects.</maml:name>
+        </dev:type>
+        <maml:description>
+          <maml:para></maml:para>
+        </maml:description>
+      </command:inputType>
+      <command:inputType>
+        <dev:type>
+          <maml:name>[string] - A path to a CSV file.</maml:name>
         </dev:type>
         <maml:description>
           <maml:para></maml:para>
@@ -287,7 +295,7 @@
     <command:returnValues>
       <command:returnValue>
         <dev:type>
-          <maml:name>[PSCustomObject]</maml:name>
+          <maml:name>[PSCustomObject] - A custom object containing the path to the zip file and its hash.</maml:name>
         </dev:type>
         <maml:description>
           <maml:para></maml:para>