Microsoft Defender for Office 365 Integration Guide

Overview

The Microsoft Defender for Office 365 (MDO365) integration connects your NINA workflows to two distinct Microsoft APIs:

Microsoft Graph Security API — alerts, incidents, secure scores, advanced hunting, and threat submissions
Exchange Online Admin REST API — email security policy configuration via two transport layers:
- OData endpoint (/EntitySet): Safe Links, Anti-Phishing, Anti-Spam, Anti-Malware rules, Mailbox Junk settings
- InvokeCommand endpoint (POST /InvokeCommand): Safe Attachment policies, Malware Filter policies, outbound spam, quarantine, allow/block lists, protection policy rules, reporting cmdlets, and more

This integration lets you monitor and respond to email-borne threats, manage anti-phishing and anti-spam policies, query hunting data across mailflow events, submit suspicious messages and URLs for analysis, and audit changes across your Exchange Online security posture — all directly from your workflows.

Microsoft Defender for Office 365 is Microsoft's cloud-based email filtering and threat protection service layered on top of Exchange Online Protection (EOP). Plan 1 adds Safe Attachments, Safe Links, and ATP anti-phishing. Plan 2 adds threat trackers, attack simulators, advanced hunting, and automated investigation and response (AIR).

Resources at a Glance

Group	Resource	API Used
Graph Security	`alert`	Graph Security API
Graph Security	`incident`	Graph Security API
Graph Security	`secureScore`	Graph Security API
Graph Security	`secureScoreControlProfile`	Graph Security API
Graph Security	`advancedHunting`	Graph Security API
Graph Security (Advanced Hunting tables)	`emailEvents`, `emailAttachmentInfo`, `emailUrlInfo`, `emailPostDeliveryEvents`, `cloudAppEvents`, `alertInfo`, `alertEvidence`	Graph Security API
Threat Submissions (Plan 2)	`emailThreatSubmission`, `urlThreatSubmission`, `fileThreatSubmission`	Graph Security API
Exchange Online Policy (OData)	`safeAttachmentRule`, `atpPolicyForO365`	EXO Admin API (OData)
Exchange Online Policy (OData)	`safeLinksPolicy`, `safeLinksRule`	EXO Admin API (OData)
Exchange Online Policy (OData)	`antiPhishPolicy`, `antiPhishRule`	EXO Admin API (OData)
Exchange Online Policy (OData)	`hostedContentFilterPolicy`, `hostedContentFilterRule`	EXO Admin API (OData)
Exchange Online Policy (OData)	`malwareFilterRule`	EXO Admin API (OData)
Exchange Online Policy (OData)	`mailboxJunkEmailConfiguration`	EXO Admin API (OData)
Exchange Online Policy (IC)	`safeAttachmentPolicy`, `malwareFilterPolicy`	EXO Admin API (InvokeCommand)
Exchange Online Policy (IC)	`hostedOutboundSpamFilterPolicy`, `hostedOutboundSpamFilterRule`	EXO Admin API (InvokeCommand)
Exchange Online Policy (IC)	`hostedConnectionFilterPolicy`	EXO Admin API (InvokeCommand)
Exchange Online Policy (IC)	`blockedSenderAddress`	EXO Admin API (InvokeCommand)
Exchange Online Policy (IC)	`quarantinePolicy`, `quarantineMessage`	EXO Admin API (InvokeCommand)
Exchange Online Policy (IC)	`tenantAllowBlockListItems`, `tenantAllowBlockListSpoofItems`	EXO Admin API (InvokeCommand)
Exchange Online Policy (IC)	`eopProtectionPolicyRule`, `atpProtectionPolicyRule`	EXO Admin API (InvokeCommand)
Exchange Online Policy (IC)	`teamsProtectionPolicy`, `teamsProtectionPolicyRule`	EXO Admin API (InvokeCommand)
Exchange Online Policy (IC)	`reportSubmissionPolicy`, `reportSubmissionRule`	EXO Admin API (InvokeCommand)
Exchange Online Policy (IC)	`protectionAlert`, `emailTenantSettings`	EXO Admin API (InvokeCommand)
Exchange Online Reports (IC)	`mailTrafficATPReport`, `mailDetailATPReport`	EXO Admin API (InvokeCommand)
Exchange Online Reports (IC)	`safeLinksAggregateReport`, `safeLinksDetailReport`	EXO Admin API (InvokeCommand)
Exchange Online Reports (IC)	`contentMalwareMdoAggregateReport`, `contentMalwareMdoDetailReport`	EXO Admin API (InvokeCommand)
Exchange Online Reports (IC)	`mailFlowStatusReport`, `mailTrafficSummaryReport`	EXO Admin API (InvokeCommand)
Exchange Online Reports (IC)	`compromisedUserAggregateReport`, `compromisedUserDetailReport`	EXO Admin API (InvokeCommand)
Exchange Online Reports (IC)	`spoofMailReport`, `aggregateZapReport`, `detailZapReport`	EXO Admin API (InvokeCommand)
Exchange Online Reports (IC)	`mailTrafficPolicyReport`, `mailDetailTransportRuleReport`	EXO Admin API (InvokeCommand)
Exchange Online Reports (IC)	`spoofIntelligenceInsight`	EXO Admin API (InvokeCommand)
Exchange Online Audit	`unifiedAuditLog`	EXO Admin API (OData)
Exchange Online Management	`priorityAccountUser`	EXO Admin API (OData)

Resources that require Defender for Office 365 Plan 2 (emailThreatSubmission, urlThreatSubmission, fileThreatSubmission) are compiled and dispatched correctly but will return an error if your tenant does not have the required license. See the License Requirements section.

InvokeCommand (IC) resources use the POST /InvokeCommand endpoint rather than OData entity sets. They use the same EXO bearer token and require the same Exchange.ManageAsApp permission and Exchange Administrator role. No additional configuration is needed.

License Requirements

Licensing requirements apply at the tenant level — the Microsoft 365 subscription must include (or have add-on access to) the relevant plan. User-level licensing may also be required for policies that protect specific mailboxes.

