Get-S1AgentHealthReport.ps1

<#
.SYNOPSIS
    Generates a comprehensive agent health report covering pending actions, missing
    permissions, and operational state across all agents in the environment.

.DESCRIPTION
    Queries GET /web/api/v2.1/agents and aggregates the userActionsNeeded,
    missingPermissions, and operationalState fields for every agent.

    The report produces:
      - Operational State breakdown (Not Disabled, Limited Functionality, Disabled by S1, etc.)
      - Pending Actions breakdown (Attention Needed, Missing Permission, Unprotected, etc.)
      - Missing Permissions breakdown (FDA, Remote Shell, Network Extension, etc.)
      - Issues summary per client
      - Details by agent

.PARAMETER BaseUrl
    SentinelOne console URL (e.g. "https://usea1-swprd1.sentinelone.net")

.PARAMETER ApiToken
    SentinelOne API token.

.PARAMETER ClientName
    Optional. Filter results to a specific client/site by fuzzy name match.

.PARAMETER ExportFormat
    Output format: Console | CSV | JSON | HTML | All
    Default: HTML

.PARAMETER OutputPath
    Directory for exported files. Default: current directory.

.PARAMETER HealthyOnly
    Switch. When set, shows ONLY agents with no health issues.

.EXAMPLE
    .\Get-S1AgentHealthReport.ps1 -ExportFormat All -ClientName "Contoso"

.EXAMPLE
    .\Get-S1AgentHealthReport.ps1 -ExportFormat HTML

.NOTES
    Author: Geoff Tankersley
    Version: 1.0
#>

[CmdletBinding()]
param (
    [Parameter(Mandatory = $false)]
    [string]$BaseUrl,

    [Parameter(Mandatory = $false)]
    [string]$ApiToken,

    [Parameter(Mandatory = $false)]
    [string]$ClientName,

    [Parameter(Mandatory = $false)]
    [ValidateSet("Console", "CSV", "JSON", "HTML", "All")]
    [string]$OutputFormat = "HTML",

    [Parameter(Mandatory = $false)]
    [string]$OutputPath = ".",

    [Parameter(Mandatory = $false)]
    [switch]$HealthyOnly
)

Set-StrictMode -Off
$ErrorActionPreference = "Stop"
$ProgressPreference    = "SilentlyContinue"
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

$BaseUrl = $BaseUrl.TrimEnd('/')

# Label mappings
$OperationalStateLabels = @{
    'disabled_error'              = 'Agent Disable Error'
    'disabled_s1'                 = 'Disabled by SentinelOne'
    'disabled_user'               = 'Disabled Completely by User'
    'disabled_user_not_restarted' = 'Disabled - Not Rebooted Yet'
    'fully_disabled'              = 'Disabled Completely by User'
    'auto_fully_disabled'         = 'Auto Fully Disabled'
    'db_corruption'               = 'DB Corruption'
    'limited'                     = 'Limited Functionality: Agent Data Expired'
    'na'                          = 'Not Disabled'
    'none'                        = 'Not Disabled'
    ''                            = 'Not Disabled'
}

$PendingActionLabels = @{
    'user_action_needed_reboot_required'    = 'Reboot Required'
    'user_action_needed_reboot_agent'       = 'Reboot Required'
    'user_action_needed_reboot_needed'      = 'Reboot Needed'
    'reboot_needed'                         = 'Reboot Needed'
    'user_action_needed_unprotected'        = 'Unprotected'
    'user_action_needed_incompatible_os'    = 'Incompatible OS'
    'user_action_needed_agent_suppressed'   = 'Agent Suppressed'
    'user_action_needed_missing_permission' = 'Missing Permission'
    'user_action_needed_fda'                = 'Missing Permission'
    'user_action_needed_rs_fda'             = 'Missing Permission'
    'user_action_needed_fda_helper'         = 'Missing Permission'
    'user_action_needed_fda_sentineld'      = 'Missing Permission'
    'user_action_needed_bluetooth_per'      = 'Missing Permission'
    'user_action_needed_network'            = 'Missing Permission'
    'user_action_needed_notifications'      = 'Missing Permission'
    'attention_needed'                      = 'Attention Needed'
    'ne_cf_not_active'                      = 'Network Extension Config Not Active'
    'ne_not_running'                        = 'Network Extension Not Running'
    'extended_exclusions_partially_accepted' = 'Extended Exclusions Partially Accepted'
    'pending_deprecation'                   = 'Pending Deprecation'
    'auto_fully_disabled'                   = 'Auto Fully Disabled'
    'db_corruption'                         = 'DB Corruption'
}

