SentinelOne PowerShell Automation Scripts

#Requires -Version 5.1
<#
.SYNOPSIS
    SentinelOne API Authentication and Request Module
.DESCRIPTION
    Provides secure credential storage, token management, rate limiting,
    and error handling wrapper functions for SentinelOne API operations.
.NOTES
    Version: 2.0
    Author: CosmicBytez
    Requires: PowerShell 5.1+
#>
 
# Module-scoped variables
$script:S1Config = @{
    ApiToken = $null
    ConsoleUrl = $null
    RateLimitRemaining = 1000
    RateLimitReset = $null
    LastRequestTime = $null
    MinRequestInterval = 100  # milliseconds between requests
}
 
$script:LogPath = "C:\BIN\LOGS"
 
#region Credential Management
 
function Set-S1CredentialStore {
    <#
    .SYNOPSIS
        Securely stores SentinelOne API credentials using Windows DPAPI
    .PARAMETER ConsoleUrl
        SentinelOne console URL (e.g., https://usea1-partners.sentinelone.net)
    .PARAMETER ApiToken
        API token (will prompt securely if not provided)
    .PARAMETER CredentialPath
        Path to store encrypted credentials (default: user profile)
    .EXAMPLE
        Set-S1CredentialStore -ConsoleUrl "https://usea1-partners.sentinelone.net"
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [ValidatePattern('^https://.*\.sentinelone\.net$')]
        [string]$ConsoleUrl,
 
        [Parameter(Mandatory = $false)]
        [string]$ApiToken,
 
        [Parameter(Mandatory = $false)]
        [string]$CredentialPath = "$env:USERPROFILE\.sentinelone\credentials.xml"
    )
 
    # Create directory if needed
    $credDir = Split-Path $CredentialPath -Parent
    if (-not (Test-Path $credDir)) {
        New-Item -Path $credDir -ItemType Directory -Force | Out-Null
    }
 
    # Get token securely if not provided
    if (-not $ApiToken) {
        $secureToken = Read-Host -Prompt "Enter SentinelOne API Token" -AsSecureString
    } else {
        $secureToken = ConvertTo-SecureString $ApiToken -AsPlainText -Force
    }
 
    # Create credential object
    $credential = @{
        ConsoleUrl = $ConsoleUrl
        ApiToken = $secureToken | ConvertFrom-SecureString
        CreatedAt = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
        CreatedBy = $env:USERNAME
    }
 
    # Export encrypted
    $credential | Export-Clixml -Path $CredentialPath -Force
 
    # Set restrictive permissions
    $acl = Get-Acl $CredentialPath
    $acl.SetAccessRuleProtection($true, $false)
    $rule = New-Object System.Security.AccessControl.FileSystemAccessRule(
        $env:USERNAME, "FullControl", "Allow"
    )
    $acl.SetAccessRule($rule)
    Set-Acl -Path $CredentialPath -AclObject $acl
 
    Write-Host "[SUCCESS] Credentials stored securely at: $CredentialPath" -ForegroundColor Green
}
 
function Get-S1StoredCredential {
    <#
    .SYNOPSIS
        Retrieves stored SentinelOne credentials
    .PARAMETER CredentialPath
        Path to credential file
    .EXAMPLE
        $creds = Get-S1StoredCredential
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $false)]
        [string]$CredentialPath = "$env:USERPROFILE\.sentinelone\credentials.xml"
    )
 
    if (-not (Test-Path $CredentialPath)) {
        throw "Credential file not found. Run Set-S1CredentialStore first."
    }
 
    $stored = Import-Clixml -Path $CredentialPath
 
    return @{
        ConsoleUrl = $stored.ConsoleUrl
        ApiToken = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto(
            [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR(
                ($stored.ApiToken | ConvertTo-SecureString)
            )
        )
    }
}
 
#endregion
 
#region Connection Management
 
function Connect-S1Console {
    <#
    .SYNOPSIS
        Establishes connection to SentinelOne API
    .PARAMETER ConsoleUrl
        SentinelOne console URL
    .PARAMETER ApiToken
        API token (use stored credentials if not provided)
    .PARAMETER UseStoredCredentials
        Use credentials from secure store
    .EXAMPLE
        Connect-S1Console -UseStoredCredentials
    .EXAMPLE
        Connect-S1Console -ConsoleUrl "https://usea1-partners.sentinelone.net" -ApiToken $token
    #>
    [CmdletBinding(DefaultParameterSetName = 'Stored')]
    param(
        [Parameter(ParameterSetName = 'Manual', Mandatory = $true)]
        [string]$ConsoleUrl,
 
        [Parameter(ParameterSetName = 'Manual', Mandatory = $true)]
        [string]$ApiToken,
 
        [Parameter(ParameterSetName = 'Stored')]
        [switch]$UseStoredCredentials
    )
 
    if ($UseStoredCredentials -or $PSCmdlet.ParameterSetName -eq 'Stored') {
        $creds = Get-S1StoredCredential
        $ConsoleUrl = $creds.ConsoleUrl
        $ApiToken = $creds.ApiToken
    }
 
    $script:S1Config.ConsoleUrl = $ConsoleUrl.TrimEnd('/')
    $script:S1Config.ApiToken = $ApiToken
 
    # Validate connection
    try {
        $test = Invoke-S1ApiRequest -Endpoint "/web/api/v2.1/system/info" -Method GET
        Write-Host "[SUCCESS] Connected to SentinelOne" -ForegroundColor Green
        Write-Host "  Console: $($script:S1Config.ConsoleUrl)" -ForegroundColor Cyan
        Write-Host "  Version: $($test.data.consoleVersion)" -ForegroundColor Cyan
        return $true
    }
    catch {
        Write-Error "Failed to connect to SentinelOne: $($_.Exception.Message)"
        $script:S1Config.ApiToken = $null
        $script:S1Config.ConsoleUrl = $null
        return $false
    }
}
 
function Disconnect-S1Console {
    <#
    .SYNOPSIS
        Clears SentinelOne API session
    #>
    $script:S1Config.ApiToken = $null
    $script:S1Config.ConsoleUrl = $null
    Write-Host "[INFO] Disconnected from SentinelOne" -ForegroundColor Yellow
}
 
#endregion
 
#region API Request Handling
 
function Invoke-S1ApiRequest {
    <#
    .SYNOPSIS
        Generic wrapper for SentinelOne API requests with rate limiting and error handling
    .PARAMETER Endpoint
        API endpoint path (e.g., "/web/api/v2.1/agents")
    .PARAMETER Method
        HTTP method (GET, POST, PUT, DELETE)
    .PARAMETER Body
        Request body for POST/PUT requests
    .PARAMETER QueryParams
        Hashtable of query parameters
    .PARAMETER MaxRetries
        Maximum retry attempts for rate limiting (default: 3)
    .EXAMPLE
        Invoke-S1ApiRequest -Endpoint "/web/api/v2.1/agents" -Method GET
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]$Endpoint,
 
        [Parameter(Mandatory = $false)]
        [ValidateSet('GET', 'POST', 'PUT', 'DELETE')]
        [string]$Method = 'GET',
 
        [Parameter(Mandatory = $false)]
        [hashtable]$Body = @{},
 
        [Parameter(Mandatory = $false)]
        [hashtable]$QueryParams = @{},
 
        [Parameter(Mandatory = $false)]
        [int]$MaxRetries = 3
    )
 
    if (-not $script:S1Config.ApiToken -or -not $script:S1Config.ConsoleUrl) {
        throw "Not connected to SentinelOne. Run Connect-S1Console first."
    }
 
    # Build query string
    if ($QueryParams.Count -gt 0) {
        $queryString = ($QueryParams.GetEnumerator() | ForEach-Object {
            "$($_.Key)=$([System.Web.HttpUtility]::UrlEncode($_.Value.ToString()))"
        }) -join "&"
        $Endpoint = "$Endpoint`?$queryString"
    }
 
    $uri = "$($script:S1Config.ConsoleUrl)$Endpoint"
 
    $headers = @{
        "Authorization" = "ApiToken $($script:S1Config.ApiToken)"
        "Content-Type"  = "application/json"
        "Accept"        = "application/json"
    }
 
    $requestParams = @{
        Uri                = $uri
        Method             = $Method
        Headers            = $headers
        ErrorAction        = 'Stop'
        UseBasicParsing    = $true
    }
 
    if ($Method -in @('POST', 'PUT') -and $Body.Count -gt 0) {
        $requestParams.Body = ($Body | ConvertTo-Json -Depth 20 -Compress)
    }
 
    # Rate limiting - ensure minimum interval between requests
    if ($script:S1Config.LastRequestTime) {
        $elapsed = (Get-Date) - $script:S1Config.LastRequestTime
        if ($elapsed.TotalMilliseconds -lt $script:S1Config.MinRequestInterval) {
            Start-Sleep -Milliseconds ($script:S1Config.MinRequestInterval - $elapsed.TotalMilliseconds)
        }
    }
 
    $retryCount = 0
    while ($retryCount -le $MaxRetries) {
        try {
            $script:S1Config.LastRequestTime = Get-Date
            $response = Invoke-RestMethod @requestParams
 
            # Update rate limit tracking from headers (if available)
            return $response
        }
        catch {
            $statusCode = $_.Exception.Response.StatusCode.value__
 
            # Handle rate limiting (429)
            if ($statusCode -eq 429) {
                $retryAfter = 60
                if ($_.Exception.Response.Headers['Retry-After']) {
                    $retryAfter = [int]$_.Exception.Response.Headers['Retry-After']
                }
                Write-Warning "Rate limited. Waiting $retryAfter seconds..."
                Start-Sleep -Seconds ($retryAfter + 1)
                $retryCount++
                continue
            }
 
            # Handle other errors
            $errorMessage = $_.Exception.Message
            try {
                $reader = New-Object System.IO.StreamReader($_.Exception.Response.GetResponseStream())
                $responseBody = $reader.ReadToEnd() | ConvertFrom-Json
                if ($responseBody.errors) {
                    $errorMessage = $responseBody.errors[0].detail
                }
            } catch {}
 
            Write-Error "API Error [$statusCode]: $errorMessage`nEndpoint: $Endpoint"
            throw
        }
    }
 
    throw "Max retries exceeded due to rate limiting"
}
 
