Collecting SaaS audit logs is not the same as detecting attacks in them, and most organisations that stream the logs still have no rule that fires when a trusted user or app empties the CRM. The attacks that matter in SaaS look alike across platforms: a sign-in that should not have worked, a new way back in, an app granted broad access, an admin setting quietly changed, and then a lot of data leaving. This guide sets out a cross-SaaS detection set built on those shared patterns: a normalised event model, eight detections with sample logic, the signal names on common platforms, tuning, testing and the metrics that show the rules work. It is for detection engineers and SOC leads. Log collection and retention are covered in the SaaS Audit Log Retention and Licensing Guide, and the identity detection programme as a whole in the ITDR Guide.
Key takeaways
- Detect behaviours, not products. Account takeover, rogue apps, admin tampering and mass download look the same across platforms once events are normalised to actor, action, object, source and outcome.
- Integrations need their own rules. An OAuth app or API token never triggers a risky sign-in, so data access by applications must be baselined per client ID.
- Correlation beats single events. A new MFA method is noise; a new MFA method followed within an hour by a consent grant and a bulk export is an incident.
- Use the provider's own detections as inputs. Built-in signals such as suspicious login warnings and anomaly events are cheap, high-value inputs to your own correlation.
- Prove each rule fires. Test every detection with a safe, scripted reproduction in a test tenant and measure time from event to alert, because SaaS log lag can be minutes to hours.
A normalised event model for SaaS detection
Each platform names events differently. Map every source to the same small set of fields at ingest, so that one rule can run across all of them.
| Normalised field | What it holds | Why detections need it |
|---|---|---|
| actor.type | Human user, admin, service account, OAuth app or API token | Human and integration activity need different baselines |
| actor.id and actor.app_id | User ID or email; OAuth client ID or token ID where the action was made by an app on a user's behalf | Lets you see a user's data pulled by an app, not by the user |
| action.category | authentication, mfa_change, role_change, app_grant, config_change, data_read, data_export, share_external, rule_change | One rule per category instead of one per product event |
| object | File, report, repository, mailbox, channel, record type | Sensitivity weighting and volume counting |
| source.ip, source.asn, user_agent | Network origin and client string | Pivoting across apps and spotting hosting or anonymising networks |
| volume | Records, files or bytes returned, where logged | Mass download and export detection |
| outcome | Success, failure, blocked | Spraying and blocked-then-successful patterns |
| event_time and ingest_time | Provider timestamp in UTC and time received | Measures lag, so you know when absence of events means anything |
Keep the original event name and raw payload alongside the normalised fields. Analysts need them at triage, and the provider's field names are what its documentation and support teams will use.
Signal names on common platforms
The table gives examples of documented events and built-in detections that feed the normalised categories. Platforms are listed alphabetically, and audit log availability and retention depend on plan and edition, so confirm each source in the vendor's documentation. The per-platform detection guides go much deeper.
| Platform | Examples of documented signals | Normalised categories | Detailed guide |
|---|---|---|---|
| GitHub | integration_installation.create (a GitHub App was installed); git.clone (available through the REST API, streaming or exports rather than the web interface) | app_grant, data_read | GitHub Audit Log Detection Guide |
| Google Workspace | Token log authorize (with client_id and scope) and activity (with num_response_bytes); Login log suspicious_login, 2sv_disable, account_disabled_hijacked | app_grant, data_read, authentication, mfa_change | Google Workspace Audit Log Detection Guide |
| Microsoft 365 and Entra ID | Audit activity Consent to application with IsAdminConsent; Defender for Cloud Apps detections Impossible travel and Unusual multiple file download activities | app_grant, authentication, data_read | Microsoft Graph Exfiltration Detection |
| Okta | System Log app.oauth2.as.consent.grant (user granted consent to app); application.lifecycle.create | app_grant, config_change | Okta System Log Detection Guide |
| Salesforce | Real-Time Event Monitoring objects such as ReportEvent, BulkApiResultEvent, ApiAnomalyEvent, ReportAnomalyEvent, SessionHijackingEvent and PermissionSetEvent | data_export, data_read, authentication, role_change | How to review Salesforce connected apps and integration users |
| Slack | Audit Logs API actions app_installed, app_scopes_expanded, file_downloaded, file_public_link_created, anomaly | app_grant, data_read, share_external, authentication | How to find secrets in Slack and Teams messages |
Availability: Salesforce documents the event objects above under Real-Time Event Monitoring; Slack's Audit Logs API is documented for Enterprise plans; GitHub notes that Git events such as git.clone have separate access and retention rules. Check edition requirements for every source before building rules on it.
Eight detections to build first
Each detection below runs on the normalised model. Thresholds are starting points to tune against your own baseline, not recommended values.
| # | Detection | Sample logic | ATT&CK |
|---|---|---|---|
| 1 | Mass download or export by a user | Count data_read and data_export events per actor per hour; alert when the count exceeds both a fixed floor and several times the actor's 30-day 95th percentile, weighted up for sensitive objects | T1530 Data from Cloud Storage; T1213 Data from Information Repositories |
| 2 | Bulk data access by an app or token | Per actor.app_id, compare records or bytes returned per hour with the app's 30-day baseline; alert on first-ever access to an object type, or on volume far above baseline | T1550.001 Application Access Token |
| 3 | Rogue or high-risk app grant | app_grant where the client ID is not on the approved list and the scope includes mail, files, full drive, admin or offline access; raise severity when admin consent applies to all users | T1528 Steal Application Access Token |
| 4 | Takeover chain | Within 60 minutes for one actor: authentication from a new ASN or country, then mfa_change or new device, then app_grant, rule_change or data_export | T1078.004 Cloud Accounts; T1098.005 Device Registration |
| 5 | Impossible travel or anomalous sign-in, enriched | Take the provider or IdP anomaly alert, then add context: did the same session go on to export data, change MFA or grant an app? Alert on enriched hits, report the rest | T1078.004 Cloud Accounts; T1539 Steal Web Session Cookie |
| 6 | Admin role or security setting change | role_change granting admin, or config_change to SSO, MFA enforcement, session policy, audit logging or IP allow lists, outside an approved change window or by an actor who rarely does it | T1098.003 Additional Cloud Roles; T1556.006 Multi-Factor Authentication |
| 7 | Mail forwarding or inbox rule to an external address | rule_change creating forwarding, redirect or delete-and-move rules targeting an external domain, especially soon after a new-location sign-in | T1114.003 Email Forwarding Rule |
| 8 | New credential on an app or new API token | Creation of a client secret, certificate, personal access token or API key by a user who has not done so before, or on an app that already holds high-privilege scopes | T1098.001 Additional Cloud Credentials |
- Password spraying and MFA fatigue: build these at the IdP, not per app. Many failed sign-ins across many users from one source (T1110.003 Password Spraying), or repeated push denials followed by an approval (T1621 Multi-Factor Authentication Request Generation). See the Impossible Travel and Anomalous Sign-In Detection guide for sign-in rules in depth.
- External sharing burst: share_external events per actor per hour, especially public links. Slack's
file_public_link_createdand Google Drive visibility changes are examples. Feed this into detection 1 as a multiplier rather than alerting on it alone.
Why mass download is the hardest to get right
Volume rules fail in two directions. Set them low and every quarter-end report run or migration fires; set them high and an attacker who pulls a few thousand records an hour stays under them. Four techniques make the rule usable:
- Per-actor baselines: compare each user and each app with its own history, not a global threshold. A sales operations analyst and a support agent export very different volumes.
- Peer groups: compare a user with others in the same department or role. A new joiner has no history, but their team does.
- Object weighting: count records from customer, finance, HR and source code objects at a higher weight than low-sensitivity data.
- Sequence context: a large export after a sign-in from a new location, a new app grant or a resignation notice is far more significant than the same export on a normal day.
Microsoft documents a seven-day initial learning period for Defender for Cloud Apps anomaly detection, after which sessions are compared with the past month of activity. Plan for a similar warm-up for your own baselines and suppress volume alerts for new sources until they have history. The ShinyHunters Salesforce data theft campaign is the case for detection 2 and 3 together: an attacker-controlled connected app, authorised after a vishing call, bulk-exported whole CRM tables through the API.
Where identity fits: integrations and tokens
Most SaaS detection content assumes a person at a keyboard. OAuth apps, integration users and API tokens break that assumption: they do not sign in interactively, MFA does not apply, and their activity often appears under the consenting user's name with an app identifier attached. Build a baseline for every approved integration (object types touched, typical volume, source addresses or ASNs, active hours), alert on deviation, and alert on any token used from a new network. The Detection Engineering for Non-Human Identities Guide covers this in depth, and the SaaS and OAuth App Governance Guide covers the approved-app list that detection 3 depends on.
Choosing where detections run
| Approach | Strengths | Trade-offs | Fits |
|---|---|---|---|
| Provider built-in alerts | No engineering; uses provider-side signals you cannot see | One app at a time; limited correlation; tuning options vary | Every organisation, as inputs |
| SIEM with normalised SaaS logs | Cross-app correlation, your own retention, custom logic | Ingest cost; parsers and connectors need upkeep; log lag | Organisations with a SOC or detection engineer |
| SaaS security or ITDR platform | Prebuilt SaaS and identity detections, app inventory, posture context | Another privileged integration in every tenant; less control over logic | Many SaaS apps and a small team |
| Managed detection service | 24x7 coverage and analyst capacity | Needs clear runbooks and access to act quickly | Teams without out-of-hours cover |
Small organisations should turn on every built-in alert for their IdP, email and file platform, route them to a monitored queue, and add detections 3, 6 and 7, which are low-volume and high-value. Large organisations should normalise all tier-one SaaS sources into one schema and run all eight detections with per-actor baselines. For selection criteria, see the Account Takeover Protection Buyer's Guide and the ITDR Buyer's Guide.
Rolling it out
- Inventory sources: list tier-one SaaS applications, the audit events each exposes, the edition needed and the documented lag.
- Normalise: build parsers to the model above and check field completeness per source (what share of events carry source IP, app ID and volume).
- Start in report-only mode: run each detection for two to four weeks writing results to a review table rather than paging anyone.
- Tune: add allow lists for approved apps, scheduled exports and known migration accounts, each with an owner and an expiry date.
- Test: reproduce each behaviour safely in a test tenant (a scripted bulk download of dummy files, a consent to a test app with broad scopes, an admin role grant to a test account) and confirm the alert fires.
- Promote with a runbook: move each rule to alerting only with a triage runbook that names the first three things to check and links the response playbook.
- Roll back safely: if a rule floods the queue, return it to report-only rather than deleting it, and record why.
For the detection-as-code practices behind these steps, see the Detection Engineering Guide. When a detection confirms an incident, hand over to the SaaS Incident Response Guide.
Detection and measurement
- Source coverage: percentage of tier-one SaaS applications whose logs are normalised and covered by at least detections 1, 3 and 6.
- Test pass rate: percentage of detections that fired in the last scheduled test. Target 100 percent; investigate every miss.
- Event-to-alert time: median time from the provider event timestamp to the alert, per source. This exposes log lag and pipeline delay.
- Alert precision: share of alerts per detection that analysts mark as true positive or useful. Retune detections that stay low.
- Integration baseline coverage: percentage of approved OAuth apps and API tokens with a volume and network baseline.
Framework mapping
| Activity | NIST CSF 2.0 | NIST SP 800-53 Rev. 5 |
|---|---|---|
| Monitoring user and app activity in SaaS | DE.CM-03 | SI-4 System Monitoring |
| Analysing alerts and anomalies | DE.AE-02 | AU-6 Audit Record Review, Analysis, and Reporting |
| Correlating events across applications | DE.AE-03 | AU-6 Audit Record Review, Analysis, and Reporting |
| Feeding confirmed detections into response | RS.AN-03 | IR-5 Incident Monitoring |
The ATT&CK techniques in the detection table give each rule a coverage mapping. Use them to show which techniques have a tested detection and which do not.
Common failure patterns
- Collecting without detecting: logs land in the SIEM and nothing reads them. Every source should have at least one rule within a month of ingestion.
- Only watching sign-ins: integrations never sign in interactively, and stolen but valid credentials produce ordinary sign-ins. In the Snowflake breach, infostealer credentials worked against customer accounts that lacked MFA, so the data theft that followed was the event worth catching.
- Global volume thresholds: one number for every user produces either noise or silence. Use per-actor and peer baselines.
- Permanent allow lists: an integration allow-listed for a migration two years ago becomes the blind spot an attacker uses. Give every exception an owner and an expiry.
- Ignoring lag: a rule that looks for a sequence within ten minutes misses it when one source arrives hours later. Window by event time and wait out each source's documented lag.
- Untested rules: a parser change renames a field and a detection silently stops firing. Scheduled tests catch it.
Practitioner checklist
- Normalise every tier-one SaaS source to actor, actor type, app ID, action category, object, source, volume, outcome and both timestamps.
- Turn on and ingest each provider's built-in anomaly and suspicious login signals.
- Build the eight detections, starting with rogue app grants, admin changes and mail forwarding rules.
- Baseline every approved integration by object type, volume and network origin.
- Run new detections in report-only mode, then tune with owned, expiring allow lists.
- Test every detection on a schedule in a test tenant and record event-to-alert time.
- Attach a triage runbook and a response playbook link to every alerting rule.
- Report coverage against ATT&CK techniques and the metrics above each quarter.
Standards and references
- Microsoft Learn: Create anomaly detection policies in Defender for Cloud Apps
- Microsoft Learn: Detect and remediate illicit consent grants
- Google for Developers: OAuth Token audit activity events
- Google for Developers: Login audit activity events
- Okta Developer: Event types
- Salesforce Developers: Real-Time Event Monitoring objects
- Slack Developer Docs: Audit Logs API methods and actions reference
- GitHub Docs: Audit log events for your organization
Related NHI Mgmt Group resources: SaaS Audit Log Retention and Licensing Guide · ITDR Guide · SaaS Incident Response Guide · Impossible Travel and Anomalous Sign-In Detection · Detection Engineering for Non-Human Identities Guide