Private/Backup/Test-BackupIntegrity.ps1
|
#region Test-BackupIntegrity.ps1 - Backup integrity check for restore operations <# .SYNOPSIS The integrity check every restore runs on a backup before applying it. .DESCRIPTION Test-BackupIntegrity takes an imported backup and checks its required properties, its signature, that the SHA256 of its SDDL matches the stored hash, and, when an expected object is given, that the backup was recorded for that object. Invoke-RestoreWorkflow calls it at the Standard level for every backup it restores. This file used to be Test-BackupValidation.ps1 and also held Test-BackupValidation, Test-BackupFormat and Get-BackupMetadata, which no command called; they were removed (#53). .NOTES Author: Jeffrey Stuhr SECURITY CONSIDERATIONS: - Uses SHA256 cryptographic hash verification - Validates SDDL format to prevent injection attacks - Confirms backup signatures to prevent malicious data #> function Test-BackupIntegrity { <# .SYNOPSIS Validates backup file integrity and format compatibility. .DESCRIPTION Performs comprehensive validation of backup files including: - Required property verification for completeness - Signature validation for version compatibility - SDDL hash integrity checking using SHA256 - Metadata completeness validation - Format validation to prevent malicious data injection This function is the primary validation gate before any restore operation, ensuring backup data is complete, uncorrupted, and safe to apply. BUSINESS VALUE: - Prevents data corruption through cryptographic verification - Ensures backup compatibility across different script versions - Provides detailed validation reporting for audit compliance - Reduces restoration failures through comprehensive pre-validation .PARAMETER BackupData PSCustomObject containing backup data to validate. Must include required properties: ObjectDN, BackupDate, SDDL, SDDLHash, ValidationSignature. .PARAMETER ExpectedObjectDN Optional distinguished name to verify backup target object. When specified, confirms backup was created for the intended object. .PARAMETER ValidationLevel Level of validation to perform: Basic, Standard, or Comprehensive. - Basic: Required properties and signature only - Standard: Includes SDDL integrity and format validation (default) - Comprehensive: Adds metadata validation and security checks .PARAMETER CorrelationId Unique identifier for tracking this validation operation. Used for correlation across logs and troubleshooting. .EXAMPLE PS> $backup = Import-Clixml "C:\Backups\user_backup.xml" PS> Test-BackupIntegrity -BackupData $backup DESCRIPTION: Validates imported backup with standard validation level OUTPUT: Validation result with IsValid status and detailed issues USE CASE: Pre-restoration validation for safety verification .EXAMPLE PS> Test-BackupIntegrity -BackupData $backup -ExpectedObjectDN "CN=TestUser,CN=Users,DC=contoso,DC=com" -ValidationLevel Comprehensive DESCRIPTION: Comprehensive validation with object DN verification OUTPUT: Detailed validation result with security checks USE CASE: High-security environments requiring full validation .EXAMPLE PS> $backups | Test-BackupIntegrity -ValidationLevel Basic DESCRIPTION: Bulk validation of multiple backups with basic checks OUTPUT: Validation results for each backup in the pipeline USE CASE: Quick validation of backup collection for bulk operations .INPUTS [PSCustomObject] Backup data objects from pipeline or parameter .OUTPUTS [PSCustomObject] BackupValidationResult with properties: - IsValid: Boolean indicating overall validation success - ValidationLevel: Level of validation performed - Issues: Array of specific validation issues found - ErrorMessage: Consolidated error information if validation fails - BackupInfo: Metadata about the validated backup - CorrelationId: Tracking identifier for this operation .NOTES Author: Jeffrey Stuhr Blog: https://www.techbyjeff.net LinkedIn: https://www.linkedin.com/in/jeffrey-stuhr-034214aa/ INTEGRITY VERIFICATION: - SHA256 hash verification prevents corruption detection - Format validation ensures compatibility and prevents injection - Version checking prevents incompatible restoration attempts PERFORMANCE CHARACTERISTICS: - Basic validation: ~10ms per backup - Standard validation: ~25ms per backup (includes crypto operations) - Comprehensive validation: ~50ms per backup (includes security checks) TROUBLESHOOTING: - For hash mismatches: .\Troubleshooting\Common\Backup-Restore-Issues.md .LINK .\Troubleshooting\Common\Backup-Restore-Issues.md .\Documentation\RestoreOperations-Analysis-Report.md #> [CmdletBinding()] [OutputType('BackupValidationResult')] param( [Parameter(Mandatory, ValueFromPipeline)] [ValidateNotNull()] [PSCustomObject]$BackupData, [Parameter()] [ValidateNotNullOrEmpty()] [string]$ExpectedObjectDN, [Parameter()] [ValidateSet('Basic', 'Standard', 'Comprehensive')] [string]$ValidationLevel = 'Standard', [Parameter()] [string]$CorrelationId = [System.Guid]::NewGuid().ToString() ) begin { Write-Verbose "Starting backup validation - CorrelationId: $CorrelationId" Write-Verbose "Validation level: $ValidationLevel" } process { try { $issues = @() $backupInfo = @{} # Phase 1: Basic validation - Required properties $requiredProperties = @('ObjectDN', 'BackupDate', 'SDDL', 'SDDLHash', 'ValidationSignature') foreach ($prop in $requiredProperties) { $property = $BackupData.PSObject.Properties[$prop] if (-not $property) { $issues += "Missing required property: $prop" } elseif ([string]::IsNullOrWhiteSpace([string]$property.Value)) { # Present but empty: an empty SDDL and hash would otherwise skip every check below $issues += "Empty required property: $prop" } else { $backupInfo[$prop] = $property.Value } } # Phase 2: Signature validation $validSignatures = @("PSSecurityBackup_v1.0", "PSSecurityBackup_v2.0", "PSSecurityBackup_v2.1") if ($BackupData.ValidationSignature -notin $validSignatures) { $issues += "Invalid backup signature: $($BackupData.ValidationSignature). Expected: $($validSignatures -join ', ')" } # Phase 3: Object DN validation (if specified) if ($ExpectedObjectDN -and $BackupData.ObjectDN -ne $ExpectedObjectDN) { $issues += "ObjectDN mismatch: Expected '$ExpectedObjectDN', found '$($BackupData.ObjectDN)'" } # Exit early for Basic validation if ($ValidationLevel -eq 'Basic') { return [PSCustomObject]@{ PSTypeName = 'BackupValidationResult' IsValid = $issues.Count -eq 0 ValidationLevel = $ValidationLevel Issues = $issues ErrorMessage = if ($issues.Count -gt 0) { $issues -join '; ' } else { $null } BackupInfo = $backupInfo CorrelationId = $CorrelationId ValidatedAt = Get-Date } } # Phase 4: Standard validation - SDDL integrity if ($BackupData.SDDL -and $BackupData.SDDLHash) { try { $sddlBytes = [System.Text.Encoding]::UTF8.GetBytes($BackupData.SDDL) $sha256 = [System.Security.Cryptography.SHA256]::Create() $calculatedHash = [System.Convert]::ToBase64String($sha256.ComputeHash($sddlBytes)) $sha256.Dispose() if ($calculatedHash -cne $BackupData.SDDLHash) { $issues += "SDDL integrity check failed: Hash mismatch (expected: $($BackupData.SDDLHash), calculated: $calculatedHash)" } } catch { $issues += "SDDL hash validation error: $($_.Exception.Message)" } } # Phase 5: SDDL format validation if ($BackupData.SDDL) { try { $testSecurityDescriptor = [System.DirectoryServices.ActiveDirectorySecurity]::new() $testSecurityDescriptor.SetSecurityDescriptorSddlForm($BackupData.SDDL) $testSecurityDescriptor = $null # Cleanup } catch { $issues += "Invalid SDDL format: $($_.Exception.Message)" } } # Exit for Standard validation if ($ValidationLevel -eq 'Standard') { return [PSCustomObject]@{ PSTypeName = 'BackupValidationResult' IsValid = $issues.Count -eq 0 ValidationLevel = $ValidationLevel Issues = $issues ErrorMessage = if ($issues.Count -gt 0) { $issues -join '; ' } else { $null } BackupInfo = $backupInfo CorrelationId = $CorrelationId ValidatedAt = Get-Date } } # Phase 6: Comprehensive validation - Additional security and metadata checks if ($ValidationLevel -eq 'Comprehensive') { # Validate backup date is reasonable if ($BackupData.BackupDate) { try { $backupDate = [DateTime]$BackupData.BackupDate $daysDiff = ((Get-Date) - $backupDate).Days if ($daysDiff -lt 0) { $issues += "Backup date is in the future: $($BackupData.BackupDate)" } elseif ($daysDiff -gt 365) { $issues += "Backup is older than 1 year: $($BackupData.BackupDate) (consider validation)" } } catch { $issues += "Invalid backup date format: $($BackupData.BackupDate)" } } # Validate ObjectDN format if ($BackupData.ObjectDN) { if (-not ($BackupData.ObjectDN -match '^(CN|OU|DC)=.+')) { $issues += "Invalid ObjectDN format: $($BackupData.ObjectDN)" } } # Check for suspicious SDDL patterns (basic security scan) if ($BackupData.SDDL) { $suspiciousPatterns = @('Everyone', 'Anonymous', 'S-1-1-0', 'S-1-5-7') foreach ($pattern in $suspiciousPatterns) { if ($BackupData.SDDL -like "*$pattern*") { $issues += "Security warning: SDDL contains potentially risky permission: $pattern" } } } } $result = [PSCustomObject]@{ PSTypeName = 'BackupValidationResult' IsValid = $issues.Count -eq 0 ValidationLevel = $ValidationLevel Issues = $issues ErrorMessage = if ($issues.Count -gt 0) { $issues -join '; ' } else { $null } BackupInfo = $backupInfo CorrelationId = $CorrelationId ValidatedAt = Get-Date } Write-Verbose "Backup validation completed - IsValid: $($result.IsValid) - CorrelationId: $CorrelationId" return $result } catch { $errorResult = [PSCustomObject]@{ PSTypeName = 'BackupValidationResult' IsValid = $false ValidationLevel = $ValidationLevel Issues = @("Validation error: $($_.Exception.Message)") ErrorMessage = "Validation error: $($_.Exception.Message)" BackupInfo = @{} CorrelationId = $CorrelationId ValidatedAt = Get-Date } Write-Error "Backup validation failed: $($_.Exception.Message) - CorrelationId: $CorrelationId" return $errorResult } } end { Write-Verbose "Completed backup validation process - CorrelationId: $CorrelationId" } } #endregion |