linux-scripts/ad-health-exporter.ps1

<#
.SYNOPSIS
    Active Directory Health Prometheus Metrics Exporter
.DESCRIPTION
    Prometheus exporter for Active Directory health. Monitors replication,
    FSMO roles, account hygiene, dcdiag tests, DNS SRV records, SYSVOL/NETLOGON
    accessibility, and domain controller metadata. Exports metrics as
    Prometheus-compatible text format for windows_exporter textfile collector.
.PARAMETER Mode
    Output mode: 'stdout' (default), 'textfile', or 'http'
.PARAMETER Port
    HTTP port for http mode (default: 9198)
.PARAMETER TextfileDir
    Directory for textfile collector output (default: C:\ProgramData\node_exporter)
.PARAMETER OutputFile
    Custom output file path
.PARAMETER InstallScheduledTask
    Switch to create a scheduled task for auto-start on system boot
.PARAMETER TaskIntervalMinutes
    Interval in minutes for the scheduled task (default: 5)
.NOTES
    Author:  Phil Connor
    Contact: contact@mylinux.work
    Website: https://mylinux.work
    License: MIT
    Version: 1.0

    Metrics Exported:
      Core Status:
        - windows_ad_up
        - windows_ad_exporter_info{version}

      Replication:
        - windows_ad_replication_failure_total{partner}
        - windows_ad_replication_last_success_timestamp{partner}
        - windows_ad_replication_pending_objects{partner}

      FSMO Roles:
        - windows_ad_fsmo_role_holder{role}

      Account Health:
        - windows_ad_account_lockout_total
        - windows_ad_account_disabled_total
        - windows_ad_account_expired_total
        - windows_ad_account_password_expired_total
        - windows_ad_account_inactive_total

      Computer Health:
        - windows_ad_computer_stale_total

      Group Health:
        - windows_ad_group_empty_total

      DCDiag:
        - windows_ad_dcdiag_test_result{test}

      DNS and Shares:
        - windows_ad_dns_srv_record_status
        - windows_ad_sysvol_accessible
        - windows_ad_netlogon_accessible

      Domain Controller Info:
        - windows_ad_domain_controller_info{domain,site,gc}

      Exporter:
        - windows_ad_exporter_duration_seconds
        - windows_ad_exporter_last_run_timestamp
#>

param(
    [ValidateSet('stdout', 'textfile', 'http')]
    [string]$Mode = 'stdout',

    [int]$Port = 9198,

    [string]$TextfileDir = 'C:\ProgramData\node_exporter',

    [string]$OutputFile,

    [switch]$InstallScheduledTask,

    [int]$TaskIntervalMinutes = 5
)

# Create a scheduled task to run this script every $TaskIntervalMinutes minutes
# The task will run as SYSTEM and will be set to run at startup
if ($InstallScheduledTask) {
    $taskName = "ADHealthExporter"
    $existingTask = Get-ScheduledTask -TaskName $taskName -ErrorAction SilentlyContinue

    if (-not $existingTask) {
        $taskAction = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-NoProfile -ExecutionPolicy Bypass -File `"$($MyInvocation.MyCommand.Path)`" -Mode textfile"

        if (-not $TaskIntervalMinutes -or $TaskIntervalMinutes -le 0) {
            throw "TaskIntervalMinutes must be a positive integer"
        }

        $taskTrigger = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes(1) -RepetitionInterval (New-TimeSpan -Minutes $TaskIntervalMinutes) -RepetitionDuration (New-TimeSpan -Days 365)
        $taskPrincipal = New-ScheduledTaskPrincipal -UserId "SYSTEM" -LogonType ServiceAccount -RunLevel Highest

        try {
            Write-Host "Creating scheduled task: $taskName"
            Register-ScheduledTask -TaskName $taskName -Action $taskAction -Trigger $taskTrigger -Principal $taskPrincipal -Description "Exports Active Directory health metrics for Prometheus every $TaskIntervalMinutes minutes"

            $createdTask = Get-ScheduledTask -TaskName $taskName -ErrorAction SilentlyContinue
            if (-not $createdTask) {
                throw "Failed to verify scheduled task creation"
            }
            Write-Host "Successfully created scheduled task: $taskName" -ForegroundColor Green
        } catch {
            Write-Error "Failed to create auto-start task: $($_.Exception.Message)"
            throw
        }
    } else {
        Write-Host "Scheduled task '$taskName' already exists, skipping creation"
    }
}

