SentinelOne Health Check: Agent Status Monitoring and

flowchart TD
    Start([Script Execution]) --> CheckInstall[Step 1: Test-SentinelOneInstalled]
 
    CheckInstall --> InstallFound{sentinelctl.exe<br/>Found?}
    InstallFound -->|No| NotInstalled[Set Status: NOT_INSTALLED<br/>Exit Code 1]
    InstallFound -->|Yes| CheckService[Step 2: Get-SentinelService]
 
    CheckService --> ServiceRunning{Service<br/>Running?}
    ServiceRunning -->|No| ServiceStopped[Set Status: SERVICE_STOPPED<br/>Exit Code 1]
    ServiceRunning -->|Yes| GetInfo[Step 3: Get-SentinelAgentInfo]
 
    GetInfo --> InfoSuccess{Query<br/>Successful?}
    InfoSuccess -->|No| QueryFailed[Set Status: QUERY_FAILED<br/>Exit Code 1]
    InfoSuccess -->|Yes| CheckProtection[Step 4: Get-SentinelThreatProtection]
 
    CheckProtection --> CheckConnectivity[Step 5: Test-SentinelConsoleConnectivity]
    CheckConnectivity --> CheckUpdates[Step 6: Get-SentinelPendingActions]
    CheckUpdates --> Evaluate[Step 7: Determine Overall Status]
 
    Evaluate --> EvalConsole{Console<br/>Connected?}
    EvalConsole -->|No| StatusDisc[Status: DISCONNECTED<br/>Exit Code 2]
    EvalConsole -->|Yes| EvalProtection{Protection<br/>Active?}
 
    EvalProtection -->|No| StatusProt[Status: PROTECTION_DISABLED<br/>Exit Code 2]
    EvalProtection -->|Yes| EvalUpdate{Pending<br/>Updates?}
 
    EvalUpdate -->|Yes| StatusUpdate[Status: UPDATE_PENDING<br/>Exit Code 2]
    EvalUpdate -->|No| StatusHealthy[Status: HEALTHY<br/>Exit Code 0]
 
    StatusDisc --> Report[Step 8: Report to NinjaRMM]
    StatusProt --> Report
    StatusUpdate --> Report
    StatusHealthy --> Report
 
    Report --> UpdateFields[Update Custom Fields:<br/>- s1_agent_status<br/>- s1_agent_version<br/>- s1_last_update<br/>- s1_protection_status<br/>- s1_console_connectivity]
    UpdateFields --> Complete([Script Exit])
 
    NotInstalled --> Complete
    ServiceStopped --> Complete
    QueryFailed --> Complete
 
    style Start fill:#90EE90
    style StatusHealthy fill:#90EE90
    style Complete fill:#90EE90
    style NotInstalled fill:#FF6B6B
    style ServiceStopped fill:#FF6B6B
    style QueryFailed fill:#FF6B6B
    style StatusDisc fill:#FFD700
    style StatusProt fill:#FFD700
    style StatusUpdate fill:#FFA500

pwsh -NoLogo -File .\Check-SentinelOne-Health.ps1 -WhatIf

 
.\Check-SentinelOne-Health.ps1

# Open today's log file
notepad "C:\BIN\LOGS-$(Get-Date -Format 'yyyy-MM-dd')-SentinelOne-Health.log"

graph TB
    subgraph Endpoint["Windows Endpoint"]
        subgraph Agent["SentinelOne Agent Installation"]
            SentinelCtl[sentinelctl.exe<br/>CLI Management Tool]
            Service[SentinelAgent Service<br/>Windows Service]
            Engine[Threat Protection Engine<br/>Behavioral AI]
            Config[Agent Configuration<br/>Console URL, Policies]
        end
 
        subgraph OS["Operating System"]
            WinService[Windows Service Manager]
            Network[Network Stack]
            FileSystem[File System Monitoring]
        end
    end
 
    subgraph External["External Dependencies"]
        Console[SentinelOne Management Console<br/>Cloud/On-Premises]
        ThreatIntel[Threat Intelligence Feed<br/>Real-Time Updates]
    end
 
    Service --> WinService
    Service --> Engine
    Service --> FileSystem
    Engine --> FileSystem
    Engine --> ThreatIntel
    Service --> Network
    Network --> Console
    Config --> Console
    SentinelCtl --> Service
 
    Script[Health Check Script] -.Query.-> SentinelCtl
    Script -.Check Status.-> Service
    Script -.Validate.-> Engine
    Script -.Test Connectivity.-> Console
 
    style Service fill:#FF9999,stroke:#333,stroke-width:3px
    style Engine fill:#99CCFF,stroke:#333,stroke-width:2px
    style Console fill:#90EE90,stroke:#333,stroke-width:2px
    style Script fill:#FFD700,stroke:#333,stroke-width:3px