function Get-S1AllPages {
    <#
    .SYNOPSIS
        Retrieves all pages of results using cursor pagination
    .PARAMETER Endpoint
        API endpoint path
    .PARAMETER QueryParams
        Initial query parameters
    .PARAMETER MaxItems
        Maximum items to retrieve (default: unlimited)
    .EXAMPLE
        $allAgents = Get-S1AllPages -Endpoint "/web/api/v2.1/agents"
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]$Endpoint,
 
        [Parameter(Mandatory = $false)]
        [hashtable]$QueryParams = @{},
 
        [Parameter(Mandatory = $false)]
        [int]$MaxItems = 0
    )
 
    $allData = @()
    $cursor = $null
    $QueryParams.limit = 1000
 
    do {
        if ($cursor) {
            $QueryParams.cursor = $cursor
        }
 
        $response = Invoke-S1ApiRequest -Endpoint $Endpoint -Method GET -QueryParams $QueryParams
 
        if ($response.data) {
            $allData += $response.data
        }
 
        $cursor = $response.pagination.nextCursor
 
        Write-Verbose "Retrieved $($allData.Count) items..."
 
        if ($MaxItems -gt 0 -and $allData.Count -ge $MaxItems) {
            $allData = $allData | Select-Object -First $MaxItems
            break
        }
 
    } while ($cursor)
 
    return $allData
}
 
#endregion
 
#region Logging Functions
 
function Write-S1Log {
    <#
    .SYNOPSIS
        Writes log entry to file and console
    .PARAMETER Message
        Log message
    .PARAMETER Level
        Log level (INFO, WARN, ERROR, SUCCESS)
    .PARAMETER LogFile
        Log file name (auto-generated if not specified)
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]$Message,
 
        [Parameter(Mandatory = $false)]
        [ValidateSet('INFO', 'WARN', 'ERROR', 'SUCCESS', 'DEBUG')]
        [string]$Level = 'INFO',
 
        [Parameter(Mandatory = $false)]
        [string]$LogFile
    )
 
    if (-not (Test-Path $script:LogPath)) {
        New-Item -Path $script:LogPath -ItemType Directory -Force | Out-Null
    }
 
    if (-not $LogFile) {
        $LogFile = "SentinelOne-$(Get-Date -Format 'yyyy-MM-dd').log"
    }
 
    $logFilePath = Join-Path $script:LogPath $LogFile
    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
    $logEntry = "[$timestamp] [$Level] $Message"
 
    Add-Content -Path $logFilePath -Value $logEntry
 
    $color = switch ($Level) {
        'INFO'    { 'White' }
        'WARN'    { 'Yellow' }
        'ERROR'   { 'Red' }
        'SUCCESS' { 'Green' }
        'DEBUG'   { 'Gray' }
    }
 
    Write-Host $logEntry -ForegroundColor $color
}
 
#endregion
 
# Export module members
Export-ModuleMember -Function @(
    'Set-S1CredentialStore',
    'Get-S1StoredCredential',
    'Connect-S1Console',
    'Disconnect-S1Console',
    'Invoke-S1ApiRequest',
    'Get-S1AllPages',
    'Write-S1Log'
)

# First-time setup - store credentials securely
Import-Module "C:\Scripts\SentinelOne-API-Module.psm1"
Set-S1CredentialStore -ConsoleUrl "https://usea1-partners.sentinelone.net"
 
# In automation scripts - use stored credentials
Import-Module "C:\Scripts\SentinelOne-API-Module.psm1"
Connect-S1Console -UseStoredCredentials
 
# Make API calls
$agents = Invoke-S1ApiRequest -Endpoint "/web/api/v2.1/agents" -Method GET

# Create scheduled task for daily automation
$action = New-ScheduledTaskAction -Execute "powershell.exe" `
    -Argument "-NoProfile -ExecutionPolicy Bypass -File C:\Scripts\S1-DailyAutomation.ps1"
$trigger = New-ScheduledTaskTrigger -Daily -At "06:00AM"
$principal = New-ScheduledTaskPrincipal -UserId "SYSTEM" -LogonType ServiceAccount
Register-ScheduledTask -TaskName "SentinelOne-DailyAutomation" `
    -Action $action -Trigger $trigger -Principal $principal

#Requires -Version 5.1
<#
.SYNOPSIS
    Retrieves SentinelOne agents with flexible filtering options
.DESCRIPTION
    Queries all agents across sites with filtering by status, OS, version, site, etc.
    Supports export to CSV/JSON and integration with other automation.
.PARAMETER SiteId
    Filter by specific site ID
.PARAMETER SiteName
    Filter by site name (partial match)
.PARAMETER Status
    Filter by agent status (online, offline, all)
.PARAMETER OSType
    Filter by OS type (windows, linux, macos)
.PARAMETER MinVersion
    Filter agents below this version
.PARAMETER Infected
    Filter for infected agents only
.PARAMETER ExportPath
    Path to export results (CSV or JSON based on extension)
.EXAMPLE
    .\Get-S1Agents.ps1 -Status offline -ExportPath "C:\Reports\offline-agents.csv"
.EXAMPLE
    .\Get-S1Agents.ps1 -SiteName "Contoso" -OSType windows
#>
 
[CmdletBinding()]
param(
    [string]$SiteId,
    [string]$SiteName,
    [ValidateSet('online', 'offline', 'all')]
    [string]$Status = 'all',
    [ValidateSet('windows', 'linux', 'macos', 'all')]
    [string]$OSType = 'all',
    [string]$MinVersion,
    [switch]$Infected,
    [string]$ExportPath
)
 
$ErrorActionPreference = 'Stop'
Import-Module "C:\Scripts\SentinelOne-API-Module.psm1" -Force
 
try {
    Connect-S1Console -UseStoredCredentials
 
    Write-S1Log -Message "Starting agent inventory query" -Level INFO
 
    # Build query parameters
    $queryParams = @{
        limit = 1000
    }
 
    if ($SiteId) { $queryParams.siteIds = $SiteId }
    if ($Status -eq 'online') { $queryParams.isActive = $true }
    if ($Status -eq 'offline') { $queryParams.isActive = $false }
    if ($OSType -ne 'all') { $queryParams.osTypes = $OSType }
    if ($Infected) { $queryParams.infected = $true }
 
    # Get all agents
    $agents = Get-S1AllPages -Endpoint "/web/api/v2.1/agents" -QueryParams $queryParams
 
    # Filter by site name if specified
    if ($SiteName) {
        $agents = $agents | Where-Object { $_.siteName -like "*$SiteName*" }
    }
 
    # Filter by minimum version if specified
    if ($MinVersion) {
        $agents = $agents | Where-Object {
            [version]$_.agentVersion -lt [version]$MinVersion
        }
    }
 
    # Format output
    $report = $agents | Select-Object @(
        @{N='ComputerName'; E={$_.computerName}}
        @{N='SiteName'; E={$_.siteName}}
        @{N='GroupName'; E={$_.groupName}}
        @{N='AgentVersion'; E={$_.agentVersion}}
        @{N='OSType'; E={$_.osType}}
        @{N='OSName'; E={$_.osName}}
        @{N='IsActive'; E={$_.isActive}}
        @{N='LastActive'; E={$_.lastActiveDate}}
        @{N='Infected'; E={$_.infected}}
        @{N='NetworkStatus'; E={$_.networkStatus}}
        @{N='Domain'; E={$_.domain}}
        @{N='ExternalIP'; E={$_.externalIp}}
        @{N='AgentId'; E={$_.id}}
    )
 
    # Display summary
    Write-S1Log -Message "Found $($report.Count) agents" -Level SUCCESS
    Write-Host "`nAgent Summary:" -ForegroundColor Cyan
    Write-Host "  Total: $($report.Count)"
    Write-Host "  Online: $(($report | Where-Object IsActive).Count)"
    Write-Host "  Offline: $(($report | Where-Object {-not $_.IsActive}).Count)"
    Write-Host "  Infected: $(($report | Where-Object Infected).Count)"
 
    # Export if path specified
    if ($ExportPath) {
        $extension = [System.IO.Path]::GetExtension($ExportPath)
        if ($extension -eq '.json') {
            $report | ConvertTo-Json -Depth 5 | Out-File $ExportPath -Encoding UTF8
        } else {
            $report | Export-Csv -Path $ExportPath -NoTypeInformation
        }
        Write-S1Log -Message "Exported to: $ExportPath" -Level SUCCESS
    }
 
    return $report
 
} catch {
    Write-S1Log -Message "Error: $($_.Exception.Message)" -Level ERROR
    throw
} finally {
    Disconnect-S1Console
}

