Private/Logging/Write-SecretRotationLog.ps1
|
function Write-SecretRotationLog { <# .SYNOPSIS Writes a log entry to the configured logging destination (file or Windows Event Log). .DESCRIPTION Central logging entry point, called by every public cmdlet. Reads and normalizes the Logging section of the configuration, filters by MinimumLevel, and dispatches to Write-SecretRotationFileLogEntry or Write-SecretRotationEventLogEntry depending on Mode. Every entry is stamped with the current OS user name ([System.Environment]::UserName, not WindowsIdentity - this module must also run under PowerShell Core on non-Windows platforms for its non-ActiveDirectory backends). When -BoundParameters is supplied, its keys/values are appended to the message with Credential/Password/Secret/Token/APIKey-named parameters redacted, so secrets - most importantly a freshly generated account password - never reach a log file or the Windows Event Log. Callers typically pass this only on the Debug-level entry-point log for each cmdlet invocation. No-ops silently when logging is disabled (Logging.Enabled = $false, the default) or when Level is below the configured MinimumLevel. Never throws - a logging failure must never break the cmdlet's actual password-rotation work. .PARAMETER Config The parsed configuration object returned by Read-SecretRotationConfigFile. .PARAMETER Level Severity of this entry: Debug, Information, Warning, or Error. .PARAMETER Message The log message. .PARAMETER CmdletName Name of the calling cmdlet, e.g. $MyInvocation.MyCommand.Name. .PARAMETER TargetName Optional. The config target involved in this action. .PARAMETER BoundParameters Optional. $PSBoundParameters of the calling cmdlet; appended to the message with sensitive values redacted. .EXAMPLE Write-SecretRotationLog -Config $config -Level Debug -CmdletName $MyInvocation.MyCommand.Name -Message 'Cmdlet invoked' -BoundParameters $PSBoundParameters Logs cmdlet entry with its bound parameters (secrets redacted) at Debug level. .EXAMPLE Write-SecretRotationLog -Config $config -Level Information -CmdletName 'Update-SecretRotationAccountPassword' -TargetName 'corp-ad-svcaccount1' -Message 'Password rotated and split into 5 share(s)' Logs a one-line summary of a successful operation. #> [CmdletBinding()] param( [Parameter(Mandatory)] [PSCustomObject] $Config, [Parameter(Mandatory)] [ValidateSet('Debug', 'Information', 'Warning', 'Error')] [string] $Level, [Parameter(Mandatory)] [string] $Message, [Parameter(Mandatory)] [string] $CmdletName, [Parameter()] [string] $TargetName, [Parameter()] [hashtable] $BoundParameters ) try { $loggingConfig = Get-SecretRotationLoggingConfig -Config $Config if (-not $loggingConfig.Enabled) { return } $minimumSeverity = $script:LogLevelSeverity[$loggingConfig.MinimumLevel] $entrySeverity = $script:LogLevelSeverity[$Level] if ($entrySeverity -lt $minimumSeverity) { return } $fullMessage = $Message if ($BoundParameters) { $redacted = foreach ($key in ($BoundParameters.Keys | Sort-Object)) { if ($key -match 'Credential|Password|Secret|Token|APIKey') { "$key=<redacted>" } else { "$key=$($BoundParameters[$key])" } } $fullMessage = "$Message ($($redacted -join '; '))" } $entry = [PSCustomObject]@{ Timestamp = Get-Date Level = $Level UserName = [System.Environment]::UserName CmdletName = $CmdletName TargetName = $TargetName Message = $fullMessage } if ($loggingConfig.Mode -eq 'EventLog') { Write-SecretRotationEventLogEntry -EventLog $loggingConfig.EventLog -Entry $entry } else { Write-SecretRotationFileLogEntry -File $loggingConfig.File -Entry $entry } } catch { if (-not $script:LoggingSinkFailed) { $script:LoggingSinkFailed = $true Write-Warning "Posh-SecretRotation logging failed and will be skipped for the rest of this session: $_" } } } |