Microsoft Graph API Integration

​

Overview

​

What is Microsoft Graph API?

• 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

​

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

​

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

​

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

wazuh.integration.name: "ms-graph"

• 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

<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

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

​

Date Filtering

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

​

Microsoft Graph API Versions

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

​

Rate Limits and Throttling

• 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