Microsoft Graph API Integration

Monitor security events from Microsoft Graph services

The Microsoft Graph API integration enables monitoring of security events from Microsoft Graph services, providing access to a wide range of Microsoft 365 and Azure security data.

Overview

Microsoft Graph API integration allows you to collect security events related to your Microsoft Graph services. This integration provides deeper insights into Microsoft cloud services beyond what Office 365 monitoring offers, including advanced threat protection, identity protection, and security scores.

Reference: plugins/main/common/wazuh-modules.ts:73

What is Microsoft Graph API?

Microsoft Graph is the unified API endpoint for accessing Microsoft 365, Windows 10, and Enterprise Mobility + Security services. It provides a unified programmability model for accessing data across:

• Azure Active Directory
• Microsoft 365 services
• Windows 10 services
• Enterprise Mobility + Security
• Security and threat intelligence

Key Features

• Unified security event collection
• Advanced threat detection events
• Identity protection alerts
• Security score monitoring
• Incident and alert management
• Threat intelligence integration
• User risk detection
• Sign-in risk analysis
• Conditional access policy monitoring

Collected Security Events

The Microsoft Graph API integration collects:

Security Alerts

• Microsoft Defender Alerts - Endpoint protection events
• Azure AD Identity Protection - User and sign-in risk events
• Cloud App Security - Cloud application threats
• Azure Security Center - Infrastructure security alerts
• Office 365 ATP - Advanced Threat Protection events

Identity and Access Events

• User risk detections
• Sign-in risk detections
• Risky users
• Risk events
• Conditional access failures
• Authentication methods changes

Threat Intelligence

• Threat indicators (IPs, URLs, domains, files)
• Threat assessment requests
• Security scores
• Secure score control profiles

Incidents

• Security incidents
• Incident assignments
• Incident status changes
• Investigation findings

Setup and Configuration

Prerequisites

• Microsoft 365 E5 or Azure AD Premium P2 license
• Azure AD Global Administrator or Security Administrator role
• Azure AD application registration
• Wazuh manager configured for Microsoft Graph integration

Configuration Steps

