Private/Reporting/Write-ProcessingSummary.ps1
|
#Requires -Version 5.1 <# .SYNOPSIS Processing summary and result reporting module for Find-UnknownSID .DESCRIPTION Provides comprehensive result formatting, summary generation, and export capabilities for Find-UnknownSID processing results. Focused solely on result presentation and data export functionality. .NOTES Author: Jeffrey Stuhr Blog: https://www.techbyjeff.net LinkedIn: https://www.linkedin.com/in/jeffrey-stuhr-034214aa/ Last Updated: 2025-07-04 Version: 2.0.0 TROUBLESHOOTING: - For output issues: .\Troubleshooting\Common\Common-Issues.md #> function Write-ProcessingSummary { <# .SYNOPSIS Write comprehensive processing summary with statistics and results .DESCRIPTION Generates and displays a comprehensive summary of processing results including performance statistics, findings, and recommendations for enterprise reporting and audit requirements. BUSINESS VALUE: - Provides executive-level summary for decision making - Supports compliance reporting and audit requirements - Enables performance monitoring and optimization - Delivers actionable insights for security teams - Facilitates automation integration and monitoring REPORTING FEATURES: - Multi-format output for different audiences - Comprehensive performance metrics and statistics - Automated CSV export for downstream processing - Structured JSON output for automation integration - Color-coded console output for immediate assessment .PARAMETER ProcessingResults [Object] (Mandatory) Hashtable containing processing results and statistics. Must include required properties for different operation types. EXPECTED PROPERTIES: - TotalObjectsProcessed: Number of objects analyzed - ProcessingDuration: Time taken for processing - ProcessingErrors: Count of errors encountered - CorrelationId: Tracking identifier for audit OPERATION-SPECIFIC PROPERTIES: Discovery/Removal: OrphanedSIDsFound, RemovalResults, StreamingManager Restore: SuccessfulRestores, FailedRestores, RestoreResults .PARAMETER OutputPath [String] (Optional) Path for CSV export of results. Enables downstream processing and analysis. VALIDATION RULES: - Directory must exist or be creatable - Must have write permissions to specified location - File extension should be .csv for consistency BUSINESS CONTEXT: Supports integration with reporting systems, compliance documentation, and change management processes. .PARAMETER CorrelationId [String] (Optional) Correlation ID for tracking this operation. Auto-generated if not provided for audit purposes. .OUTPUTS [Void] Writes summary to console and optionally exports to files. Side effects include console output and file creation if specified. .EXAMPLE PS> Write-ProcessingSummary -ProcessingResults $results -OutputPath ".\results.csv" DESCRIPTION: Write summary and export results to CSV OUTPUT: Console summary and CSV file export USE CASE: Standard result reporting and documentation COMPLIANCE: Supports audit trail requirements .EXAMPLE PS> Write-ProcessingSummary -ProcessingResults $restoreResults DESCRIPTION: Display restore operation summary OUTPUT: Detailed restore operation results BUSINESS CASE: Change management and rollback reporting AUDIT: Supports compliance documentation requirements .NOTES Author: Jeffrey Stuhr Blog: https://www.techbyjeff.net LinkedIn: https://www.linkedin.com/in/jeffrey-stuhr-034214aa/ SECURITY CONSIDERATIONS: - Results may contain sensitive information about AD structure - Export files should be protected with appropriate permissions - Correlation IDs enable security event tracking - Summary data supports security audit requirements PERFORMANCE CHARACTERISTICS: - Summary generation typically completes in <1 second - CSV export time varies with result count (1-10 seconds for large datasets) - Memory usage minimal for summary display - Streaming export for large result sets TROUBLESHOOTING: - For output issues: .\Troubleshooting\Common\Common-Issues.md - For performance optimization: .\Troubleshooting\Performance\Performance-Tuning.md KNOWN LIMITATIONS: - Large result sets may impact console display performance - CSV export requires sufficient disk space - Color output may not display correctly in all terminals #> [CmdletBinding()] param( [Parameter(Mandatory)] [object]$ProcessingResults, [Parameter()] [string]$OutputPath, [Parameter()] [string]$CorrelationId = [System.Guid]::NewGuid().ToString() ) begin { Write-StructuredLog "Generating processing summary" -Level Information -Component 'Summary' -CorrelationId $CorrelationId } process { try { # Invoke-MainProcessingLogic returns a hashtable, whose keys PSObject.Properties does not # list; read the names from whichever shape arrived $resultKeys = if ($ProcessingResults -is [System.Collections.IDictionary]) { @($ProcessingResults.Keys) } else { @($ProcessingResults.PSObject.Properties.Name) } # Display processing summary Write-StructuredLog "Processing summary details:" -Level Information -Component 'Summary' -CorrelationId $CorrelationId Write-StructuredLog "=== PROCESSING SUMMARY ===" -Level Information -Component 'Summary' -CorrelationId $CorrelationId Write-StructuredLog "Total objects processed: $($ProcessingResults.TotalObjectsProcessed)" -Level Information -Component 'Summary' -CorrelationId $CorrelationId Write-StructuredLog "Processing duration: $($ProcessingResults.ProcessingDuration.ToString('hh\:mm\:ss\.fff'))" -Level Information -Component 'Summary' -CorrelationId $CorrelationId # Handle different result types if ($resultKeys -contains 'ObjectsPerSecond') { Write-StructuredLog "Processing rate: $([Math]::Round($ProcessingResults.ObjectsPerSecond, 2)) objects/second" -Level Information -Component 'Summary' -CorrelationId $CorrelationId } if ($resultKeys -contains 'PeakMemoryUsageMB') { Write-StructuredLog "Peak memory usage: $($ProcessingResults.PeakMemoryUsageMB) MB" -Level Information -Component 'Summary' -CorrelationId $CorrelationId } # Check if this is a restore operation if ($resultKeys -contains 'SuccessfulRestores') { # Restore operation summary Write-StructuredLog "=== RESTORE SUMMARY ===" -Level Information -Component 'Summary' -CorrelationId $CorrelationId Write-StructuredLog "Successful restores: $($ProcessingResults.SuccessfulRestores)" -Level Information -Component 'Summary' -CorrelationId $CorrelationId Write-StructuredLog "Failed restores: $($ProcessingResults.FailedRestores)" -Level Information -Component 'Summary' -CorrelationId $CorrelationId Write-StructuredLog "Backup source: $($ProcessingResults.BackupPath)" -Level Information -Component 'Summary' -CorrelationId $CorrelationId Write-StructuredLog "WhatIf mode: $($ProcessingResults.WhatIfMode)" -Level Information -Component 'Summary' -CorrelationId $CorrelationId # Show detailed restore results if ($ProcessingResults.RestoreResults -and $ProcessingResults.RestoreResults.Count -gt 0) { Write-StructuredLog "=== RESTORE DETAILS ===" -Level Information -Component 'Summary' -CorrelationId $CorrelationId foreach ($result in $ProcessingResults.RestoreResults) { $status = if ($result.Success) { "SUCCESS" } else { "FAILED" } $entriesInfo = if ($result.EntriesRestored) { " ($($result.EntriesRestored) entries)" } else { "" } Write-StructuredLog " [$status] $($result.ObjectDN)$entriesInfo" -Level Information -Component 'Summary' -CorrelationId $CorrelationId if (-not $result.Success -and $result.ErrorMessage) { Write-StructuredLog " Error: $($result.ErrorMessage)" -Level Information -Component 'Summary' -CorrelationId $CorrelationId } } } # Overall restore operation status if ($ProcessingResults.FailedRestores -eq 0) { Write-StructuredLog "All restore operations completed successfully!" -Level Information -Component 'Summary' -CorrelationId $CorrelationId } else { Write-StructuredLog "Some restore operations failed. Review the details above." -Level Warning -Component 'Summary' -CorrelationId $CorrelationId } } else { # Standard discovery/removal operation summary if ($resultKeys -contains 'ProcessingErrors') { Write-StructuredLog "Processing errors: $($ProcessingResults.ProcessingErrors)" -Level Information -Component 'Summary' -CorrelationId $CorrelationId } if ($resultKeys -contains 'OrphanedSIDsFound') { Write-StructuredLog "Orphaned SIDs found: $($ProcessingResults.OrphanedSIDsFound)" -Level Information -Component 'Summary' -CorrelationId $CorrelationId } if ($resultKeys -contains 'UnexaminedObjects') { Write-StructuredLog "Objects not examined (security descriptor not readable): $($ProcessingResults.UnexaminedObjects)" -Level Information -Component 'Summary' -CorrelationId $CorrelationId if ($ProcessingResults.UnexaminedObjects -gt 0) { Write-StructuredLog "$($ProcessingResults.UnexaminedObjects) object(s) could not be examined because their security descriptor could not be read; each is named in a Warning above. Orphaned entries on them, if any, were neither reported nor removed. Re-run with an account that may read them." -Level Warning -Component 'Summary' -CorrelationId $CorrelationId } } if ($resultKeys -contains 'UnverifiedSIDsFound') { Write-StructuredLog "Unverified SIDs (lookup failed, not removed): $($ProcessingResults.UnverifiedSIDsFound)" -Level Information -Component 'Summary' -CorrelationId $CorrelationId if ($ProcessingResults.UnverifiedSIDsFound -gt 0) { Write-StructuredLog "$($ProcessingResults.UnverifiedSIDsFound) SID(s) could not be verified because a directory lookup failed. They are marked VerificationStatus Unverified in the results and were not removed; re-run once the domain controller is reachable and the account can read the targets." -Level Warning -Component 'Summary' -CorrelationId $CorrelationId } } } # Removal summary if applicable if ($ProcessingResults.RemovalResults -and $ProcessingResults.RemovalResults.Count -gt 0) { # @(...): on Windows PowerShell 5.1 a single object from Where-Object has no Count, so a run # with one removal logged an empty number $successfulRemovals = @($ProcessingResults.RemovalResults | Where-Object Success).Count $failedRemovals = @($ProcessingResults.RemovalResults | Where-Object { -not $_.Success }).Count Write-StructuredLog "Removal summary details:" -Level Information -Component 'Summary' -CorrelationId $CorrelationId Write-StructuredLog "=== REMOVAL SUMMARY ===" -Level Information -Component 'Summary' -CorrelationId $CorrelationId Write-StructuredLog "Removal operations attempted: $($ProcessingResults.RemovalResults.Count)" -Level Information -Component 'Summary' -CorrelationId $CorrelationId Write-StructuredLog "Successful removals: $successfulRemovals" -Level Information -Component 'Summary' -CorrelationId $CorrelationId Write-StructuredLog "Failed removals: $failedRemovals" -Level Information -Component 'Summary' -CorrelationId $CorrelationId } # Export results to CSV if path provided # Check if we have streaming results or restore results $hasStreamingResults = $ProcessingResults.StreamingManager -and $ProcessingResults.StreamingManager.Summary.TotalResults -gt 0 $hasRestoreResults = $ProcessingResults.RestoreResults -and $ProcessingResults.RestoreResults.Count -gt 0 if ($hasStreamingResults -or $hasRestoreResults) { if ($OutputPath) { try { # Under -WhatIf neither export writes a file: the streaming manager skips it in # WhatIf mode, and Export-Csv honours the inherited $WhatIfPreference $exported = $false if ($hasStreamingResults) { # Use StreamingManager's efficient CSV export $exported = $ProcessingResults.StreamingManager.ExportToCsv($OutputPath) } elseif ($hasRestoreResults) { if (-not $WhatIfPreference) { $ProcessingResults.RestoreResults | Export-Csv -Path $OutputPath -NoTypeInformation -Encoding UTF8 $exported = $true } } if ($exported) { Write-StructuredLog "Results exported to: $OutputPath" -Level Information -Component 'Summary' -CorrelationId $CorrelationId } elseif ($WhatIfPreference -or ($hasStreamingResults -and $ProcessingResults.StreamingManager.WhatIfMode)) { Write-StructuredLog "WhatIf: results would be exported to $OutputPath; no file was written" -Level Information -Component 'Summary' -CorrelationId $CorrelationId } else { Write-StructuredLog "No results were read back to export; $OutputPath was not written" -Level Warning -Component 'Summary' -CorrelationId $CorrelationId } } catch { Write-StructuredLog "Failed to export results to CSV: $($_.Exception.Message)" -Level Error -Component 'Summary' -CorrelationId $CorrelationId } } } else { # Handle different operation types appropriately if ($resultKeys -contains 'SuccessfulRestores') { # This is a restore operation with no results - shouldn't happen but handle gracefully Write-StructuredLog "No restore operations were performed." -Level Information -Component 'Summary' -CorrelationId $CorrelationId } else { # This is a discovery/removal operation if ($resultKeys -contains 'ProcessingErrors' -and $ProcessingResults.ProcessingErrors -gt 0) { Write-StructuredLog "Consider reviewing the error log for detailed information." -Level Information -Component 'Summary' -CorrelationId $CorrelationId } else { Write-StructuredLog "No orphaned SIDs found. Active Directory ACLs appear to be clean." -Level Information -Component 'Summary' -CorrelationId $CorrelationId } } } Write-StructuredLog "Processing summary completed" -Level Information -Component 'Summary' -CorrelationId $CorrelationId } catch { Write-StructuredLog "Error generating processing summary: $($_.Exception.Message)" -Level Error -Component 'Summary' -CorrelationId $CorrelationId throw } } } |