SfSkills Domains Docs GitHub

Home / security / event-monitoring

event-monitoring

Shield Event Monitoring: event log types, downloading logs via REST API and SOQL, real-time event monitoring with streaming API, and threat detection policies. NOT for debug logs — use apex/debug-logs-and-developer-console. NOT for custom platform event publishing/subscribing — use apex/platform-events-apex.

Open the skill folder on GitHub

Event Monitoring

This skill activates when a practitioner needs to audit user activity, download event log files, configure real-time threat detection, or investigate security anomalies in a Salesforce org. It covers both batch EventLogFile-based monitoring and real-time streaming-based monitoring via Shield. It does not cover debug logs (see debug-logs-and-developer-console) or custom platform event publishing (see platform-events-apex).

Before Starting

Gather this context before working on anything in this domain:

ContextWhat to confirm
License checkEvent Monitoring requires Salesforce Shield or the Event Monitoring add-on. Without one, only 5 basic event types (Login, Logout, URI, API Total Usage, Apex Unexpected Exception) are available with 1-day retention.
Real-Time vs. BatchEvent Log Files (batch, next-day) and Real-Time Event Monitoring (streaming, immediate) are distinct access patterns. Confirm which the request requires.
Permissions"View Event Log Files" is needed for EventLogFile access; "View Real-Time Event Monitoring Data" is required for RTEM streaming events.
Log delayStandard Event Log Files are generated once per day with a 24-hour delay. Hourly log files are Shield-only.
CSV deliveryEventLogFile content is a gzip-compressed CSV retrieved via a separate REST call — not returned inline in the SOQL query result.

Core Concepts

Mode 1 — Event Log Files (Batch)

Event Log Files are the primary mechanism for historical audit analysis. They are stored as the EventLogFile sObject and queryable via SOQL.

Key fields on EventLogFile:

There are 70+ event types. Security-relevant examples: Login, LoginAs, Logout, API, Report, ContentTransfer, ApexExecution, BulkApi, URI, VisualforceRequest.

Retention:

SOQL query pattern:

SELECT Id, EventType, LogDate, LogFileLength, Interval
FROM EventLogFile
WHERE EventType = 'Login'
  AND LogDate = LAST_N_DAYS:7
ORDER BY LogDate DESC

Download log content via REST (Id from above SOQL):

GET /services/data/v63.0/sobjects/EventLogFile/{Id}/LogFile
Authorization: Bearer {sessionId}

Response: gzip-compressed CSV. First row is the column header. Each subsequent row is one event record. Column names and semantics are event-type specific and documented in the EventLogFile Object Reference.

Mode 2 — Real-Time Event Monitoring (RTEM)

Real-Time Event Monitoring delivers security events as they happen, via Streaming API (CometD) or Pub/Sub API. Events fire in real time rather than in a next-day batch.

Requires: Salesforce Shield OR Event Monitoring add-on, plus the "View Real-Time Event Monitoring Data" user permission.

RTEM events follow the naming convention ObjectNameEvent (e.g., LoginEvent, ApiAnomalyEvent, FileEvent). Corresponding storage objects (ObjectNameEventStore or ObjectNameEventStream for older API versions) persist event data for post-hoc SOQL queries.

Key RTEM event types:

Threat Detection events (ML-powered, Shield only):

ML processing lag note: Threat Detection models require brief processing time. The EventDate on anomaly events reflects when the ML model reported the anomaly — not the exact moment the suspicious action occurred. Do not treat the timestamp as perfectly synchronous with the underlying activity.

Mode 3 — Transaction Security Policies

Transaction Security Policies evaluate RTEM events and fire automated enforcement actions in real time. They are the enforcement layer on top of RTEM.

Available enforcement actions:

Policies are configured in Setup > Security > Transaction Security Policies. Each policy references an RTEM event type, defines condition logic, and specifies the action.

Not all RTEM events support Transaction Security Policies. Several event types (e.g., MobileEmailEvent, MobileScreenshotEvent, IdentityProviderEvent, IdentityVerificationEvent) do not support policy enforcement. Always verify the Can Be Used in a Transaction Security Policy? flag in the Object Reference before designing enforcement logic.

Common Patterns

Pattern: Bulk Log Download for SIEM Integration

When to use: You need to feed Salesforce event data into a SIEM (Splunk, Sumo Logic, etc.) or export logs for compliance analysis.

How it works:

  1. SOQL query EventLogFile for the desired EventType and LogDate range.
  2. For each record returned, issue an authenticated REST GET on /services/data/v63.0/sobjects/EventLogFile/{Id}/LogFile.
  3. Decompress the gzip response. Parse the CSV. The first row contains column headers.
  4. Load parsed rows into the SIEM or data store.
  5. Track the latest LogDate successfully processed to avoid re-ingesting on subsequent runs.

Why not the alternative: Attempting to read the LogFile field inline in SOQL returns only a relative endpoint path, not the binary content. The CSV bytes always require a separate authenticated REST call.

Pattern: Real-Time Threat Alerting with RTEM + Transaction Security

When to use: You need immediate enforcement response to suspicious activity — e.g., block or challenge a session hijack in progress rather than discover it next day.

How it works:

  1. Confirm Shield license and enable RTEM in Setup > Security > Real-Time Event Monitoring.
  2. Create a PlatformEventChannel with channelType=event and eventType=monitoring.
  3. Add target events as PlatformEventChannelMember records (one per event type per channel).
  4. Subscribe via CometD or Pub/Sub API to receive events in real time.
  5. For automated enforcement, create a Transaction Security Policy on the event type (e.g., block logins from unrecognized IP ranges using LoginEvent).