#Requires -Version 5.1
<#
.SYNOPSIS
    Performs comprehensive health check on SentinelOne agents
.DESCRIPTION
    Checks agent connectivity, version compliance, policy sync, and scan status.
    Generates health report and can send alerts for critical issues.
.PARAMETER SiteId
    Limit check to specific site
.PARAMETER AlertEmail
    Email address for critical alerts
.PARAMETER VersionThreshold
    Minimum acceptable agent version
.EXAMPLE
    .\Get-S1AgentHealth.ps1 -VersionThreshold "23.4.2.0" -AlertEmail "soc@company.com"
#>
 
[CmdletBinding()]
param(
    [string]$SiteId,
    [string]$AlertEmail,
    [string]$VersionThreshold = "23.3.0.0",
    [int]$OfflineThresholdHours = 24,
    [string]$ReportPath = "C:\BIN\LOGS\S1-HealthReport-$(Get-Date -Format 'yyyyMMdd').html"
)
 
$ErrorActionPreference = 'Stop'
Import-Module "C:\Scripts\SentinelOne-API-Module.psm1" -Force
 
function Get-AgentHealthStatus {
    param($Agent)
 
    $issues = @()
    $severity = 'Healthy'
 
    # Check online status
    if (-not $Agent.isActive) {
        $lastActive = [datetime]$Agent.lastActiveDate
        $hoursOffline = (Get-Date) - $lastActive | Select-Object -ExpandProperty TotalHours
        if ($hoursOffline -gt $OfflineThresholdHours) {
            $issues += "Offline for $([math]::Round($hoursOffline, 1)) hours"
            $severity = 'Warning'
        }
        if ($hoursOffline -gt ($OfflineThresholdHours * 7)) {
            $severity = 'Critical'
        }
    }
 
    # Check version
    if ([version]$Agent.agentVersion -lt [version]$VersionThreshold) {
        $issues += "Outdated version: $($Agent.agentVersion)"
        if ($severity -ne 'Critical') { $severity = 'Warning' }
    }
 
    # Check infected status
    if ($Agent.infected) {
        $issues += "INFECTED - Active threat detected"
        $severity = 'Critical'
    }
 
    # Check network quarantine
    if ($Agent.networkStatus -eq 'quarantined') {
        $issues += "Network quarantined"
        $severity = 'Critical'
    }
 
    # Check scan status
    if ($Agent.scanStatus -eq 'aborted' -or $Agent.scanStatus -eq 'failed') {
        $issues += "Scan status: $($Agent.scanStatus)"
        if ($severity -ne 'Critical') { $severity = 'Warning' }
    }
 
    return @{
        Severity = $severity
        Issues = $issues -join "; "
        IssueCount = $issues.Count
    }
}
 
