PUA Alerts Handling with SIEM Events API

Note: This information is provided as-is for the benefit of the Community. Please contact Sophos Professional Services if you require assistance with your specific environment.


Overview


Sophos Central does not generate an alert every time PUA's are detected so as to not flood the admins with alerts or emails that are usually taken care of by Intercept X automatically. In some environments, you want to know about every PUA detection. Central stores literally all events in the event log database, and through the SIEM events API you can access them quite easily. The (current) PUA detection types are:

  • Event::Endpoint::Threat::PuaDetected
  • Event::Endpoint::HmpaPuaDetected
  • Event::Endpoint::CorePuaDetection
  • Event::Endpoint::CorePuaRemoteDetection
  • Event::Endpoint::HomePuaRemnantsDetected

Sophos Central Admin: Event types and descriptions for Sophos Central API

What to do

All we need to do is to ask the SIEM API to report back (in the frequency you desire) and send (e.g. via mail) the output. For ease of use, I just looked for "-like *Pua*detect*". Below is a PowerShell sample for the first steps, but needs the cursor handling to be finished to avoid duplicate entries if you query more often than every 24 hours and the send email part.

param([switch] $CheckDNS, [switch] $GetVendor)
<#
    SIEM PUA Events
	
#>

cls
Write-Host("PUA Detection Events")
Write-Host("=====================================")

# Check if Central API Credentials have been stored, if not then prompt the user to add them
if ((Test-Path $env:userprofile\sophos_central_admin.json) -eq $false){
	# Prompt for Credentials
	$clientId = Read-Host "Please Enter your Client ID"
	$clientSecret = Read-Host "Please Enter your Client Secret" -AsSecureString | ConvertFrom-SecureString

	# Out to JSON Config File
	ConvertTo-Json $ClientID, $ClientSecret | Out-File $env:userprofile\sophos_central_admin.json -Force
}

# Read Credentials from JSON Config File
$credentials = Get-Content $env:userprofile\sophos_central_admin.json | ConvertFrom-Json
$clientId = $credentials[0]
$clientSecret = $credentials[1] | ConvertTo-SecureString


# Create PSCredential Object for Credentials
$SecureCredentials = New-Object System.Management.Automation.PSCredential -ArgumentList $clientId , $clientSecret


Write-Host("[API] Authenticate to Sophos Central...")

# SOPHOS OAuth URL
$TokenURI = "https://id.sophos.com/api/v2/oauth2/token"

# TokenRequestBody for oAuth2
$TokenRequestBody = @{
	"grant_type" = "client_credentials";
	"client_id" = $SecureCredentials.GetNetworkCredential().Username;
	"client_secret" = $SecureCredentials.GetNetworkCredential().Password;
	"scope" = "token";
}
$TokenRequestHeaders = @{
	"content-type" = "application/x-www-form-urlencoded";
}

# Set TLS Version
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

# Post Request to SOPHOS OAuth2 token:
$APIAuthResult = (Invoke-RestMethod -Method Post -Uri $TokenURI -Body $TokenRequestBody -Headers $TokenRequestHeaders -ErrorAction SilentlyContinue -ErrorVariable ScriptError)

# If there's an error requesting the token, say so, display the error, and break:
if ($ScriptError) {
	Write-Output "FAILED - Unable to retreive SOPHOS API Authentication Token - $($ScriptError)"
	Break
}

# Set the Token for use later on:
$script:Token = $APIAuthResult.access_token


Write-Host("[API] Get tenant details...")
# SOPHOS Whoami URI:
$WhoamiURI = "https://api.central.sophos.com/whoami/v1"

# SOPHOS Whoami Headers:
$WhoamiRequestHeaders = @{
	"Content-Type" = "application/json";
	"Authorization" = "Bearer $script:Token";
}

# Get Request SOPHOS Whoami Details:
$APIWhoamiResult = (Invoke-RestMethod -Method Get -Uri $WhoamiURI -Headers $WhoamiRequestHeaders -ErrorAction SilentlyContinue -ErrorVariable ScriptError)

# Set TenantID and ApiHost for use later on:
$script:ApiTenantId = $APIWhoamiResult.id
$script:ApiHost = $APIWhoamiResult.apiHosts.dataRegion	


# SOPHOS API Headers:
$SIEMAPIHeaders = @{
	"Authorization" = "Bearer $script:Token";
	"X-Tenant-ID" = "$script:ApiTenantId";
    "Content-Type" = "application/json";
}

Write-Host("=====================================")

if ($apihost -ne $null){

    $EventsResponse = (Invoke-RestMethod -Method Get -Uri $script:ApiHost"/siem/v1/events" -Headers $SIEMAPIHeaders -ErrorAction SilentlyContinue -ErrorVariable ScriptError)
	
	#cursor management > need to finish code with cursor from next_cursor /siem/v1/events?cursor=<next_cursor>
	Write-Host $EventsResponse.next_cursor
	Write-Host("=====================================")
	
	Foreach ($item in  $EventsResponse.items ){
	$PUAAlert = $item.type
	# Write-Host $PUAAlert
	if ( $PUAAlert -like "*Pua*Detect*" ) {
	Write-Host $PUAAlert $item.created_at $item.endpoint_type $item.location  $item.name
	# Send-MailMessage -From 'User01 <user01@fabrikam.com>' -To 'User02 <user02@fabrikam.com>' -Subject 'PUA Detected'
	}
	}
}

The output looks like this (the first few lines are just there for debugging)



Added TAGs
[edited by: Qoosh at 1:23 AM (GMT -7) on 21 Jul 2022]
  • Thank you for posting this, really helpful but wondering how this would work for a partner trying to monitor all customers if possible?

  • The section "# SOPHOS Whoami URI:" referenced below, will need to be adjusted so that you’re running the query for each of the tenant IDs within your Partner Portal instead of just for one tenant. Alternatively, you could compose a different script for each of the tenant sites if you feel that would be easier.

    # Get Request SOPHOS Whoami Details:
    $APIWhoamiResult = (Invoke-RestMethod -Method Get -Uri $WhoamiURI -Headers $WhoamiRequestHeaders -ErrorAction SilentlyContinue -ErrorVariable ScriptError)
    
    # Set TenantID and ApiHost for use later on:
    $script:ApiTenantId = $APIWhoamiResult.id
    $script:ApiHost = $APIWhoamiResult.apiHosts.dataRegion	
    
    
    # SOPHOS API Headers:
    $SIEMAPIHeaders = @{
    	"Authorization" = "Bearer $script:Token";
    	"X-Tenant-ID" = "$script:ApiTenantId";
        "Content-Type" = "application/json";

    The script as it is may return errors as no "Events" or "Alerts" are directly associated with your Partner Portal but are aggregated from the sub-estates. 

    Kushal Lakhan
    Global Community Support Engineer
    Connect with Sophos Support, get alerted, and be informed.
    If a post solves your question, please use the "Verify Answer" button.
    The New Home of Sophos Support Videos!  Visit Sophos Techvids