Resource	Minimum License Required
`alert`, `incident`, `secureScore`, `secureScoreControlProfile`	Microsoft Defender for Office 365 Plan 1 or Plan 2 (included in Microsoft 365 E5, Microsoft 365 Business Premium, or as a standalone add-on)
`advancedHunting` (all Advanced Hunting tables)	Microsoft Defender for Office 365 Plan 2 (included in Microsoft 365 E5 or standalone Plan 2)
`emailThreatSubmission`, `urlThreatSubmission`, `fileThreatSubmission`	Microsoft Defender for Office 365 Plan 2
`safeAttachmentRule`, `atpPolicyForO365`	Microsoft Defender for Office 365 Plan 1 or Plan 2
`safeAttachmentPolicy`	Microsoft Defender for Office 365 Plan 1 or Plan 2
`safeLinksPolicy`, `safeLinksRule`	Microsoft Defender for Office 365 Plan 1 or Plan 2
`antiPhishPolicy`, `antiPhishRule`	Microsoft Defender for Office 365 Plan 1 or Plan 2 (EOP includes basic anti-phishing; ATP impersonation protection requires Plan 1+)
`hostedContentFilterPolicy`, `hostedContentFilterRule`	Exchange Online Protection (EOP) — included in all Exchange Online/Microsoft 365 plans
`malwareFilterRule`, `malwareFilterPolicy`	Exchange Online Protection (EOP) — included in all Exchange Online/Microsoft 365 plans
`hostedOutboundSpamFilterPolicy`, `hostedOutboundSpamFilterRule`	Exchange Online Protection (EOP) — included in all Exchange Online/Microsoft 365 plans
`hostedConnectionFilterPolicy`, `blockedSenderAddress`	Exchange Online Protection (EOP) — included in all Exchange Online/Microsoft 365 plans
`quarantinePolicy`, `quarantineMessage`	Exchange Online Protection (EOP) — included in all Exchange Online/Microsoft 365 plans
`tenantAllowBlockListItems`, `tenantAllowBlockListSpoofItems`	Exchange Online Protection (EOP) — included in all Exchange Online/Microsoft 365 plans
`eopProtectionPolicyRule`, `atpProtectionPolicyRule`	Microsoft Defender for Office 365 Plan 1 or Plan 2
`teamsProtectionPolicy`, `teamsProtectionPolicyRule`	Microsoft Defender for Office 365 Plan 1 or Plan 2
`reportSubmissionPolicy`, `reportSubmissionRule`	Exchange Online — any plan that includes Exchange Online
`protectionAlert`	Microsoft Defender for Office 365 Plan 1 or Plan 2
`emailTenantSettings`	Exchange Online — any plan that includes Exchange Online
All report resources (`mailTrafficATPReport`, etc.)	Microsoft Defender for Office 365 Plan 1 or Plan 2 (ATP reports); EOP (flow/status reports)
`mailboxJunkEmailConfiguration`	Exchange Online — any plan that includes Exchange Online
`unifiedAuditLog`	Exchange Online — Unified Audit Log must be enabled in the Microsoft 365 compliance center
`priorityAccountUser`	Microsoft 365 E3, E5, or Business Premium (Priority Account is a premium feature)

Confirming your plan: In the Microsoft 365 admin center, go to Billing > Your products and verify that you have a Defender for Office 365 Plan 1 or Plan 2 subscription (or a bundle that includes it, such as Microsoft 365 E5).

Credential Configuration

This integration requires a single Azure App Registration. The app authenticates against two separate APIs using distinct OAuth2 token scopes — the integration handles token acquisition and caching for both automatically.

API	Token endpoint	Scope
Microsoft Graph	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`	`https://graph.microsoft.com/.default`
Exchange Online Admin	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`	`https://outlook.office365.com/.default`

Authentication Method

OAuth2 Client Credentials

Field	Description	Example
Tenant ID	Directory (tenant) ID from Azure portal	`87654321-4321-4321-4321-fedcba987654`
Client ID	Application (client) ID from the App Registration	`12345678-1234-1234-1234-123456789abc`
Client Secret	Client secret value	`abcd1234~efgh5678ijklMNOP9012qrst.UV`
Base URL	Graph API base URL. Change only for sovereign cloud.	`https://graph.microsoft.com/v1.0`

Creating the Azure App Registration

Sign in to the Azure portal
Navigate to Microsoft Entra ID > App registrations
Click New registration
Provide a name (e.g., "NINA MDO365 Integration")
Select Accounts in this organizational directory only
Click Register
Note the Application (client) ID and Directory (tenant) ID from the overview page
Go to Certificates & secrets > Client secrets > New client secret
Enter a description and expiration period, then click Add
Copy the Value immediately — it will not be shown again

Required API Permissions

Microsoft Graph (Application permissions)

Grant the following and click Grant admin consent:

Permission	Required for	Required operations
`SecurityAlert.Read.All`	Reading alerts	`alert.list`, `alert.get`
`SecurityAlert.ReadWrite.All`	Updating alerts	`alert.update`
`SecurityIncident.Read.All`	Reading incidents	`incident.list`, `incident.get`, `incident.listAlerts`
`SecurityIncident.ReadWrite.All`	Updating incidents	`incident.update`
`SecurityEvents.Read.All`	Reading secure scores	`secureScore.list`, `secureScore.get`, `secureScoreControlProfile.list`, `secureScoreControlProfile.get`
`ThreatHunting.Read.All`	Advanced hunting queries	All `advancedHunting.`, `emailEvents.`, `emailAttachmentInfo.`, `emailUrlInfo.`, `emailPostDeliveryEvents.`, `cloudAppEvents.`, `alertInfo.`, `alertEvidence.`
`ThreatSubmission.Read.All`	Reading threat submissions	`emailThreatSubmission.list`, `emailThreatSubmission.get`, `urlThreatSubmission.list`, `urlThreatSubmission.get`, `fileThreatSubmission.list`, `fileThreatSubmission.get`
`ThreatSubmission.ReadWrite.All`	Submitting threats for analysis	`emailThreatSubmission.create`, `emailThreatSubmission.review`, `urlThreatSubmission.create`, `fileThreatSubmission.create`

Note: SecurityEvents.Read.All is a broad permission that also covers alerts and incidents. If you prefer finer-grained control, use SecurityAlert.Read.All and SecurityIncident.Read.All separately instead.

Exchange Online Admin API (Application permissions)

In API permissions, click Add a permission > APIs my organization uses > search for Office 365 Exchange Online:

Permission	Description
`Exchange.ManageAsApp`	Allows the application to manage Exchange Online as a service account, required for all EXO Admin API calls

Important: After granting Exchange.ManageAsApp, you must also assign the Azure AD role Exchange Administrator (or a more scoped role) to the service principal. This is done in Microsoft Entra ID > Roles and administrators > Exchange administrator > Add assignments.

Assigning the Exchange Administrator Role

In the Azure portal, go to Microsoft Entra ID > Roles and administrators
Search for and open Exchange administrator
Click Add assignments
Search for your App Registration by name, select it, and click Add

The service principal must have this role — Exchange.ManageAsApp alone is not sufficient without it.

Creating a Microsoft Defender for Office 365 Credential in NINA

Navigate to the Credentials section in NINA
Click Add New Credential
Fill in:
- Name: A descriptive name (e.g., "MDO365 Production")
- Integration Service: Select "Microsoft Defender for Office 365"
- Auth Type: Select "OAuth2"
- Tenant ID: Your Directory (tenant) ID
- Client ID: Your Application (client) ID
- Client Secret: Your client secret value
- Base URL: Leave blank for commercial cloud
Click Test Connection to verify credentials
Click Save

Sovereign Cloud Environments

Cloud	Graph Base URL
Commercial (default)	`https://graph.microsoft.com/v1.0`
US Government GCC	`https://graph.microsoft.us/v1.0`
US Government GCC High	`https://dod-graph.microsoft.us/v1.0`

