Invoke SentinelOne Threat Hunt

<#
.SYNOPSIS
    Automates SentinelOne Deep Visibility threat hunting queries via API with optional response actions.
 
.DESCRIPTION
    Connects to SentinelOne management console API to execute Deep Visibility queries for threat hunting.
    Supports IOC searches (hash, IP, domain), process patterns, registry modifications, and network connections.
    Generates categorized reports and optionally executes response actions (isolate, kill process, quarantine).
    Logs all operations to C:\BIN\LOGS-\<date\>-S1-ThreatHunt.log.
 
.PARAMETER ManagementUrl
    SentinelOne console URL (e.g., https://yourinstance.sentinelone.net)
 
.PARAMETER ApiToken
    API token with Deep Visibility and response permissions (if not provided, prompts securely)
 
.PARAMETER QueryType
    Type of hunt: FileHash, IPAddress, Domain, ProcessPattern, RegistryMod, NetworkConnection, CustomQuery
 
.PARAMETER SearchValue
    Search term (hash, IP, domain, process name, registry key, etc.)
 
.PARAMETER CustomQuery
    Full Deep Visibility SQL query (used when QueryType is CustomQuery)
 
.PARAMETER TimeRange
    Hours to search back (default: 24)
 
.PARAMETER AutoResponse
    Enable automated response actions with confirmation prompts
 
.PARAMETER ExportPath
    Directory for CSV/JSON exports (default: C:\BIN\S1-ThreatHunt)
 
.EXAMPLE
    .\Invoke-SentinelOne-ThreatHunt.ps1 -ManagementUrl "https://company.sentinelone.net" -QueryType FileHash -SearchValue "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
 
.EXAMPLE
    .\Invoke-SentinelOne-ThreatHunt.ps1 -ManagementUrl "https://company.sentinelone.net" -QueryType ProcessPattern -SearchValue "powershell.exe" -TimeRange 168 -AutoResponse
 
.EXAMPLE
    .\Invoke-SentinelOne-ThreatHunt.ps1 -ManagementUrl "https://company.sentinelone.net" -QueryType CustomQuery -CustomQuery "SELECT * FROM events WHERE processName = 'cmd.exe' AND cmdLine CONTAINS 'mimikatz'"
 
.NOTES
    Version: 1.0
    Author: CosmicBytez IT Automation
    Requires: SentinelOne API token with DeepVisibility.Read and optional RemoteOps permissions
    Dependencies: PowerShell 5.1+, Internet connectivity to SentinelOne console
#>
 
[CmdletBinding()]
param(
    [Parameter(Mandatory = $true)]
    [ValidatePattern('^https://.*\.sentinelone\.(net|com)$')]
    [string]$ManagementUrl,
 
    [Parameter(Mandatory = $false)]
    [SecureString]$ApiToken,
 
    [Parameter(Mandatory = $true)]
    [ValidateSet('FileHash', 'IPAddress', 'Domain', 'ProcessPattern', 'RegistryMod', 'NetworkConnection', 'CustomQuery')]
    [string]$QueryType,
 
    [Parameter(Mandatory = $false)]
    [string]$SearchValue,
 
    [Parameter(Mandatory = $false)]
    [string]$CustomQuery,
 
    [Parameter(Mandatory = $false)]
    [ValidateRange(1, 8760)]
    [int]$TimeRange = 24,
 
    [Parameter(Mandatory = $false)]
    [switch]$AutoResponse,
 
    [Parameter(Mandatory = $false)]
    [string]$ExportPath = "C:\BIN\S1-ThreatHunt"
)
 
$ErrorActionPreference = 'Stop'
 
# Initialize logging
$timestamp = Get-Date -Format "yyyy-MM-dd"
$logFile = "C:\BIN\LOGS-$timestamp-S1-ThreatHunt.log"
 
# Ensure log directory exists
if (-not (Test-Path "C:\BIN")) {
    New-Item -Path "C:\BIN" -ItemType Directory -Force | Out-Null
}
 
function Write-Log {
    param(
        [Parameter(Mandatory = $true)]
        [string]$Message,
 
        [Parameter(Mandatory = $false)]
        [ValidateSet('INFO', 'WARNING', 'ERROR', 'SUCCESS')]
        [string]$Level = 'INFO'
    )
 
    $logTimestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
    $logEntry = "[$logTimestamp] [$Level] $Message"
    Add-Content -Path $logFile -Value $logEntry
 
    switch ($Level) {
        'ERROR'   { Write-Host $logEntry -ForegroundColor Red }
        'WARNING' { Write-Host $logEntry -ForegroundColor Yellow }
        'SUCCESS' { Write-Host $logEntry -ForegroundColor Green }
        default   { Write-Host $logEntry -ForegroundColor White }
    }
}
 
function Get-S1ApiToken {
    if ($null -eq $ApiToken) {
        Write-Host "`nSentinelOne API Token required (with DeepVisibility.Read permission)" -ForegroundColor Cyan
        Write-Host "Obtain from: $ManagementUrl/settings/users > API Token" -ForegroundColor Gray
        $ApiToken = Read-Host "Enter API Token" -AsSecureString
    }
 
    $BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($ApiToken)
    $plainToken = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR)
    [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($BSTR)
 
    return $plainToken
}
 
function Invoke-S1ApiRequest {
    param(
        [Parameter(Mandatory = $true)]
        [string]$Endpoint,
 
        [Parameter(Mandatory = $false)]
        [string]$Method = 'GET',
 
        [Parameter(Mandatory = $false)]
        [hashtable]$Body,
 
        [Parameter(Mandatory = $true)]
        [string]$Token
    )
 
    $headers = @{
        'Authorization' = "ApiToken $Token"
        'Content-Type'  = 'application/json'
    }
 
    $uri = "$ManagementUrl/web/api/v2.1/$Endpoint"
 
    try {
        $params = @{
            Uri     = $uri
            Method  = $Method
            Headers = $headers
        }
 
        if ($Body) {
            $params.Body = ($Body | ConvertTo-Json -Depth 10 -Compress)
        }
 
        Write-Log "API Request: $Method $Endpoint" -Level INFO
        $response = Invoke-RestMethod @params
        return $response
    }
    catch {
        Write-Log "API Request Failed: $_" -Level ERROR
        throw
    }
}
 
function Get-DeepVisibilityQuery {
    param(
        [Parameter(Mandatory = $true)]
        [string]$Type,
 
        [Parameter(Mandatory = $false)]
        [string]$Value,
 
        [Parameter(Mandatory = $false)]
        [string]$Custom
    )
 
    # Deep Visibility SQL-like query templates
    switch ($Type) {
        'FileHash' {
            return @"
SELECT
    AgentName,
    SrcProcUser,
    SrcProcCmdLine,
    SrcProcName,
    SrcProcSha1,
    SrcProcSha256,
    TgtFilePath,
    TgtFileSha1,
    TgtFileSha256,
    EventTime
FROM events
WHERE (SrcProcSha1 = '$Value' OR SrcProcSha256 = '$Value' OR TgtFileSha1 = '$Value' OR TgtFileSha256 = '$Value')
ORDER BY EventTime DESC
LIMIT 1000
"@
        }
 
        'IPAddress' {
            return @"
SELECT
    AgentName,
    SrcProcName,
    SrcProcCmdLine,
    DstIp,
    DstPort,
    SrcIp,
    IndicatorName,
    EventType,
    EventTime
FROM events
WHERE (DstIp = '$Value' OR SrcIp = '$Value')
ORDER BY EventTime DESC
LIMIT 1000
"@
        }
 
        'Domain' {
            return @"
SELECT
    AgentName,
    SrcProcName,
    SrcProcCmdLine,
    DnsRequest,
    DnsResponse,
    DstIp,
    EventTime
FROM events
WHERE DnsRequest CONTAINS '$Value'
ORDER BY EventTime DESC
LIMIT 1000
"@
        }
 
        'ProcessPattern' {
            return @"
SELECT
    AgentName,
    SrcProcUser,
    SrcProcName,
    SrcProcCmdLine,
    SrcProcSha256,
    SrcProcParentName,
    SrcProcIntegrityLevel,
    EventTime
FROM events
WHERE (SrcProcName CONTAINS '$Value' OR SrcProcCmdLine CONTAINS '$Value')
ORDER BY EventTime DESC
LIMIT 1000
"@
        }
 
        'RegistryMod' {
            return @"
SELECT
    AgentName,
    SrcProcName,
    SrcProcCmdLine,
    RegistryKeyPath,
    RegistryOldValue,
    RegistryValue,
    EventType,
    EventTime
FROM events
WHERE (EventType = 'Registry Value Create' OR EventType = 'Registry Value Modified')
  AND RegistryKeyPath CONTAINS '$Value'
ORDER BY EventTime DESC
LIMIT 1000
"@
        }
 
        'NetworkConnection' {
            return @"
SELECT
    AgentName,
    SrcProcName,
    SrcProcCmdLine,
    DstIp,
    DstPort,
    DstPortName,
    IndicatorName,
    EventType,
    EventTime
FROM events
WHERE EventType IN ('IP Connect', 'IP Listen')
  AND (DstPort IN (4444, 5555, 8080, 8443, 1337) OR DstPortName = 'unknown')
ORDER BY EventTime DESC
LIMIT 1000
"@
        }
 
        'CustomQuery' {
            return $Custom
        }
    }
}
 
function Invoke-DeepVisibilityQuery {
    param(
        [Parameter(Mandatory = $true)]
        [string]$Query,
 
        [Parameter(Mandatory = $true)]
        [int]$Hours,
 
        [Parameter(Mandatory = $true)]
        [string]$Token
    )
 
    # Calculate time range
    $toDate = Get-Date
    $fromDate = $toDate.AddHours(-$Hours)
 
    $body = @{
        query    = $Query
        fromDate = $fromDate.ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ss.fffZ")
        toDate   = $toDate.ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ss.fffZ")
        limit    = 1000
    }
 
    Write-Log "Executing Deep Visibility Query (last $Hours hours)" -Level INFO
    Write-Log "Query: $($Query -replace "`n",' ')" -Level INFO
 
    # Create query
    $queryResponse = Invoke-S1ApiRequest -Endpoint "dv/init-query" -Method POST -Body $body -Token $Token
 
    if (-not $queryResponse.data.queryId) {
        Write-Log "Failed to initialize query" -Level ERROR
        return $null
    }
 
    $queryId = $queryResponse.data.queryId
    Write-Log "Query ID: $queryId" -Level INFO
 
    # Poll for query completion
    $maxAttempts = 30
    $attempt = 0
    $queryStatus = $null
 
    while ($attempt -lt $maxAttempts) {
        Start-Sleep -Seconds 2
        $attempt++
 
        $statusResponse = Invoke-S1ApiRequest -Endpoint "dv/query-status?queryId=$queryId" -Token $Token
        $queryStatus = $statusResponse.data.responseState
 
        Write-Verbose "Query status: $queryStatus (attempt $attempt/$maxAttempts)"
 
        if ($queryStatus -eq 'FINISHED') {
            break
        }
        elseif ($queryStatus -eq 'FAILED') {
            Write-Log "Query execution failed" -Level ERROR
            return $null
        }
    }
 
    if ($queryStatus -ne 'FINISHED') {
        Write-Log "Query timeout after $maxAttempts attempts" -Level ERROR
        return $null
    }
 
    # Retrieve results
    $results = @()
    $cursor = $null
 
    do {
        $resultsEndpoint = "dv/events?queryId=$queryId"
        if ($cursor) {
            $resultsEndpoint += "&cursor=$cursor"
        }
 
        $resultsResponse = Invoke-S1ApiRequest -Endpoint $resultsEndpoint -Token $Token
 
        if ($resultsResponse.data) {
            $results += $resultsResponse.data
        }
 
        $cursor = $resultsResponse.pagination.nextCursor
    } while ($cursor)
 
    Write-Log "Retrieved $($results.Count) events" -Level SUCCESS
    return $results
}
 
function Get-ThreatSeverity {
    param(
        [Parameter(Mandatory = $true)]
        [object]$Event
    )
 
    $criticalIndicators = @(
        'mimikatz', 'psexec', 'bloodhound', 'sharphound', 'rubeus', 'cobalt',
        'meterpreter', 'empire', 'covenant', 'ransomware', 'lazagne'
    )
 
    $highIndicators = @(
        'powershell -enc', '-nop -w hidden', 'invoke-expression', 'downloadstring',
        'iex(', 'invoke-mimikatz', 'net user', 'net localgroup administrators',
        'wmic', 'reg add', 'schtasks', 'vssadmin delete shadows'
    )
 
    $eventText = ($Event | ConvertTo-Json -Compress).ToLower()
 
    # Critical severity checks
    foreach ($indicator in $criticalIndicators) {
        if ($eventText -match $indicator) {
            return 'CRITICAL'
        }
    }
 
    # High severity checks
    foreach ($indicator in $highIndicators) {
        if ($eventText -match [regex]::Escape($indicator)) {
            return 'HIGH'
        }
    }
 
    # Medium severity for suspicious patterns
    if ($Event.SrcProcIntegrityLevel -eq 'high' -or
        $Event.IndicatorName -or
        $Event.DstPort -in @(4444, 5555, 1337, 31337)) {
        return 'MEDIUM'
    }
 
    return 'LOW'
}
 
function New-ThreatHuntReport {
    param(
        [Parameter(Mandatory = $true)]
        [array]$Events,
 
        [Parameter(Mandatory = $true)]
        [string]$QueryType,
 
        [Parameter(Mandatory = $false)]
        [string]$SearchTerm
    )
 
    Write-Log "Analyzing $($Events.Count) events for threats..." -Level INFO
 
    # Categorize by severity
    $findings = $Events | ForEach-Object {
        $severity = Get-ThreatSeverity -Event $_
        $_ | Add-Member -NotePropertyName 'ThreatSeverity' -NotePropertyValue $severity -Force -PassThru
    }
 
    $critical = @($findings | Where-Object { $_.ThreatSeverity -eq 'CRITICAL' })
    $high = @($findings | Where-Object { $_.ThreatSeverity -eq 'HIGH' })
    $medium = @($findings | Where-Object { $_.ThreatSeverity -eq 'MEDIUM' })
    $low = @($findings | Where-Object { $_.ThreatSeverity -eq 'LOW' })
 
    # Generate report
    $report = @{
        GeneratedAt    = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
        QueryType      = $QueryType
        SearchTerm     = $SearchTerm
        TimeRangeHours = $TimeRange
        TotalEvents    = $Events.Count
        Severity       = @{
            Critical = $critical.Count
            High     = $high.Count
            Medium   = $medium.Count
            Low      = $low.Count
        }
        CriticalFindings = $critical
        HighFindings     = $high
        MediumFindings   = $medium
        LowFindings      = $low
    }
 
    # Console output
    Write-Host "`n========================================" -ForegroundColor Cyan
    Write-Host "  SentinelOne Threat Hunt Report" -ForegroundColor Cyan
    Write-Host "========================================" -ForegroundColor Cyan
    Write-Host "Generated: $($report.GeneratedAt)" -ForegroundColor White
    Write-Host "Query Type: $QueryType" -ForegroundColor White
    if ($SearchTerm) {
        Write-Host "Search Term: $SearchTerm" -ForegroundColor White
    }
    Write-Host "Time Range: Last $TimeRange hours" -ForegroundColor White
    Write-Host "`nTotal Events: $($report.TotalEvents)" -ForegroundColor White
    Write-Host "`nSeverity Distribution:" -ForegroundColor Yellow
    Write-Host "  CRITICAL: $($critical.Count)" -ForegroundColor Red
    Write-Host "  HIGH:     $($high.Count)" -ForegroundColor DarkRed
    Write-Host "  MEDIUM:   $($medium.Count)" -ForegroundColor DarkYellow
    Write-Host "  LOW:      $($low.Count)" -ForegroundColor Gray
 
    if ($critical.Count -gt 0) {
        Write-Host "`nCRITICAL Findings:" -ForegroundColor Red
        $critical | Select-Object -First 5 | ForEach-Object {
            Write-Host "  - Agent: $($_.AgentName) | Process: $($_.SrcProcName) | Cmd: $($_.SrcProcCmdLine)" -ForegroundColor Red
        }
        if ($critical.Count -gt 5) {
            Write-Host "  ... and $($critical.Count - 5) more" -ForegroundColor Red
        }
    }
 
    if ($high.Count -gt 0) {
        Write-Host "`nHIGH Findings:" -ForegroundColor DarkRed
        $high | Select-Object -First 3 | ForEach-Object {
            Write-Host "  - Agent: $($_.AgentName) | Process: $($_.SrcProcName) | Cmd: $($_.SrcProcCmdLine)" -ForegroundColor DarkRed
        }
        if ($high.Count -gt 3) {
            Write-Host "  ... and $($high.Count - 3) more" -ForegroundColor DarkRed
        }
    }
 
    Write-Host "`n========================================`n" -ForegroundColor Cyan
 
    Write-Log "Threat analysis complete: $($critical.Count) CRITICAL, $($high.Count) HIGH, $($medium.Count) MEDIUM, $($low.Count) LOW" -Level SUCCESS
 
    return $report
}
 
function Export-ThreatHuntResults {
    param(
        [Parameter(Mandatory = $true)]
        [hashtable]$Report,
 
        [Parameter(Mandatory = $true)]
        [string]$ExportDirectory
    )
 
    # Ensure export directory exists
    if (-not (Test-Path $ExportDirectory)) {
        New-Item -Path $ExportDirectory -ItemType Directory -Force | Out-Null
        Write-Log "Created export directory: $ExportDirectory" -Level INFO
    }
 
    $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
    $baseFilename = "$ExportDirectory\S1-ThreatHunt-$timestamp"
 
    # Export JSON (full report)
    $jsonPath = "$baseFilename.json"
    $Report | ConvertTo-Json -Depth 10 | Out-File -FilePath $jsonPath -Encoding UTF8
    Write-Log "Exported JSON report: $jsonPath" -Level SUCCESS
 
    # Export CSV (flattened findings)
    $csvPath = "$baseFilename.csv"
    $allFindings = @()
    $allFindings += $Report.CriticalFindings
    $allFindings += $Report.HighFindings
    $allFindings += $Report.MediumFindings
    $allFindings += $Report.LowFindings
 
    if ($allFindings.Count -gt 0) {
        $allFindings | Export-Csv -Path $csvPath -NoTypeInformation -Encoding UTF8
        Write-Log "Exported CSV findings: $csvPath" -Level SUCCESS
    }
 
    return @{
        JsonPath = $jsonPath
        CsvPath  = $csvPath
    }
}
 
function Invoke-ThreatResponse {
    param(
        [Parameter(Mandatory = $true)]
        [hashtable]$Report,
 
        [Parameter(Mandatory = $true)]
        [string]$Token
    )
 
    if (-not $AutoResponse) {
        Write-Host "`nAutomated response actions disabled. Use -AutoResponse to enable." -ForegroundColor Yellow
        return
    }
 
    $criticalEvents = $Report.CriticalFindings + $Report.HighFindings
 
    if ($criticalEvents.Count -eq 0) {
        Write-Host "`nNo CRITICAL or HIGH severity findings requiring response." -ForegroundColor Green
        return
    }
 
    Write-Host "`n========================================" -ForegroundColor Red
    Write-Host "  Automated Response Actions" -ForegroundColor Red
    Write-Host "========================================" -ForegroundColor Red
    Write-Host "Found $($criticalEvents.Count) CRITICAL/HIGH severity events`n" -ForegroundColor Yellow
 
    # Get unique agents from critical events
    $affectedAgents = $criticalEvents | Select-Object -ExpandProperty AgentName -Unique
 
    Write-Host "Affected Endpoints:" -ForegroundColor Yellow
    $affectedAgents | ForEach-Object { Write-Host "  - $_" -ForegroundColor White }
 
    Write-Host "`nAvailable Response Actions:" -ForegroundColor Cyan
    Write-Host "  1. Isolate affected endpoints from network" -ForegroundColor White
    Write-Host "  2. Kill suspicious processes" -ForegroundColor White
    Write-Host "  3. Quarantine malicious files" -ForegroundColor White
    Write-Host "  4. No action (manual investigation)" -ForegroundColor White
 
    $choice = Read-Host "`nSelect action (1-4)"
 
    switch ($choice) {
        '1' {
            $confirm = Read-Host "Confirm network isolation of $($affectedAgents.Count) endpoints? (yes/no)"
            if ($confirm -eq 'yes') {
                Write-Log "Network isolation requested for $($affectedAgents.Count) endpoints" -Level WARNING
                # Note: Actual implementation requires agent IDs and disconnect endpoint API
                Write-Host "Network isolation would be executed here (requires agent ID resolution)" -ForegroundColor Yellow
                Write-Host "API Endpoint: POST /web/api/v2.1/agents/actions/disconnect" -ForegroundColor Gray
            }
            else {
                Write-Log "Network isolation cancelled by user" -Level INFO
            }
        }
 
        '2' {
            $confirm = Read-Host "Confirm process termination on affected endpoints? (yes/no)"
            if ($confirm -eq 'yes') {
                Write-Log "Process termination requested" -Level WARNING
                Write-Host "Process termination would be executed here (requires agent ID and process ID)" -ForegroundColor Yellow
                Write-Host "API Endpoint: POST /web/api/v2.1/agents/actions/kill-process" -ForegroundColor Gray
            }
            else {
                Write-Log "Process termination cancelled by user" -Level INFO
            }
        }
 
        '3' {
            $confirm = Read-Host "Confirm file quarantine on affected endpoints? (yes/no)"
            if ($confirm -eq 'yes') {
                Write-Log "File quarantine requested" -Level WARNING
                Write-Host "File quarantine would be executed here (requires threat ID)" -ForegroundColor Yellow
                Write-Host "API Endpoint: POST /web/api/v2.1/threats/actions/mitigate" -ForegroundColor Gray
            }
            else {
                Write-Log "File quarantine cancelled by user" -Level INFO
            }
        }
 
        '4' {
            Write-Log "No automated action taken - manual investigation recommended" -Level INFO
        }
 
        default {
            Write-Host "Invalid selection. No action taken." -ForegroundColor Red
        }
    }
}
 
# ============================================================================
# MAIN EXECUTION
# ============================================================================
 
Write-Log "=== SentinelOne Threat Hunt Started ===" -Level INFO
Write-Log "Management Console: $ManagementUrl" -Level INFO
Write-Log "Query Type: $QueryType" -Level INFO
 
try {
    # Get API token
    $token = Get-S1ApiToken
 
    # Test API connectivity
    Write-Log "Testing API connectivity..." -Level INFO
    $accountInfo = Invoke-S1ApiRequest -Endpoint "accounts" -Token $token
    Write-Log "Connected to SentinelOne console successfully" -Level SUCCESS
 
    # Validate parameters
    if ($QueryType -ne 'CustomQuery' -and [string]::IsNullOrEmpty($SearchValue)) {
        throw "SearchValue parameter required for QueryType: $QueryType"
    }
 
    if ($QueryType -eq 'CustomQuery' -and [string]::IsNullOrEmpty($CustomQuery)) {
        throw "CustomQuery parameter required when QueryType is CustomQuery"
    }
 
    # Build Deep Visibility query
    $dvQuery = Get-DeepVisibilityQuery -Type $QueryType -Value $SearchValue -Custom $CustomQuery
 
    # Execute query
    $queryResults = Invoke-DeepVisibilityQuery -Query $dvQuery -Hours $TimeRange -Token $token
 
    if ($null -eq $queryResults -or $queryResults.Count -eq 0) {
        Write-Log "No events found matching query criteria" -Level WARNING
        Write-Host "`nNo results found. Consider expanding time range or adjusting search criteria." -ForegroundColor Yellow
        exit 0
    }
 
    # Generate threat hunt report
    $report = New-ThreatHuntReport -Events $queryResults -QueryType $QueryType -SearchTerm $SearchValue
 
    # Export results
    $exportedFiles = Export-ThreatHuntResults -Report $report -ExportDirectory $ExportPath
 
    Write-Host "Results exported to:" -ForegroundColor Cyan
    Write-Host "  JSON: $($exportedFiles.JsonPath)" -ForegroundColor White
    Write-Host "  CSV:  $($exportedFiles.CsvPath)" -ForegroundColor White
 
    # Automated response actions
    Invoke-ThreatResponse -Report $report -Token $token
 
    Write-Log "=== Threat Hunt Completed Successfully ===" -Level SUCCESS
}
catch {
    Write-Log "Threat hunt failed: $_" -Level ERROR
    Write-Log "Stack Trace: $($_.ScriptStackTrace)" -Level ERROR
    throw
}
finally {
    # Secure cleanup
    if ($token) {
        $token = $null
        [System.GC]::Collect()
    }
}
 
<#
EXAMPLE DEEP VISIBILITY QUERIES FOR REFERENCE:
 
1. Credential Access Detection (Mimikatz, LSASS dumping):
SELECT AgentName, SrcProcName, SrcProcCmdLine, TgtProcName, EventTime
FROM events
WHERE (SrcProcCmdLine CONTAINS 'lsass' OR SrcProcCmdLine CONTAINS 'sekurlsa'
       OR TgtProcName = 'lsass.exe')
  AND EventType IN ('Process Creation', 'Open Remote Process')
ORDER BY EventTime DESC
 
2. Lateral Movement Detection (PSExec, WMI, Remote Services):
SELECT AgentName, SrcProcName, SrcProcCmdLine, DstIp, DstPort, EventTime
FROM events
WHERE (SrcProcName IN ('psexec.exe', 'wmic.exe', 'mmc.exe', 'wmiprvse.exe')
       OR DstPort IN (445, 135, 5985, 5986))
  AND EventType IN ('IP Connect', 'Process Creation')
ORDER BY EventTime DESC
 
3. Persistence Mechanism Detection (Registry Run Keys, Scheduled Tasks):
SELECT AgentName, SrcProcName, RegistryKeyPath, RegistryValue, EventTime
FROM events
WHERE EventType IN ('Registry Value Create', 'Registry Value Modified')
  AND (RegistryKeyPath CONTAINS 'CurrentVersion\Run'
       OR RegistryKeyPath CONTAINS 'CurrentVersion\Policies\Explorer\Run'
       OR RegistryKeyPath CONTAINS 'CurrentVersion\Windows\Load')
ORDER BY EventTime DESC
 
4. Command and Control Detection (Encoded Commands, Suspicious Network):
SELECT AgentName, SrcProcName, SrcProcCmdLine, DstIp, DnsRequest, EventTime
FROM events
WHERE (SrcProcCmdLine CONTAINS '-enc' OR SrcProcCmdLine CONTAINS '-e '
       OR SrcProcCmdLine CONTAINS 'FromBase64String'
       OR SrcProcCmdLine CONTAINS 'DownloadString')
  AND SrcProcName IN ('powershell.exe', 'cmd.exe', 'wscript.exe', 'cscript.exe')
ORDER BY EventTime DESC
 
5. Data Exfiltration Detection (Large Uploads, Archiving):
SELECT AgentName, SrcProcName, SrcProcCmdLine, TgtFilePath, EventTime
FROM events
WHERE (SrcProcName IN ('7z.exe', 'winrar.exe', 'tar.exe')
       OR SrcProcCmdLine CONTAINS 'compress-archive'
       OR (EventType = 'IP Connect' AND DstPort IN (21, 22, 443, 8443)))
ORDER BY EventTime DESC
 
6. Ransomware Behavior Detection (Shadow Copy Deletion, Mass File Encryption):
SELECT AgentName, SrcProcName, SrcProcCmdLine, TgtFilePath, EventTime
FROM events
WHERE (SrcProcCmdLine CONTAINS 'vssadmin delete shadows'
       OR SrcProcCmdLine CONTAINS 'wbadmin delete catalog'
       OR SrcProcCmdLine CONTAINS 'bcdedit /set {default} recoveryenabled no'
       OR TgtFilePath CONTAINS '.encrypted' OR TgtFilePath CONTAINS '.locked')
ORDER BY EventTime DESC
 
7. Living Off The Land Binaries (LOLBins):
SELECT AgentName, SrcProcName, SrcProcCmdLine, SrcProcParentName, EventTime
FROM events
WHERE SrcProcName IN ('certutil.exe', 'bitsadmin.exe', 'regsvr32.exe', 'mshta.exe',
                      'rundll32.exe', 'regasm.exe', 'installutil.exe', 'msbuild.exe')
  AND EventType = 'Process Creation'
ORDER BY EventTime DESC
 
8. Suspicious Parent-Child Process Relationships:
SELECT AgentName, SrcProcParentName, SrcProcName, SrcProcCmdLine, EventTime
FROM events
WHERE (SrcProcParentName IN ('winword.exe', 'excel.exe', 'powerpnt.exe', 'outlook.exe')
       AND SrcProcName IN ('powershell.exe', 'cmd.exe', 'wscript.exe', 'cscript.exe'))
  OR (SrcProcParentName IN ('w3wp.exe', 'httpd.exe', 'nginx.exe')
      AND SrcProcName IN ('cmd.exe', 'powershell.exe', 'net.exe'))
ORDER BY EventTime DESC
 
API ENDPOINTS REFERENCE:
- Deep Visibility Query Init: POST /web/api/v2.1/dv/init-query
- Query Status: GET /web/api/v2.1/dv/query-status?queryId={id}
- Query Results: GET /web/api/v2.1/dv/events?queryId={id}
- Network Isolation: POST /web/api/v2.1/agents/actions/disconnect
- Process Kill: POST /web/api/v2.1/agents/actions/kill-process
- Threat Mitigation: POST /web/api/v2.1/threats/actions/mitigate
- Agent Details: GET /web/api/v2.1/agents?computerName={name}
 
SENTINELCTL CLI ALTERNATIVE (Windows Agent):
sentinelctl.exe deepvisibility query --query "SELECT * FROM events WHERE..." --from "2025-11-05T00:00:00Z" --to "2025-11-06T00:00:00Z"
sentinelctl.exe network disconnect
sentinelctl.exe process kill --pid {pid}
#>