Metadata API configuration:

<!-- PlatformEventChannel -->
<PlatformEventChannel>
  <channelType>event</channelType>
  <eventType>monitoring</eventType>
  <label>Security Monitoring Channel</label>
</PlatformEventChannel>

<!-- PlatformEventChannelMember for ApiAnomalyEvent -->
<PlatformEventChannelMember>
  <eventChannel>Security_Monitoring_Channel__chn</eventChannel>
  <selectedEntity>ApiAnomalyEvent</selectedEntity>
</PlatformEventChannelMember>

Why not the alternative: EventLogFile batch approach cannot block or challenge a suspicious session in real time — it only reveals what happened the following day.

Pattern: SOQL-Based Login Forensics

When to use: A user account may have been compromised; you need to reconstruct login history, source IPs, browser fingerprints, and login status codes.

How it works:

  1. Query EventLogFile for EventType = 'Login' over the desired date range.
  2. Download the CSV. Key columns: USER_ID, SOURCE_IP, BROWSER_TYPE, PLATFORM_TYPE, LOGIN_STATUS, CLIENT_VERSION, SESSION_TYPE.
  3. Filter on LOGIN_STATUS != 'LOGIN_NO_ERROR' to isolate authentication failures.
  4. Cross-reference USER_ID values with User sObject records.
  5. For same-day data (not yet in EventLogFile), query the LoginEvent big object via SOQL — SELECT UserId, LoginType, SourceIp, Status, EventDate FROM LoginEvent WHERE EventDate = TODAY. Do not issue SOQL against LoginEventStream: *EventStream objects are platform events whose only supported call is describeSObjects(), consumed by subscribing to /event/LoginEventStream over Pub/Sub API or CometD.

Decision Guidance

SituationRecommended ApproachReason
Compliance audit — who exported data last quarterEventLogFile (batch) SOQL + REST downloadHistorical coverage, up to 30 days with Shield
Block suspicious logins in real timeRTEM + Transaction Security Policy on LoginEventFires synchronously; can block or challenge immediately
SIEM integration for ongoing ingestionEventLogFile REST download (daily or hourly)Structured CSV output; standard log-shipper compatible
Detect session hijackingRTEM SessionHijackingEventML-powered, near-real-time detection
Investigate a specific user's API callsEventLogFile EventType = 'API'Per-call detail; filter by USER_ID column after download
Enforce MFA on logins from new locationsTransaction Security Policy on LoginEventNative MFA enforcement; no custom code required
Monitor file downloads for data exfiltrationRTEM FileEvent (real-time) or ContentTransfer log (historical)FileEvent for immediate alerting; ContentTransfer for audit trail
Same-day login activity (incident in progress)Query the LoginEvent / LoginAsEvent big objects (not the *EventStream platform events)RTEM storage objects are populated immediately; EventLogFile is unavailable until tomorrow

Step-by-step instructions for an AI agent or practitioner activating this skill:

  1. Gather context — confirm the org edition, relevant objects, and current configuration state
  2. Review official sources — check the references in this skill's well-architected.md before making changes
  3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
  4. Validate — run the skill's checker script and verify against the Review Checklist below
  5. Document — record any deviations from standard patterns and update the template if needed

Review Checklist

Run through these before marking work in this area complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. LogFile field returns a URL path, not CSV content — Querying SELECT LogFile FROM EventLogFile does not return the CSV bytes. It returns a relative URL path. You must issue a separate authenticated REST GET to /services/data/vXX.0/sobjects/EventLogFile/{Id}/LogFile with a valid Bearer token to retrieve the actual gzip CSV.
  2. 24-hour delay makes same-day forensics impossible with EventLogFile — EventLogFile records for a given LogDate are not available until the following UTC day. If an incident is unfolding today, EventLogFile cannot show today's activity. Use RTEM storage objects (e.g., LoginEventStream) or the Setup > Login History UI for same-day data.
  3. Not all RTEM events support Transaction Security policies — Several events including MobileEmailEvent, MobileScreenshotEvent, IdentityProviderEvent, and IdentityVerificationEvent explicitly do not support policy enforcement. Designing a policy on an unsupported event type will not produce enforcement behavior.
  4. Threat Detection ML events have a processing lag — ApiAnomalyEvent, ReportAnomalyEvent, SessionHijackingEvent, and similar ML-powered events do not fire the instant the suspicious action occurs. The EventDate field reflects when the ML model completed its evaluation. Do not assume this timestamp equals the moment of the underlying suspicious activity.
  5. Free tier covers only 5 event types — Without Shield or the add-on, only Login, Logout, URI, API Total Usage, and Apex Unexpected Exception events are available. Many practitioners assume all event types are included at no cost. This gap causes silent misses when trying to audit Report exports, ContentTransfer downloads, or VisualforceRequest activity.

Output Artifacts

ArtifactDescription
SOQL query for EventLogFileParameterized query by EventType and LogDate range for log discovery
REST download commandAuthenticated GET for log CSV binary content
RTEM channel configuration (Metadata API XML)PlatformEventChannel + PlatformEventChannelMember deployment metadata
Transaction Security Policy designEvent type, condition logic, and enforcement action specification
Threat detection querySOQL against EventStore objects for post-hoc anomaly review

Package files