1. Register Azure AD Application

   • Sign in to Azure Portal (https://portal.azure.com)
   • Navigate to Azure Active Directory > App registrations
   • Click “New registration”
   • Name: “Wazuh Microsoft Graph Integration”
   • Account type: “Accounts in this organizational directory only”
   • Click Register

2. Configure API Permissions

   Add Microsoft Graph API permissions (Application permissions):

   Security Alerts:

   • SecurityEvents.Read.All
   • SecurityAlert.Read.All
   • ThreatIndicators.Read.All

   Identity Protection:

   • IdentityRiskEvent.Read.All
   • IdentityRiskyUser.Read.All

   Directory Data:

   • Directory.Read.All
   • User.Read.All

   After adding permissions, click “Grant admin consent”

3. Create Client Secret

   • In the app registration, go to Certificates & secrets
   • Click “New client secret”
   • Description: “Wazuh Integration Secret”
   • Expiration: Choose appropriate duration
   • Click Add and copy the secret value

4. Gather Configuration Information

   Note the following from your app registration:

   • Application (client) ID
   • Directory (tenant) ID
   • Client secret value

5. Configure Wazuh Manager

   Edit /var/ossec/etc/ossec.conf:

   <wodle name="ms-graph">
     <disabled>no</disabled>
     <interval>5m</interval>
     <curl_max_size>1M</curl_max_size>
     <api_auth>
       <tenant_id>your-tenant-id</tenant_id>
       <client_id>your-client-id</client_id>
       <client_secret>your-client-secret</client_secret>
     </api_auth>
     <resource>
       <name>security</name>
       <relationship>alerts</relationship>
     </resource>
     <resource>
       <name>security</name>
       <relationship>securescores</relationship>
     </resource>
   </wodle>
   

6. Verify Configuration

   • Restart Wazuh manager: systemctl restart wazuh-manager
   • Check logs: tail -f /var/ossec/logs/ossec.log
   • Look for successful Microsoft Graph API connections
   • Verify events appear in Wazuh Dashboard

Available Resources

The integration can query various Microsoft Graph resources:

Security Resource

• alerts - Security alerts from various providers
• secureScores - Microsoft Secure Score over time
• secureScoreControlProfiles - Security control details
• incidents - Security incidents
• alerts_v2 - Next-generation security alerts

Identity Protection

• riskDetections - Risk detections for users and sign-ins
• riskyUsers - Users flagged as at-risk
• servicePrincipalRiskDetections - Service principal risk events

Threat Intelligence

• tiIndicators - Threat intelligence indicators

Event Fields

Microsoft Graph events include rich metadata:

Alert Fields

• title - Alert title
• severity - High, Medium, Low, Informational
• category - Alert category
• status - New, InProgress, Resolved
• provider - Alert provider (Azure ATP, MCAS, etc.)
• vendorInformation - Provider details
• assignedTo - User assigned to alert
• confidence - Confidence score (0-100)
• riskScore - Risk score

User Risk Fields

• userPrincipalName - User identifier
• riskLevel - Low, Medium, High
• riskState - Active, Remediated, Dismissed
• riskDetail - Risk reason
• riskLastUpdatedDateTime - Last update time

Filtering Events

Filter Microsoft Graph events in the dashboard:

wazuh.integration.name: "ms-graph"

Additional filters:

• By severity: data.ms-graph.severity: "high"
• By category: data.ms-graph.category: "malware"
• By status: data.ms-graph.status: "new"
• By provider: data.ms-graph.provider: "Azure ATP"

Use Cases

Advanced Threat Detection

• Credential Theft Detection

  • Password spray attacks
  • Leaked credentials usage
  • Anonymous IP address sign-ins

• Malware and Phishing

  • Malicious file downloads
  • Phishing email detection
  • Suspicious URL access

• Anomalous Behavior

  • Impossible travel
  • Atypical sign-in properties
  • Unfamiliar sign-in locations

Identity Protection

• Risk-Based Access Control

  • Monitor risky sign-ins
  • Track user risk levels
  • Conditional access policy enforcement

• Account Compromise Prevention

  • Leaked credential alerts
  • Anonymous IP usage
  • Malware-infected devices

Security Posture Management

• Secure Score Monitoring

  • Track security score trends
  • Monitor control improvements
  • Identify security gaps

• Compliance Tracking

  • Security control compliance
  • Recommendation implementation
  • Risk mitigation progress

Incident Response

• Incident Investigation

  • Related alert correlation
  • User activity analysis
  • Attack timeline reconstruction

• Threat Hunting

  • Indicator of Compromise (IoC) searching
  • Cross-service correlation
  • Historical pattern analysis

Common Alert Categories

• Credential Access - Password attacks, credential theft
• Malware - Malicious software detection
• Phishing - Phishing attempts and campaigns
• Suspicious Activity - Anomalous behavior
• Initial Access - Unauthorized access attempts
• Exfiltration - Data theft indicators
• Lateral Movement - Internal network propagation
• Command and Control - C2 communication

Troubleshooting

Authentication Issues

• Error: Invalid client secret

  • Verify client secret is correct
  • Check if secret has expired
  • Generate new secret if needed

• Error: Insufficient permissions

  • Verify API permissions are configured
  • Ensure admin consent was granted
  • Check application permissions (not delegated)

No Events Appearing

• Verify Microsoft 365 E5 or appropriate license is active
• Check if security features are enabled
• Confirm Azure AD Identity Protection is configured
• Verify resources are specified correctly in configuration
• Review Wazuh manager logs for API errors

Performance Issues

• Adjust polling interval based on alert volume
• Limit resources to only required endpoints
• Monitor API throttling limits
• Increase curl_max_size for large responses

Missing Specific Alert Types

• Verify the security product is configured (Defender, MCAS, etc.)
• Check license includes the specific feature
• Confirm alert provider is enabled
• Review Microsoft 365 security center configuration

Security Best Practices

1. Application Security

   • Use application permissions, not delegated
   • Implement certificate-based authentication for production
   • Rotate client secrets regularly
   • Monitor application sign-in logs

2. Least Privilege

   • Grant only required Graph API permissions
   • Use separate app registrations for different integrations
   • Regular permission audits

3. Monitoring

   • Alert on integration authentication failures
   • Track API call patterns
   • Monitor for unusual data access
   • Log all configuration changes

4. Data Protection

   • Secure storage of credentials
   • Encrypt credentials in Wazuh configuration
   • Implement network restrictions
   • Use Azure Key Vault for secrets

Advanced Configuration

Multiple Resources

Query multiple Graph resources:

<wodle name="ms-graph">
  <disabled>no</disabled>
  <interval>5m</interval>
  <api_auth>
    <!-- auth configuration -->
  </api_auth>
  <resource>
    <name>security</name>
    <relationship>alerts</relationship>
  </resource>
  <resource>
    <name>security</name>
    <relationship>incidents</relationship>
  </resource>
  <resource>
    <name>identityProtection</name>
    <relationship>riskDetections</relationship>
  </resource>
  <resource>
    <name>identityProtection</name>
    <relationship>riskyUsers</relationship>
  </resource>
</wodle>

Filtering by Severity

Collect only high-severity alerts:

<resource>
  <name>security</name>
  <relationship>alerts</relationship>
  <query>severity eq 'high'</query>
</resource>

Date Filtering

Query recent events only:

<resource>
  <name>security</name>
  <relationship>alerts</relationship>
  <query>createdDateTime ge ${timestamp}</query>
</resource>

Microsoft Graph API Versions

The integration supports:

• v1.0 - Production-ready, stable APIs
• beta - Preview APIs with latest features (may change)

By default, v1.0 is used for stability.

Rate Limits and Throttling

Microsoft Graph API has throttling limits:

• Monitor 429 (Too Many Requests) responses
• Implement exponential backoff
• Adjust polling intervals to stay within limits
• Use webhooks for real-time events (advanced)

Related Resources

• Cloud Integrations Overview
• Office 365 Integration
• AWS Integration
• Threat Hunting
• Microsoft Graph API Documentation