# Verify network connectivity to management console
Test-NetConnection -ComputerName <your-sentinelone-console>.sentinelone.net -Port 443
 
# Check proxy settings if applicable
& "C:\Program Files\SentinelOne\Sentinel Agent *\SentinelCtl.exe" config show
 
# Force agent re-registration
& "C:\Program Files\SentinelOne\Sentinel Agent *\SentinelCtl.exe" management reconnect

# Check protection engine state
& "C:\Program Files\SentinelOne\Sentinel Agent *\SentinelCtl.exe" engine status
 
# Enable protection (if disabled locally)
& "C:\Program Files\SentinelOne\Sentinel Agent *\SentinelCtl.exe" engine start
 
# Verify policy in SentinelOne console (may be disabled by policy)

# Check service startup type
Get-Service SentinelAgent | Select-Object Name, Status, StartType
 
# Set to automatic and start
Set-Service SentinelAgent -StartupType Automatic
Start-Service SentinelAgent
 
# Verify service started successfully
Get-Service SentinelAgent

# Create daily scheduled task (runs at 2 AM)
$action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument '-ExecutionPolicy Bypass -NoProfile -File "C:\Scripts\Check-SentinelOne-Health.ps1"'
$trigger = New-ScheduledTaskTrigger -Daily -At 2AM
$principal = New-ScheduledTaskPrincipal -UserId "SYSTEM" -LogonType ServiceAccount -RunLevel Highest
$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries
 
Register-ScheduledTask -TaskName "SentinelOne Health Monitor" -Action $action -Trigger $trigger -Principal $principal -Settings $settings

$sentinelCtlPath = "${env:ProgramFiles}\SentinelOne\Sentinel Agent *\SentinelCtl.exe"
$sentinelCtl = Get-Item $sentinelCtlPath -ErrorAction SilentlyContinue | Select-Object -First 1

$service = Get-Service -Name $serviceName -ErrorAction Stop
if ($status -ne 'Running') {
    Set-NinjaProperty -PropertyName "s1_agent_status" -PropertyValue "SERVICE_STOPPED"
    return $false
}

$agentInfo = & $SentinelCtlPath status 2>&1
 
foreach ($line in $agentInfo) {
    if ($line -match "Agent version:\s*(.+)") {
        $agentData.Version = $matches[1].Trim()
    } elseif ($line -match "Last updated:\s*(.+)") {
        $agentData.LastUpdate = $matches[1].Trim()
    }
    # ... additional parsing
}

$protectionInfo = & $SentinelCtlPath engine status 2>&1
 
if ($line -match "Engine state:\s*(.+)") {
    $engineStatus = $matches[1].Trim()
}

$isConnected = $ConnectionStatus -match "(?i)yes|true|connected|online"

$updateInfo = & $SentinelCtlPath check-update 2>&1
 
foreach ($line in $updateInfo) {
    if ($line -match "(?i)update available|new version") {
        $hasPendingUpdate = $true
    }
}

$overallStatus = "HEALTHY"
if ($consoleStatus -eq "DISCONNECTED") {
    $overallStatus = "DISCONNECTED"  # Critical - no management
} elseif ($protectionStatus -notmatch "(?i)active|enabled|on") {
    $overallStatus = "PROTECTION_DISABLED"  # High - no threat blocking
} elseif ($hasPendingUpdates) {
    $overallStatus = "UPDATE_PENDING"  # Low - functional but outdated
}

if (Get-Command Ninja-Property-Set -ErrorAction SilentlyContinue) {
    Ninja-Property-Set $PropertyName $PropertyValue
} else {
    Write-Log "NinjaRMM integration not available" -Level 'WARNING'
}

<#
.SYNOPSIS
    Checks SentinelOne agent health status and reports metrics to NinjaRMM.
 