$MissingPermissionLabels = @{
    'user_action_needed_fda'           = 'FDA - Sentinel Agent'
    'user_action_needed_rs_fda'        = 'FDA - Remote Shell'
    'user_action_needed_fda_helper'    = 'FDA - Sentinel Agent Helper'
    'user_action_needed_fda_sentineld' = 'FDA - Sentinel Agent Detection'
    'user_action_needed_bluetooth_per' = 'Bluetooth Permission'
    'user_action_needed_network'       = 'Network Extension'
    'user_action_needed_notifications' = 'Agent Notifications'
}

function Get-FriendlyLabel {
    param([hashtable]$Map, [string]$Key)
    if ($null -eq $Key -or $Key -eq "") { return "" }
    $k = $Key.ToLower().Trim()
    if ($Map.ContainsKey($k))   { return $Map[$k] }
    if ($Map.ContainsKey($Key)) { return $Map[$Key] }
    $words = $Key -replace '_', ' '
    return (Get-Culture).TextInfo.ToTitleCase($words.ToLower())
}

# functions
function Write-Log {
    param([string]$Message, [string]$Level = "Info")
    $colors = @{ Info = "White"; Success = "Green"; Warning = "Yellow"; Error = "Red" }
    $ts = Get-Date -Format "HH:mm:ss"
    Write-Host "[$ts][$Level] $Message" -ForegroundColor $colors[$Level]
}

function New-Headers {
    param([string]$Token)
    return @{
        "Authorization" = "ApiToken $Token"
        "Content-Type"  = "application/json"
        "Accept"        = "*/*"
    }
}

function Invoke-S1Api {
    param([string]$Url, [hashtable]$Headers)
    try {
        return Invoke-RestMethod -Uri $Url -Method GET -Headers $Headers -TimeoutSec 90
    } catch {
        Write-Log "API error on $Url - $($_.Exception.Message)" -Level Warning
        return $null
    }
}
function Get-SiteLookup {
    param([string]$BaseUrl, [hashtable]$Headers)
    $lookup = @{}
    $cursor = $null
    do {
        $url  = "$BaseUrl/web/api/v2.1/sites?limit=1000$(if($cursor){"&cursor=$cursor"})"
        $resp = Invoke-S1Api -Url $url -Headers $Headers
        if ($resp -and $resp.data.sites) {
            foreach ($s in $resp.data.sites) {
                $lookup[$s.id] = @{
                    SiteName    = if ($s.name)        { $s.name }        else { "Unknown Site" }
                    AccountName = if ($s.accountName) { $s.accountName } else { "Unknown Account" }
                }
            }
        }
        $cursor = if ($resp) { $resp.pagination.nextCursor } else { $null }
    } while ($cursor)
        return $lookup
}

function Resolve-ClientSiteIds {
    param([hashtable]$Lookup, [string]$Pattern)
    $ids = @()
    foreach ($kv in $Lookup.GetEnumerator()) {
        $sn = $kv.Value.SiteName
        # Extract client name from site name
        if ($sn -match '^(.+?)\s*\([^)]+\)\s*$') { $cn = $Matches[1].Trim() } else { $cn = $sn }
        if ($sn -like "*$Pattern*" -or $cn -like "*$Pattern*") { $ids += $kv.Key }
    }
    return $ids
}

