making investigation guides more contextual

Author: terrancedejesus

rules/integrations/azure/initial_access_entra_id_oauth_auth_code_grant_unusual_app_resource_user.toml

@@ -24,30 +24,36 @@ note = """## Triage and analysis
 
 ### Investigating Entra ID OAuth Authorization Code Grant for Unusual User, App, and Resource
 
-This New Terms rule detects the first occurrence of an OAuth 2.0 authorization code grant flow for a specific combination of client application, target resource, and user principal. When a user has never used a particular app+resource combination in the last 14 days and it involves FOCI applications or legacy Azure AD, this may indicate OAuth phishing.
+This New Terms rule detects the first occurrence of an OAuth 2.0 authorization code grant flow for a specific combination of client application ID, target resource ID, and user principal within the last 14 days. When a user has never used a particular app+resource combination and it involves FOCI applications or legacy Azure AD, this may indicate OAuth phishing attacks like ConsentFix.
+
+The rule is particularly effective at catching attacks where adversaries use stolen OAuth codes with first-party apps to access resources the victim has never accessed before. For example, if a non-developer suddenly uses Azure CLI to access legacy AAD for the first time, this is highly suspicious regardless of other factors.
 
 ### Possible investigation steps
 
-- Identify the affected user and confirm if they typically use developer tools like Azure CLI or PowerShell.
-- Determine if the application and resource combination is expected for this user's role.
-- Analyze source IP and geolocation for anomalies. Attackers typically exchange codes from different IPs.
-- Check for non-interactive sign-ins shortly after interactive ones from different IPs, indicating token replay.
-- Correlate with other sign-in events using session ID to identify the full OAuth flow sequence.
-- Look for subsequent Graph API or AAD API activity from unusual locations.
+- Review `azure.signinlogs.properties.user_principal_name` to identify the affected user and determine if they are a developer who would legitimately use these tools.
+- Check `azure.signinlogs.properties.app_display_name` to confirm which application was used. Azure CLI or PowerShell access by non-technical users is suspicious.
+- Examine `azure.signinlogs.properties.resource_id` to identify the target resource. Legacy AAD (`00000002-0000-0000-c000-000000000000`) access is unusual for most users.
+- Analyze `source.ip` and `source.geo.*` for geographic anomalies. ConsentFix attackers exchange codes from different IPs than the victim.
+- Review `azure.signinlogs.properties.is_interactive` - if this is a non-interactive sign-in shortly after an interactive one from a different IP, it indicates token replay.
+- Correlate with other sign-in events using `azure.signinlogs.properties.session_id` to identify the full OAuth flow sequence.
+- Pivot to `azure.graphactivitylogs` to search for subsequent Graph API or AAD API activity from unusual locations.
+- Check `azure.auditlogs` for device registration events around the same timeframe.
 
 ### False positive analysis
 
-- Developers or IT administrators legitimately using these tools for the first time.
-- Users onboarding to new development environments or tools.
+- Developers or IT administrators legitimately using Azure CLI, PowerShell, or VS Code for the first time to access specific resources.
+- Users onboarding to new development environments or receiving new tooling.
 - Automation scripts that run with user-delegated permissions for the first time.
+- Consider the user's role and typical activity patterns when evaluating alerts.
 
 ### Response and remediation
 
-- Contact the user to confirm if they initiated the OAuth flow.
-- If unauthorized, immediately revoke all refresh tokens for the user via Entra ID.
-- Review recent activity from the same session for signs of data access or enumeration.
+- Contact the user to confirm if they initiated the OAuth flow and used the detected application.
+- If unauthorized, immediately revoke all refresh tokens for the user via Microsoft Entra ID.
+- Review recent activity from the same `session_id` for signs of data access or enumeration.
 - Block the source IP if confirmed malicious.
-- Implement Conditional Access policies to restrict OAuth flows for these applications.
+- Implement Conditional Access policies to restrict OAuth flows for these applications to compliant devices.
+- Educate users about OAuth phishing and the risks of pasting authorization codes.
 """
 references = [
     "https://pushsecurity.com/blog/consentfix",

rules/integrations/azure/initial_access_entra_id_oauth_phishing_via_first_party_microsoft_application.toml

@@ -25,35 +25,38 @@ note = """## Triage and analysis
 
 ### Investigating Entra ID OAuth Phishing via First-Party Microsoft Application
 
-This rule detects OAuth authorization activity where FOCI (Family of Client IDs) applications access Microsoft Graph or legacy Azure AD resources. Adversaries exploit these trusted first-party apps in phishing campaigns like ConsentFix to steal authorization codes and exchange them for tokens from attacker infrastructure.
+This rule detects OAuth authorization activity where FOCI (Family of Client IDs) applications access Microsoft Graph or legacy Azure AD resources. Adversaries exploit these trusted first-party apps in phishing campaigns like ConsentFix to steal authorization codes and exchange them for tokens from attacker infrastructure. Because first-party apps are pre-consented and cannot be blocked, attackers use them to bypass consent prompts and access user data without triggering typical OAuth alerts.
+
+The rule uses split detection logic: developer tools (Azure CLI, VSCode, PowerShell) accessing either Graph or legacy AAD are flagged, while any FOCI app accessing legacy AAD is flagged since this deprecated API is rarely used legitimately and attackers target it for stealth.
 
 ### Possible investigation steps
 
-- Identify the affected user and determine if they are a high-value target (privileged roles, executives, IT admins).
-- Analyze source IP and geolocation for anomalies. Attackers typically exchange codes from different IPs than the victim.
-- Confirm which first-party application was used. Azure CLI or PowerShell access by non-developers is suspicious.
-- Identify the target resource. Legacy AAD access is unusual for most users and indicates potential evasion.
-- Check for non-interactive sign-ins shortly after interactive ones from different IPs, which may indicate token replay.
-- Correlate with other sign-in events using session ID to identify the full OAuth flow sequence.
-- Look for suspicious user agent patterns (automation tools, headless browsers).
-- Search for subsequent Graph API or AAD API activity from unusual locations.
+- Review `azure.signinlogs.properties.user_principal_name` to identify the affected user and determine if they are a high-value target (privileged roles, executives, IT admins).
+- Analyze `source.ip` and `source.geo.*` for geographic anomalies. ConsentFix attackers exchange codes from different IPs than the victim's location.
+- Check `azure.signinlogs.properties.app_display_name` to confirm which first-party application was used. Azure CLI or PowerShell access by non-developers is suspicious.
+- Examine `azure.signinlogs.properties.resource_id` to identify the target resource. Legacy AAD (`00000002-0000-0000-c000-000000000000`) access is unusual for most users.
+- Review `azure.signinlogs.properties.is_interactive` - non-interactive sign-ins shortly after interactive ones from different IPs indicate token replay.
+- Correlate with other sign-in events using `azure.signinlogs.properties.session_id` to identify the full OAuth flow sequence.
+- Pivot to `azure.graphactivitylogs` to search for subsequent Graph API activity from the same session or user from unusual locations.
+- Check `azure.auditlogs` for device registration events around the same timeframe, which may indicate persistence attempts.
 
 ### False positive analysis
 
-- Developers or IT administrators legitimately using Azure CLI, PowerShell, or VS Code.
+- Developers or IT administrators legitimately using Azure CLI, PowerShell, or VS Code to access Microsoft Graph or Azure AD.
 - Enterprise automation or CI/CD pipelines using these tools with user-delegated permissions.
 - Users working from multiple locations (VPN, travel) may show different IPs.
-- Consider excluding known developer machines or specific user groups that regularly use these tools.
+- Consider excluding known developer machines, managed devices, or specific user groups that regularly use these tools.
+- Maintain an allowlist of expected source IPs tied to corporate infrastructure or developer environments.
 
 ### Response and remediation
 
-- Contact the user to confirm if they initiated the OAuth flow.
-- If unauthorized, revoke all refresh tokens for the user via Microsoft Entra ID.
-- Review recent Microsoft Graph activity for signs of data exfiltration.
+- Contact the user immediately to confirm if they initiated the OAuth flow and used the detected application.
+- If unauthorized, revoke all refresh tokens for the user via Microsoft Entra ID portal or PowerShell.
+- Review the user's recent Microsoft Graph activity (email access, file downloads, Teams messages) for signs of data exfiltration.
 - Block the source IP if confirmed malicious.
-- Check for and remove any unauthorized device registrations.
-- Implement Conditional Access policies to restrict OAuth flows to compliant devices.
-- Educate users about OAuth phishing and the risks of pasting authorization codes.
+- Check for any devices registered during this session via `azure.auditlogs` and remove unauthorized device registrations.
+- Implement Conditional Access policies to restrict OAuth flows for these applications to compliant devices only.
+- Educate users about OAuth phishing and the risks of pasting authorization codes into websites.
 """
 references = [
     "https://docs.microsoft.com/en-us/azure/active-directory/reports-monitoring/reference-azure-monitor-sign-ins-log-schema",

rules/integrations/o365/defense_evasion_entra_id_susp_oauth2_authorization.toml

@@ -23,28 +23,36 @@ note = """## Triage and analysis
 
 ### Investigating M365 Identity OAuth Flow by First-Party Microsoft App from Multiple IPs
 
-This rule detects when the same user authenticates to Microsoft Graph or legacy Azure AD using FOCI applications from multiple IP addresses within a short time window. This pattern indicates OAuth code/token theft where the victim completes OAuth flow on their device and the attacker exchanges the stolen code from different infrastructure.
+This rule detects when the same user authenticates to Microsoft Graph or legacy Azure AD using FOCI applications from multiple IP addresses within a 30-minute window. This pattern is a strong indicator of OAuth code/token theft attacks like ConsentFix, where the victim completes the OAuth authorize flow on their device (first IP), and the attacker exchanges the stolen authorization code for tokens from their infrastructure (second IP).
+
+The rule aggregates events by user, application, and resource, requiring both `OAuth2:Authorize` and `OAuth2:Token` requests from at least 2 different IPs to fire - this indicates the code was generated on one IP and exchanged on another.
 
 ### Possible investigation steps
 
-- Identify the affected user and analyze the list of unique IP addresses used within the 30-minute window.
-- Determine whether IPs originate from different geographic regions, cloud providers, or anonymizing infrastructure.
-- Pivot into raw events to reconstruct the full sequence of resource access events.
-- Check Azure audit logs for device join or registration events around the same timeframe.
-- Review identity protection alerts for correlated risk detections such as anonymized IP access or token replay.
+- Review `o365.audit.UserId` to identify the affected user and determine if they are a high-value target.
+- Analyze `Esql.source_ip_values` to see all unique IP addresses used within the 30-minute window. Determine whether these originate from different geographic regions, cloud providers (AWS, Azure, GCP), or anonymizing infrastructure (Tor, VPNs).
+- Use `Esql.time_window_date_trunc` to pivot into raw events and reconstruct the full sequence of resource access events with exact timestamps.
+- Check `Esql.source_as_organization_name_values` for unfamiliar ASN organizations that may indicate attacker infrastructure.
+- Review `Esql.o365_audit_ApplicationId_values` to confirm which first-party application was used.
+- Pivot to `azure.auditlogs` to check for device join or registration events around the same timeframe, which may indicate persistence attempts.
+- Correlate with `azure.identityprotection` to identify related risk detections such as anonymized IP access or token replay.
+- Search for additional sign-ins from the IPs involved across other users to determine if this is part of a broader campaign.
 
 ### False positive analysis
 
-- Developers or IT administrators working across environments may produce similar behavior.
-- Users on VPN or traveling between networks may show multiple IPs.
+- Developers or IT administrators working across environments (office, home, cloud VMs) may produce similar behavior.
+- Users on VPN who switch servers or traveling between networks may show multiple IPs.
+- Mobile users moving between cellular and WiFi networks during the time window.
+- Consider correlating with device compliance status to distinguish managed vs. unmanaged access.
 
 ### Response and remediation
 
-- If confirmed unauthorized, revoke all refresh tokens for the affected user.
-- Remove any devices registered during this session.
-- Notify the user and determine whether the authentication activity was expected.
-- Implement Conditional Access policies to restrict OAuth flows from suspicious locations.
-- Monitor for follow-on activity like lateral movement or privilege escalation.
+- If confirmed unauthorized, immediately revoke all refresh tokens for the affected user via Entra ID.
+- Remove any devices registered during this session by checking `azure.auditlogs` for `Add device` events.
+- Notify the user and determine whether they may have shared an OAuth code via phishing.
+- Block the attacker IPs at the perimeter and add to threat intel feeds.
+- Implement Conditional Access policies to restrict OAuth flows for these applications to compliant devices and approved locations.
+- Monitor for follow-on activity like lateral movement, privilege escalation, or data exfiltration via Graph API.
 """
 references = [
     "https://www.volexity.com/blog/2025/04/22/phishing-for-codes-russian-threat-actors-target-microsoft-365-oauth-workflows/",

rules/integrations/o365/initial_access_identity_oauth_phishing_via_first_party_microsoft_application.toml

@@ -25,29 +25,36 @@ note = """## Triage and analysis
 
 ### Investigating M365 Identity OAuth Phishing via First-Party Microsoft Application
 
-This rule detects OAuth authorization activity where FOCI (Family of Client IDs) applications access Microsoft Graph or legacy Azure AD resources. Adversaries exploit these trusted first-party apps in phishing campaigns like ConsentFix to steal authorization codes and exchange them for tokens from attacker infrastructure.
+This rule detects OAuth authorization activity where FOCI (Family of Client IDs) applications access Microsoft Graph or legacy Azure AD resources. Adversaries exploit these trusted first-party apps in phishing campaigns like ConsentFix to steal authorization codes and exchange them for tokens from attacker infrastructure. The rule specifically looks for `OAuth2:Authorize` requests with `Redirect` status, which indicates the user was redirected after authorization and the OAuth code was exposed.
+
+The rule uses split detection logic: developer tools (Azure CLI, VSCode, PowerShell) accessing either Graph or legacy AAD are flagged, while any FOCI app accessing legacy AAD is flagged since this deprecated API is rarely used legitimately and attackers target it for stealth.
 
 ### Possible investigation steps
 
-- Identify the impacted account and validate whether the user expected to authorize the application.
-- Check if the source IP is unexpected or outside corporate ranges, especially from proxy networks.
-- Examine user agent and device properties for suspicious patterns (automation tools, headless browsers).
-- Identify the target resource. Legacy AAD access is unusual for most users and indicates potential evasion.
-- Check for follow-up access events or mailbox enumeration using the Graph API from unfamiliar locations.
-- Look for subsequent non-interactive sign-ins from different IPs using the same session.
+- Review `o365.audit.UserId` to identify the impacted account and validate whether the user expected to authorize the application.
+- Check `o365.audit.ActorIpAddress` for unexpected IPs, especially outside corporate ranges or from proxy/VPN networks.
+- Examine `user_agent.original` and `o365.audit.DeviceProperties` for suspicious patterns (automation tools, headless browsers, unusual browser/OS combinations).
+- Confirm `o365.audit.Target.ID` to identify the resource being accessed. Legacy AAD (`00000002-0000-0000-c000-000000000000`) access is unusual for most users.
+- Review `o365.audit.ExtendedProperties.RequestType` and `ResultStatusDetail` - `OAuth2:Authorize` with `Redirect` indicates the OAuth code was exposed to the user.
+- Look for subsequent `OAuth2:Token` events from different IPs using the same `o365.audit.UserId`, which indicates token exchange from attacker infrastructure.
+- Pivot to `azure.graphactivitylogs` to check for follow-up Graph API activity (mailbox enumeration, file access) from unfamiliar locations.
+- Correlate with `azure.signinlogs` for additional sign-in context and device details.
 
 ### False positive analysis
 
-- Developers or IT users intentionally using Azure CLI, VS Code, or PowerShell.
+- Developers or IT users intentionally using Visual Studio Code, Azure CLI, or Azure PowerShell to connect to Microsoft 365.
+- Legitimate VS Code extensions that sync or query Graph API data (calendars, tasks, cloud-hosted notebooks).
 - Enterprise automation or CI/CD pipelines using these tools with user-delegated permissions.
-- Consider excluding known developer machines or specific user groups that regularly use these tools.
+- Exclude known user agents and hosts that regularly use these applications against Graph.
+- Whitelist specific source IPs or devices tied to developer machines.
 
 ### Response and remediation
 
-- Contact the user to confirm if they expected this login or may have shared an OAuth code.
-- If unauthorized, revoke all refresh tokens and reset credentials.
-- Review recent Microsoft Graph activity for signs of data exfiltration.
+- Contact the user to confirm if they expected this login or may have shared an OAuth code via phishing page, Signal, or WhatsApp.
+- If unauthorized, revoke all refresh tokens for the user and reset credentials.
+- Review recent Microsoft Graph activity (email, file access, Teams) for signs of data exfiltration.
 - Block or restrict future use of OAuth tokens from unknown apps or IPs via Conditional Access.
+- Check `azure.auditlogs` for device registration events and remove any unauthorized registrations.
 - Educate users about OAuth phishing techniques and the risks of sharing authorization codes.
 """
 references = [