try {
    Connect-S1Console -UseStoredCredentials
 
    Write-S1Log -Message "Starting agent health check" -Level INFO
 
    $queryParams = @{}
    if ($SiteId) { $queryParams.siteIds = $SiteId }
 
    $agents = Get-S1AllPages -Endpoint "/web/api/v2.1/agents" -QueryParams $queryParams
 
    $healthReport = foreach ($agent in $agents) {
        $health = Get-AgentHealthStatus -Agent $agent
 
        [PSCustomObject]@{
            ComputerName = $agent.computerName
            SiteName = $agent.siteName
            AgentVersion = $agent.agentVersion
            IsActive = $agent.isActive
            LastActive = $agent.lastActiveDate
            Infected = $agent.infected
            NetworkStatus = $agent.networkStatus
            Severity = $health.Severity
            Issues = $health.Issues
            AgentId = $agent.id
        }
    }
 
    # Categorize results
    $critical = $healthReport | Where-Object { $_.Severity -eq 'Critical' }
    $warning = $healthReport | Where-Object { $_.Severity -eq 'Warning' }
    $healthy = $healthReport | Where-Object { $_.Severity -eq 'Healthy' }
 
    # Generate HTML report
    $html = @"
<!DOCTYPE html>
\<html\>
\<head\>
    \<title\>SentinelOne Agent Health Report</title>
    \<style\>
        body { font-family: 'Segoe UI', Arial, sans-serif; margin: 20px; background: #f5f5f5; }
        .container { max-width: 1200px; margin: 0 auto; background: white; padding: 20px; border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.1); }
        h1 { color: #333; border-bottom: 2px solid #6B2D9E; padding-bottom: 10px; }
        .summary { display: flex; gap: 20px; margin: 20px 0; }
        .stat-box { flex: 1; padding: 20px; border-radius: 8px; text-align: center; }
        .critical { background: #FFE5E5; border: 2px solid #FF4444; }
        .warning { background: #FFF3E0; border: 2px solid #FF9800; }
        .healthy { background: #E8F5E9; border: 2px solid #4CAF50; }
        .stat-number { font-size: 36px; font-weight: bold; }
        .stat-label { font-size: 14px; color: #666; }
        table { width: 100%; border-collapse: collapse; margin-top: 20px; }
        th { background: #6B2D9E; color: white; padding: 12px; text-align: left; }
        td { padding: 10px; border-bottom: 1px solid #ddd; }
        tr:hover { background: #f9f9f9; }
        .severity-critical { color: #FF4444; font-weight: bold; }
        .severity-warning { color: #FF9800; font-weight: bold; }
        .severity-healthy { color: #4CAF50; }
        .timestamp { color: #999; font-size: 12px; margin-top: 20px; }
    </style>
</head>
\<body\>
    <div class="container">
        <h1>SentinelOne Agent Health Report</h1>
 
        <div class="summary">
            <div class="stat-box critical">
                <div class="stat-number">$($critical.Count)</div>
                <div class="stat-label">Critical Issues</div>
            </div>
            <div class="stat-box warning">
                <div class="stat-number">$($warning.Count)</div>
                <div class="stat-label">Warnings</div>
            </div>
            <div class="stat-box healthy">
                <div class="stat-number">$($healthy.Count)</div>
                <div class="stat-label">Healthy</div>
            </div>
        </div>
 
        <h2>Critical Issues</h2>
        \<table\>
            \<tr\>\<th\>Computer</th>\<th\>Site</th>\<th\>Version</th>\<th\>Status</th>\<th\>Issues</th></tr>
            $(foreach ($item in $critical) {
                "\<tr\>\<td\>$($item.ComputerName)</td>\<td\>$($item.SiteName)</td>\<td\>$($item.AgentVersion)</td>\<td\>$(if($item.IsActive){'Online'}else{'Offline'})</td>\<td\>$($item.Issues)</td></tr>"
            })
        </table>
 
        <h2>Warnings</h2>
        \<table\>
            \<tr\>\<th\>Computer</th>\<th\>Site</th>\<th\>Version</th>\<th\>Status</th>\<th\>Issues</th></tr>
            $(foreach ($item in ($warning | Select-Object -First 50)) {
                "\<tr\>\<td\>$($item.ComputerName)</td>\<td\>$($item.SiteName)</td>\<td\>$($item.AgentVersion)</td>\<td\>$(if($item.IsActive){'Online'}else{'Offline'})</td>\<td\>$($item.Issues)</td></tr>"
            })
        </table>
 
        <p class="timestamp">Generated: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss') | Total Agents: $($healthReport.Count)</p>
    </div>
</body>
</html>
"@
 
    $html | Out-File $ReportPath -Encoding UTF8
    Write-S1Log -Message "Health report saved to: $ReportPath" -Level SUCCESS
 
    # Send alert if critical issues found
    if ($AlertEmail -and $critical.Count -gt 0) {
        $subject = "ALERT: $($critical.Count) SentinelOne Agents with Critical Issues"
        $body = "Critical issues detected on the following agents:`n`n"
        $body += ($critical | ForEach-Object { "$($_.ComputerName) - $($_.Issues)" }) -join "`n"
 
        # Uncomment to enable email alerts
        # Send-MailMessage -To $AlertEmail -From "sentinelone@company.com" -Subject $subject -Body $body -SmtpServer "smtp.company.com"
        Write-S1Log -Message "Alert would be sent to $AlertEmail" -Level WARN
    }
 
    # Console summary
    Write-Host "`nHealth Check Summary:" -ForegroundColor Cyan
    Write-Host "  Critical: $($critical.Count)" -ForegroundColor Red
    Write-Host "  Warning: $($warning.Count)" -ForegroundColor Yellow
    Write-Host "  Healthy: $($healthy.Count)" -ForegroundColor Green
 
    return $healthReport
 
} catch {
    Write-S1Log -Message "Error: $($_.Exception.Message)" -Level ERROR
    throw
} finally {
    Disconnect-S1Console
}

#Requires -Version 5.1
<#
.SYNOPSIS
    Initiates bulk agent upgrades across sites
.DESCRIPTION
    Upgrades agents to specified version with scheduling and rollback options.
    Supports filtering by site, group, OS type, and current version.
.PARAMETER TargetVersion
    Target agent version (or 'latest' for newest GA)
.PARAMETER SiteIds
    Array of site IDs to upgrade
.PARAMETER MaxConcurrent
    Maximum concurrent upgrades per site
.PARAMETER ScheduleTime
    Schedule upgrade for specific time (UTC)
.EXAMPLE
    .\Update-S1Agents.ps1 -TargetVersion "latest" -SiteIds @("site1","site2")
#>
 
[CmdletBinding(SupportsShouldProcess)]
param(
    [Parameter(Mandatory = $true)]
    [string]$TargetVersion,
 
    [Parameter(Mandatory = $false)]
    [string[]]$SiteIds,
 
    [Parameter(Mandatory = $false)]
    [string[]]$GroupIds,
 
    [Parameter(Mandatory = $false)]
    [ValidateSet('windows', 'linux', 'macos')]
    [string]$OSType = 'windows',
 
    [Parameter(Mandatory = $false)]
    [int]$MaxConcurrent = 50,
 
    [Parameter(Mandatory = $false)]
    [datetime]$ScheduleTime,
 
    [Parameter(Mandatory = $false)]
    [switch]$Force
)
 
$ErrorActionPreference = 'Stop'
Import-Module "C:\Scripts\SentinelOne-API-Module.psm1" -Force
 
try {
    Connect-S1Console -UseStoredCredentials
 
    Write-S1Log -Message "Starting bulk agent upgrade process" -Level INFO
 
    # Get available packages if 'latest' specified
    if ($TargetVersion -eq 'latest') {
        $packages = Invoke-S1ApiRequest -Endpoint "/web/api/v2.1/update/agent/packages" -QueryParams @{
            osTypes = $OSType
            status = 'ga'
            sortBy = 'version'
            sortOrder = 'desc'
            limit = 1
        }
 
        if ($packages.data.Count -eq 0) {
            throw "No GA packages found for $OSType"
        }
 
        $TargetVersion = $packages.data[0].version
        $packageId = $packages.data[0].id
        Write-S1Log -Message "Latest GA version for $OSType`: $TargetVersion" -Level INFO
    } else {
        # Find specific package
        $packages = Invoke-S1ApiRequest -Endpoint "/web/api/v2.1/update/agent/packages" -QueryParams @{
            osTypes = $OSType
            version = $TargetVersion
        }
 
        if ($packages.data.Count -eq 0) {
            throw "Package version $TargetVersion not found for $OSType"
        }
        $packageId = $packages.data[0].id
    }
 
    # Build agent filter
    $agentQuery = @{
        osTypes = $OSType
        isActive = $true
    }
 
    if ($SiteIds) { $agentQuery.siteIds = $SiteIds -join ',' }
    if ($GroupIds) { $agentQuery.groupIds = $GroupIds -join ',' }
 
    # Get agents needing upgrade
    $agents = Get-S1AllPages -Endpoint "/web/api/v2.1/agents" -QueryParams $agentQuery
 
    $agentsToUpgrade = $agents | Where-Object {
        [version]$_.agentVersion -lt [version]$TargetVersion
    }
 
    if ($agentsToUpgrade.Count -eq 0) {
        Write-S1Log -Message "All agents are already at version $TargetVersion or higher" -Level SUCCESS
        return
    }
 
    Write-S1Log -Message "Found $($agentsToUpgrade.Count) agents requiring upgrade to $TargetVersion" -Level INFO
 
    # Confirm upgrade
    if (-not $Force -and -not $PSCmdlet.ShouldProcess("$($agentsToUpgrade.Count) agents", "Upgrade to $TargetVersion")) {
        Write-S1Log -Message "Upgrade cancelled by user" -Level WARN
        return
    }
 
    # Process in batches
    $batches = [System.Collections.ArrayList]@()
    for ($i = 0; $i -lt $agentsToUpgrade.Count; $i += $MaxConcurrent) {
        $batch = $agentsToUpgrade | Select-Object -Skip $i -First $MaxConcurrent
        [void]$batches.Add($batch)
    }
 
    Write-S1Log -Message "Processing $($batches.Count) batches of up to $MaxConcurrent agents" -Level INFO
 
    $results = @()
    $batchNum = 0
 
    foreach ($batch in $batches) {
        $batchNum++
        Write-S1Log -Message "Processing batch $batchNum of $($batches.Count)" -Level INFO
 
        $agentIds = $batch | Select-Object -ExpandProperty id
 
        $upgradeBody = @{
            data = @{
                packageId = $packageId
            }
            filter = @{
                ids = $agentIds
            }
        }
 
        if ($ScheduleTime) {
            $upgradeBody.data.scheduleTime = $ScheduleTime.ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
        }
 
        try {
            $response = Invoke-S1ApiRequest -Endpoint "/web/api/v2.1/agents/actions/update-software" `
                -Method POST -Body $upgradeBody
 
            $results += [PSCustomObject]@{
                Batch = $batchNum
                AgentCount = $agentIds.Count
                Affected = $response.data.affected
                Status = 'Initiated'
            }
 
            Write-S1Log -Message "Batch $batchNum`: Upgrade initiated for $($response.data.affected) agents" -Level SUCCESS
        }
        catch {
            $results += [PSCustomObject]@{
                Batch = $batchNum
                AgentCount = $agentIds.Count
                Affected = 0
                Status = "Failed: $($_.Exception.Message)"
            }
            Write-S1Log -Message "Batch $batchNum failed: $($_.Exception.Message)" -Level ERROR
        }
 
        # Rate limiting between batches
        if ($batchNum -lt $batches.Count) {
            Start-Sleep -Seconds 2
        }
    }
 
    # Summary
    $totalAffected = ($results | Measure-Object -Property Affected -Sum).Sum
    Write-Host "`nUpgrade Summary:" -ForegroundColor Cyan
    Write-Host "  Target Version: $TargetVersion"
    Write-Host "  Total Agents Upgraded: $totalAffected"
    Write-Host "  Batches Processed: $($batches.Count)"
 
    return $results
 
} catch {
    Write-S1Log -Message "Error: $($_.Exception.Message)" -Level ERROR
    throw
} finally {
    Disconnect-S1Console
}

#Requires -Version 5.1
<#
.SYNOPSIS
    Retrieves agent uninstall passphrases
.DESCRIPTION
    Gets uninstall passphrase for specific agents or exports all for a site.
    Useful for agent removal and reimaging scenarios.
.PARAMETER ComputerName
    Computer name to retrieve passphrase for
.PARAMETER AgentId
    Agent ID to retrieve passphrase for
.PARAMETER SiteId
    Site ID to export all passphrases for
.PARAMETER ExportPath
    Path to export passphrases (encrypted CSV)
.EXAMPLE
    .\Get-S1UninstallPassphrase.ps1 -ComputerName "WKS-001"
.EXAMPLE
    .\Get-S1UninstallPassphrase.ps1 -SiteId "12345" -ExportPath "C:\Secure\passphrases.csv"
#>
 
[CmdletBinding()]
param(
    [Parameter(ParameterSetName = 'ByName')]
    [string]$ComputerName,
 
    [Parameter(ParameterSetName = 'ById')]
    [string]$AgentId,
 
    [Parameter(ParameterSetName = 'BySite')]
    [string]$SiteId,
 
    [Parameter(ParameterSetName = 'BySite')]
    [string]$ExportPath
)
 
$ErrorActionPreference = 'Stop'
Import-Module "C:\Scripts\SentinelOne-API-Module.psm1" -Force
 
try {
    Connect-S1Console -UseStoredCredentials
 
    Write-S1Log -Message "Retrieving uninstall passphrase(s)" -Level INFO
 
    $results = @()
 
    if ($ComputerName) {
        # Find agent by computer name
        $agents = Invoke-S1ApiRequest -Endpoint "/web/api/v2.1/agents" -QueryParams @{
            computerName = $ComputerName
        }
 
        if ($agents.data.Count -eq 0) {
            throw "Agent not found: $ComputerName"
        }
 
        $AgentId = $agents.data[0].id
    }
 
    if ($AgentId) {
        # Get passphrase for single agent
        $passphrase = Invoke-S1ApiRequest -Endpoint "/web/api/v2.1/agents/passphrases" -QueryParams @{
            ids = $AgentId
        }
 
        if ($passphrase.data.Count -gt 0) {
            $agentInfo = $agents.data[0]
            $results += [PSCustomObject]@{
                ComputerName = $agentInfo.computerName
                SiteName = $agentInfo.siteName
                Passphrase = $passphrase.data[0].passphrase
                AgentId = $AgentId
            }
 
            Write-Host "`nUninstall Passphrase for $($agentInfo.computerName):" -ForegroundColor Cyan
            Write-Host "  Passphrase: $($passphrase.data[0].passphrase)" -ForegroundColor Yellow
            Write-Host "  Site: $($agentInfo.siteName)"
        }
    }
    elseif ($SiteId) {
        # Get all agents for site
        $agents = Get-S1AllPages -Endpoint "/web/api/v2.1/agents" -QueryParams @{
            siteIds = $SiteId
        }
 
        Write-S1Log -Message "Found $($agents.Count) agents in site" -Level INFO
 
        # Get passphrases in batches
        for ($i = 0; $i -lt $agents.Count; $i += 100) {
            $batch = $agents | Select-Object -Skip $i -First 100
            $agentIds = ($batch | Select-Object -ExpandProperty id) -join ','
 
            $passphrases = Invoke-S1ApiRequest -Endpoint "/web/api/v2.1/agents/passphrases" -QueryParams @{
                ids = $agentIds
            }
 
            foreach ($pp in $passphrases.data) {
                $agent = $batch | Where-Object { $_.id -eq $pp.id }
                $results += [PSCustomObject]@{
                    ComputerName = $agent.computerName
                    SiteName = $agent.siteName
                    Passphrase = $pp.passphrase
                    AgentId = $pp.id
                }
            }
 
            Write-Verbose "Processed $([math]::Min($i + 100, $agents.Count)) of $($agents.Count) agents"
        }
 
        if ($ExportPath) {
            # Export with warning about sensitivity
            Write-Warning "Exporting uninstall passphrases - ensure secure storage!"
            $results | Export-Csv -Path $ExportPath -NoTypeInformation
            Write-S1Log -Message "Passphrases exported to: $ExportPath" -Level SUCCESS
        }
    }
 
    return $results
 
} catch {
    Write-S1Log -Message "Error: $($_.Exception.Message)" -Level ERROR
    throw
} finally {
    Disconnect-S1Console
}

#Requires -Version 5.1
<#
.SYNOPSIS
    Decommissions SentinelOne agents
.DESCRIPTION
    Removes agents from management, optionally triggering uninstall.
    Use for endpoint retirement, reimaging, or cleanup scenarios.
.PARAMETER ComputerName
    Computer name(s) to decommission
.PARAMETER AgentId
    Agent ID(s) to decommission
.PARAMETER Uninstall
    Send uninstall command (requires agent online)
.PARAMETER Force
    Skip confirmation prompt
.EXAMPLE
    .\Remove-S1Agent.ps1 -ComputerName "WKS-001","WKS-002" -Uninstall
#>
 
[CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')]
param(
    [Parameter(ParameterSetName = 'ByName')]
    [string[]]$ComputerName,
 
    [Parameter(ParameterSetName = 'ById')]
    [string[]]$AgentId,
 
    [switch]$Uninstall,
 
    [switch]$Force
)
 
$ErrorActionPreference = 'Stop'
Import-Module "C:\Scripts\SentinelOne-API-Module.psm1" -Force
 
try {
    Connect-S1Console -UseStoredCredentials
 
    Write-S1Log -Message "Starting agent decommission process" -Level INFO
 
    $agentIds = @()
 
    if ($ComputerName) {
        foreach ($name in $ComputerName) {
            $agents = Invoke-S1ApiRequest -Endpoint "/web/api/v2.1/agents" -QueryParams @{
                computerName = $name
            }
 
            if ($agents.data.Count -eq 0) {
                Write-S1Log -Message "Agent not found: $name" -Level WARN
                continue
            }
 
            $agentIds += $agents.data[0].id
            Write-S1Log -Message "Found agent: $name (ID: $($agents.data[0].id))" -Level INFO
        }
    } else {
        $agentIds = $AgentId
    }
 
    if ($agentIds.Count -eq 0) {
        Write-S1Log -Message "No agents to process" -Level WARN
        return
    }
 
    # Confirmation
    if (-not $Force) {
        Write-Host "`nAgents to decommission: $($agentIds.Count)" -ForegroundColor Yellow
        if (-not $PSCmdlet.ShouldProcess("$($agentIds.Count) agents", "Decommission")) {
            return
        }
    }
 
    $results = @()
 
    # Initiate uninstall if requested
    if ($Uninstall) {
        Write-S1Log -Message "Initiating remote uninstall for $($agentIds.Count) agents" -Level INFO
 
        $uninstallBody = @{
            filter = @{
                ids = $agentIds
            }
        }
 
        try {
            $response = Invoke-S1ApiRequest -Endpoint "/web/api/v2.1/agents/actions/uninstall" `
                -Method POST -Body $uninstallBody
 
            Write-S1Log -Message "Uninstall initiated for $($response.data.affected) agents" -Level SUCCESS
 
            $results += [PSCustomObject]@{
                Action = 'Uninstall'
                AgentCount = $agentIds.Count
                Affected = $response.data.affected
                Status = 'Initiated'
            }
        }
        catch {
            Write-S1Log -Message "Uninstall failed: $($_.Exception.Message)" -Level ERROR
            $results += [PSCustomObject]@{
                Action = 'Uninstall'
                AgentCount = $agentIds.Count
                Affected = 0
                Status = "Failed: $($_.Exception.Message)"
            }
        }
    }
 
    # Decommission (remove from console)
    Write-S1Log -Message "Decommissioning $($agentIds.Count) agents from console" -Level INFO
 
    $decommBody = @{
        filter = @{
            ids = $agentIds
        }
    }
 
    try {
        $response = Invoke-S1ApiRequest -Endpoint "/web/api/v2.1/agents/actions/decommission" `
            -Method POST -Body $decommBody
 
        Write-S1Log -Message "Decommissioned $($response.data.affected) agents" -Level SUCCESS
 
        $results += [PSCustomObject]@{
            Action = 'Decommission'
            AgentCount = $agentIds.Count
            Affected = $response.data.affected
            Status = 'Completed'
        }
    }
    catch {
        Write-S1Log -Message "Decommission failed: $($_.Exception.Message)" -Level ERROR
        $results += [PSCustomObject]@{
            Action = 'Decommission'
            AgentCount = $agentIds.Count
            Affected = 0
            Status = "Failed: $($_.Exception.Message)"
        }
    }
 
    return $results
 
} catch {
    Write-S1Log -Message "Error: $($_.Exception.Message)" -Level ERROR
    throw
} finally {
    Disconnect-S1Console
}

#Requires -Version 5.1
<#
.SYNOPSIS
    Retrieves threats across all sites with filtering options
.DESCRIPTION
    Queries active and historical threats with filtering by status,
    severity, date range, and site.
.PARAMETER Status
    Filter by resolution status (unresolved, resolved, all)
.PARAMETER Severity
    Filter by AI confidence level
.PARAMETER DaysBack
    Number of days to look back (default: 7)
.PARAMETER SiteId
    Filter by specific site
.PARAMETER ExportPath
    Path to export threat data
.EXAMPLE
    .\Get-S1Threats.ps1 -Status unresolved -DaysBack 1
#>
 
[CmdletBinding()]
param(
    [ValidateSet('unresolved', 'resolved', 'all')]
    [string]$Status = 'unresolved',
 
    [ValidateSet('malicious', 'suspicious', 'all')]
    [string]$Severity = 'all',
 
    [int]$DaysBack = 7,
 
    [string]$SiteId,
 
    [string]$ExportPath
)
 
$ErrorActionPreference = 'Stop'
Import-Module "C:\Scripts\SentinelOne-API-Module.psm1" -Force
 
try {
    Connect-S1Console -UseStoredCredentials
 
    Write-S1Log -Message "Querying threats (Status: $Status, Days: $DaysBack)" -Level INFO
 
    $queryParams = @{
        createdAt__gte = (Get-Date).AddDays(-$DaysBack).ToString("yyyy-MM-ddT00:00:00Z")
    }
 
    if ($Status -ne 'all') {
        $queryParams.resolved = ($Status -eq 'resolved')
    }
 
    if ($Severity -ne 'all') {
        $queryParams.confidenceLevels = $Severity
    }
 
    if ($SiteId) {
        $queryParams.siteIds = $SiteId
    }
 
    $threats = Get-S1AllPages -Endpoint "/web/api/v2.1/threats" -QueryParams $queryParams
 
    $report = $threats | Select-Object @(
        @{N='ThreatId'; E={$_.id}}
        @{N='ThreatName'; E={$_.threatInfo.threatName}}
        @{N='Classification'; E={$_.threatInfo.classification}}
        @{N='Confidence'; E={$_.threatInfo.confidenceLevel}}
        @{N='ComputerName'; E={$_.agentRealtimeInfo.agentComputerName}}
        @{N='SiteName'; E={$_.agentRealtimeInfo.siteName}}
        @{N='FilePath'; E={$_.threatInfo.filePath}}
        @{N='SHA256'; E={$_.threatInfo.sha256}}
        @{N='MitigationStatus'; E={$_.threatInfo.mitigationStatus}}
        @{N='AnalystVerdict'; E={$_.threatInfo.analystVerdict}}
        @{N='Resolved'; E={$_.threatInfo.resolved}}
        @{N='CreatedAt'; E={$_.threatInfo.createdAt}}
        @{N='Username'; E={$_.threatInfo.processUser}}
    )
 
    # Summary by classification
    Write-Host "`nThreat Summary:" -ForegroundColor Cyan
    Write-Host "  Total: $($report.Count)"
 
    $byClass = $report | Group-Object Classification
    foreach ($group in $byClass) {
        Write-Host "  $($group.Name): $($group.Count)"
    }
 
    # Export if requested
    if ($ExportPath) {
        $report | Export-Csv -Path $ExportPath -NoTypeInformation
        Write-S1Log -Message "Threats exported to: $ExportPath" -Level SUCCESS
    }
 
    return $report
 
} catch {
    Write-S1Log -Message "Error: $($_.Exception.Message)" -Level ERROR
    throw
} finally {
    Disconnect-S1Console
}

#Requires -Version 5.1
<#
.SYNOPSIS
    Automates threat mitigation actions
.DESCRIPTION
    Performs bulk threat mitigation including kill, quarantine, remediate,
    and rollback actions. Supports automatic resolution based on rules.
.PARAMETER ThreatIds
    Specific threat IDs to mitigate
.PARAMETER Action
    Mitigation action to perform
.PARAMETER AutoResolve
    Automatically resolve after successful mitigation
.PARAMETER Classification
    Filter threats by classification for bulk action
.EXAMPLE
    .\Invoke-S1ThreatMitigation.ps1 -ThreatIds @("123","456") -Action quarantine
.EXAMPLE
    .\Invoke-S1ThreatMitigation.ps1 -Classification "pup" -Action remediate -AutoResolve
#>
 
[CmdletBinding(SupportsShouldProcess)]
param(
    [Parameter(ParameterSetName = 'ById')]
    [string[]]$ThreatIds,
 
    [Parameter(ParameterSetName = 'ByFilter')]
    [ValidateSet('malware', 'pup', 'suspicious', 'trojan', 'ransomware')]
    [string]$Classification,
 
    [Parameter(ParameterSetName = 'ByFilter')]
    [int]$DaysBack = 1,
 
    [Parameter(Mandatory = $true)]
    [ValidateSet('kill', 'quarantine', 'remediate', 'rollback', 'disconnect-from-network')]
    [string]$Action,
 
    [switch]$AutoResolve,
 
    [ValidateSet('true_positive', 'false_positive', 'suspicious', 'undefined')]
    [string]$Verdict = 'true_positive'
)
 
$ErrorActionPreference = 'Stop'
Import-Module "C:\Scripts\SentinelOne-API-Module.psm1" -Force
 
try {
    Connect-S1Console -UseStoredCredentials
 
    Write-S1Log -Message "Starting threat mitigation process" -Level INFO
 
    # Get threats if filtering
    if ($Classification) {
        $queryParams = @{
            resolved = $false
            classification = $Classification
            createdAt__gte = (Get-Date).AddDays(-$DaysBack).ToString("yyyy-MM-ddT00:00:00Z")
        }
 
        $threats = Get-S1AllPages -Endpoint "/web/api/v2.1/threats" -QueryParams $queryParams
        $ThreatIds = $threats | Select-Object -ExpandProperty id
    }
 
    if ($ThreatIds.Count -eq 0) {
        Write-S1Log -Message "No threats to process" -Level WARN
        return
    }
 
    Write-S1Log -Message "Processing $($ThreatIds.Count) threats with action: $Action" -Level INFO
 
    # Map action to endpoint
    $actionEndpoint = switch ($Action) {
        'kill' { 'kill' }
        'quarantine' { 'quarantine' }
        'remediate' { 'remediate' }
        'rollback' { 'rollback' }
        'disconnect-from-network' { 'disconnect-from-network' }
    }
 
    if (-not $PSCmdlet.ShouldProcess("$($ThreatIds.Count) threats", $Action)) {
        return
    }
 
    # Perform mitigation action
    $mitigationBody = @{
        filter = @{
            ids = $ThreatIds
        }
    }
 
    try {
        $response = Invoke-S1ApiRequest `
            -Endpoint "/web/api/v2.1/threats/actions/$actionEndpoint" `
            -Method POST -Body $mitigationBody
 
        Write-S1Log -Message "$Action action applied to $($response.data.affected) threats" -Level SUCCESS
    }
    catch {
        Write-S1Log -Message "Mitigation action failed: $($_.Exception.Message)" -Level ERROR
        throw
    }
 
    # Auto-resolve if requested
    if ($AutoResolve) {
        Start-Sleep -Seconds 2  # Allow mitigation to process
 
        $resolveBody = @{
            filter = @{
                ids = $ThreatIds
            }
            data = @{
                analystVerdict = $Verdict
            }
        }
 
        try {
            $response = Invoke-S1ApiRequest `
                -Endpoint "/web/api/v2.1/threats/analyst-verdict" `
                -Method POST -Body $resolveBody
 
            Write-S1Log -Message "Resolved $($response.data.affected) threats as $Verdict" -Level SUCCESS
        }
        catch {
            Write-S1Log -Message "Resolution failed: $($_.Exception.Message)" -Level ERROR
        }
    }
 
    return @{
        Action = $Action
        ThreatsProcessed = $ThreatIds.Count
        AutoResolved = $AutoResolve
    }
 
} catch {
    Write-S1Log -Message "Error: $($_.Exception.Message)" -Level ERROR
    throw
} finally {
    Disconnect-S1Console
}

#Requires -Version 5.1
<#
.SYNOPSIS
    Exports threat intelligence data including IOCs
.DESCRIPTION
    Extracts threat indicators (hashes, IPs, domains) from threats
    for use in other security tools or threat intel platforms.
.PARAMETER DaysBack
    Number of days to analyze
.PARAMETER Format
    Output format (csv, json, stix)
.PARAMETER ExportPath
    Path to save export
.EXAMPLE
    .\Export-S1ThreatIntelligence.ps1 -DaysBack 30 -Format json -ExportPath "C:\Intel\iocs.json"
#>
 
[CmdletBinding()]
param(
    [int]$DaysBack = 30,
 
    [ValidateSet('csv', 'json', 'stix')]
    [string]$Format = 'csv',
 
    [Parameter(Mandatory = $true)]
    [string]$ExportPath
)
 
$ErrorActionPreference = 'Stop'
Import-Module "C:\Scripts\SentinelOne-API-Module.psm1" -Force
 
try {
    Connect-S1Console -UseStoredCredentials
 
    Write-S1Log -Message "Extracting threat intelligence for last $DaysBack days" -Level INFO
 
    $threats = Get-S1AllPages -Endpoint "/web/api/v2.1/threats" -QueryParams @{
        createdAt__gte = (Get-Date).AddDays(-$DaysBack).ToString("yyyy-MM-ddT00:00:00Z")
    }
 
    Write-S1Log -Message "Processing $($threats.Count) threats" -Level INFO
 
    $iocs = @()
 
    foreach ($threat in $threats) {
        # File hash IOCs
        if ($threat.threatInfo.sha256) {
            $iocs += [PSCustomObject]@{
                Type = 'sha256'
                Value = $threat.threatInfo.sha256
                ThreatName = $threat.threatInfo.threatName
                Classification = $threat.threatInfo.classification
                Confidence = $threat.threatInfo.confidenceLevel
                FirstSeen = $threat.threatInfo.createdAt
                Source = 'SentinelOne'
            }
        }
 
        if ($threat.threatInfo.sha1) {
            $iocs += [PSCustomObject]@{
                Type = 'sha1'
                Value = $threat.threatInfo.sha1
                ThreatName = $threat.threatInfo.threatName
                Classification = $threat.threatInfo.classification
                Confidence = $threat.threatInfo.confidenceLevel
                FirstSeen = $threat.threatInfo.createdAt
                Source = 'SentinelOne'
            }
        }
 
        if ($threat.threatInfo.md5) {
            $iocs += [PSCustomObject]@{
                Type = 'md5'
                Value = $threat.threatInfo.md5
                ThreatName = $threat.threatInfo.threatName
                Classification = $threat.threatInfo.classification
                Confidence = $threat.threatInfo.confidenceLevel
                FirstSeen = $threat.threatInfo.createdAt
                Source = 'SentinelOne'
            }
        }
    }
 
    # Deduplicate
    $uniqueIOCs = $iocs | Sort-Object Type, Value -Unique
 
    Write-S1Log -Message "Extracted $($uniqueIOCs.Count) unique IOCs" -Level SUCCESS
 
    # Export based on format
    switch ($Format) {
        'csv' {
            $uniqueIOCs | Export-Csv -Path $ExportPath -NoTypeInformation
        }
        'json' {
            $uniqueIOCs | ConvertTo-Json -Depth 5 | Out-File $ExportPath -Encoding UTF8
        }
        'stix' {
            # Basic STIX 2.1 format
            $stixBundle = @{
                type = 'bundle'
                id = "bundle--$(New-Guid)"
                objects = @()
            }
 
            foreach ($ioc in $uniqueIOCs) {
                $stixBundle.objects += @{
                    type = 'indicator'
                    id = "indicator--$(New-Guid)"
                    created = (Get-Date).ToString("yyyy-MM-ddTHH:mm:ss.fffZ")
                    modified = (Get-Date).ToString("yyyy-MM-ddTHH:mm:ss.fffZ")
                    name = $ioc.ThreatName
                    pattern = "[file:hashes.'$($ioc.Type.ToUpper())' = '$($ioc.Value)']"
                    pattern_type = 'stix'
                    valid_from = $ioc.FirstSeen
                }
            }
 
            $stixBundle | ConvertTo-Json -Depth 10 | Out-File $ExportPath -Encoding UTF8
        }
    }
 
    Write-S1Log -Message "IOCs exported to: $ExportPath" -Level SUCCESS
 
    # Summary
    Write-Host "`nIOC Summary:" -ForegroundColor Cyan
    $uniqueIOCs | Group-Object Type | ForEach-Object {
        Write-Host "  $($_.Name): $($_.Count)"
    }
 
    return $uniqueIOCs
 
} catch {
    Write-S1Log -Message "Error: $($_.Exception.Message)" -Level ERROR
    throw
} finally {
    Disconnect-S1Console
}

#Requires -Version 5.1
<#
.SYNOPSIS
    Executes scheduled threat hunting queries via Deep Visibility
.DESCRIPTION
    Runs predefined or custom hunting queries, exports results,
    and can trigger alerts for findings.
.PARAMETER HuntName
    Name of predefined hunt (or 'custom' for custom query)
.PARAMETER CustomQuery
    Custom S1QL query string
.PARAMETER SiteId
    Limit hunt to specific site
.PARAMETER AlertOnFindings
    Send alert if results found
.EXAMPLE
    .\Invoke-S1ThreatHunt.ps1 -HuntName "EncodedPowerShell"
.EXAMPLE
    .\Invoke-S1ThreatHunt.ps1 -CustomQuery 'SrcProcName = "mimikatz.exe"' -AlertOnFindings
#>
 
[CmdletBinding()]
param(
    [Parameter(ParameterSetName = 'Predefined')]
    [ValidateSet('EncodedPowerShell', 'LSASSAccess', 'ScheduledTaskCreation',
                 'EventLogClearing', 'WebShellCreation', 'CertutilDownload',
                 'WMIPersistence', 'SuspiciousParentChild', 'All')]
    [string]$HuntName,
 
    [Parameter(ParameterSetName = 'Custom')]
    [string]$CustomQuery,
 
    [string]$SiteId,
    [int]$HoursBack = 24,
    [switch]$AlertOnFindings,
    [string]$AlertEmail,
    [string]$OutputPath = "C:\BIN\LOGS\ThreatHunting"
)
 
$ErrorActionPreference = 'Stop'
Import-Module "C:\Scripts\SentinelOne-API-Module.psm1" -Force
 
# Predefined hunting queries
$HuntingQueries = @{
    EncodedPowerShell = @{
        Name = "Encoded PowerShell Execution"
        Query = 'EventType = "Process Creation" AND SrcProcName = "powershell.exe" AND (SrcProcCmdLine ContainsCIS "-enc" OR SrcProcCmdLine ContainsCIS "-encodedcommand" OR SrcProcCmdLine ContainsCIS "frombase64string")'
        MITRE = "T1059.001"
        Severity = "High"
    }
    LSASSAccess = @{
        Name = "LSASS Memory Access"
        Query = 'TgtProcName = "lsass.exe" AND EventType = "Open Remote Process Handle" AND SrcProcName Not In ("svchost.exe","lsm.exe","wmiprvse.exe","csrss.exe","MsMpEng.exe")'
        MITRE = "T1003.001"
        Severity = "Critical"
    }
    ScheduledTaskCreation = @{
        Name = "Suspicious Scheduled Task Creation"
        Query = '(TgtProcName = "schtasks.exe" AND TgtProcCmdLine ContainsCIS "/create") AND SrcProcParentName Not In ("services.exe","svchost.exe","msiexec.exe")'
        MITRE = "T1053.005"
        Severity = "Medium"
    }
    EventLogClearing = @{
        Name = "Windows Event Log Clearing"
        Query = '(TgtProcName = "wevtutil.exe" AND TgtProcCmdLine ContainsCIS "cl ") OR (SrcProcCmdLine ContainsCIS "Clear-EventLog")'
        MITRE = "T1070.001"
        Severity = "High"
    }
    WebShellCreation = @{
        Name = "Web Shell File Creation"
        Query = 'EventType = "File Creation" AND FileFullName ContainsCIS "inetpub\wwwroot" AND TgtFileExtension In Contains Anycase ("jsp","aspx","php","asp")'
        MITRE = "T1505.003"
        Severity = "Critical"
    }
    CertutilDownload = @{
        Name = "Certutil File Download"
        Query = 'TgtProcName = "certutil.exe" AND (TgtProcCmdLine ContainsCIS "urlcache" OR TgtProcCmdLine ContainsCIS "verifyctl")'
        MITRE = "T1105"
        Severity = "High"
    }
    WMIPersistence = @{
        Name = "WMI Event Subscription Persistence"
        Query = 'SrcProcCmdLine ContainsCIS "New-CimInstance" AND SrcProcCmdLine ContainsCIS "root/subscription"'
        MITRE = "T1546.003"
        Severity = "High"
    }
    SuspiciousParentChild = @{
        Name = "Office Spawning Shell"
        Query = 'SrcProcName In ("winword.exe","excel.exe","powerpnt.exe","outlook.exe") AND TgtProcName In ("cmd.exe","powershell.exe","wscript.exe","cscript.exe","mshta.exe")'
        MITRE = "T1566.001"
        Severity = "High"
    }
}
 
function Invoke-DVQuery {
    param(
        [string]$Query,
        [string]$FromDate,
        [string]$ToDate,
        [string]$SiteId
    )
 
    $body = @{
        query = $Query
        fromDate = $FromDate
        toDate = $ToDate
        limit = 10000
    }
 
    if ($SiteId) {
        $body.siteIds = @($SiteId)
    }
 
    $response = Invoke-S1ApiRequest -Endpoint "/web/api/v2.1/dv/query" `
        -Method POST -Body $body
 
    return $response.data
}
 
try {
    Connect-S1Console -UseStoredCredentials
 
    # Ensure output directory exists
    if (-not (Test-Path $OutputPath)) {
        New-Item -Path $OutputPath -ItemType Directory -Force | Out-Null
    }
 
    $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
    $fromDate = (Get-Date).AddHours(-$HoursBack).ToString("yyyy-MM-ddTHH:mm:ss.fffZ")
    $toDate = (Get-Date).ToString("yyyy-MM-ddTHH:mm:ss.fffZ")
 
    $huntsToRun = @()
 
    if ($CustomQuery) {
        $huntsToRun += @{
            Name = "CustomQuery"
            Query = $CustomQuery
            MITRE = "Custom"
            Severity = "Medium"
        }
    }
    elseif ($HuntName -eq 'All') {
        $huntsToRun = $HuntingQueries.Values
    }
    else {
        $huntsToRun += $HuntingQueries[$HuntName]
    }
 
    Write-S1Log -Message "Starting threat hunt - $($huntsToRun.Count) queries" -Level INFO
 
    $summaryResults = @()
    $allFindings = @()
 
    foreach ($hunt in $huntsToRun) {
        Write-S1Log -Message "Running hunt: $($hunt.Name)" -Level INFO
 
        try {
            $results = Invoke-DVQuery -Query $hunt.Query -FromDate $fromDate -ToDate $toDate -SiteId $SiteId
 
            $resultCount = if ($results) { $results.Count } else { 0 }
 
            $summaryResults += [PSCustomObject]@{
                HuntName = $hunt.Name
                MITRE = $hunt.MITRE
                Severity = $hunt.Severity
                ResultCount = $resultCount
                Status = if ($resultCount -gt 0) { "FINDINGS" } else { "Clear" }
            }
 
            if ($resultCount -gt 0) {
                Write-S1Log -Message "  [!] Found $resultCount results" -Level WARN
 
                # Export individual hunt results
                $huntFile = Join-Path $OutputPath "$($hunt.Name -replace ' ','_')_$timestamp.csv"
                $results | Export-Csv -Path $huntFile -NoTypeInformation
 
                $allFindings += $results | ForEach-Object {
                    $_ | Add-Member -NotePropertyName 'HuntName' -NotePropertyValue $hunt.Name -PassThru
                }
            }
            else {
                Write-S1Log -Message "  [OK] No findings" -Level SUCCESS
            }
        }
        catch {
            Write-S1Log -Message "  Hunt failed: $($_.Exception.Message)" -Level ERROR
            $summaryResults += [PSCustomObject]@{
                HuntName = $hunt.Name
                MITRE = $hunt.MITRE
                Severity = $hunt.Severity
                ResultCount = -1
                Status = "ERROR"
            }
        }
 
        Start-Sleep -Seconds 2  # Rate limiting
    }
 
    # Export summary
    $summaryFile = Join-Path $OutputPath "HuntingSummary_$timestamp.csv"
    $summaryResults | Export-Csv -Path $summaryFile -NoTypeInformation
 
    # Display summary
    Write-Host "`n=== Threat Hunting Summary ===" -ForegroundColor Cyan
    $summaryResults | Format-Table -AutoSize
 
    # Alert if findings
    $findingsCount = ($summaryResults | Where-Object { $_.Status -eq "FINDINGS" }).Count
    if ($findingsCount -gt 0) {
        Write-S1Log -Message "$findingsCount hunts returned findings - review required!" -Level WARN
 
        if ($AlertOnFindings -and $AlertEmail) {
            $subject = "[SentinelOne] Threat Hunt Findings - $findingsCount Detections"
            $body = "Threat hunting completed with findings:`n`n"
            $body += ($summaryResults | Where-Object { $_.Status -eq "FINDINGS" } |
                      ForEach-Object { "$($_.HuntName): $($_.ResultCount) results" }) -join "`n"
 
            # Send-MailMessage -To $AlertEmail -From "sentinelone@company.com" -Subject $subject -Body $body -SmtpServer "smtp.company.com"
            Write-S1Log -Message "Alert sent to $AlertEmail" -Level INFO
        }
    }
 
    return $summaryResults
 
} catch {
    Write-S1Log -Message "Error: $($_.Exception.Message)" -Level ERROR
    throw
} finally {
    Disconnect-S1Console
}

#Requires -Version 5.1
<#
.SYNOPSIS
    Searches for IOCs across the entire fleet using Deep Visibility
.DESCRIPTION
    Hunts for file hashes, IPs, domains, and file names across all endpoints.
    Supports bulk IOC import from file.
.PARAMETER IOCType
    Type of IOC to search
.PARAMETER IOCValue
    Single IOC value to search
.PARAMETER IOCFile
    Path to file containing IOCs (one per line)
.PARAMETER DaysBack
    Days to search back in telemetry
.EXAMPLE
    .\Search-S1IOC.ps1 -IOCType sha256 -IOCValue "abc123..."
.EXAMPLE
    .\Search-S1IOC.ps1 -IOCType domain -IOCFile "C:\Intel\bad-domains.txt"
#>
 
[CmdletBinding()]
param(
    [Parameter(Mandatory = $true)]
    [ValidateSet('sha256', 'sha1', 'md5', 'ip', 'domain', 'filename')]
    [string]$IOCType,
 
    [Parameter(ParameterSetName = 'Single')]
    [string]$IOCValue,
 
    [Parameter(ParameterSetName = 'Bulk')]
    [string]$IOCFile,
 
    [int]$DaysBack = 14,
    [string]$SiteId,
    [string]$ExportPath
)
 
$ErrorActionPreference = 'Stop'
Import-Module "C:\Scripts\SentinelOne-API-Module.psm1" -Force
 
function Build-IOCQuery {
    param($Type, $Value)
 
    switch ($Type) {
        'sha256' { return "FileSha256 = `"$Value`"" }
        'sha1' { return "FileSha1 = `"$Value`"" }
        'md5' { return "FileMD5 = `"$Value`"" }
        'ip' { return "DstIp = `"$Value`"" }
        'domain' { return "DnsRequest ContainsCIS `"$Value`"" }
        'filename' { return "FileName ContainsCIS `"$Value`"" }
    }
}
 
try {
    Connect-S1Console -UseStoredCredentials
 
    # Get IOC list
    $iocs = @()
    if ($IOCFile) {
        $iocs = Get-Content $IOCFile | Where-Object { $_ -and $_ -notmatch '^#' }
    } else {
        $iocs = @($IOCValue)
    }
 
    Write-S1Log -Message "Searching for $($iocs.Count) IOCs of type: $IOCType" -Level INFO
 
    $fromDate = (Get-Date).AddDays(-$DaysBack).ToString("yyyy-MM-ddTHH:mm:ss.fffZ")
    $toDate = (Get-Date).ToString("yyyy-MM-ddTHH:mm:ss.fffZ")
 
    $allResults = @()
 
    foreach ($ioc in $iocs) {
        $query = Build-IOCQuery -Type $IOCType -Value $ioc
 
        try {
            $body = @{
                query = $query
                fromDate = $fromDate
                toDate = $toDate
                limit = 1000
            }
 
            if ($SiteId) { $body.siteIds = @($SiteId) }
 
            $response = Invoke-S1ApiRequest -Endpoint "/web/api/v2.1/dv/query" `
                -Method POST -Body $body
 
            $resultCount = if ($response.data) { $response.data.Count } else { 0 }
 
            if ($resultCount -gt 0) {
                Write-S1Log -Message "[!] Found $resultCount hits for: $ioc" -Level WARN
 
                foreach ($hit in $response.data) {
                    $allResults += [PSCustomObject]@{
                        IOC = $ioc
                        IOCType = $IOCType
                        AgentName = $hit.agentName
                        SiteName = $hit.siteName
                        EventType = $hit.eventType
                        ProcessName = $hit.srcProcName
                        CommandLine = $hit.srcProcCmdLine
                        FilePath = $hit.fileFullName
                        EventTime = $hit.eventTime
                    }
                }
            } else {
                Write-Verbose "No hits for: $ioc"
            }
        }
        catch {
            Write-S1Log -Message "Query failed for $ioc`: $($_.Exception.Message)" -Level ERROR
        }
 
        Start-Sleep -Milliseconds 500  # Rate limiting
    }
 
    Write-S1Log -Message "Total IOC hits: $($allResults.Count)" -Level SUCCESS
 
    if ($ExportPath -and $allResults.Count -gt 0) {
        $allResults | Export-Csv -Path $ExportPath -NoTypeInformation
        Write-S1Log -Message "Results exported to: $ExportPath" -Level SUCCESS
    }
 
    # Summary by IOC
    if ($allResults.Count -gt 0) {
        Write-Host "`nIOC Hit Summary:" -ForegroundColor Cyan
        $allResults | Group-Object IOC | ForEach-Object {
            Write-Host "  $($_.Name): $($_.Count) hits" -ForegroundColor Yellow
        }
    }
 
    return $allResults
 
} catch {
    Write-S1Log -Message "Error: $($_.Exception.Message)" -Level ERROR
    throw
} finally {
    Disconnect-S1Console
}