.DESCRIPTION
    SCENARIO:
    Organizations using SentinelOne need automated monitoring of agent health to ensure
    continuous endpoint protection. This script validates service status, console connectivity,
    agent version, threat protection state, and pending actions.
 
    REQUIREMENTS:
    - SentinelOne agent installed (sentinelctl.exe present in Program Files)
    - Local administrator privileges
    - NinjaRMM agent with custom fields configured:
        * s1_agent_status (text)
        * s1_agent_version (text)
        * s1_last_update (text)
        * s1_protection_status (text)
        * s1_console_connectivity (text)
    - C:\BIN\ directory for logging (created automatically if missing)
 
    PROCESS:
    1. Validate sentinelctl.exe presence and service status
    2. Query agent version and last update timestamp
    3. Check management console connectivity
    4. Verify threat protection engine status
    5. Detect pending updates or actions
    6. Report all metrics to NinjaRMM custom fields
    7. Log detailed results with timestamps
 
.NOTES
    Author: CosmicBytez IT Operations
    Version: 1.0
    Requires: PowerShell 5.1+, Administrator privileges
#>
 
#Requires -RunAsAdministrator
 
$ErrorActionPreference = 'Stop'
 
# Configuration
$logDirectory = "C:\BIN"
$logFile = Join-Path $logDirectory "LOGS-$(Get-Date -Format 'yyyy-MM-dd')-SentinelOne-Health.log"
$sentinelCtlPath = "${env:ProgramFiles}\SentinelOne\Sentinel Agent *\SentinelCtl.exe"
$serviceName = "SentinelAgent"
 
# Initialize logging
function Write-Log {
    param(
        [Parameter(Mandatory = $true)]
        [string]$Message,
 
        [Parameter(Mandatory = $false)]
        [ValidateSet('INFO', 'WARNING', 'ERROR', 'SUCCESS')]
        [string]$Level = 'INFO'
    )
 
    $timestamp = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
    $logEntry = "[$timestamp] [$Level] $Message"
 
    # Create log directory if it doesn't exist
    if (-not (Test-Path $logDirectory)) {
        New-Item -ItemType Directory -Path $logDirectory -Force | Out-Null
    }
 
    Add-Content -Path $logFile -Value $logEntry
 
    # Console output with color
    $color = switch ($Level) {
        'ERROR'   { 'Red' }
        'WARNING' { 'Yellow' }
        'SUCCESS' { 'Green' }
        default   { 'White' }
    }
    Write-Host $logEntry -ForegroundColor $color
}
 
function Set-NinjaProperty {
    param(
        [Parameter(Mandatory = $true)]
        [string]$PropertyName,
 
        [Parameter(Mandatory = $true)]
        [AllowEmptyString()]
        [string]$PropertyValue
    )
 
    try {
        if (Get-Command Ninja-Property-Set -ErrorAction SilentlyContinue) {
            Ninja-Property-Set $PropertyName $PropertyValue
            Write-Log "NinjaRMM: Set $PropertyName = $PropertyValue" -Level 'INFO'
        } else {
            Write-Log "NinjaRMM integration not available (Ninja-Property-Set not found)" -Level 'WARNING'
        }
    } catch {
        Write-Log "Failed to set NinjaRMM property ${PropertyName}: $($_.Exception.Message)" -Level 'WARNING'
    }
}
 
function Test-SentinelOneInstalled {
    Write-Log "Checking SentinelOne installation..." -Level 'INFO'
 
    $sentinelCtl = Get-Item $sentinelCtlPath -ErrorAction SilentlyContinue | Select-Object -First 1
 
    if (-not $sentinelCtl) {
        Write-Log "SentinelOne agent not found at expected path" -Level 'ERROR'
        Set-NinjaProperty -PropertyName "s1_agent_status" -PropertyValue "NOT_INSTALLED"
        return $null
    }
 
    Write-Log "SentinelOne sentinelctl.exe found: $($sentinelCtl.FullName)" -Level 'SUCCESS'
    return $sentinelCtl.FullName
}
 
function Get-SentinelService {
    Write-Log "Checking SentinelOne service status..." -Level 'INFO'
 
    try {
        $service = Get-Service -Name $serviceName -ErrorAction Stop
 
        $status = $service.Status
        Write-Log "Service '$serviceName' status: $status" -Level $(if ($status -eq 'Running') { 'SUCCESS' } else { 'WARNING' })
 
        if ($status -ne 'Running') {
            Set-NinjaProperty -PropertyName "s1_agent_status" -PropertyValue "SERVICE_STOPPED"
            return $false
        }
 
        return $true
    } catch {
        Write-Log "Service '$serviceName' not found: $($_.Exception.Message)" -Level 'ERROR'
        Set-NinjaProperty -PropertyName "s1_agent_status" -PropertyValue "SERVICE_NOT_FOUND"
        return $false
    }
}
 