$ErrorActionPreference = 'SilentlyContinue'

# ============================================================================
# HELPER FUNCTIONS
# ============================================================================

function Get-UnixTimestamp {
    [int][double]::Parse((Get-Date -UFormat '%s'))
}

function Format-MetricValue {
    param([double]$Value, [int]$Decimals = 2)
    [math]::Round($Value, $Decimals)
}

function Sanitize-LabelValue {
    param([string]$Value)
    $Value -replace '\\', '\\\\' -replace '"', '\\"' -replace "`n", '\\n'
}

# ============================================================================
# REPLICATION METRICS
# ============================================================================

function Get-ReplicationMetrics {
    $sb = [System.Text.StringBuilder]::new()

    try {
        $partners = Get-ADReplicationPartnerMetadata -Target * -ErrorAction Stop

        [void]$sb.AppendLine('# HELP windows_ad_replication_failure_total Replication failures per partner')
        [void]$sb.AppendLine('# TYPE windows_ad_replication_failure_total gauge')
        foreach ($p in $partners) {
            $partnerName = Sanitize-LabelValue ($p.Partner -replace '^CN=NTDS Settings,CN=', '' -replace ',.*$', '')
            $failures = if ($p.ConsecutiveReplicationFailures) { $p.ConsecutiveReplicationFailures } else { 0 }
            [void]$sb.AppendLine("windows_ad_replication_failure_total{partner=`"$partnerName`"} $failures")
        }
        [void]$sb.AppendLine('')

        [void]$sb.AppendLine('# HELP windows_ad_replication_last_success_timestamp Last successful replication per partner (unix timestamp)')
        [void]$sb.AppendLine('# TYPE windows_ad_replication_last_success_timestamp gauge')
        foreach ($p in $partners) {
            $partnerName = Sanitize-LabelValue ($p.Partner -replace '^CN=NTDS Settings,CN=', '' -replace ',.*$', '')
            $ts = 0
            if ($p.LastReplicationSuccess) {
                $epoch = [datetime]'1970-01-01'
                $ts = [int]($p.LastReplicationSuccess.ToUniversalTime() - $epoch).TotalSeconds
            }
            [void]$sb.AppendLine("windows_ad_replication_last_success_timestamp{partner=`"$partnerName`"} $ts")
        }
        [void]$sb.AppendLine('')

        [void]$sb.AppendLine('# HELP windows_ad_replication_pending_objects Pending replication objects per partner')
        [void]$sb.AppendLine('# TYPE windows_ad_replication_pending_objects gauge')
        foreach ($p in $partners) {
            $partnerName = Sanitize-LabelValue ($p.Partner -replace '^CN=NTDS Settings,CN=', '' -replace ',.*$', '')
            $pending = if ($p.InboundNeighbors) {
                ($p.InboundNeighbors | Measure-Object -Property EstimatedChanges -Sum).Sum
            } else { 0 }
            if (-not $pending) { $pending = 0 }
            [void]$sb.AppendLine("windows_ad_replication_pending_objects{partner=`"$partnerName`"} $pending")
        }
        [void]$sb.AppendLine('')
    }
    catch {
        Write-Warning "Failed to collect replication metrics: $_"
        [void]$sb.AppendLine('# HELP windows_ad_replication_failure_total Replication failures per partner')
        [void]$sb.AppendLine('# TYPE windows_ad_replication_failure_total gauge')
        [void]$sb.AppendLine('')
    }

    $sb.ToString()
}

# ============================================================================
# FSMO ROLE METRICS
# ============================================================================

function Get-FsmoRoleMetrics {
    $sb = [System.Text.StringBuilder]::new()

    try {
        $domain = Get-ADDomain -ErrorAction Stop
        $forest = Get-ADForest -ErrorAction Stop
        $localDC = $env:COMPUTERNAME

        $fsmoRoles = @{
            'PDCEmulator'          = $domain.PDCEmulator
            'RIDMaster'            = $domain.RIDMaster
            'InfrastructureMaster' = $domain.InfrastructureMaster
            'SchemaMaster'         = $forest.SchemaMaster
            'DomainNamingMaster'   = $forest.DomainNamingMaster
        }

        [void]$sb.AppendLine('# HELP windows_ad_fsmo_role_holder FSMO role holder (1 if this DC holds the role)')
        [void]$sb.AppendLine('# TYPE windows_ad_fsmo_role_holder gauge')
        foreach ($role in $fsmoRoles.GetEnumerator()) {
            $holdsRole = if ($role.Value -match "^$localDC(\.|$)") { 1 } else { 0 }
            [void]$sb.AppendLine("windows_ad_fsmo_role_holder{role=`"$($role.Key)`"} $holdsRole")
        }
        [void]$sb.AppendLine('')
    }
    catch {
        Write-Warning "Failed to collect FSMO role metrics: $_"
        [void]$sb.AppendLine('# HELP windows_ad_fsmo_role_holder FSMO role holder (1 if this DC holds the role)')
        [void]$sb.AppendLine('# TYPE windows_ad_fsmo_role_holder gauge')
        [void]$sb.AppendLine('')
    }

    $sb.ToString()
}