function Get-AllAgents {
    param(
        [string]$BaseUrl,
        [hashtable]$Headers,
        [string[]]$SiteIds
    )

    $all    = [System.Collections.Generic.List[object]]::new()
    $cursor = $null
    $page   = 0

    do {
        $page++
        $params = "limit=1000"
        if ($cursor)  { $params += "&cursor=$cursor" }
        if ($SiteIds -and $SiteIds.Count -gt 0) {
            $params += "&siteIds=$($SiteIds -join ',')"
        }

        $url  = "$BaseUrl/web/api/v2.1/agents?$params"
        $resp = Invoke-S1Api -Url $url -Headers $Headers

        if ($resp -and $resp.data -and $resp.data.Count -gt 0) {
            foreach ($a in $resp.data) { $all.Add($a) }
        }

        $cursor = if ($resp) { $resp.pagination.nextCursor } else { $null }
    } while ($cursor)

    return $all
}

function ConvertTo-ReportRow {
    param($Agent, [hashtable]$SiteLookup)

    $siteId   = $Agent.siteId
    $siteName = if ($SiteLookup.ContainsKey($siteId)) { $SiteLookup[$siteId].SiteName } else { $Agent.siteName }
    # Extract client name from site name by stripping trailing site code e.g. "Acme Corp (ACM001)" -> "Acme Corp"
    # accountName in MSSP environments returns an internal partner key, not a human-readable name
    if ($siteName -match '^(.+?)\s*\([^)]+\)\s*$') {
        $clientName = $Matches[1].Trim()
    } else {
        $clientName = $siteName
    }

    $rawOpState = if ($Agent.operationalState) { $Agent.operationalState } else { "na" }
    $friendlyOp = Get-FriendlyLabel -Map $OperationalStateLabels -Key $rawOpState
    $isHealthy  = ($rawOpState -in @('na', 'none', '', $null))

    $rawPerms = @()
    if ($Agent.missingPermissions) {
        $rawPerms = @($Agent.missingPermissions | ForEach-Object { "$_" } | Where-Object { $_ })
    }
    $friendlyPerms = $rawPerms | ForEach-Object { Get-FriendlyLabel -Map $MissingPermissionLabels -Key "$_" }

    $rawActions = @()
    if ($Agent.userActionsNeeded) {
        $rawActions = @($Agent.userActionsNeeded | ForEach-Object { "$_" } | Where-Object { $_ })
    }
    $friendlyActions = @($rawActions | ForEach-Object { Get-FriendlyLabel -Map $PendingActionLabels -Key "$_" } | Select-Object -Unique)

    $hasIssue = (-not $isHealthy) -or ($rawPerms.Count -gt 0) -or ($rawActions.Count -gt 0)

    [PSCustomObject]@{
        ComputerName        = $Agent.computerName
        ClientName          = $clientName
        SiteName            = $siteName
        OS                  = if ($Agent.osName) { $Agent.osName } else { $Agent.osType }
        AgentVersion        = $Agent.agentVersion
        NetworkStatus       = $Agent.networkStatus
        OperationalState    = $friendlyOp
        OperationalStateRaw = $rawOpState
        PendingActions      = if ($friendlyActions.Count -gt 0) { $friendlyActions -join "; " } else { "" }
        MissingPermissions  = if ($friendlyPerms.Count -gt 0)   { $friendlyPerms -join "; " }   else { "" }
        MissingPermCount    = $rawPerms.Count
        PendingActionCount  = $rawActions.Count
        HasIssue            = $hasIssue
        IsHealthy           = -not $hasIssue
        LastSeen            = if ($Agent.lastActiveDate) {
                                  try { [datetime]::Parse($Agent.lastActiveDate).ToString("yyyy-MM-dd HH:mm") } catch { $Agent.lastActiveDate }
                              } else { "N/A" }
        AgentId             = $Agent.id
        SiteId              = $siteId
    }
}

