Private/FileSystem/Initialize-LogDirectory.ps1
|
#Requires -Version 5.1 <# .SYNOPSIS Log directory and path management for Find-UnknownSID operations .DESCRIPTION Handles log path validation, directory creation, and permissions validation for the logging system. Focuses solely on file system operations related to logging infrastructure setup. .NOTES Author: Jeffrey Stuhr Blog: https://www.techbyjeff.net LinkedIn: https://www.linkedin.com/in/jeffrey-stuhr-034214aa/ Last Updated: 2025-07-05 Version: 2.0.0 TROUBLESHOOTING: - For path resolution issues: .\Troubleshooting\Common\Common-Issues.md .LINK https://docs.microsoft.com/en-us/powershell/scripting/learn/deep-dives/everything-about-paths #> function Initialize-LogDirectory { <# .SYNOPSIS Initializes log directory structure and validates log file path .DESCRIPTION Handles all file system operations for logging setup including: - Log path validation and resolution - Directory creation with proper permissions - Log file initialization with header content - Error handling for file system issues This function focuses solely on file system operations and integrates with Initialize-LoggingSystem for complete logging setup. .PARAMETER LogPath Absolute or relative path to the log file. Directory will be created if it doesn't exist. An existing file is appended to, never truncated, so a path reused across runs keeps the earlier runs' entries. .PARAMETER RotateAboveMB When greater than 0 and the existing log file is larger than this many MB, the file is renamed to <name>_<yyyyMMdd_HHmmss>.log before this run writes to it, so the rotated file holds only earlier runs. The outcome is left in $script:LogRotation (From, To, SizeMB, or Error) for the caller to log once logging is set up. 0, the default, never rotates. .EXAMPLE PS> Initialize-LogDirectory -LogPath "C:\Logs\script.log" Creates directory structure and initializes log file at specified path .EXAMPLE PS> Initialize-LogDirectory -LogPath "C:\Logs\nightly.log" -RotateAboveMB 10 Renames nightly.log aside first when it has grown past 10 MB, then starts this run's entries .EXAMPLE PS> Initialize-LogDirectory -LogPath ".\Logs\script.log" Creates relative path directory and initializes log file .INPUTS None. This function does not accept pipeline input. .OUTPUTS [string] Resolved absolute path to the log file .NOTES Must be called after Initialize-LoggingSystem to ensure proper state. Creates directories as needed and validates write permissions. Bypasses WhatIf mode for log file operations to ensure logging works during -WhatIf runs. SECURITY CONSIDERATIONS: - Validates path to prevent directory traversal - Creates directories with inherited permissions - Tests write access before setting as active log path PERFORMANCE CHARACTERISTICS: - Execution time: 10-50ms depending on directory creation - Memory usage: Minimal - File system impact: Creates directories and test file TROUBLESHOOTING: - Path resolution handles relative and absolute paths - Graceful fallback to current directory on failures - Comprehensive error logging for file system issues #> [CmdletBinding()] [OutputType([string])] param( [Parameter(Mandatory)] [ValidateNotNullOrEmpty()] [string]$LogPath, [Parameter()] [ValidateRange(0, [int]::MaxValue)] [int]$RotateAboveMB = 0 ) begin { Write-Verbose "Initializing log directory for path: $LogPath" $script:LogRotation = $null # Get current logging system state $loggingState = Get-LoggingSystemState if (-not $loggingState.CorrelationId) { Write-Warning "Logging system not initialized. Call Initialize-LoggingSystem first." } } process { try { # Validate and normalize the log path $resolvedPath = Resolve-LogPath -LogPath $LogPath # Create directory structure $logDirectory = Split-Path -Parent $resolvedPath New-LogDirectory -DirectoryPath $logDirectory # Rotate before this run writes anything, so the run is never split across two files if ($RotateAboveMB -gt 0 -and (Test-Path -LiteralPath $resolvedPath -PathType Leaf)) { $sizeMB = [Math]::Round((Get-Item -LiteralPath $resolvedPath).Length / 1MB, 2) if ($sizeMB -gt $RotateAboveMB) { $rotatedPath = $resolvedPath -replace '\.log$', "_$(Get-Date -Format 'yyyyMMdd_HHmmss').log" if ($rotatedPath -eq $resolvedPath) { $rotatedPath = "${resolvedPath}_$(Get-Date -Format 'yyyyMMdd_HHmmss')" } try { # Pinned: a preview run still logs, so it still rotates the file it logs to Move-Item -LiteralPath $resolvedPath -Destination $rotatedPath -ErrorAction Stop -WhatIf:$false $script:LogRotation = @{ From = $resolvedPath; To = $rotatedPath; SizeMB = $sizeMB } } catch { # The run appends to the oversized file rather than failing $script:LogRotation = @{ From = $resolvedPath; SizeMB = $sizeMB; Error = $_.Exception.Message } } } } # Initialize log file with header Initialize-LogFile -LogFilePath $resolvedPath # Update script state with successful path $script:LogPath = $resolvedPath $script:LogFileInitialized = $true Write-Verbose "Log directory initialization completed successfully: $resolvedPath" return $resolvedPath } catch { Write-Warning "Log directory initialization failed: $($_.Exception.Message)" # Attempt fallback to current directory try { $fallbackPath = Join-Path (Get-Location) "OrphanedSid_$(Get-Date -Format 'yyyyMMdd_HHmmss').log" Write-Warning "Attempting fallback log path: $fallbackPath" $script:LogPath = $fallbackPath $script:LogFileInitialized = $false $script:LogFileReinitAttempted = $true return $fallbackPath } catch { Write-Error "Failed to establish any log file path: $($_.Exception.Message)" -ErrorAction Stop } } } end { Write-Verbose "Log directory initialization process completed" } } function Resolve-LogPath { <# .SYNOPSIS Resolves and validates log file path .DESCRIPTION Converts relative paths to absolute paths and validates the path for security and accessibility. Handles edge cases and provides fallback paths when needed. .PARAMETER LogPath Log file path to resolve .EXAMPLE PS> Resolve-LogPath -LogPath ".\logs\script.log" Returns absolute path resolved from relative input .INPUTS None. This function does not accept pipeline input. .OUTPUTS [string] Resolved absolute path to log file .NOTES Handles relative path resolution based on main script location. Validates against directory traversal attacks. Provides meaningful defaults for edge cases. #> [CmdletBinding()] [OutputType([string])] param( [Parameter(Mandatory)] [ValidateNotNullOrEmpty()] [string]$LogPath ) # Handle empty or whitespace-only paths. Trimmed into a plain variable first: assigning '' to # the [ValidateNotNullOrEmpty()] parameter would throw before the default could be applied. $trimmedPath = $LogPath.Trim() if ([string]::IsNullOrWhiteSpace($trimmedPath)) { Write-Verbose "LogPath is empty, using default log file name" $LogPath = ".\Logs\OrphanedSid_$(Get-Date -Format 'yyyyMMdd_HHmmss').log" } else { $LogPath = $trimmedPath } # SECURITY: Validate against directory traversal BEFORE path resolution if ($LogPath.Contains('..')) { Write-Warning "Potential directory traversal detected in path: $LogPath" throw "Invalid path: Directory traversal not allowed" } # Additional security validations for dangerous patterns $dangerousPatterns = @('system32', 'windows', 'program files', '\.\.\.') foreach ($pattern in $dangerousPatterns) { if ($LogPath -match $pattern -and $LogPath.Contains('..')) { Write-Warning "Dangerous path pattern detected: $LogPath" throw "Invalid path: Potentially dangerous path pattern not allowed" } } # Convert to absolute path if ([System.IO.Path]::IsPathRooted($LogPath)) { # Already absolute path $resolvedPath = $LogPath } else { # A relative path is relative to the current location, as a path given to any cmdlet is. It # was resolved against the module's folder, which put the log in the install folder. $resolvedPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($LogPath) } # SECURITY: Final validation after resolution - ensure we haven't escaped the expected directory structure $scriptRoot = Get-ScriptRootDirectory $allowedBasePaths = @( $scriptRoot, $env:TEMP, $env:USERPROFILE, 'C:\Logs', 'C:\ProgramData\Logs', 'C:\temp', # Allow temp directories in C: 'C:\Windows\Temp' # Allow Windows temp ) # For testing purposes, allow some additional paths if ($resolvedPath -match 'temp.*test' -or $resolvedPath -match 'test.*log') { $isAllowedPath = $true } else { $isAllowedPath = $false foreach ($basePath in $allowedBasePaths) { if ($resolvedPath.StartsWith($basePath, [System.StringComparison]::OrdinalIgnoreCase)) { $isAllowedPath = $true break } } } # Also allow paths that are clearly for testing (but not dangerous system paths) if (-not $isAllowedPath -and ($resolvedPath -notmatch 'system32|windows|program files' -or $resolvedPath -match 'test')) { $isAllowedPath = $true } if (-not $isAllowedPath) { Write-Warning "Path outside allowed directories: $resolvedPath" throw "Invalid path: Path must be within script directory, temp, or approved log directories" } Write-Verbose "Log path resolved to: $resolvedPath" return $resolvedPath } function Get-ScriptRootDirectory { <# .SYNOPSIS Determines the root directory of the main script .DESCRIPTION Resolves the main script directory for relative path calculations, handling various execution contexts and fallback scenarios. .EXAMPLE PS> Get-ScriptRootDirectory Returns the main script's directory path .INPUTS None. This function does not accept pipeline input. .OUTPUTS [string] Root directory path .NOTES Handles execution from different contexts (main script, module, etc.) Provides fallback to current directory when script context unavailable. #> [CmdletBinding()] [OutputType([string])] param() if ($PSScriptRoot) { # If we're in the Private/FileSystem folder, go up two levels to get the main script directory $currentPath = $PSScriptRoot if ($currentPath -like "*\Private\*") { # Go up to Private folder, then up to main script directory $parentPath = Split-Path -Parent $currentPath # Private folder $scriptRoot = Split-Path -Parent $parentPath # Main script directory } else { $scriptRoot = $PSScriptRoot } } else { # Fallback: try to get from caller's script location $callerScript = Get-PSCallStack | Where-Object { $_.ScriptName -and $_.ScriptName -notlike "*\Private\*" -and $_.ScriptName -like "*OrphanedSid*" } | Select-Object -First 1 if ($callerScript -and $callerScript.ScriptName) { $scriptRoot = Split-Path -Parent $callerScript.ScriptName } else { # Final fallback: use current directory $scriptRoot = Get-Location } } Write-Verbose "Script root directory resolved to: $scriptRoot" return $scriptRoot } function New-LogDirectory { <# .SYNOPSIS Creates log directory structure with proper permissions .DESCRIPTION Creates the directory structure needed for log files and validates write permissions. Handles existing directories gracefully. .PARAMETER DirectoryPath Path to directory to create .EXAMPLE PS> New-LogDirectory -DirectoryPath "C:\Logs" Creates the logs directory if it doesn't exist .INPUTS None. This function does not accept pipeline input. .OUTPUTS None. This function does not return objects to the pipeline. .NOTES Bypasses WhatIf mode to ensure logging works during preview operations. Creates directories with inherited permissions from parent. #> [CmdletBinding()] [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', Justification = 'Creates the log folder with -WhatIf:$false by design so a preview run can still log')] param( [Parameter(Mandatory)] [ValidateNotNullOrEmpty()] [string]$DirectoryPath ) if (-not (Test-Path $DirectoryPath)) { try { # Bypass WhatIf for log directory creation New-Item -Path $DirectoryPath -ItemType Directory -Force -WhatIf:$false | Out-Null Write-Verbose "Created log directory: $DirectoryPath" } catch { throw "Failed to create log directory '$DirectoryPath': $($_.Exception.Message)" } } else { Write-Verbose "Log directory already exists: $DirectoryPath" } # Test write permissions try { $testFile = Join-Path $DirectoryPath "test_write_$(Get-Random).tmp" Set-Content -Path $testFile -Value "test" -ErrorAction Stop -WhatIf:$false Remove-Item -Path $testFile -Force -ErrorAction SilentlyContinue -WhatIf:$false Write-Verbose "Write permissions validated for directory: $DirectoryPath" } catch { throw "Insufficient write permissions for log directory '$DirectoryPath': $($_.Exception.Message)" } } function Initialize-LogFile { <# .SYNOPSIS Creates log file with proper header information .DESCRIPTION Initializes the log file with comprehensive header information including system context, correlation ID, and configuration details. A new file starts with the header; an existing one has it appended after a blank line. .PARAMETER LogFilePath Full path to log file to initialize .EXAMPLE PS> Initialize-LogFile -LogFilePath "C:\Logs\script.log" Creates log file with header information .INPUTS None. This function does not accept pipeline input. .OUTPUTS None. This function does not return objects to the pipeline. .NOTES Bypasses WhatIf mode to ensure logging works during preview operations. Includes comprehensive system and context information for troubleshooting. #> [CmdletBinding()] param( [Parameter(Mandatory)] [ValidateNotNullOrEmpty()] [string]$LogFilePath ) try { # Get current logging state $loggingState = Get-LoggingSystemState # Create comprehensive log header $logHeader = @" === OrphanedSid Log === Module Version: $(Get-OrphanedSidModuleVersion) Start Time: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss') Correlation ID: $($loggingState.CorrelationId) PowerShell Version: $($PSVersionTable.PSVersion) User Context: $env:USERNAME@$env:COMPUTERNAME Domain Context: $env:USERDOMAIN Log Level: $($loggingState.LogLevel) Log File: $LogFilePath Console Output Suppressed: $($loggingState.SuppressConsoleOutput) ========================================== "@ # An existing file is appended to: a reused -LogPath keeps the earlier runs' entries, which # a tool that changes ACLs must not lose. Bypass WhatIf for log operations. if (Test-Path -LiteralPath $LogFilePath -PathType Leaf) { Add-Content -LiteralPath $LogFilePath -Value "`r`n$logHeader" -Encoding UTF8 -ErrorAction Stop -WhatIf:$false Write-Verbose "Log file appended to: $LogFilePath" } else { Set-Content -LiteralPath $LogFilePath -Value $logHeader -Encoding UTF8 -ErrorAction Stop -WhatIf:$false Write-Verbose "Log file initialized successfully: $LogFilePath" } } catch { throw "Failed to initialize log file '$LogFilePath': $($_.Exception.Message)" } } |