EPM Elastic events

Why change to Elastic Common Schema (ECS)?

EPM is developing a more scalable data infrastructure to better support your reporting, analytics, and insights needs.

We’re using the elastic stack to provide scale and speed in ingesting and searching the millions of events we process every day.

To enable better correlation of our data with others sources and make our events easier to work with, we have adopted the well-known open source schema that was built for Elastic: the Elastic Common Schema (ECS).

ℹ️

For more information, see Elastics Docs.

What does it mean for me?

There is no change in your existing analytics or SIEM integrations in EPM.

A new API is exposed to extract the events in bulk.

get /v{version}/Events/FromStartDate

The following is an example PowerShell usage script.

## Example Usage .\Events_FromStartDate.ps1 -nextDate "YYYY-MM-DDTHH:MM:SSZ" -tenantName "Prefix" -apiClientId "CLIENT ID" -apiClientSecret "CLIENT SECRET"

param (
    [Parameter(mandatory = $true)] $nextDate,
    [Parameter(mandatory = $true)] $tenantName,
    [Parameter(mandatory = $true)] $apiClientId,
    [Parameter(mandatory = $true)] $apiClientSecret
)

$_baseUrl = "https://$tenantName-services.pm.beyondtrustcloud.com"
$scriptDir = $PSScriptRoot
$finalFile = Join-Path $scriptDir "Events.json"

function Get-AccessToken(
    [Parameter(mandatory = $true)][string] $apiClientId,
    [Parameter(mandatory = $true)][string] $apiClientSecret) {

    $authBody = @{
        client_id     = "$apiClientId"
        client_secret = "$apiClientSecret"
        scope         = "urn:management:api"
        grant_type    = "client_credentials"
    }
    $tokenUrl = "$_baseUrl/oauth/token"
    $response = Invoke-WebRequest -Uri $tokenUrl -ContentType "application/x-www-form-urlencoded" -Body $authBody -Method Post -ErrorAction Stop
    $accessToken = $response.content | ConvertFrom-Json
    return $accessToken
}

function Fix-DuplicateKeys($jsonString) {
    $fixedJsonString = $jsonString -replace '"Owner":', '"owner":'
    return $fixedJsonString
}

function Get-AllPages( 
    [Parameter(mandatory = $true)][System.Object] $accessToken, 
    [Parameter(mandatory = $true)][string] $nextDate) {

    $page = 1
    $eventIds = @{}
    $totalEvents = 0

    try {
        $writer = [System.IO.StreamWriter]::new($finalFile)
        $writer.WriteLine("{") | Out-Null
        $writer.WriteLine("\`"totalRecordsReturned\`": 0,") | Out-Null
        $writer.WriteLine("\`"events\`": [") | Out-Null

        $firstEvent = $true

        while ($true) {
            if (($accessToken.expires_in - $TotalStopwatch.Elapsed.Seconds) -lt 10) {
                Write-Host "******* AccessToken Expiring in 10 Sec So Requesting New Accesstoken ********"
                $accessToken = Get-AccessToken $apiClientId $apiClientSecret
            }
            $headers = @{
                'Authorization'     = "Bearer " + $accessToken.access_token
                'Content-Type'      = 'application/json'
                'ExpiresOn'         = $accessToken.expires_in
                'client-request-id' = New-Guid
            }
            $Stopwatch = [System.Diagnostics.Stopwatch]::StartNew()
            $resourceUrl = "$_baseUrl/management-api/v2/Events/FromStartDate?StartDate=$nextDate&RecordSize=1000"
            $Response = Invoke-WebRequest -Uri $resourceUrl -Headers $headers -Method Get -ErrorAction Stop
            $Stopwatch.Stop()

            $fixedJsonString = Fix-DuplicateKeys $Response.content
            $jsonObj = $fixedJsonString | ConvertFrom-Json

            foreach ($event in $jsonObj.events) {
                if (-not $eventIds.ContainsKey($event.event.id)) {
                    $eventIds[$event.event.id] = $true
                    $eventJson = $event | ConvertTo-Json -Depth 10 -Compress
                    if (-not $firstEvent) {
                        $writer.WriteLine(",") | Out-Null
                    }
                    $writer.Write($eventJson) | Out-Null
                    $firstEvent = $false
                    $totalEvents++
                }
            }

            $lastEvent = $jsonObj.events[$jsonObj.events.Count - 1].event
            $lastTimeStamp = [DateTime]::Parse($lastEvent.ingested).ToUniversalTime().ToString('o')

            $timetake = $Stopwatch.ElapsedMilliseconds 
            $line = "$page*1000 -- $nextDate  TimeTake: $timetake"
            Write-Host $line 

            $page++
            $nextDate = $lastTimeStamp
            if ($jsonObj.events.Count -lt 1000) { break; }
        }

        $writer.WriteLine("]") | Out-Null
        $writer.WriteLine("}") | Out-Null
        $writer.Close()
    (Get-Content $finalFile) -replace '"totalRecordsReturned": 0,', "\`"totalRecordsReturned\`": $totalEvents," | Set-Content $finalFile
    }
    catch {
        Write-Host "An error occurred: $_"
    }
}

$TotalStopwatch = [System.Diagnostics.Stopwatch]::StartNew()
$accessToken = Get-AccessToken $apiClientId $apiClientSecret
Get-AllPages $accessToken $nextDate
$TotalStopwatch.Stop()
$sec = $TotalStopwatch.Elapsed.TotalSeconds
$finishLine = "Total Time Taken To Fetch All Pages $sec Seconds"
Write-Host $finishLine
exit(0)

Elastic based events

The following tables indicate the presence of field sets for each event type currently raised.

The Field Sets tables contain the following:

• Some field sets are always present.
• Some are always present for that event type.
• Some always present for a given application type.
• Some are always optional, present when a particular rule configuration drives them.

The Fields Sets Details tables contain fields within a field set and whether they are mandatory or optional (within that field set).

Some ECS field sets are extended with custom fields where necessary. For those properties specific to Endpoint Privilege Management, there is a EPMWinMac field set too.

ℹ️

For more information on Elastic custom fields, see Elastic's Custom Fields documentation.

Field sets

Key for field sets

Windows processes - field sets

'- when Parent Process is not msiexec.exe

^- when Parent Process is msiexec.exe

Mac processes - field sets

Other - field sets

Field sets detail

Key for field sets detail

Common

All events raised will have these fields.

User

Configuration

Any event raised by an Endpoint Privilege Management for Windows or Endpoint Privilege Management for Mac rule match has these fields.

Process

Windows process

macOS process

File

Windows executable file

macOS executable file

Hosted file

macOS hosted file

Windows COM

Windows ActiveX

Windows Store apps

Windows remote PowerShell

Windows installers

Uninstallers

Services

PPAM

DLL

User session

EPM start

EPM stop

Authorizing user

Rule script

Trusted application protection

These fields are populated when the Trusted Application Workstyles are enabled and a Trusted Application has a child process launch or DLL load blocked.