function Write-ConsoleReport {
    param([object[]]$Rows, [string]$ReportTitle)

    $issues  = $Rows | Where-Object { $_.HasIssue }
    $healthy = $Rows | Where-Object { $_.IsHealthy }

    Write-Host ""
    Write-Host ("=" * 70) -ForegroundColor Cyan
    Write-Host "  $ReportTitle" -ForegroundColor Cyan
    Write-Host "  Generated: $(Get-Date -Format 'yyyy-MM-dd HH:mm')" -ForegroundColor Gray
    Write-Host ("=" * 70) -ForegroundColor Cyan

    Write-Host ""
    Write-Host "SUMMARY" -ForegroundColor Yellow
    Write-Host ("-" * 40) -ForegroundColor Gray
    Write-Host "  Total Agents        : $($Rows.Count)"
    Write-Host "  Agents with Issues  : $($issues.Count)" -ForegroundColor $(if ($issues.Count -gt 0) { "Red" } else { "Green" })
    Write-Host "  Healthy Agents      : $($healthy.Count)" -ForegroundColor Green

    Write-Host ""
    Write-Host "OPERATIONAL STATE BREAKDOWN" -ForegroundColor Yellow
    Write-Host ("-" * 40) -ForegroundColor Gray
    $Rows | Group-Object OperationalState | Sort-Object Count -Descending | ForEach-Object {
        $color = if ($_.Name -eq 'Not Disabled') { "Green" } else { "Red" }
        Write-Host ("  {0,-45} {1,6}" -f $_.Name, $_.Count) -ForegroundColor $color
    }

    $withActions = $Rows | Where-Object { $_.PendingActions -ne "" }
    Write-Host ""
    Write-Host "PENDING ACTIONS  ($($withActions.Count) agents affected)" -ForegroundColor Yellow
    Write-Host ("-" * 40) -ForegroundColor Gray
    if ($withActions.Count -gt 0) {
        $actionCounts = @{}
        foreach ($r in $withActions) {
            foreach ($a in ($r.PendingActions -split "; ")) {
                if ($a) { $actionCounts[$a] = ($actionCounts[$a] -as [int]) + 1 }
            }
        }
        $actionCounts.GetEnumerator() | Sort-Object Value -Descending | ForEach-Object {
            Write-Host ("  {0,-45} {1,6}" -f $_.Key, $_.Value) -ForegroundColor Red
        }
    } else {
        Write-Host "  No pending actions found." -ForegroundColor Green
    }

    $withPerms = $Rows | Where-Object { $_.MissingPermissions -ne "" }
    Write-Host ""
    Write-Host "MISSING PERMISSIONS  ($($withPerms.Count) agents affected)" -ForegroundColor Yellow
    Write-Host ("-" * 40) -ForegroundColor Gray
    if ($withPerms.Count -gt 0) {
        $permCounts = @{}
        foreach ($r in $withPerms) {
            foreach ($p in ($r.MissingPermissions -split "; ")) {
                if ($p) { $permCounts[$p] = ($permCounts[$p] -as [int]) + 1 }
            }
        }
        $permCounts.GetEnumerator() | Sort-Object Value -Descending | ForEach-Object {
            Write-Host ("  {0,-45} {1,6}" -f $_.Key, $_.Value) -ForegroundColor Red
        }
    } else {
        Write-Host "  No missing permissions found." -ForegroundColor Green
    }

    Write-Host ""
    Write-Host "ISSUES BY CLIENT" -ForegroundColor Yellow
    Write-Host ("-" * 40) -ForegroundColor Gray
    $issues | Group-Object ClientName | Sort-Object Count -Descending | ForEach-Object {
        Write-Host ("  {0,-45} {1,6} agents with issues" -f $_.Name, $_.Count) -ForegroundColor Yellow
    }

    if ($issues.Count -gt 0) {
        Write-Host ""
        Write-Host "AGENT DETAIL (Issues Only)" -ForegroundColor Yellow
        Write-Host ("-" * 40) -ForegroundColor Gray
        $issues | Sort-Object ClientName, ComputerName |
            Format-Table ComputerName, ClientName, OperationalState, PendingActions, MissingPermissions, LastSeen -AutoSize -Wrap
    }
}