The Exchange Online Admin API base URL (https://outlook.office365.com/adminapi/beta/{tenantId}/) does not vary by sovereign cloud in the current implementation.

Supported Resources and Operations

Alert

Manage MDO365 security alerts via the Microsoft Graph Security API. Use serviceSource eq 'microsoftDefenderForOffice365' in $filter to scope results to MDO365 only.

Minimum license: Microsoft Defender for Office 365 Plan 1 or Plan 2 Required permissions: SecurityAlert.Read.All (read), SecurityAlert.ReadWrite.All (update)

Operation	Description
`list`	Retrieve security alerts with OData filtering, sorting, and shortcuts
`get`	Retrieve a single alert by ID
`update`	Update status, classification, determination, assignee, or add a comment

Key parameters for list:

$filter — OData filter (e.g., serviceSource eq 'microsoftDefenderForOffice365' and severity eq 'high')
$top — max results (default: 50, max: 2000)
$skip — pagination offset
$orderby — sort expression (e.g., createdDateTime desc)
severity — shortcut: unknown, informational, low, medium, high
status — shortcut: unknown, new, inProgress, resolved
serviceSource — shortcut: microsoftDefenderForOffice365

Key parameters for update:

alertId (required) — the alert ID
updateFields.status — new, inProgress, resolved
updateFields.classification — unknown, truePositive, informationalExpectedActivity, falsePositive
updateFields.determination — unknown, apt, malware, securityPersonnel, securityTesting, unwantedSoftware, other, multiStagedAttack, compromisedUser, phishing, maliciousUserActivity, notMalicious, notEnoughDataToValidate, confirmedUserActivity, lineOfBusinessApplication
updateFields.assignedTo — analyst email address
updateFields.comment — comment text to append

Incident

Query and update MDO365 security incidents, which group related alerts into a single investigation case.

Minimum license: Microsoft Defender for Office 365 Plan 1 or Plan 2 Required permissions: SecurityIncident.Read.All (read), SecurityIncident.ReadWrite.All (update)

Operation	Description
`list`	Retrieve incidents with OData filtering
`get`	Retrieve a single incident by ID
`update`	Update status, classification, determination, or assignment
`listAlerts`	Retrieve all alerts associated with an incident

Key parameters for list:

$filter — OData filter (e.g., status eq 'active')
$top — max results (default: 50)
$skip — pagination offset
$orderby — sort expression
status — shortcut: active, resolved, inProgress, redirected
severity — shortcut: unknown, informational, low, medium, high

Key parameters for update:

incidentId (required) — the incident ID
updateFields.status — active, resolved, inProgress, redirected
updateFields.assignedTo — analyst UPN
updateFields.classification — unknown, falsePositive, truePositive, informationalExpectedActivity
updateFields.determination — same values as alert determination
updateFields.tags — array of string tags

Secure Score

Retrieve the organization's Microsoft Secure Score for identity and threat protection.

Minimum license: Microsoft Defender for Office 365 Plan 1 or Plan 2 Required permissions: SecurityEvents.Read.All

Operation	Description
`list`	Retrieve historical secure score snapshots
`get`	Retrieve a specific secure score snapshot by ID

Key parameters for list:

$top — max snapshots (default: 10)
$filter — OData filter expression

Secure Score Control Profile

Retrieve the control profiles that make up the secure score.

Minimum license: Microsoft Defender for Office 365 Plan 1 or Plan 2 Required permissions: SecurityEvents.Read.All

Operation	Description
`list`	Retrieve all secure score control profiles
`get`	Retrieve a specific control profile by ID

Key parameters for list:

$filter — OData filter expression
$top — max results (default: 100)

Advanced Hunting

Execute KQL (Kusto Query Language) queries across MDO365 hunting tables via the Microsoft Graph runHuntingQuery API. All Advanced Hunting resources share the same query operation.

Minimum license: Microsoft Defender for Office 365 Plan 2 Required permissions: ThreatHunting.Read.All

Resource	Table	Key columns
`advancedHunting`	Generic — provide any valid MDO365 KQL query	N/A
`emailEvents`	`EmailEvents`	`NetworkMessageId`, `SenderFromAddress`, `RecipientEmailAddress`, `Subject`, `ThreatNames`, `DeliveryAction`
`emailAttachmentInfo`	`EmailAttachmentInfo`	`NetworkMessageId`, `FileName`, `FileType`, `SHA256`, `ThreatNames`
`emailUrlInfo`	`EmailUrlInfo`	`NetworkMessageId`, `Url`, `UrlDomain`
`emailPostDeliveryEvents`	`EmailPostDeliveryEvents`	`NetworkMessageId`, `RecipientEmailAddress`, `ActionType`, `ActionResult`
`cloudAppEvents`	`CloudAppEvents`	`AccountDisplayName`, `AccountObjectId`, `Application`, `ActionType`, `IPAddress`
`alertInfo`	`AlertInfo`	`AlertId`, `Title`, `Category`, `Severity`, `ServiceSource`, `DetectionSource`
`alertEvidence`	`AlertEvidence`	`AlertId`, `EntityType`, `RemoteIP`, `AccountName`, `FileName`, `ProcessCommandLine`

Common parameters for all query operations:

query — full KQL query; if omitted, a default TABLE | take N query is built from $top and timeRange
$top — max rows (default: 25); appended as | take N when no query is provided
timeRange — look-back in days; appended as | where Timestamp > ago(Nd) when no query is provided
timeoutInSeconds — max query execution time in seconds

When you provide a query, the table name is automatically prepended if not already present at the start of the query.

Email Threat Submission

Submit and manage email messages reported as threats to Microsoft for analysis.

Minimum license: Microsoft Defender for Office 365 Plan 2 Required permissions: ThreatSubmission.Read.All (list/get), ThreatSubmission.ReadWrite.All (create/review)

Operation	Description
`list`	Retrieve email threat submissions with filtering
`get`	Retrieve a specific submission by ID
`create`	Submit an email message for threat analysis
`review`	Request a review of an existing submission

Key parameters for create:

category (required) — notJunk, spam, phishing, malware
recipientEmailAddress (required) — recipient who received the message
networkMessageId — message ID from X-MS-Exchange-Organization-Network-Message-Id header
sender — sender email address
senderIp — sender IP address
subject — email subject
messageDateTime — receipt time (RFC3339)

Rate limit: 150 submissions per 15 minutes.

URL Threat Submission

Submit URLs reported as threats to Microsoft for analysis.

Minimum license: Microsoft Defender for Office 365 Plan 2 Required permissions: ThreatSubmission.Read.All (list/get), ThreatSubmission.ReadWrite.All (create)

Operation	Description
`list`	Retrieve URL threat submissions
`get`	Retrieve a specific submission by ID
`create`	Submit a URL for threat analysis

Key parameters for create:

category (required) — notJunk, spam, phishing, malware
webUrl (required) — the URL to submit (e.g., https://example.com/suspicious-page)

File Threat Submission

Submit files reported as threats to Microsoft for analysis.

Minimum license: Microsoft Defender for Office 365 Plan 2 Required permissions: ThreatSubmission.Read.All (list/get), ThreatSubmission.ReadWrite.All (create)

Operation	Description
`list`	Retrieve file threat submissions
`get`	Retrieve a specific submission by ID
`create`	Submit a file for threat analysis

Key parameters for create:

category (required) — notJunk, spam, phishing, malware
fileName (required) — the file name (e.g., suspicious.exe)
fileContent (required) — the base64-encoded content of the file

Safe Attachment Rule

Manage Safe Attachments rules via the Exchange Online Admin API. Rules define the recipient scope (users, groups, domains) and link to a Safe Attachments policy.

Minimum license: Microsoft Defender for Office 365 Plan 1 or Plan 2 Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all Safe Attachment rules
`get`	Get a rule by name or GUID
`create`	Create a rule and link it to an existing policy
`update`	Update rule filters or priority
`delete`	Delete a rule
`enable`	Enable a disabled rule
`disable`	Disable an enabled rule

Key parameters for create:

name (required) — unique rule name
safeAttachmentPolicy (required) — name of the policy to link to
recipientDomainIs — comma-separated recipient domains
sentTo — comma-separated recipient addresses
sentToMemberOf — group names or email addresses
priority — rule evaluation order (lower number = higher priority)

Key parameters for update:

identity (required) — name or GUID of the rule

Safe Attachment Policy

Manage Safe Attachments policies via the EXO InvokeCommand endpoint. Policies define the scanning action applied to email attachments (Allow, Block, DynamicDelivery). Each policy is linked to one or more safeAttachmentRule rules that define the recipient scope.

Minimum license: Microsoft Defender for Office 365 Plan 1 or Plan 2 Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all Safe Attachment policies
`get`	Get a policy by name
`create`	Create a new policy
`update`	Update policy settings
`delete`	Delete a policy

Key parameters for create:

name (required) — unique policy name
action — Allow, Block, DynamicDelivery
quarantineTag — quarantine policy to apply to blocked attachments
redirect — boolean; redirect attachments to an admin address on scan error
redirectAddress — admin email for redirection
actionOnError — boolean; apply the action even if scanning fails
adminDisplayName — optional description

ATP Policy for Office 365

Retrieve and update the singleton ATP policy that controls Safe Attachments for SharePoint, OneDrive, and Microsoft Teams.

Minimum license: Microsoft Defender for Office 365 Plan 1 or Plan 2 Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`get`	Retrieve the singleton ATP policy
`update`	Update Safe Docs and related settings

Key parameters for update:

enableSafeDocs — boolean; enable Safe Documents for Office clients
enableATPForSPOTeamsODB — boolean; enable Safe Attachments for SharePoint, OneDrive, and Teams
enableSafeLinksForO365Clients — boolean; enable Safe Links in Office 365 clients

Safe Links Policy

Manage Safe Links policies, which define URL rewriting and click-protection behavior.

Minimum license: Microsoft Defender for Office 365 Plan 1 or Plan 2 Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all Safe Links policies
`get`	Get a policy by name
`create`	Create a new Safe Links policy
`update`	Update policy settings
`delete`	Delete a policy

Key parameters for create:

name (required) — unique policy name
enableSafeLinksForEmail — boolean; enable URL rewriting in email
enableSafeLinksForTeams — boolean; enable Safe Links in Teams
enableSafeLinksForOffice — boolean; enable Safe Links in Office apps
trackClicks — boolean; track user clicks on URLs
allowClickThrough — boolean; let users bypass blocked URLs
scanUrls — boolean; enable real-time URL scanning before delivery
enableForInternalSenders — boolean; apply policy to internal senders

Safe Links Rule

Manage Safe Links rules that specify recipient scope and link to a Safe Links policy.

Minimum license: Microsoft Defender for Office 365 Plan 1 or Plan 2 Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all Safe Links rules
`get`	Get a rule by name
`create`	Create a rule
`update`	Update rule filters or priority
`delete`	Delete a rule
`enable`	Enable a rule
`disable`	Disable a rule

Key parameters for list:

state — shortcut: Enabled, Disabled
$filter — OData filter (takes precedence over state)
$top — max results

Anti-Phishing Policy

Manage ATP anti-phishing policies, which configure impersonation protection, spoof intelligence, and mailbox intelligence.

Minimum license: Microsoft Defender for Office 365 Plan 1 or Plan 2 (EOP includes basic anti-phishing; impersonation and advanced features require Plan 1+) Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all anti-phishing policies
`get`	Get a policy by name
`create`	Create a new policy
`update`	Update policy settings
`delete`	Delete a policy

Key parameters for create:

name (required) — unique policy name
enableAntiSpoofEnforcement — boolean; enable spoof intelligence enforcement
enableMailboxIntelligence — boolean; enable mailbox intelligence
enableMailboxIntelligenceProtection — boolean; enable action on mailbox intelligence signals
enableTargetedUserProtection — boolean; enable targeted user impersonation protection
targetedUsersToProtect — array of name;email pairs to protect
enableOrganizationDomainsProtection — boolean; protect organization's own domains
enableTargetedDomainsProtection — boolean; enable targeted domain impersonation protection
targetedDomainsToProtect — array of domain names

Anti-Phishing Rule

Manage anti-phishing rules that define recipient scope for anti-phishing policies.

Minimum license: Microsoft Defender for Office 365 Plan 1 or Plan 2 Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all anti-phishing rules
`get`	Get a rule by name
`create`	Create a rule
`update`	Update filters or priority
`delete`	Delete a rule
`enable`	Enable a rule
`disable`	Disable a rule

Hosted Content Filter Policy (Anti-Spam)

Manage inbound anti-spam (content filter) policies, which define spam and bulk-mail thresholds and actions.

Minimum license: Exchange Online Protection (EOP) — no Defender plan required Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all anti-spam policies
`get`	Get a policy by name
`create`	Create a policy
`update`	Update policy settings
`delete`	Delete a policy

Key parameters for create:

name (required) — unique policy name
spamAction — action for spam: MoveToJmf, AddXHeader, ModifySubject, Redirect, Delete, Quarantine
highConfidenceSpamAction — action for high-confidence spam (same values)
phishSpamAction — action for phish: MoveToJmf, Redirect, Delete, Quarantine
bulkThreshold — bulk complaint level threshold (1–9, lower = more aggressive)
zAPEnabled — boolean; enable Zero-hour Auto Purge
quarantineTag — quarantine policy name to apply

Hosted Content Filter Rule (Anti-Spam Rule)

Manage anti-spam rules that link policies to recipient scopes.

Minimum license: Exchange Online Protection (EOP) Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all anti-spam rules
`get`	Get a rule by name
`create`	Create a rule
`update`	Update filters or priority
`delete`	Delete a rule
`enable`	Enable a rule
`disable`	Disable a rule

Key parameters for list:

state — shortcut: Enabled, Disabled
$filter — OData filter

Malware Filter Rule (Anti-Malware Rule)

Manage anti-malware rules that link malware filter policies to recipient scopes.

Minimum license: Exchange Online Protection (EOP) — no Defender plan required Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all malware filter rules
`get`	Get a rule by name
`create`	Create a rule
`update`	Update filters or priority
`delete`	Delete a rule
`enable`	Enable a rule
`disable`	Disable a rule

Malware Filter Policy (Anti-Malware Policy)

Manage anti-malware policies via the EXO InvokeCommand endpoint. Policies define the action to take on detected malware and configure admin notifications.

Minimum license: Exchange Online Protection (EOP) — no Defender plan required Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all malware filter policies
`get`	Get a policy by name
`create`	Create a policy
`update`	Update policy settings
`delete`	Delete a policy

Key parameters for create:

name (required) — unique policy name
action — DeleteMessage, DeleteAttachmentAndUseDefaultAlertText, DeleteAttachmentAndUseCustomAlertText
enableFileFilter — boolean; enable common attachments filter
fileTypes — comma-separated list of blocked file extensions
zAPEnabled — boolean; enable Zero-hour Auto Purge for malware
enableInternalSenderAdminNotifications — boolean; send admin notifications for internal senders
internalSenderAdminAddress — admin email for internal notifications
enableExternalSenderAdminNotifications — boolean
externalSenderAdminAddress — admin email for external notifications

Hosted Outbound Spam Filter Policy

Manage outbound spam filter policies via the EXO InvokeCommand endpoint. These policies control per-user sending limits and the action taken when a user exceeds those limits.

Minimum license: Exchange Online Protection (EOP) Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all outbound spam filter policies
`get`	Get a policy by name
`create`	Create a policy
`update`	Update policy settings
`delete`	Delete a policy

Key parameters for create:

name (required) — unique policy name
recipientLimitExternalPerHour — max external recipients per hour (0 = unlimited)
recipientLimitInternalPerHour — max internal recipients per hour
recipientLimitPerDay — max recipients per day
actionWhenThresholdReached — Alert, BlockUser, BlockMessageAndNotifyUser

Hosted Outbound Spam Filter Rule

Manage outbound spam filter rules that link policies to sender scopes.

Minimum license: Exchange Online Protection (EOP) Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all outbound spam filter rules
`get`	Get a rule by name
`create`	Create a rule
`update`	Update rule settings
`delete`	Delete a rule

Hosted Connection Filter Policy

Retrieve and update the connection filter policy (IP Allow/Block lists). This is a tenant-wide singleton — only one exists per organization.

Minimum license: Exchange Online Protection (EOP) Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`get`	Retrieve the singleton connection filter policy
`update`	Update IP allow/block lists

Key parameters for update:

ipAllowList — comma-separated list of allowed IP addresses/CIDR ranges
ipBlockList — comma-separated list of blocked IP addresses/CIDR ranges
enableSafeList — boolean; enable Microsoft's Safe List (automatic reputation-based bypass)

Blocked Sender Address

List and unblock users who have been restricted from sending outbound mail (typically due to compromised account detection or exceeding send limits).

Minimum license: Exchange Online Protection (EOP) Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all restricted (blocked) sender addresses
`get`	Get a specific blocked sender by address
`delete`	Remove a sender from the blocked list (unblock)

Key parameters for get / delete:

senderAddress (required) — the email address to look up or unblock

Quarantine Policy

Manage quarantine policies that define what end users can do with their quarantined messages.

Minimum license: Exchange Online Protection (EOP) Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all quarantine policies
`get`	Get a policy by name
`create`	Create a quarantine policy
`updateGlobal`	Update the global quarantine policy settings
`delete`	Delete a quarantine policy

Key parameters for create:

name (required) — unique policy name
endUserQuarantinePermissionsValue — permission bitmask (0–236)
eSNEnabled — boolean; enable end-user spam notifications
multiLanguageSetting — notification language(s)
endUserSpamNotificationFrequency — notification frequency in days

Quarantine Message

Query and manage messages currently held in the Exchange Online quarantine.

Minimum license: Exchange Online Protection (EOP) Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List quarantined messages with filtering
`get`	Get a specific quarantined message by identity
`release`	Release one or more messages from quarantine
`delete`	Delete one or more quarantined messages

Key parameters for list:

$top — max results
startReceivedDate, endReceivedDate — date range filter
senderAddress, recipientAddress — sender/recipient filter
type — Spam, Malware, Phish, Bulk, etc.

Key parameters for release / delete:

identities (required) — comma-separated list of quarantine message IDs

Tenant Allow/Block List Items

Manage organization-level entries in the Tenant Allow/Block List for URLs, file hashes, sender addresses, and IP addresses.

Minimum license: Exchange Online Protection (EOP) Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List entries (requires `listType`)
`get`	Get a specific entry by identity
`create`	Create allow or block entries
`update`	Update existing entries
`delete`	Delete entries

Key parameters for list / create:

listType (required for list/create) — Url, FileHash, Sender, IP
entries (required for create) — comma-separated list of values to add
action — Allow or Block
expirationDate — expiry date (ISO 8601) or use noExpiration: true
notes — optional note

Tenant Allow/Block List Spoof Items

Manage allow/block entries for spoofed sender/infrastructure pairs used by spoof intelligence.

Minimum license: Exchange Online Protection (EOP) Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all spoof items
`get`	Get a spoof item by identity
`create`	Create a spoof allow or block entry
`update`	Update an entry
`delete`	Delete an entry

Key parameters for create:

spoofedUser (required) — spoofed sender domain or email
sendingInfrastructure (required) — sending IP or domain
spoofType — Internal or External
action — Allow or Block

EOP Protection Policy Rule

Manage EOP preset security policy rules (Standard/Strict) that bundle anti-spam, anti-malware, and anti-phishing policies into a single scoped assignment.

Minimum license: Exchange Online Protection (EOP) Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all EOP protection policy rules
`get`	Get a rule by name
`create`	Create a rule
`update`	Update rule settings
`enable`	Enable a rule
`disable`	Disable a rule

Key parameters for create:

name (required) — unique rule name
antiSpamPolicy, antiMalwarePolicy, antiPhishPolicy — linked policy names
sentTo, sentToMemberOf, recipientDomainIs — recipient conditions
exceptIfSentTo, exceptIfSentToMemberOf, exceptIfRecipientDomainIs — exclusions
priority — rule evaluation order

ATP Protection Policy Rule

Manage ATP preset security policy rules (Standard/Strict) that bundle Safe Attachments and Safe Links into a single scoped assignment.

Minimum license: Microsoft Defender for Office 365 Plan 1 or Plan 2 Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all ATP protection policy rules
`get`	Get a rule by name
`create`	Create a rule
`update`	Update rule settings
`enable`	Enable a rule
`disable`	Disable a rule

Key parameters: same as eopProtectionPolicyRule with safeAttachmentPolicy and safeLinksPolicy instead of EOP-specific policy names.

Teams Protection Policy

Retrieve and update the singleton Teams protection policy that controls Safe Attachments and Safe Links enforcement for Microsoft Teams messages.

Minimum license: Microsoft Defender for Office 365 Plan 1 or Plan 2 Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`get`	Retrieve the singleton Teams protection policy
`create`	Create the policy (if not yet provisioned)
`update`	Update Safe Links / Safe Attachments settings

Key parameters for update:

enableSafeLinks — boolean
enableSafeAttachments — boolean
zAPEnabled — boolean; enable Zero-hour Auto Purge for Teams messages

Teams Protection Policy Rule

Manage Teams protection policy rules that apply the Teams protection policy to specific recipients.

Minimum license: Microsoft Defender for Office 365 Plan 1 or Plan 2 Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all Teams protection policy rules
`get`	Get a rule by name
`create`	Create a rule
`update`	Update rule settings

Key parameters for create:

name (required) — unique rule name
teamsProtectionPolicy (required) — name of the Teams protection policy to link
sentTo, sentToMemberOf, recipientDomainIs — recipient conditions
exceptIfSentTo, exceptIfSentToMemberOf, exceptIfRecipientDomainIs — exclusions
priority — rule evaluation order

Report Submission Policy

Retrieve and manage the report submission policy (singleton) that controls how users report messages in Outlook and how admin notifications are configured.

Minimum license: Exchange Online Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`get`	Retrieve the singleton report submission policy
`create`	Create the policy (if not yet provisioned)
`update`	Update policy settings
`delete`	Delete the policy

Key parameters for update:

enableReportToMicrosoft — boolean; allow users to report to Microsoft
enableUserEmailNotification — boolean; send email notification to users after admin review
reportJunkAddresses, reportNotJunkAddresses, reportPhishAddresses — admin mailboxes for each type

Report Submission Rule

Manage report submission rules that route user-reported messages to specific mailboxes.

Minimum license: Exchange Online Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all report submission rules
`get`	Get a rule by name
`create`	Create a rule
`update`	Update rule settings
`enable`	Enable a rule
`disable`	Disable a rule
`delete`	Delete a rule

Key parameters for create:

name (required) — unique rule name
reportSubmissionPolicy (required) — name of the linked policy
sentTo — destination mailbox for reported messages

Protection Alert

Manage custom alert policies in the Microsoft 365 Defender portal.

Minimum license: Microsoft Defender for Office 365 Plan 1 or Plan 2 Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`list`	List all protection alerts
`get`	Get an alert policy by name
`create`	Create a custom alert policy

Key parameters for create:

name (required) — unique alert name
description — alert description
category — alert category
threatType — type of threat that triggers the alert
operation — array of operations to monitor
notifyUser — array of email addresses to notify
aggregationType — how to group alerts

Email Tenant Settings

Retrieve and update tenant-wide email security settings (singleton).

Minimum license: Exchange Online Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`get`	Retrieve the singleton email tenant settings
`update`	Update tenant-wide settings

Key parameters for update:

enablePriorityAccountProtection — boolean; enable enhanced monitoring for priority accounts

EXO Report Resources

All EXO report resources use the InvokeCommand endpoint and support list only. They accept optional date range and filter parameters.

Minimum license: Microsoft Defender for Office 365 Plan 1 or Plan 2 (ATP reports); EOP for flow/status reports Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Common parameters for all report list operations:

startDate — report start date (ISO 8601)
endDate — report end date (ISO 8601)
domain — filter by domain (where supported)
direction — Inbound or Outbound (where supported)

Resource	PowerShell cmdlet	Description
`mailTrafficATPReport`	`Get-MailTrafficATPReport`	Per-day mail traffic summary with ATP verdicts
`mailDetailATPReport`	`Get-MailDetailATPReport`	Per-message ATP verdict details
`safeLinksAggregateReport`	`Get-SafeLinksAggregateReport`	Aggregate Safe Links URL click statistics
`safeLinksDetailReport`	`Get-SafeLinksDetailReport`	Per-URL Safe Links click details
`contentMalwareMdoAggregateReport`	`Get-ContentMalwareMdoAggregateReport`	Aggregate malware detected in SharePoint/OneDrive/Teams
`contentMalwareMdoDetailReport`	`Get-ContentMalwareMdoDetailReport`	Per-file malware details in SharePoint/OneDrive/Teams
`mailFlowStatusReport`	`Get-MailFlowStatusReport`	Daily summary of mail flow by status
`mailTrafficSummaryReport`	`Get-MailTrafficSummaryReport`	Summary mail traffic statistics
`compromisedUserAggregateReport`	`Get-CompromisedUserAggregateReport`	Daily count of compromised user accounts
`compromisedUserDetailReport`	`Get-CompromisedUserDetailReport`	Per-user compromised account details
`spoofMailReport`	`Get-SpoofMailReport`	Summary of spoofed mail
`aggregateZapReport`	`Get-AggregateZapReport`	Aggregate Zero-hour Auto Purge statistics
`detailZapReport`	`Get-DetailZapReport`	Per-message ZAP action details
`mailTrafficPolicyReport`	`Get-MailTrafficPolicyReport`	Mail traffic broken down by policy
`mailDetailTransportRuleReport`	`Get-MailDetailTransportRuleReport`	Per-message transport rule match details
`spoofIntelligenceInsight`	`Get-SpoofIntelligenceInsight`	Spoof intelligence insights and allow/block decisions

Mailbox Junk Email Configuration

Read and configure the per-mailbox junk email settings, including trusted senders, blocked senders, and contact trust.

Minimum license: Exchange Online (any plan) Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`get`	Retrieve junk email settings for a specific mailbox
`update`	Update junk email settings

Key parameters for get:

identity (required) — mailbox identity (UPN, email address, or GUID)

Key parameters for update:

identity (required) — mailbox identity
contactsTrusted — boolean; trust all contacts as senders
trustedSendersAndDomains — array of trusted sender addresses or domains
blockedSendersAndDomains — array of blocked sender addresses or domains

Priority Account User

Mark or unmark a mailbox user as a Priority Account, which enables enhanced monitoring and faster threat signals.

Minimum license: Microsoft 365 E3, E5, or Business Premium Required permissions: Exchange.ManageAsApp + Exchange Administrator role

Operation	Description
`update`	Set or clear Priority Account status for a user

Key parameters:

identity (required) — user UPN or email address
isPriorityAccount (required) — boolean; true to tag as a priority account, false to untag

Unified Audit Log

Search the Exchange Online Unified Audit Log for security and compliance events.

Minimum license: Exchange Online — Unified Audit Log must be enabled (default in Microsoft 365 E3/E5; must be manually enabled for standalone Exchange Online) Required permissions: Exchange.ManageAsApp + Exchange Administrator role (or Audit Logs role in Exchange)

Operation	Description
`search`	Search audit log events with date range and optional filters

Key parameters:

startDate (required) — ISO 8601 start date/time (e.g., 2026-01-01T00:00:00Z)
endDate (required) — ISO 8601 end date/time (e.g., 2026-01-31T23:59:59Z)
recordType — filter by record type (e.g., ExchangeAdmin, AzureActiveDirectory)
operations — comma-separated list of operations to filter on (e.g., New-TransportRule,Set-TransportRule)
userIds — comma-separated list of user UPNs to filter on
$top — max results (default: 100)

The Unified Audit Log retains data for 90 days (Microsoft 365 E3) or up to 1 year (Microsoft 365 E5). The maximum date range per query is 90 days.

Parameter Merging and Templating

Parameter Sources (in order of precedence)

Node Parameters: Parameters configured directly in the MDO365 Integration Node
Extracted Parameters: Parameters automatically extracted from the input data
Input Data: The complete input data from upstream nodes

When an MDO365 Integration Node executes:

Parameters from all sources are merged
Node parameters take precedence over extracted parameters
Template variables within parameters are processed using {{variable_name}} syntax

OData Filter Shortcuts vs. Raw Filters

Several list operations provide shortcut filter parameters (e.g., severity, status) that are automatically converted to OData $filter expressions. When you provide a raw $filter parameter, shortcut parameters are ignored and the raw filter takes full precedence.

Behavior	When to use
Shortcut filters (`severity`, `status`, `state`, etc.)	Simple, single-field filters — no OData syntax required
Raw `$filter`	Complex expressions, `or` logic, multiple fields, or OData functions

Examples

Listing MDO365 Alerts with Service Source Filter

{
  "integration_service": "microsoft-defender-office-365",
  "resource": "alert",
  "operation": "list",
  "parameters": {
    "serviceSource": "microsoftDefenderForOffice365",
    "severity": "high",
    "status": "new",
    "$top": 50,
    "$orderby": "createdDateTime desc"
  }
}

Updating an Alert with Template Variables

{
  "integration_service": "microsoft-defender-office-365",
  "resource": "alert",
  "operation": "update",
  "parameters": {
    "alertId": "{{alert_id}}",
    "updateFields": {
      "status": "inProgress",
      "assignedTo": "{{analyst_email}}",
      "classification": "truePositive",
      "determination": "phishing",
      "comment": "Confirmed phishing attempt targeting {{recipient}} — under investigation by {{analyst_email}}"
    }
  }
}

Retrieving an Incident and Its Alerts

{
  "integration_service": "microsoft-defender-office-365",
  "resource": "incident",
  "operation": "get",
  "parameters": {
    "incidentId": "{{incident_id}}"
  }
}

{
  "integration_service": "microsoft-defender-office-365",
  "resource": "incident",
  "operation": "listAlerts",
  "parameters": {
    "incidentId": "{{incident_id}}"
  }
}

Retrieving the Current Secure Score

{
  "integration_service": "microsoft-defender-office-365",
  "resource": "secureScore",
  "operation": "list",
  "parameters": {
    "$top": 1
  }
}

Getting a Specific Secure Score Snapshot by ID

{
  "integration_service": "microsoft-defender-office-365",
  "resource": "secureScore",
  "operation": "get",
  "parameters": {
    "id": "{{secure_score_id}}"
  }
}

Listing All Secure Score Control Profiles

{
  "integration_service": "microsoft-defender-office-365",
  "resource": "secureScoreControlProfile",
  "operation": "list",
  "parameters": {
    "$top": 100
  }
}

Filtering Control Profiles by Category

{
  "integration_service": "microsoft-defender-office-365",
  "resource": "secureScoreControlProfile",
  "operation": "list",
  "parameters": {
    "$filter": "controlCategory eq 'Identity'"
  }
}

Running an Advanced Hunting Query on Email Events

{
  "integration_service": "microsoft-defender-office-365",
  "resource": "emailEvents",
  "operation": "query",
  "parameters": {
    "query": "EmailEvents | where ThreatNames has 'Phish' | where Timestamp > ago(7d) | project NetworkMessageId, SenderFromAddress, RecipientEmailAddress, Subject, DeliveryAction, ThreatNames | take 100"
  }
}

Submitting a Phishing Email for Analysis

{
  "integration_service": "microsoft-defender-office-365",
  "resource": "emailThreatSubmission",
  "operation": "create",
  "parameters": {
    "category": "phishing",
    "recipientEmailAddress": "{{recipient}}",
    "networkMessageId": "{{network_message_id}}",
    "sender": "{{sender_address}}",
    "subject": "{{email_subject}}"
  }
}

Enabling a Safe Links Rule

{
  "integration_service": "microsoft-defender-office-365",
  "resource": "safeLinksRule",
  "operation": "enable",
  "parameters": {
    "identity": "{{rule_name}}"
  }
}

Listing Anti-Spam Rules Filtered by State

{
  "integration_service": "microsoft-defender-office-365",
  "resource": "hostedContentFilterRule",
  "operation": "list",
  "parameters": {
    "state": "Enabled"
  }
}

Searching the Audit Log for Admin Changes

{
  "integration_service": "microsoft-defender-office-365",
  "resource": "unifiedAuditLog",
  "operation": "search",
  "parameters": {
    "startDate": "2026-06-01T00:00:00Z",
    "endDate": "2026-06-04T23:59:59Z",
    "operations": "New-SafeLinksPolicy,Set-SafeLinksPolicy,Remove-SafeLinksPolicy",
    "$top": 200
  }
}

Tagging a User as a Priority Account

{
  "integration_service": "microsoft-defender-office-365",
  "resource": "priorityAccountUser",
  "operation": "update",
  "parameters": {
    "identity": "[email protected]",
    "isPriorityAccount": true
  }
}

Common Workflow Patterns

Phishing Alert Triage

alert.list with serviceSource=microsoftDefenderForOffice365 and severity=high — retrieve new MDO365 alerts
emailEvents.query — search for emails with matching sender or subject in the last 24 hours
emailThreatSubmission.create — submit confirmed phishing messages for Microsoft analysis
alert.update — assign and set status to inProgress
incident.update — resolve the incident once remediation is confirmed

Policy Compliance Audit

safeLinksPolicy.list — enumerate all Safe Links policies
safeLinksRule.list — verify all rules are enabled and cover expected recipient domains
antiPhishPolicy.list — enumerate anti-phishing policies
hostedContentFilterPolicy.list — verify anti-spam thresholds
unifiedAuditLog.search — retrieve recent admin changes to policies for change tracking

Threat Hunting: Suspicious Email Delivery

emailEvents.query — hunt for emails with unusual delivery actions or threat names
emailAttachmentInfo.query — identify attachments by SHA256 or file type
emailUrlInfo.query — surface suspicious URLs from email messages
emailPostDeliveryEvents.query — check for post-delivery ZAP removals or user interactions
alertInfo.query — correlate hunted emails with existing alerts

Secure Score Monitoring

secureScore.list — retrieve the latest score snapshots
secureScoreControlProfile.list — enumerate controls and their current state
Based on low-scoring controls, apply targeted policy fixes via the relevant EXO policy resources

Field Reference

Alert Severity Values

Value	Description
`unknown`	Severity not yet determined
`informational`	Informational alert, no immediate action needed
`low`	Low-impact alert
`medium`	Medium-impact, requires attention
`high`	High-impact, requires immediate investigation

Alert Status Values

Value	Description
`new`	Alert not yet reviewed
`inProgress`	Alert is actively being investigated
`resolved`	Alert investigation completed

Alert Classification Values

Value	Description
`truePositive`	Confirmed malicious activity
`informationalExpectedActivity`	Expected or authorized activity
`falsePositive`	Incorrectly triggered alert

Threat Submission Status Values

Value	Description
`notStarted`	Submission queued, not yet started
`running`	Microsoft is actively analyzing the submission
`succeeded`	Analysis completed
`failed`	Analysis failed
`skipped`	Submission skipped (duplicate or invalid)

Threat Submission Category Values

Value	Description
`notJunk`	Legitimate message or content incorrectly flagged
`spam`	Unsolicited bulk mail
`phishing`	Credential-harvesting or deceptive message
`malware`	Message or file contains malware

Troubleshooting

Issue	Resolution
`Azure AD token error [invalid_client]`	Verify that Client ID and Client Secret are correct and that the secret has not expired
`Azure AD token error [unauthorized_client]`	Confirm the App Registration exists in the correct tenant and that application (not delegated) permissions are configured
`Graph API error [Forbidden]`	Ensure the required Graph API permissions are configured and admin consent has been granted
`Graph API error [BadRequest]: Resource not found for the segment 'threatSubmissions'`	Your tenant does not have a Defender for Office 365 Plan 2 license — threat submission resources require Plan 2
`EXO API error [Unauthorized]`	Ensure `Exchange.ManageAsApp` is granted and the service principal is assigned the Exchange Administrator Azure AD role
`EXO API error [BadRequest]` on policy operations	If trying a resource listed in `microsoft-defender-office-365-not-integrated.md`, that resource is not supported by this integration
`EXO InvokeCommand error [cmdlet not recognized]`	The EXO cmdlet is not available on this tenant's Exchange Online version. The skip helper in E2E tests will catch this — it is not a code defect
Alert or incident list returns results from non-MDO365 sources	Add `"serviceSource": "microsoftDefenderForOffice365"` to your list parameters to scope results
OData filter syntax error	String values require single quotes (e.g., `severity eq 'high'`). Use raw `$filter` for complex expressions
Shortcut filter ignored	If both a shortcut (e.g., `severity`) and a raw `$filter` are provided, the shortcut is ignored. Use one approach per query
Advanced Hunting returns no rows	Verify the table name is correct and the time range covers the period of interest. Check that `ThreatHunting.Read.All` is granted
`EXO token: 401 Unauthorized` on EXO resources	Token acquisition may have failed for the EXO scope. Verify `Exchange.ManageAsApp` is configured on the `Office 365 Exchange Online` API (not on Microsoft Graph)
Priority Account operations fail	The Priority Account feature requires Microsoft 365 E3, E5, or Business Premium
Audit log returns no results	Ensure Unified Audit Log is enabled in the Microsoft 365 compliance center. Allow up to 30 minutes after enabling before events appear
Token expiry issues	The integration caches tokens and refreshes them automatically. Recreate the credential if persistent auth errors occur

Best Practices

Grant minimum required permissions: For read-only workflows, grant only *.Read.All variants and omit *.ReadWrite.All. This limits the blast radius if credentials are compromised.
Rotate client secrets regularly: Azure App Registration client secrets expire. Set calendar reminders before the expiry date and update the NINA credential in advance to avoid workflow disruptions.
Scope alert and incident queries to MDO365: The Graph Security API returns alerts from all Microsoft security services. Always use the serviceSource = "microsoftDefenderForOffice365" shortcut (or equivalent $filter) to scope results unless your workflow specifically needs cross-service data.
Use Advanced Hunting for correlation: The Advanced Hunting tables (emailEvents, emailPostDeliveryEvents, etc.) are significantly more powerful than alert queries for investigating specific messages, senders, or URLs. Use them for hunting before escalating to alert management.
Use shortcut filters for simple queries: The severity, status, state, and similar shortcut parameters are simpler to configure than raw OData and are combined automatically with and. Switch to raw $filter only when you need or logic, multiple conditions, or OData functions.
Understand the policy/rule split for EXO resources: Safe Attachments, Safe Links, Anti-Phishing, and Anti-Spam all follow a two-object model — a policy defines settings and a rule defines the recipient scope. This integration exposes rules (which can be listed, filtered, enabled/disabled) and policies where available. Create policies first via the portal or PowerShell, then manage their rules through NINA.
Do not delete the default policy: Exchange Online creates a default "Built-in Protection" policy for each protection type. Deleting or modifying default policies may leave mailboxes unprotected.
Set appropriate Unified Audit Log date ranges: Audit log queries are bounded by the log retention period (90 days for E3, 1 year for E5). Querying wide date ranges with no filters can be slow — narrow with operations or userIds when possible.
Protect client secrets: Store credentials exclusively through NINA's credential manager. Never include Client IDs or secrets in workflow parameters, logs, or comments.
Use a dedicated App Registration: Register a dedicated Azure App for this integration rather than reusing credentials shared across other systems. This isolates the credential lifecycle and makes permission auditing easier.

Updated: 2026-06-10

Overview​

Resources at a Glance​

License Requirements​

Credential Configuration​

Authentication Method​

OAuth2 Client Credentials​

Creating the Azure App Registration​

Required API Permissions​

Microsoft Graph (Application permissions)​

Exchange Online Admin API (Application permissions)​

Assigning the Exchange Administrator Role​

Creating a Microsoft Defender for Office 365 Credential in NINA​

Sovereign Cloud Environments​

Supported Resources and Operations​

Alert​

Incident​

Secure Score​

Secure Score Control Profile​

Advanced Hunting​

Email Threat Submission​

URL Threat Submission​

File Threat Submission​

Safe Attachment Rule​

Safe Attachment Policy​

ATP Policy for Office 365​

Safe Links Policy​

Safe Links Rule​

Anti-Phishing Policy​

Anti-Phishing Rule​

Hosted Content Filter Policy (Anti-Spam)​

Hosted Content Filter Rule (Anti-Spam Rule)​

Malware Filter Rule (Anti-Malware Rule)​

Malware Filter Policy (Anti-Malware Policy)​

Hosted Outbound Spam Filter Policy​

Hosted Outbound Spam Filter Rule​

Hosted Connection Filter Policy​

Blocked Sender Address​

Quarantine Policy​

Quarantine Message​

Tenant Allow/Block List Items​

Tenant Allow/Block List Spoof Items​

EOP Protection Policy Rule​

ATP Protection Policy Rule​

Teams Protection Policy​

Teams Protection Policy Rule​

Report Submission Policy​

Report Submission Rule​

Protection Alert​

Email Tenant Settings​

EXO Report Resources​

Mailbox Junk Email Configuration​

Priority Account User​

Unified Audit Log​

Parameter Merging and Templating​

Parameter Sources (in order of precedence)​

OData Filter Shortcuts vs. Raw Filters​

Examples​

Listing MDO365 Alerts with Service Source Filter​

Updating an Alert with Template Variables​

Retrieving an Incident and Its Alerts​

Retrieving the Current Secure Score​

Getting a Specific Secure Score Snapshot by ID​

Listing All Secure Score Control Profiles​

Filtering Control Profiles by Category​

Running an Advanced Hunting Query on Email Events​

Submitting a Phishing Email for Analysis​

Enabling a Safe Links Rule​

Listing Anti-Spam Rules Filtered by State​

Searching the Audit Log for Admin Changes​

Tagging a User as a Priority Account​

Common Workflow Patterns​

Phishing Alert Triage​

Policy Compliance Audit​

Threat Hunting: Suspicious Email Delivery​

Secure Score Monitoring​

Field Reference​

Alert Severity Values​

Alert Status Values​

Alert Classification Values​

Threat Submission Status Values​

Overview

Resources at a Glance

License Requirements

Credential Configuration

Authentication Method

OAuth2 Client Credentials

Creating the Azure App Registration

Required API Permissions

Microsoft Graph (Application permissions)

Exchange Online Admin API (Application permissions)

Assigning the Exchange Administrator Role

Creating a Microsoft Defender for Office 365 Credential in NINA

Sovereign Cloud Environments

Supported Resources and Operations

Alert

Incident

Secure Score

Secure Score Control Profile

Advanced Hunting

Email Threat Submission

URL Threat Submission

File Threat Submission

Safe Attachment Rule

Safe Attachment Policy

ATP Policy for Office 365

Safe Links Policy

Safe Links Rule

Anti-Phishing Policy

Anti-Phishing Rule

Hosted Content Filter Policy (Anti-Spam)

Hosted Content Filter Rule (Anti-Spam Rule)

Malware Filter Rule (Anti-Malware Rule)

Malware Filter Policy (Anti-Malware Policy)

Hosted Outbound Spam Filter Policy

Hosted Outbound Spam Filter Rule

Hosted Connection Filter Policy

Blocked Sender Address

Quarantine Policy

Quarantine Message

Tenant Allow/Block List Items

Tenant Allow/Block List Spoof Items

EOP Protection Policy Rule

ATP Protection Policy Rule

Teams Protection Policy

Teams Protection Policy Rule

Report Submission Policy

Report Submission Rule

Protection Alert

Email Tenant Settings

EXO Report Resources

Mailbox Junk Email Configuration

Priority Account User

Unified Audit Log

Parameter Merging and Templating

Parameter Sources (in order of precedence)

OData Filter Shortcuts vs. Raw Filters

Examples

Listing MDO365 Alerts with Service Source Filter

Updating an Alert with Template Variables

Retrieving an Incident and Its Alerts

Retrieving the Current Secure Score

Getting a Specific Secure Score Snapshot by ID

Listing All Secure Score Control Profiles

Filtering Control Profiles by Category

Running an Advanced Hunting Query on Email Events

Submitting a Phishing Email for Analysis

Enabling a Safe Links Rule

Listing Anti-Spam Rules Filtered by State

Searching the Audit Log for Admin Changes

Tagging a User as a Priority Account

Common Workflow Patterns

Phishing Alert Triage

Policy Compliance Audit

Threat Hunting: Suspicious Email Delivery

Secure Score Monitoring

Field Reference

Alert Severity Values

Alert Status Values

Alert Classification Values

Threat Submission Status Values