function Get-SentinelAgentInfo {
    param(
        [Parameter(Mandatory = $true)]
        [string]$SentinelCtlPath
    )
 
    Write-Log "Querying SentinelOne agent information..." -Level 'INFO'
 
    try {
        $agentInfo = & $SentinelCtlPath status 2>&1
 
        if ($LASTEXITCODE -ne 0) {
            Write-Log "sentinelctl status command failed with exit code $LASTEXITCODE" -Level 'ERROR'
            return $null
        }
 
        # Parse output
        $agentData = @{
            Version = ""
            LastUpdate = ""
            ConnectionStatus = ""
            ProtectionStatus = ""
            AgentId = ""
        }
 
        foreach ($line in $agentInfo) {
            if ($line -match "Agent version:\s*(.+)") {
                $agentData.Version = $matches[1].Trim()
            } elseif ($line -match "Last updated:\s*(.+)") {
                $agentData.LastUpdate = $matches[1].Trim()
            } elseif ($line -match "Connected to management:\s*(.+)") {
                $agentData.ConnectionStatus = $matches[1].Trim()
            } elseif ($line -match "Protection status:\s*(.+)") {
                $agentData.ProtectionStatus = $matches[1].Trim()
            } elseif ($line -match "Agent ID:\s*(.+)") {
                $agentData.AgentId = $matches[1].Trim()
            }
        }
 
        Write-Log "Agent Version: $($agentData.Version)" -Level 'INFO'
        Write-Log "Last Update: $($agentData.LastUpdate)" -Level 'INFO'
        Write-Log "Console Connectivity: $($agentData.ConnectionStatus)" -Level 'INFO'
        Write-Log "Protection Status: $($agentData.ProtectionStatus)" -Level 'INFO'
 
        return $agentData
    } catch {
        Write-Log "Error querying agent info: $($_.Exception.Message)" -Level 'ERROR'
        return $null
    }
}
 
function Get-SentinelThreatProtection {
    param(
        [Parameter(Mandatory = $true)]
        [string]$SentinelCtlPath
    )
 
    Write-Log "Checking threat protection engine status..." -Level 'INFO'
 
    try {
        $protectionInfo = & $SentinelCtlPath engine status 2>&1
 
        if ($LASTEXITCODE -ne 0) {
            Write-Log "sentinelctl engine status command failed with exit code $LASTEXITCODE" -Level 'WARNING'
            return "UNKNOWN"
        }
 
        $engineStatus = "UNKNOWN"
        foreach ($line in $protectionInfo) {
            if ($line -match "Engine state:\s*(.+)") {
                $engineStatus = $matches[1].Trim()
                break
            } elseif ($line -match "Protection:\s*(.+)") {
                $engineStatus = $matches[1].Trim()
                break
            }
        }
 
        Write-Log "Threat Protection Engine: $engineStatus" -Level $(if ($engineStatus -match "(?i)active|enabled|on") { 'SUCCESS' } else { 'WARNING' })
        return $engineStatus
    } catch {
        Write-Log "Error checking threat protection: $($_.Exception.Message)" -Level 'WARNING'
        return "ERROR"
    }
}
 
function Get-SentinelPendingActions {
    param(
        [Parameter(Mandatory = $true)]
        [string]$SentinelCtlPath
    )
 
    Write-Log "Checking for pending actions or updates..." -Level 'INFO'
 
    try {
        # Check for pending updates
        $updateInfo = & $SentinelCtlPath check-update 2>&1
 
        $hasPendingUpdate = $false
        foreach ($line in $updateInfo) {
            if ($line -match "(?i)update available|new version") {
                $hasPendingUpdate = $true
                Write-Log "Pending update detected: $line" -Level 'WARNING'
            }
        }
 
        if (-not $hasPendingUpdate) {
            Write-Log "No pending updates detected" -Level 'SUCCESS'
        }
 
        return $hasPendingUpdate
    } catch {
        Write-Log "Error checking pending actions: $($_.Exception.Message)" -Level 'WARNING'
        return $false
    }
}
 