function Export-HtmlReport {
    param([object[]]$Rows, [string]$ReportTitle, [string]$OutputPath)

    $issues  = @($Rows | Where-Object { $_.HasIssue })
    $healthy = @($Rows | Where-Object { $_.IsHealthy })

    $opStateRows = $Rows | Group-Object OperationalState | Sort-Object Count -Descending | ForEach-Object {
        $color = if ($_.Name -eq 'Not Disabled') { '#22c55e' } else { '#f87171' }
        "<tr><td>$($_.Name)</td><td style='text-align:center;font-weight:bold;color:$color'>$($_.Count)</td></tr>"
    }

    $actionCounts = @{}
    foreach ($r in ($Rows | Where-Object { $_.PendingActions -ne "" })) {
        foreach ($a in ($r.PendingActions -split "; ")) {
            if ($a) { $actionCounts[$a] = ($actionCounts[$a] -as [int]) + 1 }
        }
    }
    $pendingRows = $actionCounts.GetEnumerator() | Sort-Object Value -Descending | ForEach-Object {
        "<tr><td>$($_.Key)</td><td style='text-align:center;font-weight:bold;color:#f87171'>$($_.Value)</td></tr>"
    }
    if (-not $pendingRows) { $pendingRows = "<tr><td colspan='2' style='color:#22c55e;text-align:center'>No pending actions</td></tr>" }

    $permCounts = @{}
    foreach ($r in ($Rows | Where-Object { $_.MissingPermissions -ne "" })) {
        foreach ($p in ($r.MissingPermissions -split "; ")) {
            if ($p) { $permCounts[$p] = ($permCounts[$p] -as [int]) + 1 }
        }
    }
    $permRows = $permCounts.GetEnumerator() | Sort-Object Value -Descending | ForEach-Object {
        "<tr><td>$($_.Key)</td><td style='text-align:center;font-weight:bold;color:#f87171'>$($_.Value)</td></tr>"
    }
    if (-not $permRows) { $permRows = "<tr><td colspan='2' style='color:#22c55e;text-align:center'>No missing permissions</td></tr>" }

    $clientRows = $issues | Group-Object ClientName | Sort-Object Count -Descending | ForEach-Object {
        $withPerms   = @($_.Group | Where-Object { $_.MissingPermissions -ne "" }).Count
        $withActions = @($_.Group | Where-Object { $_.PendingActions -ne "" }).Count
        $withOpIssue = @($_.Group | Where-Object { $_.OperationalStateRaw -notin @('na','none','') }).Count
        "<tr>
            <td>$($_.Name)</td>
            <td style='text-align:center'>$($_.Count)</td>
            <td style='text-align:center;color:$(if($withOpIssue -gt 0){"#f87171"}else{"#6b7280"})'>$withOpIssue</td>
            <td style='text-align:center;color:$(if($withActions -gt 0){"#fbbf24"}else{"#6b7280"})'>$withActions</td>
            <td style='text-align:center;color:$(if($withPerms -gt 0){"#f87171"}else{"#6b7280"})'>$withPerms</td>
        </tr>"
    }
    if (-not $clientRows) { $clientRows = "<tr><td colspan='5' style='color:#22c55e;text-align:center'>No issues found</td></tr>" }

    $agentDetailRows = $issues | Sort-Object ClientName, ComputerName | ForEach-Object {
        $opColor = if ($_.OperationalStateRaw -notin @('na','none','')) { "#f87171" } else { "#22c55e" }
        "<tr>
            <td>$($_.ComputerName)</td>
            <td>$($_.ClientName)</td>
            <td>$($_.OS)</td>
            <td style='color:$opColor'>$($_.OperationalState)</td>
            <td style='color:$(if($_.PendingActions){"#fbbf24"}else{"#6b7280"})'>$(if($_.PendingActions){$_.PendingActions}else{"&mdash;"})</td>
            <td style='color:$(if($_.MissingPermissions){"#f87171"}else{"#6b7280"})'>$(if($_.MissingPermissions){$_.MissingPermissions}else{"&mdash;"})</td>
            <td>$($_.LastSeen)</td>
        </tr>"
    }
    if (-not $agentDetailRows) {
        $agentDetailRows = "<tr><td colspan='7' style='color:#22c55e;text-align:center'>No agents with issues found</td></tr>"
    }

    $healthPct = if ($Rows.Count -gt 0) { [math]::Round(($healthy.Count / $Rows.Count) * 100, 1) } else { 0 }
    $issuePct  = [math]::Round(100 - $healthPct, 1)
    $permTotal = $permCounts.Values | Measure-Object -Sum | Select-Object -ExpandProperty Sum

    $html = @"
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>$ReportTitle</title>
<style>
  :root {
    --bg: #0f172a; --surface: #1e293b; --surface2: #334155;
    --border: #475569; --text: #e2e8f0; --muted: #94a3b8;
    --green: #22c55e; --red: #f87171; --yellow: #fbbf24; --blue: #60a5fa;
    --accent: #6366f1;
  }
  * { box-sizing: border-box; margin: 0; padding: 0; }
  body { font-family: 'Segoe UI', system-ui, sans-serif; background: var(--bg); color: var(--text); padding: 24px; }
  h1 { font-size: 1.6rem; color: var(--blue); margin-bottom: 4px; }
  .subtitle { color: var(--muted); font-size: 0.85rem; margin-bottom: 24px; }
  .grid-4 { display: grid; grid-template-columns: repeat(4, 1fr); gap: 16px; margin-bottom: 24px; }
  .grid-3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; margin-bottom: 24px; }
  .card { background: var(--surface); border: 1px solid var(--border); border-radius: 8px; padding: 16px; }
  .card h3 { font-size: 0.75rem; color: var(--muted); text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 8px; }
  .card .value { font-size: 2rem; font-weight: 700; }
  .card .label { font-size: 0.8rem; color: var(--muted); margin-top: 4px; }
  .green  { color: var(--green); }
  .red    { color: var(--red); }
  .yellow { color: var(--yellow); }
  .blue   { color: var(--blue); }
  section { margin-bottom: 28px; }
  section h2 { font-size: 1rem; font-weight: 600; color: var(--blue); border-bottom: 1px solid var(--border); padding-bottom: 6px; margin-bottom: 12px; }
  table { width: 100%; border-collapse: collapse; font-size: 0.82rem; }
  th { background: var(--surface2); color: var(--muted); text-transform: uppercase; font-size: 0.7rem; letter-spacing: 0.04em; padding: 8px 10px; text-align: left; border-bottom: 2px solid var(--border); }
  td { padding: 7px 10px; border-bottom: 1px solid var(--border); vertical-align: top; }
  tr:hover td { background: rgba(99,102,241,0.06); }
  .progress-bar { background: var(--surface2); border-radius: 4px; height: 8px; margin-top: 6px; overflow: hidden; }
  .progress-fill { height: 100%; border-radius: 4px; }
  @media (max-width: 900px) { .grid-4 { grid-template-columns: repeat(2,1fr); } .grid-3 { grid-template-columns: 1fr; } }