# ============================================================================
# ACCOUNT HEALTH METRICS
# ============================================================================

function Get-AccountHealthMetrics {
    $sb = [System.Text.StringBuilder]::new()

    try {
        # Locked out accounts
        $lockedOut = @(Search-ADAccount -LockedOut -ErrorAction Stop).Count
        [void]$sb.AppendLine('# HELP windows_ad_account_lockout_total Number of locked out accounts')
        [void]$sb.AppendLine('# TYPE windows_ad_account_lockout_total gauge')
        [void]$sb.AppendLine("windows_ad_account_lockout_total $lockedOut")
        [void]$sb.AppendLine('')

        # Disabled accounts
        $disabled = @(Search-ADAccount -AccountDisabled -ErrorAction Stop).Count
        [void]$sb.AppendLine('# HELP windows_ad_account_disabled_total Number of disabled accounts')
        [void]$sb.AppendLine('# TYPE windows_ad_account_disabled_total gauge')
        [void]$sb.AppendLine("windows_ad_account_disabled_total $disabled")
        [void]$sb.AppendLine('')

        # Expired accounts
        $expired = @(Search-ADAccount -AccountExpired -ErrorAction Stop).Count
        [void]$sb.AppendLine('# HELP windows_ad_account_expired_total Number of expired accounts')
        [void]$sb.AppendLine('# TYPE windows_ad_account_expired_total gauge')
        [void]$sb.AppendLine("windows_ad_account_expired_total $expired")
        [void]$sb.AppendLine('')

        # Password expired accounts
        $pwdExpired = @(Search-ADAccount -PasswordExpired -ErrorAction Stop).Count
        [void]$sb.AppendLine('# HELP windows_ad_account_password_expired_total Accounts with expired passwords')
        [void]$sb.AppendLine('# TYPE windows_ad_account_password_expired_total gauge')
        [void]$sb.AppendLine("windows_ad_account_password_expired_total $pwdExpired")
        [void]$sb.AppendLine('')

        # Inactive accounts (no logon in 90 days)
        $inactive = @(Search-ADAccount -AccountInactive -TimeSpan (New-TimeSpan -Days 90) -UsersOnly -ErrorAction Stop).Count
        [void]$sb.AppendLine('# HELP windows_ad_account_inactive_total Accounts inactive for more than 90 days')
        [void]$sb.AppendLine('# TYPE windows_ad_account_inactive_total gauge')
        [void]$sb.AppendLine("windows_ad_account_inactive_total $inactive")
        [void]$sb.AppendLine('')
    }
    catch {
        Write-Warning "Failed to collect account health metrics: $_"
    }

    $sb.ToString()
}

# ============================================================================
# COMPUTER HEALTH METRICS
# ============================================================================

