Skip to content

A comprehensive Windows security auditing and threat detection toolkit. Features 58 production-ready PowerShell functions organized into 14 modules for enterprise-grade security assessment, compliance validation, and incident response.

PowerShell
42.9 KB
Raw Blame
function Register-ScheduledSecurityScan {
    <#
    .SYNOPSIS
        Registers an automated recurring security scan with optional alerting
    .DESCRIPTION
        Creates a PowerShell scan script under the output path that imports the
        WindowsSecurityAudit module, runs Invoke-SecurityAssessment, and sends an
        alert (Teams/Slack-style incoming webhook and/or email) when Critical
        findings are detected. The script is then registered as a Scheduled Task
        running as SYSTEM at the chosen cadence (Daily, Weekly on Monday, or
        Monthly on the 1st). Use -Unregister to remove the scheduled task.
        The generated script embeds the webhook URL (a shared secret), so on
        Windows its file permissions are restricted to Administrators and SYSTEM.

        Alert deduplication is enabled by default: the generated script persists a
        stable SHA256 fingerprint (first 16 hex chars over Category + Finding text)
        of each finding to State\last-findings.json under the output path. On
        subsequent runs findings are classified as New, Persisting, or Resolved.
        An alarm is sent only for new Critical/High findings or persisting
        Critical/High findings older than -RealertAfterDays; a quiet resolved note
        (no alarm tone) is sent when findings disappear. The first run, a broken or
        missing state file, and -DisableAlertDedup all fall back to alerting on any
        Critical finding. State write failures never suppress alerts.
    .PARAMETER ScanType
        Type of scan to schedule: Quick, Standard, or Full (default: Standard).
        Mapped to Invoke-SecurityAssessment as Quick=Basic, Standard=Standard, Full=Advanced.
    .PARAMETER Frequency
        How often the scan runs: Daily, Weekly (Monday), or Monthly (1st of month) (default: Weekly)
    .PARAMETER Time
        Time of day to run the scan, as a datetime or string such as '09:00' (default: 09:00)
    .PARAMETER OutputPath
        Path where the scan script and per-run reports are stored
        (default: "$env:ProgramData\WindowsSecurityAudit\Scans")
    .PARAMETER WebhookUrl
        Optional incoming webhook URL (Microsoft Teams or Slack style) that receives
        an adaptive-card JSON POST when Critical findings exist
    .PARAMETER EmailTo
        Optional recipient address for email alerts (requires EmailFrom and SmtpServer)
    .PARAMETER EmailFrom
        Optional sender address for email alerts (requires EmailTo and SmtpServer)
    .PARAMETER SmtpServer
        Optional SMTP server for email alerts (requires EmailTo and EmailFrom)
    .PARAMETER DisableAlertDedup
        Turns off alert deduplication in the generated scan script. With dedup
        disabled the script alerts on every run whenever a Critical finding
        exists (the pre-dedup behavior)
    .PARAMETER RealertAfterDays
        Number of days after which a persisting Critical/High finding (first seen
        this many days ago or more) triggers a repeat alert (default: 7, range
        1-3650). Only used when alert deduplication is enabled
    .PARAMETER Unregister
        Removes the scheduled security scan task and exits without registering anything
    .PARAMETER WhatIf
        Shows what would happen if the command runs (SupportsShouldProcess)
    .PARAMETER Confirm
        Prompts for confirmation before registering or unregistering the task
    .EXAMPLE
        Register-ScheduledSecurityScan -ScanType Standard -Frequency Weekly -Time '09:00'
        Registers a weekly (Monday 09:00) Standard scan running as SYSTEM
    .EXAMPLE
        Register-ScheduledSecurityScan -ScanType Full -Frequency Daily -Time '22:30' -WebhookUrl 'https://outlook.office.com/webhook/...'
        Registers a nightly Full scan that posts an adaptive card to a Teams webhook on Critical findings
    .EXAMPLE
        Register-ScheduledSecurityScan -ScanType Quick -Frequency Monthly -EmailTo [email protected] -EmailFrom [email protected] -SmtpServer smtp.contoso.com
        Registers a monthly Quick scan that emails an alert when Critical findings exist
    .EXAMPLE
        Register-ScheduledSecurityScan -Frequency Daily -WebhookUrl 'https://outlook.office.com/webhook/...' -RealertAfterDays 14
        Registers a daily scan with alert deduplication (on by default) that re-alerts on Critical/High findings persisting for 14 days or more
    .EXAMPLE
        Register-ScheduledSecurityScan -Unregister -Confirm:$false
        Removes the scheduled security scan task
    .OUTPUTS
        PSCustomObject with the registration (or unregistration) result
    #>

    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
    param(
        [Parameter()]
        [ValidateSet('Quick', 'Standard', 'Full')]
        [string]$ScanType = 'Standard',

        [Parameter()]
        [ValidateSet('Daily', 'Weekly', 'Monthly')]
        [string]$Frequency = 'Weekly',

        [Parameter()]
        [datetime]$Time = '09:00',

        [Parameter()]
        [string]$OutputPath = "$env:ProgramData\WindowsSecurityAudit\Scans",

        [Parameter()]
        [string]$WebhookUrl,

        [Parameter()]
        [string]$EmailTo,

        [Parameter()]
        [string]$EmailFrom,

        [Parameter()]
        [string]$SmtpServer,

        [Parameter()]
        [switch]$DisableAlertDedup,

        [Parameter()]
        [ValidateRange(1, 3650)]
        [int]$RealertAfterDays = 7,

        [Parameter()]
        [switch]$Unregister
    )

    begin {
        Write-Host "=== SCHEDULED SECURITY SCAN REGISTRATION ===" -ForegroundColor Cyan
        Write-Host "Start Time: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')" -ForegroundColor Yellow

        $taskName = 'WindowsSecurityAudit-ScheduledScan'
        $machineName = [System.Environment]::MachineName
        $scanResult = $null

        # Resolve the module manifest so the generated script can import it standalone
        $moduleRoot = Split-Path -Path $PSScriptRoot -Parent
        $moduleManifest = Join-Path $moduleRoot 'WindowsSecurityAudit.psd1'
        if (-not (Test-Path $moduleManifest)) {
            Write-Warning "Module manifest not found at '$moduleManifest'. The generated script may fail to import the module."
        }

        # Map the public scan type to the Invoke-SecurityAssessment assessment type
        $assessmentType = switch ($ScanType) {
            'Quick'    { 'Basic' }
            'Standard' { 'Standard' }
            'Full'     { 'Advanced' }
        }

        # Email alerting requires the full triplet
        $emailPartsProvided = @($EmailTo, $EmailFrom, $SmtpServer | Where-Object { -not [string]::IsNullOrWhiteSpace($_) }).Count
        $emailConfigured = ($emailPartsProvided -eq 3)
        if ($emailPartsProvided -gt 0 -and -not $emailConfigured) {
            Write-Warning "Email alerting requires EmailTo, EmailFrom, and SmtpServer together. Email alerts will be disabled."
        }

        $webhookConfigured = (-not [string]::IsNullOrWhiteSpace($WebhookUrl))

        # Alert dedup is opt-out; the generated script embeds both values
        $alertDedupEnabled = (-not $DisableAlertDedup)
        if ($DisableAlertDedup -and $PSBoundParameters.ContainsKey('RealertAfterDays')) {
            Write-Warning "RealertAfterDays is ignored because alert deduplication is disabled."
        }
    }

    process {
        # ----- Unregister path: remove the task and exit -----
        if ($Unregister) {
            Write-Host "`nRemoving scheduled security scan..." -ForegroundColor Cyan

            try {
                $existingTask = Get-ScheduledTask -TaskName $taskName -ErrorAction SilentlyContinue

                if ($null -eq $existingTask) {
                    Write-Warning "Scheduled task '$taskName' was not found - nothing to remove."
                    $scanResult = [PSCustomObject]@{
                        ActionDate = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
                        TaskName = $taskName
                        Action = 'Unregister'
                        Status = 'NotFound'
                        ComputerName = $machineName
                    }
                    return
                }

                if ($PSCmdlet.ShouldProcess($machineName, "Unregister scheduled task '$taskName'")) {
                    Unregister-ScheduledTask -TaskName $taskName -Confirm:$false -ErrorAction Stop
                    Write-Host "Scheduled task '$taskName' removed." -ForegroundColor Green
                    $scanResult = [PSCustomObject]@{
                        ActionDate = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
                        TaskName = $taskName
                        Action = 'Unregister'
                        Status = 'Unregistered'
                        ComputerName = $machineName
                    }
                }
                else {
                    $scanResult = [PSCustomObject]@{
                        ActionDate = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
                        TaskName = $taskName
                        Action = 'Unregister'
                        Status = 'WhatIf'
                        ComputerName = $machineName
                    }
                }
            }
            catch {
                Write-Error "Failed to unregister scheduled task '$taskName': $_"
                throw
            }

            return
        }

        # ----- Registration path -----
        Write-Host "`nScan Type: $ScanType ($assessmentType assessment)" -ForegroundColor Yellow
        Write-Host "Frequency: $Frequency at $($Time.ToString('HH:mm'))" -ForegroundColor Yellow
        Write-Host "Output Path: $OutputPath" -ForegroundColor Yellow
        Write-Host "Webhook Alerts: $webhookConfigured" -ForegroundColor Yellow
        Write-Host "Email Alerts: $emailConfigured" -ForegroundColor Yellow
        Write-Host "Alert Dedup: $(if ($alertDedupEnabled) { "True (re-alert after $RealertAfterDays days)" } else { 'False' })" -ForegroundColor Yellow

        $scriptPath = Join-Path $OutputPath 'Invoke-ScheduledSecurityScan.ps1'

        # Escape single quotes in values embedded into the generated script
        $safeModuleManifest = if ($null -ne $moduleManifest) { $moduleManifest -replace "'", "''" } else { '' }
        $safeOutputPath = if ($null -ne $OutputPath) { $OutputPath -replace "'", "''" } else { '' }
        $safeWebhookUrl = if ($webhookConfigured) { $WebhookUrl -replace "'", "''" } else { '' }
        $safeEmailTo = if ($emailConfigured) { $EmailTo -replace "'", "''" } else { '' }
        $safeEmailFrom = if ($emailConfigured) { $EmailFrom -replace "'", "''" } else { '' }
        $safeSmtpServer = if ($emailConfigured) { $SmtpServer -replace "'", "''" } else { '' }
        $safeAlertDedup = if ($alertDedupEnabled) { '$true' } else { '$false' }
        $safeRealertAfterDays = "$RealertAfterDays"

        $scanScriptTemplate = @'
# ============================================================================
# WindowsSecurityAudit - Scheduled Security Scan
# Generated by Register-ScheduledSecurityScan on __GENERATED_ON__
# Re-run Register-ScheduledSecurityScan to modify this script.
# Run Register-ScheduledSecurityScan -Unregister to remove the scheduled task.
# ============================================================================

$ErrorActionPreference = 'Continue'

try {
    [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
}
catch {
    Write-Verbose "Could not enforce TLS 1.2: $_"
}

$modulePath       = '__MODULE_PATH__'
$scanOutputRoot   = '__OUTPUT_PATH__'
$assessmentType   = '__ASSESSMENT_TYPE__'
$webhookUrl       = '__WEBHOOK_URL__'
$emailTo          = '__EMAIL_TO__'
$emailFrom        = '__EMAIL_FROM__'
$smtpServer       = '__SMTP_SERVER__'
$alertDedup       = __ALERT_DEDUP__
$realertAfterDays = __REALERT_AFTER_DAYS__

$runStamp = Get-Date -Format 'yyyyMMdd_HHmmss'
$runPath = Join-Path $scanOutputRoot "Scan_$runStamp"

# Stable fingerprint of a finding: first 16 hex chars of SHA256 over Category + Finding text
function Get-FindingFingerprint {
    param(
        [string]$Category,
        [string]$Finding
    )

    $sha256 = [System.Security.Cryptography.SHA256]::Create()
    try {
        $hashBytes = $sha256.ComputeHash([System.Text.Encoding]::UTF8.GetBytes("$Category`n$Finding"))
        return (([System.BitConverter]::ToString($hashBytes)) -replace '-', '').Substring(0, 16).ToLowerInvariant()
    }
    finally {
        $sha256.Dispose()
    }
}

try {
    if (-not (Test-Path $runPath)) {
        New-Item -Path $runPath -ItemType Directory -Force | Out-Null
    }

    Import-Module $modulePath -Force -ErrorAction Stop

    $assessment = Invoke-SecurityAssessment -AssessmentType $assessmentType -OutputPath $runPath

    $findings = @()
    if ($null -ne $assessment -and $null -ne $assessment.PSObject.Properties['Findings'] -and $null -ne $assessment.Findings) {
        $findings = @($assessment.Findings)
    }

    $criticalFindings = @($findings | Where-Object { $_.Severity -eq 'Critical' })
    $highFindings = @($findings | Where-Object { $_.Severity -eq 'High' })

    $overallScore = 'N/A'
    if ($null -ne $assessment -and $null -ne $assessment.PSObject.Properties['OverallScore'] -and $null -ne $assessment.OverallScore) {
        $overallScore = "$($assessment.OverallScore)"
    }

    $runNow = Get-Date
    $runStampText = $runNow.ToString('yyyy-MM-dd HH:mm:ss')

    # Fingerprint the current findings (first occurrence wins for duplicates)
    $currentFingerprints = @{}
    foreach ($finding in $findings) {
        $fCat = ''
        $fTxt = ''
        $fSev = ''
        if ($null -ne $finding.PSObject.Properties['Category']) { $fCat = "$($finding.Category)" }
        if ($null -ne $finding.PSObject.Properties['Finding']) { $fTxt = "$($finding.Finding)" }
        if ($null -ne $finding.PSObject.Properties['Severity']) { $fSev = "$($finding.Severity)" }
        $fingerprint = Get-FindingFingerprint -Category $fCat -Finding $fTxt
        if (-not $currentFingerprints.ContainsKey($fingerprint)) {
            $currentFingerprints[$fingerprint] = [PSCustomObject]@{
                Fingerprint = $fingerprint
                Category = $fCat
                Finding = $fTxt
                Severity = $fSev
            }
        }
    }

    # Load the previous dedup state; a missing or broken state degrades to normal alerting
    $stateDir = Join-Path $scanOutputRoot 'State'
    $stateFile = Join-Path $stateDir 'last-findings.json'
    $previousState = @{}
    $stateLoaded = $false

    if ($alertDedup -and (Test-Path $stateFile)) {
        try {
            $parsedState = Get-Content -Path $stateFile -Raw -ErrorAction Stop | ConvertFrom-Json -ErrorAction Stop
            if ($null -eq $parsedState -or $null -eq $parsedState.PSObject.Properties['Findings'] -or $null -eq $parsedState.Findings) {
                Write-Warning "Alert dedup state file '$stateFile' has no findings data. Alerting without dedup for this run."
            }
            else {
                foreach ($stateEntry in @($parsedState.Findings)) {
                    if ($null -eq $stateEntry.PSObject.Properties['Fingerprint'] -or [string]::IsNullOrWhiteSpace("$($stateEntry.Fingerprint)")) { continue }
                    $sCat = ''
                    $sTxt = ''
                    $sSev = ''
                    $sFirstSeen = $null
                    if ($null -ne $stateEntry.PSObject.Properties['Category']) { $sCat = "$($stateEntry.Category)" }
                    if ($null -ne $stateEntry.PSObject.Properties['Finding']) { $sTxt = "$($stateEntry.Finding)" }
                    if ($null -ne $stateEntry.PSObject.Properties['Severity']) { $sSev = "$($stateEntry.Severity)" }
                    if ($null -ne $stateEntry.PSObject.Properties['FirstSeen'] -and -not [string]::IsNullOrWhiteSpace("$($stateEntry.FirstSeen)")) {
                        $parsedDate = [datetime]::MinValue
                        if ([datetime]::TryParseExact("$($stateEntry.FirstSeen)", 'yyyy-MM-dd HH:mm:ss', [System.Globalization.CultureInfo]::InvariantCulture, [System.Globalization.DateTimeStyles]::None, [ref]$parsedDate)) {
                            $sFirstSeen = $parsedDate
                        }
                    }
                    $previousState["$($stateEntry.Fingerprint)"] = [PSCustomObject]@{
                        Fingerprint = "$($stateEntry.Fingerprint)"
                        Category = $sCat
                        Finding = $sTxt
                        Severity = $sSev
                        FirstSeen = $sFirstSeen
                    }
                }
                $stateLoaded = $true
            }
        }
        catch {
            Write-Warning "Could not load alert dedup state file '$stateFile': $($_.Exception.Message). Alerting without dedup for this run."
        }
    }

    # Classify current findings against the previous state
    $newFindings = @()
    $persistingFindings = @()
    $resolvedFindings = @()

    if ($alertDedup) {
        foreach ($fingerprint in @($currentFingerprints.Keys)) {
            if ($stateLoaded -and $previousState.ContainsKey($fingerprint)) {
                $persistingFindings += [PSCustomObject]@{
                    Fingerprint = $fingerprint
                    Category = $currentFingerprints[$fingerprint].Category
                    Finding = $currentFingerprints[$fingerprint].Finding
                    Severity = $currentFingerprints[$fingerprint].Severity
                    FirstSeen = $previousState[$fingerprint].FirstSeen
                }
            }
            else {
                $newFindings += $currentFingerprints[$fingerprint]
            }
        }
        if ($stateLoaded) {
            foreach ($fingerprint in @($previousState.Keys)) {
                if (-not $currentFingerprints.ContainsKey($fingerprint)) {
                    $resolvedFindings += $previousState[$fingerprint]
                }
            }
        }
    }

    # Decide whether and how to alert
    $alertFindings = @()
    $alertReason = 'None'

    if ($alertDedup -and $stateLoaded) {
        $newAlerts = @($newFindings | Where-Object { $_.Severity -eq 'Critical' -or $_.Severity -eq 'High' })
        $realerts = @($persistingFindings | Where-Object {
            if ($_.Severity -ne 'Critical' -and $_.Severity -ne 'High') { return $false }
            if ($null -eq $_.FirstSeen) { return $true }
            return (($runNow - $_.FirstSeen).TotalDays -ge $realertAfterDays)
        })
        $alertFindings = @($newAlerts) + @($realerts)
        if ($alertFindings.Count -gt 0) {
            $alertReason = 'Alarm'
        }
        elseif ($resolvedFindings.Count -gt 0) {
            $alertReason = 'Resolved'
        }
    }
    else {
        # First run, dedup disabled, or unreadable state: alert on any Critical finding
        $alertFindings = $criticalFindings
        if ($criticalFindings.Count -gt 0) {
            $alertReason = 'Alarm'
        }
    }

    $runSummary = [PSCustomObject]@{
        ComputerName = $env:COMPUTERNAME
        RunDate = $runStampText
        AssessmentType = $assessmentType
        OverallScore = $overallScore
        TotalFindings = $findings.Count
        CriticalFindings = $criticalFindings.Count
        HighFindings = $highFindings.Count
        NewFindings = $newFindings.Count
        PersistingFindings = $persistingFindings.Count
        ResolvedFindings = $resolvedFindings.Count
        AlertDedup = $alertDedup
        RealertAfterDays = $realertAfterDays
        AlertReason = $alertReason
        ReportPath = $runPath
        AlertSent = $false
    }

    if ($alertReason -eq 'Alarm') {
        # ---------- Webhook alert (Teams/Slack-style incoming webhook) ----------
        if (-not [string]::IsNullOrWhiteSpace($webhookUrl)) {
            try {
                $factBlocks = @($alertFindings | ForEach-Object {
                    $cat = ''
                    $txt = ''
                    if ($null -ne $_.PSObject.Properties['Category']) { $cat = "$($_.Category)" }
                    if ($null -ne $_.PSObject.Properties['Finding']) { $txt = "$($_.Finding)" }
                    @{ title = $cat; value = $txt }
                })

                $alertFacts = @(
                    @{ title = 'Computer'; value = "$env:COMPUTERNAME" }
                    @{ title = 'Scan Time'; value = $runStampText }
                    @{ title = 'Overall Score'; value = $overallScore }
                    @{ title = 'Critical'; value = "$($criticalFindings.Count)" }
                    @{ title = 'High'; value = "$($highFindings.Count)" }
                    @{ title = 'Report'; value = "$runPath" }
                )
                if ($alertDedup) {
                    $alertFacts += @{ title = 'Since Last Run: New'; value = "$($newFindings.Count)" }
                    $alertFacts += @{ title = 'Since Last Run: Persisting'; value = "$($persistingFindings.Count)" }
                    $alertFacts += @{ title = 'Since Last Run: Resolved'; value = "$($resolvedFindings.Count)" }
                }

                $payload = @{
                    type = 'message'
                    attachments = @(
                        @{
                            contentType = 'application/vnd.microsoft.card.adaptive'
                            content = @{
                                '$schema' = 'http://adaptivecards.io/schemas/adaptive-card.json'
                                type = 'AdaptiveCard'
                                version = '1.2'
                                body = @(
                                    @{ type = 'TextBlock'; size = 'Large'; weight = 'Bolder'; color = 'Attention'; text = "CRITICAL Security Findings - $env:COMPUTERNAME" }
                                    @{ type = 'TextBlock'; text = "Scheduled $assessmentType security scan completed with $($alertFindings.Count) critical/high finding(s) requiring attention."; wrap = $true }
                                    @{ type = 'FactSet'; facts = @($alertFacts) + $factBlocks }
                                    @{ type = 'TextBlock'; text = 'Review the full report and remediate the critical findings as soon as possible.'; wrap = $true }
                                )
                            }
                        }
                    )
                }

                $jsonBody = $payload | ConvertTo-Json -Depth 12
                Invoke-RestMethod -Uri $webhookUrl -Method Post -Body $jsonBody -ContentType 'application/json; charset=utf-8' -ErrorAction Stop
                $runSummary.AlertSent = $true
            }
            catch {
                Write-Warning "Failed to send webhook alert: $($_.Exception.Message)"
            }
        }

        # ---------- Email alert ----------
        if (-not [string]::IsNullOrWhiteSpace($emailTo) -and -not [string]::IsNullOrWhiteSpace($emailFrom) -and -not [string]::IsNullOrWhiteSpace($smtpServer)) {
            try {
                $mailRows = ($alertFindings | ForEach-Object {
                    $cat = ''
                    $txt = ''
                    if ($null -ne $_.PSObject.Properties['Category']) { $cat = "$($_.Category)" }
                    if ($null -ne $_.PSObject.Properties['Finding']) { $txt = "$($_.Finding)" }
                    "<tr><td style='padding:6px;border:1px solid #ccc;'>$cat</td><td style='padding:6px;border:1px solid #ccc;'>$txt</td></tr>"
                }) -join "`n"

                $dedupSummaryHtml = ''
                if ($alertDedup) {
                    $dedupSummaryHtml = "<p>Since last run: <b>$($newFindings.Count)</b> new, <b>$($persistingFindings.Count)</b> persisting, <b>$($resolvedFindings.Count)</b> resolved finding(s).</p>"
                }

                $mailBody = @"
<html><body style='font-family:Arial;'>
<h2 style='color:#c00;'>Critical Security Findings - $env:COMPUTERNAME</h2>
<p>Scheduled <b>$assessmentType</b> scan on <b>$runStampText</b> found <b>$($criticalFindings.Count)</b> critical and <b>$($highFindings.Count)</b> high finding(s). Overall score: <b>$overallScore</b>.</p>
$dedupSummaryHtml
<table style='border-collapse:collapse;'>
<tr><th style='padding:6px;border:1px solid #ccc;background:#333;color:#fff;'>Category</th><th style='padding:6px;border:1px solid #ccc;background:#333;color:#fff;'>Finding</th></tr>
$mailRows
</table>
<p>Full report: $runPath</p>
</body></html>
"@

                Send-MailMessage -To $emailTo -From $emailFrom -SmtpServer $smtpServer -Subject "[SECURITY ALERT] $($alertFindings.Count) critical/high finding(s) on $env:COMPUTERNAME" -Body $mailBody -BodyAsHtml -Encoding UTF8 -ErrorAction Stop
                $runSummary.AlertSent = $true
            }
            catch {
                Write-Warning "Failed to send email alert: $($_.Exception.Message)"
            }
        }
    }
    elseif ($alertReason -eq 'Resolved') {
        # ---------- Resolved note (informational, no alarm tone) ----------
        if (-not [string]::IsNullOrWhiteSpace($webhookUrl)) {
            try {
                $resolvedFacts = @(
                    @{ title = 'Computer'; value = "$env:COMPUTERNAME" }
                    @{ title = 'Scan Time'; value = $runStampText }
                    @{ title = 'Overall Score'; value = $overallScore }
                    @{ title = 'Since Last Run: New'; value = "$($newFindings.Count)" }
                    @{ title = 'Since Last Run: Persisting'; value = "$($persistingFindings.Count)" }
                    @{ title = 'Since Last Run: Resolved'; value = "$($resolvedFindings.Count)" }
                    @{ title = 'Report'; value = "$runPath" }
                )

                $payload = @{
                    type = 'message'
                    attachments = @(
                        @{
                            contentType = 'application/vnd.microsoft.card.adaptive'
                            content = @{
                                '$schema' = 'http://adaptivecards.io/schemas/adaptive-card.json'
                                type = 'AdaptiveCard'
                                version = '1.2'
                                body = @(
                                    @{ type = 'TextBlock'; size = 'Large'; weight = 'Bolder'; color = 'Good'; text = "Security Findings Resolved - $env:COMPUTERNAME" }
                                    @{ type = 'TextBlock'; text = "Scheduled $assessmentType security scan: $($resolvedFindings.Count) finding(s) resolved since the last run. No new critical or high findings."; wrap = $true }
                                    @{ type = 'FactSet'; facts = $resolvedFacts }
                                )
                            }
                        }
                    )
                }

                $jsonBody = $payload | ConvertTo-Json -Depth 12
                Invoke-RestMethod -Uri $webhookUrl -Method Post -Body $jsonBody -ContentType 'application/json; charset=utf-8' -ErrorAction Stop
                $runSummary.AlertSent = $true
            }
            catch {
                Write-Warning "Failed to send webhook alert: $($_.Exception.Message)"
            }
        }

        if (-not [string]::IsNullOrWhiteSpace($emailTo) -and -not [string]::IsNullOrWhiteSpace($emailFrom) -and -not [string]::IsNullOrWhiteSpace($smtpServer)) {
            try {
                $resolvedRows = ($resolvedFindings | ForEach-Object {
                    $cat = ''
                    $txt = ''
                    if ($null -ne $_.PSObject.Properties['Category']) { $cat = "$($_.Category)" }
                    if ($null -ne $_.PSObject.Properties['Finding']) { $txt = "$($_.Finding)" }
                    "<tr><td style='padding:6px;border:1px solid #ccc;'>$cat</td><td style='padding:6px;border:1px solid #ccc;'>$txt</td></tr>"
                }) -join "`n"

                $mailBody = @"
<html><body style='font-family:Arial;'>
<h2 style='color:#080;'>Security Findings Resolved - $env:COMPUTERNAME</h2>
<p>Scheduled <b>$assessmentType</b> scan on <b>$runStampText</b>: <b>$($resolvedFindings.Count)</b> finding(s) resolved since the last run. No new critical or high findings. Overall score: <b>$overallScore</b>.</p>
<p>Since last run: <b>$($newFindings.Count)</b> new, <b>$($persistingFindings.Count)</b> persisting, <b>$($resolvedFindings.Count)</b> resolved finding(s).</p>
<table style='border-collapse:collapse;'>
<tr><th style='padding:6px;border:1px solid #ccc;background:#333;color:#fff;'>Category</th><th style='padding:6px;border:1px solid #ccc;background:#333;color:#fff;'>Resolved Finding</th></tr>
$resolvedRows
</table>
<p>Full report: $runPath</p>
</body></html>
"@

                Send-MailMessage -To $emailTo -From $emailFrom -SmtpServer $smtpServer -Subject "[SECURITY UPDATE] $($resolvedFindings.Count) finding(s) resolved on $env:COMPUTERNAME" -Body $mailBody -BodyAsHtml -Encoding UTF8 -ErrorAction Stop
                $runSummary.AlertSent = $true
            }
            catch {
                Write-Warning "Failed to send email alert: $($_.Exception.Message)"
            }
        }
    }

    # Persist the dedup state after every run; write failures never suppress alerts
    if ($alertDedup) {
        try {
            if (-not (Test-Path $stateDir)) {
                New-Item -Path $stateDir -ItemType Directory -Force | Out-Null
            }
            $stateFindings = @()
            foreach ($fingerprint in @($currentFingerprints.Keys)) {
                $currentEntry = $currentFingerprints[$fingerprint]
                $firstSeenText = $runStampText
                if ($previousState.ContainsKey($fingerprint) -and $null -ne $previousState[$fingerprint].FirstSeen) {
                    $firstSeenText = $previousState[$fingerprint].FirstSeen.ToString('yyyy-MM-dd HH:mm:ss')
                }
                $stateFindings += [PSCustomObject]@{
                    Fingerprint = $fingerprint
                    Category = $currentEntry.Category
                    Finding = $currentEntry.Finding
                    Severity = $currentEntry.Severity
                    FirstSeen = $firstSeenText
                    LastSeen = $runStampText
                }
            }
            [PSCustomObject]@{
                ComputerName = $env:COMPUTERNAME
                RunTimestamp = $runStampText
                Findings = $stateFindings
            } | ConvertTo-Json -Depth 5 | Out-File -FilePath $stateFile -Encoding UTF8 -Force
        }
        catch {
            Write-Warning "Could not write alert dedup state file '$stateFile': $($_.Exception.Message). Alerting is not affected."
        }
    }

    $runSummary | ConvertTo-Json -Depth 5 | Out-File (Join-Path $runPath 'RunSummary.json') -Encoding UTF8
}
catch {
    try {
        if (-not (Test-Path $scanOutputRoot)) {
            New-Item -Path $scanOutputRoot -ItemType Directory -Force | Out-Null
        }
        [PSCustomObject]@{
            ComputerName = $env:COMPUTERNAME
            RunDate = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
            Status = 'Failed'
            Error = $_.Exception.Message
        } | ConvertTo-Json | Out-File (Join-Path $scanOutputRoot "ScanError_$runStamp.json") -Encoding UTF8
    }
    catch {
        # Best-effort error persistence only
    }
    exit 1
}

exit 0
'@

        if ($PSCmdlet.ShouldProcess($machineName, "Register scheduled security scan '$taskName' ($Frequency at $($Time.ToString('HH:mm')))")) {
            # Section 1: Create the scan script
            try {
                Write-Host "`nCreating scan script..." -ForegroundColor Cyan

                if (Test-Path $OutputPath) {
                    # A pre-existing output folder must be owned by SYSTEM/Administrators:
                    # its owner retains WRITE_DAC even when removed from the ACL and could
                    # reopen write access to tamper with the SYSTEM-run scan script
                    if ($env:OS -eq 'Windows_NT') {
                        if (-not (Test-AdminOnlyOwnership -Path $OutputPath)) {
                            throw "OutputPath '$OutputPath' is not owned by SYSTEM/Administrators; refusing to place a SYSTEM-run script there. Remove it or choose another -OutputPath."
                        }
                    }
                    else {
                        Write-Verbose "Non-Windows host: skipping output folder ownership check for '$OutputPath'."
                    }
                }
                else {
                    New-Item -Path $OutputPath -ItemType Directory -Force | Out-Null
                }

                $scanScript = $scanScriptTemplate.
                    Replace('__GENERATED_ON__', (Get-Date -Format 'yyyy-MM-dd HH:mm:ss')).
                    Replace('__MODULE_PATH__', $safeModuleManifest).
                    Replace('__OUTPUT_PATH__', $safeOutputPath).
                    Replace('__ASSESSMENT_TYPE__', $assessmentType).
                    Replace('__WEBHOOK_URL__', $safeWebhookUrl).
                    Replace('__EMAIL_TO__', $safeEmailTo).
                    Replace('__EMAIL_FROM__', $safeEmailFrom).
                    Replace('__SMTP_SERVER__', $safeSmtpServer).
                    Replace('__ALERT_DEDUP__', $safeAlertDedup).
                    Replace('__REALERT_AFTER_DAYS__', $safeRealertAfterDays)

                # The script embeds the webhook URL (a shared secret) and runs as SYSTEM,
                # so it must never exist world-readable: create the file EMPTY, restrict
                # it to Administrators and SYSTEM, and only then write the content into
                # the locked file (avoids the permissive ProgramData default between
                # creation and lockdown)
                if ($env:OS -eq 'Windows_NT') {
                    # A pre-existing script file may be owned by a non-admin who keeps
                    # WRITE_DAC on it; delete and recreate so ownership starts clean
                    if (Test-Path $scriptPath) {
                        Remove-Item -Path $scriptPath -Force -ErrorAction Stop
                    }
                    New-Item -Path $scriptPath -ItemType File -Force | Out-Null
                    try {
                        $scriptAcl = Get-Acl -Path $scriptPath -ErrorAction Stop
                        $scriptAcl.SetAccessRuleProtection($true, $false)
                        foreach ($existingRule in @($scriptAcl.Access)) {
                            $null = $scriptAcl.RemoveAccessRule($existingRule)
                        }
                        $aclIdentities = @(
                            (New-Object System.Security.Principal.SecurityIdentifier('S-1-5-18')),
                            (New-Object System.Security.Principal.SecurityIdentifier('S-1-5-32-544'))
                        )
                        foreach ($identity in $aclIdentities) {
                            $accessRule = New-Object System.Security.AccessControl.FileSystemAccessRule(
                                $identity,
                                [System.Security.AccessControl.FileSystemRights]::FullControl,
                                [System.Security.AccessControl.AccessControlType]::Allow)
                            $scriptAcl.AddAccessRule($accessRule)
                        }
                        $scriptAcl.SetOwner([System.Security.Principal.SecurityIdentifier]'S-1-5-32-544')
                        Set-Acl -Path $scriptPath -AclObject $scriptAcl -ErrorAction Stop
                        if (-not (Test-AdminOnlyOwnership -Path $scriptPath) -or -not (Test-NoNonAdminWriteAccess -Path $scriptPath)) {
                            throw "Post-lockdown verification failed for '$scriptPath': owner or write access is not restricted to SYSTEM/Administrators."
                        }
                    }
                    catch {
                        # Fail closed: without a verified admin-only ACL the secret-bearing
                        # script must not be written and the task must not be registered
                        throw "Could not restrict permissions on '$scriptPath'; refusing to write the scan script because it embeds the webhook URL and runs as SYSTEM: $_"
                    }
                }
                else {
                    Write-Verbose "Non-Windows host: skipping ACL lockdown and ownership verification for '$scriptPath'."
                }

                $scanScript | Out-File $scriptPath -Encoding UTF8 -Force

                Write-Host "Scan script created: $scriptPath" -ForegroundColor Green
            }
            catch {
                Write-Error "Failed to create scan script at '$scriptPath': $_"
                throw
            }

            # Section 2: Register the scheduled task
            try {
                Write-Host "`nRegistering scheduled task..." -ForegroundColor Cyan

                $trigger = $null
                switch ($Frequency) {
                    'Daily' {
                        $trigger = New-ScheduledTaskTrigger -Daily -At $Time
                    }
                    'Weekly' {
                        $trigger = New-ScheduledTaskTrigger -Weekly -DaysOfWeek Monday -At $Time
                    }
                    'Monthly' {
                        # New-ScheduledTaskTrigger has no -Monthly in PS 5.1; build the CIM trigger directly
                        $triggerClass = Get-CimClass -ClassName 'MSFT_TaskMonthlyTrigger' -Namespace 'Root\Microsoft\Windows\TaskScheduler' -ErrorAction Stop
                        $trigger = New-CimInstance -CimClass $triggerClass -ClientOnly -Property @{
                            DaysOfMonth = 1
                            MonthsOfYear = 4095
                            StartBoundary = $Time.ToString("yyyy-MM-dd'T'HH:mm:ss")
                            Enabled = $true
                        } -ErrorAction Stop
                    }
                }

                $actionArgs = "-NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$scriptPath`""
                $action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument $actionArgs
                $principal = New-ScheduledTaskPrincipal -UserId 'SYSTEM' -LogonType ServiceAccount -RunLevel Highest
                $settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries

                $frequencyNote = switch ($Frequency) {
                    'Daily'   { 'every day' }
                    'Weekly'  { 'every Monday' }
                    'Monthly' { 'on the 1st of every month' }
                }
                $dedupNote = if ($alertDedupEnabled) { "on, re-alert after $RealertAfterDays days" } else { 'off' }
                $taskDescription = "WindowsSecurityAudit $ScanType scan ($assessmentType) runs $frequencyNote at $($Time.ToString('HH:mm')). Alerts on Critical findings (alert dedup: $dedupNote). Managed by Register-ScheduledSecurityScan."

                Register-ScheduledTask -TaskName $taskName -Action $action -Trigger $trigger -Principal $principal -Settings $settings -Description $taskDescription -Force -ErrorAction Stop | Out-Null

                Write-Host "Scheduled task '$taskName' registered (runs as SYSTEM)." -ForegroundColor Green
            }
            catch {
                Write-Error "Failed to register scheduled task '$taskName': $_"
                throw
            }

            $scanResult = [PSCustomObject]@{
                RegistrationDate = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
                TaskName = $taskName
                Action = 'Register'
                Status = 'Registered'
                ComputerName = $machineName
                ScanType = $ScanType
                AssessmentType = $assessmentType
                Frequency = $Frequency
                ScheduledTime = $Time.ToString('HH:mm')
                RunAs = 'SYSTEM'
                ScriptPath = $scriptPath
                OutputPath = $OutputPath
                WebhookAlertEnabled = $webhookConfigured
                EmailAlertEnabled = $emailConfigured
                AlertDedupEnabled = $alertDedupEnabled
                RealertAfterDays = $RealertAfterDays
            }
        }
        else {
            $scanResult = [PSCustomObject]@{
                RegistrationDate = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
                TaskName = $taskName
                Action = 'Register'
                Status = 'WhatIf'
                ComputerName = $machineName
                ScanType = $ScanType
                AssessmentType = $assessmentType
                Frequency = $Frequency
                ScheduledTime = $Time.ToString('HH:mm')
                RunAs = 'SYSTEM'
                ScriptPath = $scriptPath
                OutputPath = $OutputPath
                WebhookAlertEnabled = $webhookConfigured
                EmailAlertEnabled = $emailConfigured
                AlertDedupEnabled = $alertDedupEnabled
                RealertAfterDays = $RealertAfterDays
            }
        }
    }

    end {
        if ($null -ne $scanResult) {
            Write-Host "`n=== REGISTRATION COMPLETE ===" -ForegroundColor Green
            Write-Host "Task Name: $($scanResult.TaskName)" -ForegroundColor Cyan
            Write-Host "Action: $($scanResult.Action)" -ForegroundColor Cyan
            Write-Host "Status: $($scanResult.Status)" -ForegroundColor $(if ($scanResult.Status -in @('Registered', 'Unregistered')) { 'Green' } else { 'Yellow' })

            if ($null -ne $scanResult.PSObject.Properties['Frequency'] -and $scanResult.Action -eq 'Register') {
                Write-Host "Schedule: $($scanResult.Frequency) at $($scanResult.ScheduledTime)" -ForegroundColor Cyan
                Write-Host "Script: $($scanResult.ScriptPath)" -ForegroundColor Cyan
                Write-Host "Reports: $($scanResult.OutputPath)" -ForegroundColor Cyan
                Write-Host "Alert Dedup: $($scanResult.AlertDedupEnabled)" -ForegroundColor Cyan

                if ($scanResult.Status -eq 'Registered' -and -not $scanResult.WebhookAlertEnabled -and -not $scanResult.EmailAlertEnabled) {
                    Write-Warning "No alerting configured. Critical findings will be logged but no webhook or email alert will be sent."
                }
            }

            return $scanResult
        }
    }
}

# Non-exported helpers (module-internal; only the file basename is exported)

function Test-AdminOnlyOwnership {
    param([Parameter(Mandatory)][string]$Path)
    $acl = Get-Acl -Path $Path -ErrorAction Stop
    $allowedOwners = @('S-1-5-18', 'S-1-5-32-544', [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value)
    $ownerSid = $acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value
    return ($allowedOwners -contains $ownerSid)
}

function Test-NoNonAdminWriteAccess {
    param([Parameter(Mandatory)][string]$Path)
    $acl = Get-Acl -Path $Path -ErrorAction Stop
    $adminSids = @('S-1-5-18', 'S-1-5-32-544')
    $fsr = [System.Security.AccessControl.FileSystemRights]
    $writeMask = [int64]($fsr::WriteData -bor $fsr::AppendData -bor $fsr::WriteAttributes -bor $fsr::WriteExtendedAttributes -bor $fsr::Delete -bor $fsr::DeleteSubdirectoriesAndFiles -bor $fsr::ChangePermissions -bor $fsr::TakeOwnership) -bor 0x40000000 -bor 0x10000000
    $rules = @($acl.GetAccessRules($true, $true, [System.Security.Principal.SecurityIdentifier]))
    $foreign = @($rules | Where-Object {
        $_.AccessControlType -eq 'Allow' -and $adminSids -notcontains $_.IdentityReference.Value -and (([int64]$_.FileSystemRights -band $writeMask) -ne 0)
    })
    return ($foreign.Count -eq 0)
}