function Test-SentinelConsoleConnectivity {
    param(
        [Parameter(Mandatory = $true)]
        [string]$ConnectionStatus
    )
 
    Write-Log "Validating management console connectivity..." -Level 'INFO'
 
    $isConnected = $ConnectionStatus -match "(?i)yes|true|connected|online"
 
    if ($isConnected) {
        Write-Log "Console connectivity: CONNECTED" -Level 'SUCCESS'
        return "CONNECTED"
    } else {
        Write-Log "Console connectivity: DISCONNECTED" -Level 'ERROR'
        return "DISCONNECTED"
    }
}
 
# Main execution
Write-Log "========== SentinelOne Health Check Started ==========" -Level 'INFO'
 
try {
    # Step 1: Check if SentinelOne is installed
    $sentinelCtlExe = Test-SentinelOneInstalled
    if (-not $sentinelCtlExe) {
        Write-Log "SentinelOne agent not installed. Exiting." -Level 'ERROR'
        Set-NinjaProperty -PropertyName "s1_agent_version" -PropertyValue "N/A"
        Set-NinjaProperty -PropertyName "s1_last_update" -PropertyValue "N/A"
        Set-NinjaProperty -PropertyName "s1_protection_status" -PropertyValue "N/A"
        Set-NinjaProperty -PropertyName "s1_console_connectivity" -PropertyValue "N/A"
        exit 1
    }
 
    # Step 2: Check service status
    $serviceRunning = Get-SentinelService
    if (-not $serviceRunning) {
        Write-Log "SentinelOne service not running. Health check incomplete." -Level 'ERROR'
        Set-NinjaProperty -PropertyName "s1_agent_version" -PropertyValue "SERVICE_DOWN"
        Set-NinjaProperty -PropertyName "s1_last_update" -PropertyValue "N/A"
        Set-NinjaProperty -PropertyName "s1_protection_status" -PropertyValue "SERVICE_DOWN"
        Set-NinjaProperty -PropertyName "s1_console_connectivity" -PropertyValue "N/A"
        exit 1
    }
 
    # Step 3: Get agent information
    $agentInfo = Get-SentinelAgentInfo -SentinelCtlPath $sentinelCtlExe
    if (-not $agentInfo) {
        Write-Log "Failed to retrieve agent information" -Level 'ERROR'
        Set-NinjaProperty -PropertyName "s1_agent_status" -PropertyValue "QUERY_FAILED"
        exit 1
    }
 
    # Step 4: Check threat protection
    $protectionStatus = Get-SentinelThreatProtection -SentinelCtlPath $sentinelCtlExe
 
    # Step 5: Check console connectivity
    $consoleStatus = Test-SentinelConsoleConnectivity -ConnectionStatus $agentInfo.ConnectionStatus
 
    # Step 6: Check for pending actions
    $hasPendingUpdates = Get-SentinelPendingActions -SentinelCtlPath $sentinelCtlExe
 
    # Step 7: Determine overall agent status
    $overallStatus = "HEALTHY"
    if ($consoleStatus -eq "DISCONNECTED") {
        $overallStatus = "DISCONNECTED"
    } elseif ($protectionStatus -notmatch "(?i)active|enabled|on") {
        $overallStatus = "PROTECTION_DISABLED"
    } elseif ($hasPendingUpdates) {
        $overallStatus = "UPDATE_PENDING"
    }
 
    Write-Log "Overall Agent Status: $overallStatus" -Level $(if ($overallStatus -eq "HEALTHY") { 'SUCCESS' } else { 'WARNING' })
 
    # Step 8: Report to NinjaRMM
    Set-NinjaProperty -PropertyName "s1_agent_status" -PropertyValue $overallStatus
    Set-NinjaProperty -PropertyName "s1_agent_version" -PropertyValue $agentInfo.Version
    Set-NinjaProperty -PropertyName "s1_last_update" -PropertyValue $agentInfo.LastUpdate
    Set-NinjaProperty -PropertyName "s1_protection_status" -PropertyValue $protectionStatus
    Set-NinjaProperty -PropertyName "s1_console_connectivity" -PropertyValue $consoleStatus
 
    Write-Log "========== SentinelOne Health Check Completed ==========" -Level 'SUCCESS'
 
    # Exit with appropriate code
    if ($overallStatus -eq "HEALTHY") {
        exit 0
    } else {
        exit 2  # Warning status
    }
 
} catch {
    Write-Log "Critical error during health check: $($_.Exception.Message)" -Level 'ERROR'
    Write-Log "Stack trace: $($_.ScriptStackTrace)" -Level 'ERROR'
    Set-NinjaProperty -PropertyName "s1_agent_status" -PropertyValue "HEALTH_CHECK_FAILED"
    exit 1
}