function Get-ComputerHealthMetrics {
    $sb = [System.Text.StringBuilder]::new()

    try {
        $staleComputers = @(Search-ADAccount -AccountInactive -TimeSpan (New-TimeSpan -Days 90) -ComputersOnly -ErrorAction Stop).Count
        [void]$sb.AppendLine('# HELP windows_ad_computer_stale_total Computers not logged in for more than 90 days')
        [void]$sb.AppendLine('# TYPE windows_ad_computer_stale_total gauge')
        [void]$sb.AppendLine("windows_ad_computer_stale_total $staleComputers")
        [void]$sb.AppendLine('')
    }
    catch {
        Write-Warning "Failed to collect computer health metrics: $_"
    }

    $sb.ToString()
}

# ============================================================================
# GROUP HEALTH METRICS
# ============================================================================

function Get-GroupHealthMetrics {
    $sb = [System.Text.StringBuilder]::new()

    try {
        $allGroups = Get-ADGroup -Filter { GroupCategory -eq 'Security' } -Properties Members -ErrorAction Stop
        $emptyGroups = @($allGroups | Where-Object { $_.Members.Count -eq 0 }).Count
        [void]$sb.AppendLine('# HELP windows_ad_group_empty_total Empty security groups')
        [void]$sb.AppendLine('# TYPE windows_ad_group_empty_total gauge')
        [void]$sb.AppendLine("windows_ad_group_empty_total $emptyGroups")
        [void]$sb.AppendLine('')
    }
    catch {
        Write-Warning "Failed to collect group health metrics: $_"
    }

    $sb.ToString()
}

# ============================================================================
# DCDIAG METRICS
# ============================================================================

function Get-DcdiagMetrics {
    $sb = [System.Text.StringBuilder]::new()

    try {
        $tests = @('Connectivity', 'Replications', 'DNS', 'Services', 'Advertising', 'FrsEvent', 'KccEvent')

        [void]$sb.AppendLine('# HELP windows_ad_dcdiag_test_result DCDiag test result (1=pass, 0=fail)')
        [void]$sb.AppendLine('# TYPE windows_ad_dcdiag_test_result gauge')

        foreach ($test in $tests) {
            try {
                $output = dcdiag /test:$test 2>&1 | Out-String
                $passed = if ($output -match "passed test $test") { 1 } else { 0 }
                [void]$sb.AppendLine("windows_ad_dcdiag_test_result{test=`"$test`"} $passed")
            }
            catch {
                [void]$sb.AppendLine("windows_ad_dcdiag_test_result{test=`"$test`"} 0")
            }
        }
        [void]$sb.AppendLine('')
    }
    catch {
        Write-Warning "Failed to collect dcdiag metrics: $_"
        [void]$sb.AppendLine('# HELP windows_ad_dcdiag_test_result DCDiag test result (1=pass, 0=fail)')
        [void]$sb.AppendLine('# TYPE windows_ad_dcdiag_test_result gauge')
        [void]$sb.AppendLine('')
    }

    $sb.ToString()
}

# ============================================================================
# DNS AND SHARE ACCESSIBILITY METRICS
# ============================================================================

function Get-DnsAndShareMetrics {
    $sb = [System.Text.StringBuilder]::new()

    try {
        # DNS SRV record check
        $domain = (Get-ADDomain -ErrorAction Stop).DNSRoot
        $srvOk = 0
        try {
            $srvResult = Resolve-DnsName -Name "_ldap._tcp.dc._msdcs.$domain" -Type SRV -ErrorAction Stop
            if ($srvResult) { $srvOk = 1 }
        } catch {}

        [void]$sb.AppendLine('# HELP windows_ad_dns_srv_record_status DNS SRV record health (1=OK, 0=missing)')
        [void]$sb.AppendLine('# TYPE windows_ad_dns_srv_record_status gauge')
        [void]$sb.AppendLine("windows_ad_dns_srv_record_status $srvOk")
        [void]$sb.AppendLine('')
    }
    catch {
        Write-Warning "Failed to check DNS SRV records: $_"
        [void]$sb.AppendLine('# HELP windows_ad_dns_srv_record_status DNS SRV record health (1=OK, 0=missing)')
        [void]$sb.AppendLine('# TYPE windows_ad_dns_srv_record_status gauge')
        [void]$sb.AppendLine("windows_ad_dns_srv_record_status 0")
        [void]$sb.AppendLine('')
    }

    # SYSVOL accessibility
    try {
        $dcName = $env:COMPUTERNAME
        $sysvolOk = if (Test-Path "\\$dcName\SYSVOL") { 1 } else { 0 }
    }
    catch {
        $sysvolOk = 0
    }
    [void]$sb.AppendLine('# HELP windows_ad_sysvol_accessible SYSVOL share accessibility (1=OK, 0=fail)')
    [void]$sb.AppendLine('# TYPE windows_ad_sysvol_accessible gauge')
    [void]$sb.AppendLine("windows_ad_sysvol_accessible $sysvolOk")
    [void]$sb.AppendLine('')

    # NETLOGON accessibility
    try {
        $netlogonOk = if (Test-Path "\\$dcName\NETLOGON") { 1 } else { 0 }
    }
    catch {
        $netlogonOk = 0
    }
    [void]$sb.AppendLine('# HELP windows_ad_netlogon_accessible NETLOGON share accessibility (1=OK, 0=fail)')
    [void]$sb.AppendLine('# TYPE windows_ad_netlogon_accessible gauge')
    [void]$sb.AppendLine("windows_ad_netlogon_accessible $netlogonOk")
    [void]$sb.AppendLine('')

    $sb.ToString()
}