</style>
</head>
<body>
<h1>&#128203; $ReportTitle</h1>
<p class="subtitle">Generated: $(Get-Date -Format "yyyy-MM-dd HH:mm")</p>

<!-- KPI Cards -->
<div class="grid-4">
  <div class="card">
    <h3>Total Agents</h3>
    <div class="value blue">$($Rows.Count)</div>
    <div class="label">All agents in scope</div>
  </div>
  <div class="card">
    <h3>Agents with Issues</h3>
    <div class="value red">$($issues.Count)</div>
    <div class="label">$issuePct% of total agents</div>
    <div class="progress-bar"><div class="progress-fill" style="width:${issuePct}%;background:var(--red)"></div></div>
  </div>
  <div class="card">
    <h3>Healthy Agents</h3>
    <div class="value green">$($healthy.Count)</div>
    <div class="label">$healthPct% of total agents</div>
    <div class="progress-bar"><div class="progress-fill" style="width:${healthPct}%;background:var(--green)"></div></div>
  </div>
  <div class="card">
    <h3>Missing Permissions</h3>
    <div class="value yellow">$permTotal</div>
    <div class="label">Total permission gaps</div>
  </div>
</div>

<!-- Breakdown Tables -->
<div class="grid-3">
  <section>
    <h2>&#9881; Operational State</h2>
    <table>
      <thead><tr><th>State</th><th>Count</th></tr></thead>
      <tbody>$($opStateRows -join "`n")</tbody>
    </table>
  </section>
  <section>
    <h2>&#9888; Pending Actions</h2>
    <table>
      <thead><tr><th>Action</th><th>Agents</th></tr></thead>
      <tbody>$($pendingRows -join "`n")</tbody>
    </table>
  </section>
  <section>
    <h2>&#128274; Missing Permissions</h2>
    <table>
      <thead><tr><th>Permission</th><th>Agents</th></tr></thead>
      <tbody>$($permRows -join "`n")</tbody>
    </table>
  </section>
