Microsoft Graph API¶
About¶
The Microsoft Graph Security API provides a unified interface and schema to integrate with security solutions from Microsoft and ecosystem partners. This empowers customers to streamline security operations and better defend against increasing cyber threats. The Microsoft Graph Security API federates queries to all onboarded security providers and aggregates responses. Use the Microsoft Graph Security API to build applications that:
- Consolidate and correlate security alerts from multiple sources
- Unlock contextual data to inform investigations
- Automate security tasks, business processes, workflows, and reporting
- Send threat indicators to Microsoft products for customized detections
- Invoke actions to in response to new threats
- Provide visibility into security data to enable proactive risk management
Product Details¶
Vendor URL: Microsoft Graph API
Product Type: SaaS
Product Tier: Tier II
Integration Method: Custom
Integration URL: Microsoft Graph API - Cyderes Documentation
Log Guide: Sample Logs by Log Type
Parser Details¶
Log Format: JSON
Expected Normalization Rate: near 100%
Data Label: MICROSOFT_GRAPH_ALERT
UDM Fields (list of all UDM fields leveraged in the Parser):
| Log File Field | UDM Field |
|---|---|
| azureTenantId | principal.location.country_or_region |
| category,properties.alertName,riskType | security_result.rule_name |
| description,properties.description,riskEventType | metadata.description |
| description,properties.description,riskEventType | security_result.description |
| fileStates.0.path | target.file.full_path |
| hostStates.0.fqdn | principal.hostname |
| hostStates.0.netBiosName | src.hostname |
| hostStates.0.os | principal.platform |
| location.countryOrRegion | principal.location.country_or_region |
| malwareStates.0.nam | security_result.threat_name |
| networkConnections.0.protocol | network.ip_protocol |
| networkConnections.0.sourceAddress | principal.ip |
| processes.0.commandLine | principal.process.parent_process.command_line |
| processes.0.parentProcessId | principal.process.parent_process.pid |
| processes.0.path | principal.process.parent_process.file.full_path |
| properties.extendedProperties.client Hostname | principal.hostname |
| properties.extendedProperties.client IP Address | principal.ip |
| properties.extendedProperties.client Principal Name | target.user.email_addresses |
| properties.extendedProperties.client Principal Name | target.user.userid |
| recommendedActions.0-5 | security_result.category_details |
| securityResources.0.resource | security_result.about.resource.name |
| securityResources.0.resourceType | security_result.about.resource_subtype |
| severity,properties.reportedSeverity,riskLevel | security_result.severity |
| source | metadata.product_name |
| sourceMaterials.0 | metadata.url_back_to_product |
| title,properties.alertDisplayName,activity | metadata.product_event_type |
| title,properties.alertDisplayName,activity | security_result.summary |
| userPrincipalName,userStates.0.userPrincipalName | target.user.email_addresses |
| userStates.0.accountName,userDisplayName | principal.user.user_display_name |
| userStates.0.accountName,userDisplayName | target.user.user_display_name |
| userStates.0.domainName | principal.administrative_domain |
| userStates.0.domainName | target.administrative_domain |
| userStates.0.logonIp | target.ip |
| userStates.0.logonIp,ipAddress | principal.ip |
| userStates.0.logonLocation | principal.location.city |
| userStates.0.logonLocation | principal.location.country_or_region |
| userStates.0.logonLocation | principal.location.state |
| userStates.0.userPrincipalName | network.email.from |
| userStates.0.userPrincipalName | network.email.to |
| userStates.0.userPrincipalName | target.user.email_addresses |
| userStates.0.userPrincipalName,userPrincipalName | principal.user.userid |
| userStates.0.userPrincipalName,userPrincipalName | target.user.userid |
| userStates.1.accountName | about.user.user_display_name |
| userStates.1.domainName | about.user.administrative_domain |
| userStates.1.logonIp | about.ip |
| userStates.1.userPrincipalName | about.user.userid |
| vendorInformation.provider,properties.extendedProperties.client Application | metadata.product_name |
Product Event Types¶
| Event, severity | UDM Event Classification | Security Category | alerting enabled |
|---|---|---|---|
| all other events | GENERIC_EVENT | ||
| Antimalware Action Taken | SCAN_FILE | ||
| Atypical travel | USER_UNCATEGORIZED | ||
| Email reported by user as malware or phish | EMAIL_TRANSACTION | TRUE | |
| Impossible travel activity | USER_UNCATEGORIZED | ||
| Logon by an unfamiliar principal | USER_UNCATEGORIZED | ||
| Ransomware | TRUE | ||
| Critical, High, Medium | TRUE | ||
| signin | USER_UNCATEGORIZED | ||
| Unusual volume of file deletion | GENERIC_EVENT | DATA_DESTRUCTION | |
| newAlert | TRUE |
Log Sample¶
{"detectionIds":[],"severity":"low","vendorInformation":{"provider":"Office 365 Security and Compliance","providerVersion":null,"subProvider":null,"vendor":"Microsoft"},"id":"id","lastModifiedDateTime":"2021-09-26T04:10:51.557Z","sourceMaterials":["url"],"alertDetections":[],"cloudAppStates":[],"closedDateTime":null,"createdDateTime":"2021-09-26T04:15:00Z","fileStates":[],"historyStates":[],"comments":["New alert"],"category":"ThreatManagement","incidentIds":[],"malwareStates":[],"azureSubscriptionId":null,"status":"newAlert","title":"Email reported by user as malware or phish","investigationSecurityStates":[],"vulnerabilityStates":[],"tags":[],"eventDateTime":"2021-09-26T04:15:00Z","recommendedActions":[],"networkConnections":[],"uriClickSecurityStates":[],"assignedTo":null,"activityGroupName":null,"description":"This alert is triggered when any email message is reported as malware or phish by users -V1.0.0.3","feedback":null,"messageSecurityStates":[],"processes":[],"userStates":[{"logonIp":null,"logonType":null,"userAccountType":null,"aadUserId":null,"isVpn":null,"logonId":null,"emailRole":"unknown","logonDateTime":null,"userPrincipalName":"john.doe@domain.com","accountName":"john.doe","domainName":"acme.com","logonLocation":null,"onPremisesSecurityIdentifier":null,"riskScore":null},{"logonLocation":null,"userPrincipalName":"serviceuser","userAccountType":null,"emailRole":"sender","logonDateTime":null,"logonIp":"127.0.0.1","logonType":null,"aadUserId":null,"isVpn":null,"logonId":null,"accountName":"jane.doe","domainName":"domain","onPremisesSecurityIdentifier":null,"riskScore":null},{"logonDateTime":null,"logonId":null,"riskScore":null,"userPrincipalName":"john.doe@domain.com","logonIp":null,"logonLocation":null,"onPremisesSecurityIdentifier":null,"logonType":null,"userAccountType":null,"aadUserId":null,"accountName":"john.doe","domainName":"acme.com","emailRole":"recipient","isVpn":null}],"azureTenantId":"tenantid","confidence":null,"lastEventDateTime":null,"hostStates":[],"registryKeyStates":[],"securityResources":[],"triggers":[],"riskScore":null}
Sample Parsing¶
metadata.event_timestamp = "2021-09-26T04:15:00Z"
metadata.event_type = "EMAIL_TRANSACTION"
metadata.vendor_name = "Microsoft"
metadata.product_name = "Office 365 Security and Compliance"
metadata.product_event_type = "Email reported by user as malware or phish"
metadata.description = "This alert is triggered when any email message is reported as malware or phish by users -V1.0.0.3"
metadata.url_back_to_product = "url"
metadata.ingested_timestamp = "2021-09-26T04:17:10.243424Z"
principal.user.userid = "john.doe@domain.com"
principal.user.user_display_name = "john.doe"
principal.administrative_domain = "domain.com"
security_result.rule_name = "ThreatManagement"
security_result.summary = "Email reported by user as malware or phish"
security_result.description = "This alert is triggered when any email message is reported as malware or phish by users -V1.0.0.3"
security_result.severity = "LOW"
network.email.from = "jane.doe"
network.email.to = "john.doe@domain.com"
Parser Alerting¶
Alerting criteria is listed in the Product Event Types table above.