# ============================================================================
# DOMAIN CONTROLLER INFO
# ============================================================================

function Get-DomainControllerInfoMetrics {
    $sb = [System.Text.StringBuilder]::new()

    try {
        $dc = Get-ADDomainController -ErrorAction Stop
        $domainName = Sanitize-LabelValue $dc.Domain
        $siteName = Sanitize-LabelValue $dc.Site
        $isGC = if ($dc.IsGlobalCatalog) { "true" } else { "false" }

        [void]$sb.AppendLine('# HELP windows_ad_domain_controller_info Domain controller metadata')
        [void]$sb.AppendLine('# TYPE windows_ad_domain_controller_info gauge')
        [void]$sb.AppendLine("windows_ad_domain_controller_info{domain=`"$domainName`",site=`"$siteName`",gc=`"$isGC`"} 1")
        [void]$sb.AppendLine('')
    }
    catch {
        Write-Warning "Failed to collect domain controller info: $_"
        [void]$sb.AppendLine('# HELP windows_ad_domain_controller_info Domain controller metadata')
        [void]$sb.AppendLine('# TYPE windows_ad_domain_controller_info gauge')
        [void]$sb.AppendLine('')
    }

    $sb.ToString()
}

# ============================================================================
# COLLECT ALL METRICS
# ============================================================================

function Get-AllMetrics {
    $scriptStart = Get-Date
    $sb = [System.Text.StringBuilder]::new()

    # Exporter up
    [void]$sb.AppendLine('# HELP windows_ad_up Exporter status (1=up, 0=down)')
    [void]$sb.AppendLine('# TYPE windows_ad_up gauge')
    [void]$sb.AppendLine('windows_ad_up 1')
    [void]$sb.AppendLine('')

    # Exporter info
    [void]$sb.AppendLine('# HELP windows_ad_exporter_info Exporter version information')
    [void]$sb.AppendLine('# TYPE windows_ad_exporter_info gauge')
    [void]$sb.AppendLine('windows_ad_exporter_info{version="1.0"} 1')
    [void]$sb.AppendLine('')

    # Collect all sections
    [void]$sb.Append((Get-ReplicationMetrics))
    [void]$sb.Append((Get-FsmoRoleMetrics))
    [void]$sb.Append((Get-AccountHealthMetrics))
    [void]$sb.Append((Get-ComputerHealthMetrics))
    [void]$sb.Append((Get-GroupHealthMetrics))
    [void]$sb.Append((Get-DcdiagMetrics))
    [void]$sb.Append((Get-DnsAndShareMetrics))
    [void]$sb.Append((Get-DomainControllerInfoMetrics))

    # Exporter runtime
    $scriptEnd = Get-Date
    $duration = Format-MetricValue ($scriptEnd - $scriptStart).TotalSeconds
    $timestamp = Get-UnixTimestamp

    [void]$sb.AppendLine('# HELP windows_ad_exporter_duration_seconds Time to generate all metrics')
    [void]$sb.AppendLine('# TYPE windows_ad_exporter_duration_seconds gauge')
    [void]$sb.AppendLine("windows_ad_exporter_duration_seconds $duration")
    [void]$sb.AppendLine('')
    [void]$sb.AppendLine('# HELP windows_ad_exporter_last_run_timestamp Unix timestamp of last successful run')
    [void]$sb.AppendLine('# TYPE windows_ad_exporter_last_run_timestamp gauge')
    [void]$sb.AppendLine("windows_ad_exporter_last_run_timestamp $timestamp")
    [void]$sb.AppendLine('')

    $sb.ToString()
}