</div>

<!-- Issues by Client -->
<section>
  <h2>&#127970; Issues by Client</h2>
  <table>
    <thead><tr><th>Client</th><th>Agents w/ Issues</th><th>Operational State Issues</th><th>Pending Actions</th><th>Missing Permissions</th></tr></thead>
    <tbody>$($clientRows -join "`n")</tbody>
  </table>
</section>

<!-- Agent Detail -->
<section>
  <h2>&#128196; Agent Detail - Issues Only ($($issues.Count) agents)</h2>
  <table>
    <thead><tr><th>Computer</th><th>Client</th><th>OS</th><th>Op. State</th><th>Pending Actions</th><th>Missing Permissions</th><th>Last Seen</th></tr></thead>
    <tbody>$($agentDetailRows -join "`n")</tbody>
  </table>
</section>

</body>
</html>
"@

    if (-not (Test-Path $OutputPath)) { New-Item -ItemType Directory -Path $OutputPath -Force | Out-Null }
    $ts   = Get-Date -Format "yyyyMMdd_HHmmss"
    $file = Join-Path $OutputPath "S1_AgentHealth_Report_$ts.html"
    $html | Out-File -FilePath $file -Encoding UTF8
    return $file
}

# MAIN

$reportTitle = "SentinelOne Agent Health Report"
if ($ClientName) { $reportTitle += " - $ClientName" }

$headers    = New-Headers -Token $ApiToken
$siteLookup = Get-SiteLookup -BaseUrl $BaseUrl -Headers $headers

# Client filter to site IDs
$filteredSiteIds = @()
if ($ClientName) {
    $filteredSiteIds = Resolve-ClientSiteIds -Lookup $siteLookup -Pattern $ClientName
}

# Retrieve all agents
$rawAgents = Get-AllAgents -BaseUrl $BaseUrl -Headers $headers -SiteIds $filteredSiteIds
if ($rawAgents.Count -eq 0) {
    Write-Log "No agents found for the specified criteria." -Level Warning
    exit
}

# Client name failover
$agentsToProcess = $rawAgents
if ($ClientName -and $filteredSiteIds.Count -eq 0) {
    $agentsToProcess = $rawAgents | Where-Object {
        $_.siteName -like "*$ClientName*" -or $_.accountName -like "*$ClientName*"
    }
}


$reportRows = @($agentsToProcess | ForEach-Object { ConvertTo-ReportRow -Agent $_ -SiteLookup $siteLookup })

$displayRows = $reportRows
if ($HealthyOnly) { $displayRows = @($reportRows | Where-Object { $_.IsHealthy }) }

# Console
if ($OutputFormat -in @("Console", "All")) {
    Write-ConsoleReport -Rows $displayRows -ReportTitle $reportTitle
}

# CSV
if ($OutputFormat -in @("CSV", "All")) {
    if (-not (Test-Path $OutputPath)) { New-Item -ItemType Directory -Path $OutputPath -Force | Out-Null }
    $ts  = Get-Date -Format "yyyyMMdd_HHmmss"
    $csv = Join-Path $OutputPath "S1_AgentHealth_Report_$ts.csv"
    $displayRows | Export-Csv -Path $csv -NoTypeInformation
}

# JSON
if ($OutputFormat -in @("JSON", "All")) {
    if (-not (Test-Path $OutputPath)) { New-Item -ItemType Directory -Path $OutputPath -Force | Out-Null }
    $ts   = Get-Date -Format "yyyyMMdd_HHmmss"
    $json = Join-Path $OutputPath "S1_AgentHealth_Report_$ts.json"
    $displayRows | ConvertTo-Json -Depth 5 | Out-File -FilePath $json -Encoding UTF8
}

# HTML
if ($OutputFormat -in @("HTML", "All")) {
    $htmlFile = Export-HtmlReport -Rows $displayRows -ReportTitle $reportTitle -OutputPath $OutputPath
    Write-Host "Report generated: $htmlFile" -ForegroundColor Green
}

Write-Host "Report complete." -ForegroundColor Green