# ============================================================================
# HTTP SERVER MODE
# ============================================================================

function Start-HttpServer {
    param([int]$ListenPort)

    $prefix = "http://+:$ListenPort/"
    $listener = [System.Net.HttpListener]::new()
    $listener.Prefixes.Add($prefix)

    try {
        $listener.Start()
        Write-Host "Starting Active Directory health exporter on port $ListenPort..." -ForegroundColor Green
        Write-Host "Metrics available at http://localhost:$ListenPort/metrics"

        while ($listener.IsListening) {
            $context  = $listener.GetContext()
            $request  = $context.Request
            $response = $context.Response

            if ($request.Url.AbsolutePath -eq '/metrics') {
                $metrics = Get-AllMetrics
                $buffer  = [System.Text.Encoding]::UTF8.GetBytes($metrics)
                $response.ContentType = 'text/plain; version=0.0.4; charset=utf-8'
            }
            else {
                $html = @"
<!DOCTYPE html>
<html>
<head><title>AD Health Exporter v1.0</title></head>
<body>
<h1>Active Directory Health Exporter v1.0</h1>
<p><a href="/metrics">Metrics</a></p>
<h2>Sections</h2>
<ul>
<li>Replication health (failures, last success, pending objects)</li>
<li>FSMO role holders</li>
<li>Account health (locked, disabled, expired, inactive)</li>
<li>Computer health (stale computers)</li>
<li>Group health (empty security groups)</li>
<li>DCDiag test results</li>
<li>DNS SRV records and share accessibility</li>
<li>Domain controller metadata</li>
</ul>
</body>
</html>
"@
                $buffer = [System.Text.Encoding]::UTF8.GetBytes($html)
                $response.ContentType = 'text/html; charset=utf-8'
            }

            $response.ContentLength64 = $buffer.Length
            $response.OutputStream.Write($buffer, 0, $buffer.Length)
            $response.OutputStream.Close()
        }
    }
    catch {
        Write-Error "HTTP server error: $_"
        Write-Error "If access denied, run: netsh http add urlacl url=http://+:$ListenPort/ user=Everyone"
    }
    finally {
        if ($listener.IsListening) {
            $listener.Stop()
        }
    }
}

# ============================================================================
# MAIN EXECUTION
# ============================================================================

switch ($Mode) {
    'http' {
        Start-HttpServer -ListenPort $Port
    }
    'textfile' {
        if (-not $OutputFile) {
            $OutputFile = Join-Path $TextfileDir 'windows_ad_health.prom'
        }

        $outputDir = Split-Path $OutputFile -Parent
        if (-not (Test-Path $outputDir)) {
            New-Item -Path $outputDir -ItemType Directory -Force | Out-Null
        }

        $tempFile = Join-Path $outputDir ".windows_ad_health_metrics.$PID.tmp"

        try {
            $metrics = Get-AllMetrics
            $metrics | Out-File -FilePath $tempFile -Encoding utf8 -NoNewline

            $lineCount = ($metrics -split "`n").Count
            if ($lineCount -lt 10) {
                Remove-Item -Path $tempFile -Force -ErrorAction SilentlyContinue
                Write-Error "Metrics file too small ($lineCount lines), keeping previous"
                exit 1
            }

            Move-Item -Path $tempFile -Destination $OutputFile -Force
            Write-Host "Metrics written to $OutputFile ($lineCount lines)" -ForegroundColor Green
        }
        catch {
            Remove-Item -Path $tempFile -Force -ErrorAction SilentlyContinue
            Write-Error "Failed to generate metrics: $_"
            exit 1
        }
    }
    default {
        Get-AllMetrics | Write-Output
    }
}