diff --git a/api-reference/beta/api/partners-billing-billedreconciliation-export.md b/api-reference/beta/api/partners-billing-billedreconciliation-export.md index ffa13940bac..84f1e53672f 100644 --- a/api-reference/beta/api/partners-billing-billedreconciliation-export.md +++ b/api-reference/beta/api/partners-billing-billedreconciliation-export.md @@ -23,12 +23,8 @@ Export the billed invoice reconciliation data. One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). - -[!INCLUDE [permissions-table](../includes/permissions/partners-permissions.md)] + +[!INCLUDE [permissions-table](../includes/permissions/partners-billing-billedreconciliation-export-permissions.md)] ## HTTP request diff --git a/api-reference/beta/api/partners-billing-billedusage-export.md b/api-reference/beta/api/partners-billing-billedusage-export.md index 6afe056e0d0..651834f58b5 100644 --- a/api-reference/beta/api/partners-billing-billedusage-export.md +++ b/api-reference/beta/api/partners-billing-billedusage-export.md @@ -23,12 +23,8 @@ Export the billed Azure usage data. One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). - -[!INCLUDE [permissions-table](../includes/permissions/partners-permissions.md)] + +[!INCLUDE [permissions-table](../includes/permissions/partners-billing-billedusage-export-permissions.md)] ## HTTP request diff --git a/api-reference/beta/api/security-analyzedemail-get.md b/api-reference/beta/api/security-analyzedemail-get.md new file mode 100644 index 00000000000..157565909f6 --- /dev/null +++ b/api-reference/beta/api/security-analyzedemail-get.md @@ -0,0 +1,150 @@ +--- +title: "Get analyzedEmail" +description: "Read the properties and relationships of an analyzedEmail object." +author: "malvika-balaraj" +ms.localizationpriority: medium +ms.prod: "security" +doc_type: apiPageType +--- + +# Get analyzedEmail + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Read the properties and relationships of an [analyzedEmail](../resources/security-analyzedemail.md) object. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +[!INCLUDE [permissions-table](../includes/permissions/security-analyzedemail-get-permissions.md)] + +## HTTP request + + +``` http +GET /security/collaboration/analyzedEmails/{analyzedEmailId} +``` + + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a [microsoft.graph.security.analyzedEmail](../resources/security-analyzedemail.md) object in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +GET https://graph.microsoft.com/beta/security/collaboration/analyzedEmails/{analyzedEmailId} +``` + + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": { + "@odata.type": "#microsoft.graph.security.analyzedEmail", + "id": "3570a93a-82b1-ffb9-8c26-a9a2ca002a17", + "loggedDateTime": "String (timestamp)", + "networkMessageId": "String", + "internetMessageId": "String", + "senderDetail": { + "@odata.type": "microsoft.graph.security.analyzedEmailSenderDetail" + }, + "recipientEmailAddresses": [ + "String" + ], + "distributionList": "String", + "subject": "String", + "returnPath": "String", + "directionality": "String", + "originalDelivery": { + "@odata.type": "microsoft.graph.security.analyzedEmailDeliveryDetail" + }, + "latestDelivery": { + "@odata.type": "microsoft.graph.security.analyzedEmailDeliveryDetail" + }, + "attachmentsCount": "Integer", + "attachments": [ + { + "@odata.type": "microsoft.graph.security.analyzedEmailAttachment" + } + ], + "urlsCount": "Integer", + "urls": [ + { + "@odata.type": "microsoft.graph.security.analyzedEmailUrl" + } + ], + "language": "String", + "sizeInBytes": "Integer", + "alertIds": [ + "String" + ], + "exchangeTransportRules": [ + { + "@odata.type": "microsoft.graph.security.analyzedEmailExchangeTransportRuleInfo" + } + ], + "overrideSources": [ + "String" + ], + "threatType": "String", + "detectionMethods": [ + "String" + ], + "contexts": [ + "String" + ], + "authenticationDetails": { + "@odata.type": "microsoft.graph.security.analyzedEmailAuthenticationDetail" + }, + "phishConfidenceLevel": "String", + "spamConfidenceLevel": "String", + "bulkComplaintLevel": "String", + "emailClusterId": "String", + "policyAction": "String", + "policy": "String" + } +} +``` + diff --git a/api-reference/beta/api/security-analyzedemail-remediate.md b/api-reference/beta/api/security-analyzedemail-remediate.md new file mode 100644 index 00000000000..7732e99ee32 --- /dev/null +++ b/api-reference/beta/api/security-analyzedemail-remediate.md @@ -0,0 +1,120 @@ +--- +title: "analyzedEmail: remediate " +description: "Remove a potential threat from end users' mailboxes." +author: MishraSoumyaMS +ms.localizationpriority: medium +ms.prod: security +doc_type: apiPageType +--- + +# analyzedEmail: remediate + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Remove a potential threat from end users' mailboxes. + +Remediation means to take prescribed action against a threat. This API can trigger email purge actions like move to junk, move to deleted items, soft delete, hard delete, or move to Inbox. This API enables scenarios and use cases such as SOAR integration, playbooks, and automations. For more information read [email remediation, trigger action and track actions](/microsoft-365/security/office-365-security/remediate-malicious-email-delivered-office-365?view=o365-worldwide&preserve-view=true). If there is false positives admins can take move to inbox action. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +[!INCLUDE [permissions-table](../includes/permissions/security-analyzedemail-remediate-permissions.md)] + +## HTTP request + + +``` http +POST /security/collaboration/analyzedEmails/remediate +``` + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).| +|Content-Type|application/json. Required.| + +## Request body + +In the request body, supply a JSON representation of the parameters. + +The following table lists the parameters that are required when you call this action. + +|Parameter|Type|Description| +|:---|:---|:---| +|displayName|String| The name of the remediation that is used as a reference in the action center. | +|description|String| The description of the remediation. | +|severity|microsoft.graph.security.remediationSeverity| The severity of the remediation. The possible values are: `low`, `medium`, `high`, `unknownFutureValue`.| +|action|microsoft.graph.security.remediationAction|The types of move and delete actions that are supported. The possible values are: `moveToJunk`, `moveToInbox`, `hardDelete`, `softDelete`, `moveToDeletedItems`, `unknownFutureValue`.| +|approverUpn|String| Tracks who approved the action. | +|remediateSendersCopy|Boolean| For internal or outbound email, indicates whether to remediate the sender's copy of an email. | +|analyzedEmails|[microsoft.graph.security.analyzedEmail](../resources/security-analyzedemail.md) collection|The unique ID of the analyzed email. The ID can be found from the analyzedemails, analyzedemails/Id or runHuntingQuery/reportId. + +## Response + +If successful, this action returns a `202 Accepted` response code and a `Location` header with a link to the tracking information. + +>**Note:** The response to the action can be tracked in https://security.microsoft.com/action-center/history. To learn more, see [Use the Action center](/microsoft-365/security/defender/m365d-action-center?view=o365-worldwide&preserve-view=true). + +## Examples + +### Request + +The following example shows a request. + +``` http +POST https://graph.microsoft.com/beta/security/collaboration/analyzedEmails/remediate +Content-Type: application/json + +{ + "displayName": "Clean up Phish email", + "description": "Delete email", + "severity": "medium", + "action": "softDelete", + "remediateSendersCopy": "false", + "analyzedEmails": [ + { + "id": "73ca4154-58d8-43d0-a890-08dc18c52e6d-1311265001240363512-1" + }, + { + "id": "73ca4154-58d8-43d0-a890-08dc18c52e6d-13805748846361900678-1" + } + ] +} +``` + + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 202 Accepted +Location: https://security.microsoft.com/action-center/history?filters={"bulkId":["{bulkId}"]}&tid={tid} +Content-Type: application/json;text/plain +Content-Length: 0 +``` + + + + diff --git a/api-reference/beta/api/security-collaborationroot-list-analyzedemails.md b/api-reference/beta/api/security-collaborationroot-list-analyzedemails.md new file mode 100644 index 00000000000..3ac8f7b4456 --- /dev/null +++ b/api-reference/beta/api/security-collaborationroot-list-analyzedemails.md @@ -0,0 +1,175 @@ +--- +title: "List analyzedEmails " +description: "Get a list of analyzedEmail objects and their properties." +author: "ajaj-shaikh" +ms.localizationpriority: medium +ms.prod: "security" +doc_type: apiPageType +--- + +# List analyzedEmails + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Get a list of [analyzedEmail](../resources/security-analyzedemail.md) objects and their properties. + +This API allows Security Operations teams to have direct access to hunt (query) for threats, IOCs, attack vectors, and evidences for a tenant. It is a powerful, near real-time tool to help Security Operations teams investigate and respond to threats. It consists of email metadata, verdict information, related underlying entities (attachments/URL), filters, and more. + +## Permissions + +Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference). + + +[!INCLUDE [permissions-table](../includes/permissions/security-collaborationroot-list-analyzedemails-permissions.md)] + +## HTTP request + + +``` http +GET /security/collaboration/analyzedEmails +``` + +## Query parameters + +In the request URL, provide the following required query parameters with values. + +|Parameter|Type|Description +|:---|:---|:---| +|startTime|DateTime|The start time of the email search. | +|endTime|DateTime|The end time of the email search. | + +### OData query parameters + +This method supports the following OData query parameters to help customize the response: `$count`, `$filter`, `$skip`, `$top`. For general information, see [OData query parameters](/graph/query-parameters). + +The following example shows how to use the `$filter` parameter to customize the response. + +``` http +GET /security/collaboration/analyzedemails?startTime=2024-02-18&endTime=2024-02-20&filter=NetworkMessageId eq 'bde1f764-bbf4-5673-fbba-0asdhsgfhf1' +``` + +## Request headers + +|Name|Description| +|:---|:---| +|Authorization|Bearer {token}. Required.| + +## Request body + +Don't supply a request body for this method. + +## Response + +If successful, this method returns a `200 OK` response code and a collection of [microsoft.graph.security.analyzedEmail](../resources/security-analyzedemail.md) objects in the response body. + +## Examples + +### Request + +The following example shows a request. + +``` http +GET https:security/collaboration/analyzedemails?startTime=2024-02-18&endTime=2024-02-20 +``` + + +### Response + +The following example shows the response. +>**Note:** The response object shown here might be shortened for readability. + +``` http +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "value": [ + { + "@odata.type": "#microsoft.graph.security.analyzedEmail", + "id": "3570a93a-82b1-ffb9-8c26-a9a2ca002a17", + "loggedDateTime": "String (timestamp)", + "networkMessageId": "String", + "internetMessageId": "String", + "senderDetail": { + "@odata.type": "microsoft.graph.security.analyzedEmailSenderDetail" + }, + "recipientEmailAddresses": [ + "String" + ], + "distributionList": "String", + "subject": "String", + "returnPath": "String", + "directionality": "String", + "originalDelivery": { + "@odata.type": "microsoft.graph.security.analyzedEmailDeliveryDetail" + }, + "latestDelivery": { + "@odata.type": "microsoft.graph.security.analyzedEmailDeliveryDetail" + }, + "attachmentsCount": "Integer", + "attachments": [ + { + "@odata.type": "microsoft.graph.security.analyzedEmailAttachment" + } + ], + "urlsCount": "Integer", + "urls": [ + { + "@odata.type": "microsoft.graph.security.analyzedEmailUrl" + } + ], + "language": "String", + "sizeInBytes": "Integer", + "alertIds": [ + "String" + ], + "exchangeTransportRules": [ + { + "@odata.type": "microsoft.graph.security.analyzedEmailExchangeTransportRuleInfo" + } + ], + "overrideSources": [ + "String" + ], + "threatType": "String", + "detectionMethods": [ + "String" + ], + "contexts": [ + "String" + ], + "authenticationDetails": { + "@odata.type": "microsoft.graph.security.analyzedEmailAuthenticationDetail" + }, + "phishConfidenceLevel": "String", + "spamConfidenceLevel": "String", + "bulkComplaintLevel": "String", + "emailClusterId": "String", + "policyAction": "String", + "policy": "String" + } + ] +} +``` + diff --git a/api-reference/beta/includes/permissions/partners-billing-billedreconciliation-export-permissions.md b/api-reference/beta/includes/permissions/partners-billing-billedreconciliation-export-permissions.md new file mode 100644 index 00000000000..a4c48b3ccf6 --- /dev/null +++ b/api-reference/beta/includes/permissions/partners-billing-billedreconciliation-export-permissions.md @@ -0,0 +1,12 @@ +--- +description: "Automatically generated file. DO NOT MODIFY" +ms.topic: include +ms.localizationpriority: medium +--- + +|Permission type|Least privileged permissions|Higher privileged permissions| +|:---|:---|:---| +|Delegated (work or school account)|PartnerBilling.Read.All|Not available.| +|Delegated (personal Microsoft account)|Not supported.|Not supported.| +|Application|PartnerBilling.Read.All|Not available.| + diff --git a/api-reference/beta/includes/permissions/partners-billing-billedusage-export-permissions.md b/api-reference/beta/includes/permissions/partners-billing-billedusage-export-permissions.md new file mode 100644 index 00000000000..a4c48b3ccf6 --- /dev/null +++ b/api-reference/beta/includes/permissions/partners-billing-billedusage-export-permissions.md @@ -0,0 +1,12 @@ +--- +description: "Automatically generated file. DO NOT MODIFY" +ms.topic: include +ms.localizationpriority: medium +--- + +|Permission type|Least privileged permissions|Higher privileged permissions| +|:---|:---|:---| +|Delegated (work or school account)|PartnerBilling.Read.All|Not available.| +|Delegated (personal Microsoft account)|Not supported.|Not supported.| +|Application|PartnerBilling.Read.All|Not available.| + diff --git a/api-reference/beta/includes/permissions/security-analyzedemail-get-permissions.md b/api-reference/beta/includes/permissions/security-analyzedemail-get-permissions.md new file mode 100644 index 00000000000..d1f79000b19 --- /dev/null +++ b/api-reference/beta/includes/permissions/security-analyzedemail-get-permissions.md @@ -0,0 +1,13 @@ +--- +description: Automatically generated file. DO NOT MODIFY +ms.topic: include +ms.localizationpriority: medium +--- + +|Permission type|Least privileged permissions|Higher privileged permissions| +|:---|:---|:---| +|Delegated (work or school account)|Not supported.|Not supported.| +|Delegated (personal Microsoft account)|Not supported.|Not supported.| +|Application|SecurityAnalyzedMessage.Read.All|SecurityAnalyzedMessage.ReadWrite.All| + + diff --git a/api-reference/beta/includes/permissions/security-analyzedemail-remediate-permissions.md b/api-reference/beta/includes/permissions/security-analyzedemail-remediate-permissions.md new file mode 100644 index 00000000000..3a743312bfe --- /dev/null +++ b/api-reference/beta/includes/permissions/security-analyzedemail-remediate-permissions.md @@ -0,0 +1,13 @@ +--- +description: Automatically generated file. DO NOT MODIFY +ms.topic: include +ms.localizationpriority: medium +--- + +|Permission type|Least privileged permissions|Higher privileged permissions| +|:---|:---|:---| +|Delegated (work or school account)|Not supported.|Not supported.| +|Delegated (personal Microsoft account)|Not supported.|Not supported.| +|Application|SecurityAnalyzedMessage.ReadWrite.All|Not available.| + + diff --git a/api-reference/beta/includes/permissions/security-collaborationroot-list-analyzedemails-permissions.md b/api-reference/beta/includes/permissions/security-collaborationroot-list-analyzedemails-permissions.md new file mode 100644 index 00000000000..d1f79000b19 --- /dev/null +++ b/api-reference/beta/includes/permissions/security-collaborationroot-list-analyzedemails-permissions.md @@ -0,0 +1,13 @@ +--- +description: Automatically generated file. DO NOT MODIFY +ms.topic: include +ms.localizationpriority: medium +--- + +|Permission type|Least privileged permissions|Higher privileged permissions| +|:---|:---|:---| +|Delegated (work or school account)|Not supported.|Not supported.| +|Delegated (personal Microsoft account)|Not supported.|Not supported.| +|Application|SecurityAnalyzedMessage.Read.All|SecurityAnalyzedMessage.ReadWrite.All| + + diff --git a/api-reference/beta/resources/authenticationmethodconfiguration.md b/api-reference/beta/resources/authenticationmethodconfiguration.md index b6741507673..c0c3beb11fe 100644 --- a/api-reference/beta/resources/authenticationmethodconfiguration.md +++ b/api-reference/beta/resources/authenticationmethodconfiguration.md @@ -22,7 +22,7 @@ The following authentication methods are derived from the **authenticationMethod + [microsoftAuthenticatorAuthenticationMethodConfiguration](microsoftauthenticatorauthenticationmethodconfiguration.md) + [smsAuthenticationMethodConfiguration](smsauthenticationmethodconfiguration.md) + [softwareOathAuthenticationMethodConfiguration](softwareoathauthenticationmethodconfiguration.md) -+ [temporaryAccessPassAuthenticationMethodConfiguration](smsauthenticationmethodconfiguration.md) ++ [temporaryAccessPassAuthenticationMethodConfiguration](temporaryaccesspassauthenticationmethodconfiguration.md) + [voiceAuthenticationMethodConfiguration](voiceauthenticationmethodconfiguration.md) + [x509CertificateAuthenticationMethodConfiguration](x509certificateauthenticationmethodconfiguration.md) diff --git a/api-reference/beta/resources/security-analyzedemail.md b/api-reference/beta/resources/security-analyzedemail.md new file mode 100644 index 00000000000..d7afa851a38 --- /dev/null +++ b/api-reference/beta/resources/security-analyzedemail.md @@ -0,0 +1,179 @@ +--- +title: "analyzedEmail resource type" +description: Contains metadata for email messages that are analyzed for security threats. +author: "ajaj-shaikh" +ms.localizationpriority: medium +ms.prod: "security" +doc_type: resourcePageType +--- + +# analyzedEmail resource type + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Contains metadata for email messages that are analyzed for security threats. + +## Methods +|Method|Return type|Description| +|:---|:---|:---| +|[List analyzedEmail objects](../api/security-collaborationroot-list-analyzedemails.md)|[microsoft.graph.security.analyzedEmail](../resources/security-analyzedemail.md) collection|Get a list of [analyzedEmail](../resources/security-analyzedemail.md) objects and their properties.| +|[Get analyzedEmail](../api/security-analyzedemail-get.md)|[microsoft.graph.security.analyzedEmail](../resources/security-analyzedemail.md)|Read the properties and relationships of an [analyzedEmail](../resources/security-analyzedemail.md) object.| +|[remediate](../api/security-analyzedemail-remediate.md)|None|Remove a potential threat from end users' mailboxes.| + +## Properties +|Property|Type|Description| +|:---|:---|:---| +|alertIds|String collection| A collection of values that contain the IDs of any alerts associated with the email. | +|attachments|[microsoft.graph.security.analyzedEmailAttachment](../resources/security-analyzedemailattachment.md) collection|A collection of the attachments in the email.| +|attachmentsCount|Int32|The number of attachments in the email.| +|authenticationDetails|[microsoft.graph.security.analyzedEmailAuthenticationDetail](../resources/security-analyzedemailauthenticationdetail.md)| The authentication details associated with the email.| +|bulkComplaintLevel|String|The bulk complaint level of the email. A higher level is more likely to be spam.| +|contexts|String collection|Provides context of the email. | +|detectionMethods|String collection|The methods of detection used.| +|directionality|[microsoft.graph.security.antispamDirectionality](#antispamdirectionality-values)|The direction of the emails. The possible values are: `unknown`, `inbound`, `outbound`, `intraOrg`, `unknownFutureValue`.| +|distributionList|String|The distribution list details to which the email was sent.| +|emailClusterId|String|The identifier for the group of similar emails clustered based on heuristic analysis of their content.| +|exchangeTransportRules|[microsoft.graph.security.analyzedEmailExchangeTransportRuleInfo](../resources/security-analyzedemailexchangetransportruleinfo.md) collection|The name of the Exchange transport rules (ETRs) associated with the email.| +|id|String|The ID of an analyzed email.| +|internetMessageId|String|A public-facing identifier for the email that is sent. The message ID is in the format specified by [RFC2822](https://www.rfc-editor.org/rfc/rfc2822).| +|language|String|The detected language of the email content.| +|latestDelivery|[microsoft.graph.security.analyzedEmailDeliveryDetail](../resources/security-analyzedemaildeliverydetail.md)|The latest delivery details of the email.| +|loggedDateTime|DateTimeOffset|Date-time when the email record was logged.| +|networkMessageId|String|An internal identifier for the email generated by Microsoft 365.| +|originalDelivery|[microsoft.graph.security.analyzedEmailDeliveryDetail](../resources/security-analyzedemaildeliverydetail.md)|The original delivery details of the email.| +|overrideSources|String collection|An aggregated list of all overrides with source on email.| +|phishConfidenceLevel|String|The phish confidence level associated with the email| +|policy|String|The action policy that took effect.| +|policyAction|String|The action taken on the email based on the configured policy.| +|recipientEmailAddresses|String collection|Contains the email addresses of the recipients.| +|returnPath|String|A field that indicates where and how bounced emails are processed.| +|senderDetail|[microsoft.graph.security.analyzedEmailSenderDetail](../resources/security-analyzedemailsenderdetail.md)|Sender details of the email.| +|sizeInBytes|Int32| Size of the email in bytes.| +|spamConfidenceLevel|String|Spam confidence of the email.| +|subject|String|Subject of the email.| +|threatType|[microsoft.graph.security.threatType](#threattype-values)|Indicates the threat types. The possible values are: `unknown`, `spam`, `malware`, `phishing`, `none`, `unknownFutureValue`.| +|urls|[microsoft.graph.security.analyzedEmailUrl](../resources/security-analyzedemailurl.md) collection|A collection of the URLs in the email.| +|urlsCount|Int32|The number of URLs in the email.| + +### antispamDirectionality values + +|Member| +|:---| +|unknown| +|inbound| +|outbound| +|intraOrg| +|unknownFutureValue| + +### threatType values + +|Member| +|:---| +|unknown| +|spam| +|malware| +|phishing| +|none| +|unknownFutureValue| + +### remediationSeverity values + +|Member| +|:---| +|low| +|medium| +|high| +|unknownFutureValue| + +### remediationAction values + +|Member| +|:---| +|moveToJunk| +|moveToInbox| +|hardDelete| +|softDelete| +|moveToDeletedItems| +|unknownFutureValue| + +## Relationships +None. + +## JSON representation +The following JSON representation shows the resource type. + +``` json +{ + "@odata.type": "#microsoft.graph.security.analyzedEmail", + "id": "String (identifier)", + "loggedDateTime": "String (timestamp)", + "networkMessageId": "String", + "internetMessageId": "String", + "senderDetail": { + "@odata.type": "microsoft.graph.security.analyzedEmailSenderDetail" + }, + "recipientEmailAddresses": [ + "String" + ], + "distributionList": "String", + "subject": "String", + "returnPath": "String", + "directionality": "String", + "originalDelivery": { + "@odata.type": "microsoft.graph.security.analyzedEmailDeliveryDetail" + }, + "latestDelivery": { + "@odata.type": "microsoft.graph.security.analyzedEmailDeliveryDetail" + }, + "attachmentsCount": "Integer", + "attachments": [ + { + "@odata.type": "microsoft.graph.security.analyzedEmailAttachment" + } + ], + "urlsCount": "Integer", + "urls": [ + { + "@odata.type": "microsoft.graph.security.analyzedEmailUrl" + } + ], + "language": "String", + "sizeInBytes": "Integer", + "alertIds": [ + "String" + ], + "exchangeTransportRules": [ + { + "@odata.type": "microsoft.graph.security.analyzedEmailExchangeTransportRuleInfo" + } + ], + "overrideSources": [ + "String" + ], + "threatType": "String", + "detectionMethods": [ + "String" + ], + "contexts": [ + "String" + ], + "authenticationDetails": { + "@odata.type": "microsoft.graph.security.analyzedEmailAuthenticationDetail" + }, + "phishConfidenceLevel": "String", + "spamConfidenceLevel": "String", + "bulkComplaintLevel": "String", + "emailClusterId": "String", + "policyAction": "String", + "policy": "String" +} +``` + diff --git a/api-reference/beta/resources/security-analyzedemailattachment.md b/api-reference/beta/resources/security-analyzedemailattachment.md new file mode 100644 index 00000000000..631bce80132 --- /dev/null +++ b/api-reference/beta/resources/security-analyzedemailattachment.md @@ -0,0 +1,51 @@ +--- +title: "analyzedEmailAttachment resource type" +description: Represents an attachment to an analyzed email. +author: MishraSoumyaMS +ms.localizationpriority: medium +ms.prod: security +doc_type: resourcePageType +--- + +# analyzedEmailAttachment resource type + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Represents an attachment to an analyzed email. + +## Properties +|Property|Type|Description| +|:---|:---|:---| +|detonationDetails|[microsoft.graph.security.detonationDetails](../resources/security-detonationdetails.md)|The detonation details of the attachment.| +|fileName|String|The name of the attachment in the email.| +|fileType|String|The type of the attachment in the email.| +|sha256|String|The SHA256 file hash of the attachment.| +|threatName|String|The threat name associated with the threat type.| +|threatType|microsoft.graph.security.threatType|The threat type associated with the attachment. The possible values are: `unknown`, `spam`, `malware`, `phishing`, `none`, `unknownFutureValue`.| + +## Relationships +None. + +## JSON representation +The following JSON representation shows the resource type. + +``` json +{ + "@odata.type": "#microsoft.graph.security.analyzedEmailAttachment", + "fileName": "String", + "fileType": "String", + "threatType": "String", + "threatName": "String", + "sha256": "String", + "detonationDetails": { + "@odata.type": "microsoft.graph.security.detonationDetails" + } +} +``` + diff --git a/api-reference/beta/resources/security-analyzedemailauthenticationdetail.md b/api-reference/beta/resources/security-analyzedemailauthenticationdetail.md new file mode 100644 index 00000000000..0fde9f16c8b --- /dev/null +++ b/api-reference/beta/resources/security-analyzedemailauthenticationdetail.md @@ -0,0 +1,46 @@ +--- +title: "analyzedEmailAuthenticationDetail resource type" +description: Represents a list of pass or fail verdicts by email authentication protocols. +author: MishraSoumyaMS +ms.localizationpriority: medium +ms.prod: security +doc_type: resourcePageType +--- + +# analyzedEmailAuthenticationDetail resource type + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Represents a list of pass or fail verdicts by email authentication protocols such as DMARC, DKIM, SPF, or a combination of multiple authentication types (CompAuth). + + +## Properties +|Property|Type|Description| +|:---|:---|:---| +|compositeAuthentication|String|A value used by Microsoft 365 to combine email authentication such as SPF, DKIM, and DMARC, to determine whether the message is authentic.| +|dkim|String|DomainKeys identified mail (DKIM). Indicates whether it was pass/fail/soft fail.| +|dmarc|String|Domain-based Message Authentication. Indicates whether it was pass/fail/soft fail.| +|senderPolicyFramework|String|Sender Policy Framework (SPF). Indicates whether it was pass/fail/soft fail.| + +## Relationships +None. + +## JSON representation +The following JSON representation shows the resource type. + +``` json +{ + "@odata.type": "#microsoft.graph.security.analyzedEmailAuthenticationDetail", + "dmarc": "String", + "dkim": "String", + "senderPolicyFramework": "String", + "compositeAuthentication": "String" +} +``` + diff --git a/api-reference/beta/resources/security-analyzedemaildeliverydetail.md b/api-reference/beta/resources/security-analyzedemaildeliverydetail.md new file mode 100644 index 00000000000..8001adb3a91 --- /dev/null +++ b/api-reference/beta/resources/security-analyzedemaildeliverydetail.md @@ -0,0 +1,67 @@ +--- +title: "analyzedEmailDeliveryDetail resource type" +description: Represnts the delivery action and location of an analyzed email. +author: MishraSoumyaMS +ms.localizationpriority: medium +ms.prod: security +doc_type: resourcePageType +--- + +# analyzedEmailDeliveryDetail resource type + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Represnts the delivery action and location of an [analzed email](security-analyzedemail.md). + +## Properties +|Property|Type|Description| +|:---|:---|:---| +|action|[microsoft.graph.security.deliveryAction](#deliveryaction-values)|The delivery action of the email. The possible values are: `unknown`, `deliveredToJunk`, `delivered`, `blocked`, `replaced`, `unknownFutureValue`.| +|location|[microsoft.graph.security.deliveryLocation](#deliverylocation-values)|The delivery location of the email. The possible values are: `unknown`, `inbox_folder`, `junkFolder`, `deletedFolder`, `quarantine`, `onprem_external`, `failed`, `dropped`, `others`, `unknownFutureValue`.| + +### deliveryAction values + +|Member| +|:---| +|unknown| +|deliveredToJunk| +|delivered| +|blocked| +|replaced| +|unknownFutureValue| + +### deliveryLocation values + +|Member| +|:---| +|unknown| +|inbox_folder| +|junkFolder| +|deletedFolder| +|quarantine| +|onprem_external| +|failed| +|dropped| +|others| +|unknownFutureValue| + +## Relationships +None. + +## JSON representation +The following JSON representation shows the resource type. + +``` json +{ + "@odata.type": "#microsoft.graph.security.analyzedEmailDeliveryDetail", + "action": "String", + "location": "String" +} +``` + diff --git a/api-reference/beta/resources/security-analyzedemailexchangetransportruleinfo.md b/api-reference/beta/resources/security-analyzedemailexchangetransportruleinfo.md new file mode 100644 index 00000000000..7643ff4c7ce --- /dev/null +++ b/api-reference/beta/resources/security-analyzedemailexchangetransportruleinfo.md @@ -0,0 +1,41 @@ +--- +title: "analyzedEmailExchangeTransportRuleInfo resource type" +description: Represents mail flow rules in Exchange Online. +author: MishraSoumyaMS +ms.localizationpriority: medium +ms.prod: security +doc_type: resourcePageType +--- + +# analyzedEmailExchangeTransportRuleInfo resource type + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Represents mail flow rules in Exchange Online. + +## Properties +|Property|Type|Description| +|:---|:---|:---| +|name|String|Name of the Exchange transport rules (ETRs) that are part of the email.| +|ruleId|String|The ETR rule ID.| + +## Relationships +None. + +## JSON representation +The following JSON representation shows the resource type. + +``` json +{ + "@odata.type": "#microsoft.graph.security.analyzedEmailExchangeTransportRuleInfo", + "ruleId": "String", + "name": "String" +} +``` + diff --git a/api-reference/beta/resources/security-analyzedemailsenderdetail.md b/api-reference/beta/resources/security-analyzedemailsenderdetail.md new file mode 100644 index 00000000000..ba13e5b2d1e --- /dev/null +++ b/api-reference/beta/resources/security-analyzedemailsenderdetail.md @@ -0,0 +1,43 @@ +--- +title: "analyzedEmailSenderDetail resource type" +description: Represents the sender details of an email. +author: MishraSoumyaMS +ms.localizationpriority: medium +ms.prod: security +doc_type: resourcePageType +--- + +# analyzedEmailSenderDetail resource type + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Represents the sender details of an email. + +## Properties +|Property|Type|Description| +|:---|:---|:---| +|fromAddress|String|The sender email address in the mail **From** header, also known as the envelope sender or the P1 sender. | +|ipv4|String|The IPv4 address of the last detected mail server that relayed the message. | +|mailFromAddress|String|The sender email address in the **From** header, which is visible to email recipients on their email clients. Also known as P2 sender.| + +## Relationships +None. + +## JSON representation +The following JSON representation shows the resource type. + +``` json +{ + "@odata.type": "#microsoft.graph.security.analyzedEmailSenderDetail", + "mailFromAddress": "String", + "fromAddress": "String", + "ipv4": "String" +} +``` + diff --git a/api-reference/beta/resources/security-analyzedemailurl.md b/api-reference/beta/resources/security-analyzedemailurl.md new file mode 100644 index 00000000000..0d71e0bf16a --- /dev/null +++ b/api-reference/beta/resources/security-analyzedemailurl.md @@ -0,0 +1,47 @@ +--- +title: "analyzedEmailUrl resource type" +description: "Represents information about URLs found in an analyzed email." +author: "MishraSoumyaMS" +ms.localizationpriority: medium +ms.prod: security +doc_type: resourcePageType +--- + +# analyzedEmailUrl resource type + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Represents information about URLs found in an [analyzed email](security-analyzedemail.md). + +## Properties +|Property|Type|Description| +|:---|:---|:---| +|detectionMethod|String|The method used to detect threats in the URL.| +|detonationDetails|[microsoft.graph.security.detonationDetails](../resources/security-detonationdetails.md)|Detonation data associated with the URL.| +|threatType|microsoft.graph.security.threatType|The type of threat associated with the URL. The possible values are: `unknown`, `spam`, `malware`, `phishing`, `none`, `unknownFutureValue`.| +|url|String|The URL that is found in the email. This is full URL string, including query parameters.| + +## Relationships +None. + +## JSON representation +The following JSON representation shows the resource type. + +``` json +{ + "@odata.type": "#microsoft.graph.security.analyzedEmailUrl", + "url": "String", + "threatType": "String", + "detectionMethod": "String", + "detonationDetails": { + "@odata.type": "microsoft.graph.security.detonationDetails" + } +} +``` + diff --git a/api-reference/beta/resources/security-api-overview.md b/api-reference/beta/resources/security-api-overview.md index 5176caa679a..516f884340c 100644 --- a/api-reference/beta/resources/security-api-overview.md +++ b/api-reference/beta/resources/security-api-overview.md @@ -32,7 +32,7 @@ Take immediate action to defend against threats using the [securityAction](secur ## Advanced hunting Advanced hunting is a query-based threat-hunting tool that lets you explore up to 30 days of raw data. You can proactively inspect events in your network to locate threat indicators and entities. The flexible access to data enables unconstrained hunting for both known and potential threats. -Use [runHuntingQuery](../api/security-security-runhuntingquery.md) to run a [Kusto Query Language](/azure/data-explorer/kusto/query/) (KQL) query on data stored in Microsoft 365 Defender. Leverage the returned result set to enrich an existing investigation or uncover undetected threats in your network. +Use [runHuntingQuery](../api/security-security-runhuntingquery.md) to run a [Kusto Query Language](/azure/data-explorer/kusto/query/) (KQL) query on data stored in Microsoft 365 Defender. Leverage the returned result set to enrich an existing investigation or uncover undetected threats in your network. ### Quotas and resource allocation @@ -178,6 +178,12 @@ The Microsoft Graph threat submission API helps organizations to submit a threat > **Note:** We recommend that you use this API instead of the deprecated Information Protection threat assessment API. The threat submission API provides unified security threat submission functionality and adds unified result support, user submission query support, tenant allow block list support, admin review support and app-only mode support. +## Email and collaboration protection (preview) + +[Microsoft Defender for Office 365](/microsoft-365/security/office-365-security/defender-for-office-365?view=o365-worldwide&preserve-view=true) is a cloud-based email filtering service that helps protect your organization against advanced threats to email and collaboration tools, like phishing, business email compromise, and malware attacks. You can use the Microsoft Graph **analyzedemails** and **remediate** APIs to retrieve email metadata and perform response actions (soft delete, hard delete, move to junk, move to Inbox) on analyzed messages. + +> **Note:** These APIs are only availbe for Defender for Office 365 Plan 2 or Microsoft 365 A5/E5/F5/G5 Security service plans. For the most up-to-date list of service plans, see [Microsoft Defender for Office 365 service description](/office365/servicedescriptions/office-365-advanced-threat-protection-service-description). + ## Common use cases The following are some of the most popular requests for working with the Microsoft Graph security API. @@ -233,6 +239,11 @@ The following are some of the most popular requests for working with the Microso |Create email threat submission policy|[Create emailThreatSubmissionPolicy](../api/security-emailthreatsubmission-post-emailthreats.md)|[https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies](https://developer.microsoft.com/graph/graph-explorer?request=/security/threatSubmission/emailThreats&method=POST&version=beta&GraphUrl=https://graph.microsoft.com)| |Update email threat submission policy|[Update emailThreatSubmissionPolicy](../api/security-emailthreatsubmission-post-emailthreats.md)|[https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies/{id}](https://developer.microsoft.com/graph/graph-explorer?request=security/security/threatSubmission/emailThreatSubmissionPolicies/{id}&method=PATCH&version=beta&GraphUrl=https://graph.microsoft.com)| |Delete email threat submission policy|[Delete emailThreatSubmissionPolicy](../api/security-emailthreatsubmissionpolicy-delete.md)|[https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies/{id}](https://developer.microsoft.com/graph/graph-explorer?request=security/threatSubmission/emailThreatSubmissionPolicies/{id}&method=DELETE&version=beta&GraphUrl=https://graph.microsoft.com)| +|Delete email threat submission policy|[Delete emailThreatSubmissionPolicy](../api/security-emailthreatsubmissionpolicy-delete.md)|[https://graph.microsoft.com/beta/security/threatSubmission/emailThreatSubmissionPolicies/{id}](https://developer.microsoft.com/graph/graph-explorer?request=security/threatSubmission/emailThreatSubmissionPolicies/{id}&method=DELETE&version=beta&GraphUrl=https://graph.microsoft.com)| +| **Email analysis and remediation**||| +|Query email metadata|[LIST analyzedemails](../api/security-collaborationroot-list-analyzedemails.md)|[https://graph.microsoft.com/beta/security/collaboration/analyzedemails?startTime={startTime}&endTime={endTime}](https://developer.microsoft.com/graph/graph-explorer?request=security/collaboration/analyzedemails?startTime={startTime}&endTime={endTime}&method=GET&version=beta&GraphUrl=https://graph.microsoft.com)| +|Get details of a single message instance|[GET analyzedemails/Id](../api/security-analyzedemail-get.md)|[https://graph.microsoft.com/beta/security/collaboration/analyzedemails/{Id}](https://developer.microsoft.com/graph/graph-explorer?request=security/collaboration/analyzedemails/Id&method=GET&version=beta&GraphUrl=https://graph.microsoft.com)| +|Remediate analyzed email|[analyzedEmai: remediate](../api/security-analyzedemail-remediate.md )|[https://graph.microsoft.com/beta/security/collaboration/analyzedemails/remediate](https://developer.microsoft.com/graph/graph-explorer?request=security/collaboration/analyzedemails/remediate&method=POST&version=beta&GraphUrl=https://graph.microsoft.com)| You can use Microsoft Graph [webhooks](/graph/webhooks) to subscribe to and receive notifications about updates to Microsoft Graph security API entities. diff --git a/api-reference/beta/resources/security-collaborationroot.md b/api-reference/beta/resources/security-collaborationroot.md new file mode 100644 index 00000000000..d0e721f269e --- /dev/null +++ b/api-reference/beta/resources/security-collaborationroot.md @@ -0,0 +1,47 @@ +--- +title: "collaborationRoot resource type" +description: "An abstract type that enables read and other actions on collaborative entities in Microsoft Defender." +author: "MishraSoumyaMS" +ms.localizationpriority: medium +ms.prod: "security" +doc_type: resourcePageType +--- + +# collaborationRoot resource type + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +An abstract type that enables read and other actions on collaborative entities in Microsoft Defender. + +## Methods +|Method|Return type|Description| +|:---|:---|:---| +| **Analyzed email** | +|[List analyzedEmails](../api/security-collaborationroot-list-analyzedemails.md)|[microsoft.graph.security.analyzedEmail](../resources/security-analyzedemail.md) collection|Get a list of [analyzedEmail](../resources/security-analyzedemail.md) objects and their properties.| +|[Get analyzedEmail](../api/security-analyzedemail-get.md)|[microsoft.graph.security.analyzedEmail](../resources/security-analyzedemail.md)|Read the properties and relationships of an [analyzedEmail](../resources/security-analyzedemail.md) object.| +|[Remediate analyzedEmail](../api/security-analyzedemail-remediate.md)|[microsoft.graph.security.analyzedEmail](../resources/security-analyzedemail.md)|Remove a potential threat from end users' mailboxes.| + +## Properties +None. +## Relationships +|Relationship|Type|Description| +|:---|:---|:---| +|analyzedEmails|[microsoft.graph.security.analyzedEmail](../resources/security-analyzedemail.md) collection|Contains metadata for analyzed emails.| + +## JSON representation +The following JSON representation shows the resource type. + +``` json +{ + "@odata.type": "#microsoft.graph.security.collaborationRoot" +} +``` + diff --git a/api-reference/beta/resources/security-detonationchain.md b/api-reference/beta/resources/security-detonationchain.md new file mode 100644 index 00000000000..45413ea503d --- /dev/null +++ b/api-reference/beta/resources/security-detonationchain.md @@ -0,0 +1,45 @@ +--- +title: "detonationChain resource type" +description: Represents a detonation chain in Microsoft Defender for Office 365. +author: MishraSoumyaMS +ms.localizationpriority: medium +ms.prod: security +doc_type: resourcePageType +--- + +# detonationChain resource type + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Represents a detonation chain in Microsoft Defender for Office 365. A single file or URL detonation can trigger multiple detonations. The detonation chain tracks the path of detonations, including the original malicious file or URL that caused the verdict, and all other files or URLs that are affected by the detonation. These URLs or attached files might not be directly present in the email, but including that analysis is important in order to determine why the file or URL was found to be malicious. + +## Properties +|Property|Type|Description| +|:---|:---|:---| +|childNodes|[microsoft.graph.security.detonationChain](../resources/security-detonationchain.md) collection|A list of all child nodes in the chain.| +|value|String|The value of the chain.| + +## Relationships +None. + +## JSON representation +The following JSON representation shows the resource type. + +``` json +{ + "@odata.type": "#microsoft.graph.security.detonationChain", + "value": "String", + "childNodes": [ + { + "@odata.type": "microsoft.graph.security.detonationChain" + } + ] +} +``` + diff --git a/api-reference/beta/resources/security-detonationdetails.md b/api-reference/beta/resources/security-detonationdetails.md new file mode 100644 index 00000000000..5f9e3bc3050 --- /dev/null +++ b/api-reference/beta/resources/security-detonationdetails.md @@ -0,0 +1,51 @@ +--- +title: "detonationDetails resource type" +description: Represents detonation details specific to email attachments and URLs. +author: MishraSoumyaMS +ms.localizationpriority: medium +ms.prod: security +doc_type: resourcePageType +--- + +# detonationDetails resource type + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Represents detonation details specific to email attachments and URLs. These details include the detonation chain, detonation summary, and observed behavior details to help customers understand the reason the attachment or URL is deemed malicious and detonated. + +## Properties +|Property|Type|Description| +|:---|:---|:---| +|analysisDateTime|DateTimeOffset|The time of detonation.| +|detonationChain|[microsoft.graph.security.detonationChain](../resources/security-detonationchain.md)|The chain of detonation.| +|detonationObservables|[microsoft.graph.security.detonationObservables](../resources/security-detonationobservables.md)|All observables in the detonation tree.| +|detonationVerdict|String|The verdict of the detonation.| +|detonationVerdictReason|String|The reason for the verdict of the detonation.| + +## Relationships +None. + +## JSON representation +The following JSON representation shows the resource type. + +``` json +{ + "@odata.type": "#microsoft.graph.security.detonationDetails", + "analysisDateTime": "String (timestamp)", + "detonationVerdict": "String", + "detonationVerdictReason": "String", + "detonationChain": { + "@odata.type": "microsoft.graph.security.detonationChain" + }, + "detonationObservables": { + "@odata.type": "microsoft.graph.security.detonationObservables" + } +} +``` + diff --git a/api-reference/beta/resources/security-detonationobservables.md b/api-reference/beta/resources/security-detonationobservables.md new file mode 100644 index 00000000000..c68b1b6a16b --- /dev/null +++ b/api-reference/beta/resources/security-detonationobservables.md @@ -0,0 +1,49 @@ +--- +title: "detonationObservables resource type" +description: Represents detonation details. +author: malvika-balaraj +ms.localizationpriority: medium +ms.prod: security +doc_type: resourcePageType +--- + +# detonationObservables resource type + +Namespace: microsoft.graph.security + +[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)] + +Represents the resources that are included in a detonation, such as URLs, IPs, domains, and files that were found (and can either be problematic or benign). + +## Properties +|Property|Type|Description| +|:---|:---|:---| +|contactedIps|String collection|The list of all contacted IPs in the detonation.| +|contactedUrls|String collection|The list of all URLs found in the detonation.| +|droppedfiles|String collection|The list of all dropped files in the detonation.| + +## Relationships +None. + +## JSON representation +The following JSON representation shows the resource type. + +``` json +{ + "@odata.type": "#microsoft.graph.security.detonationObservables", + "droppedfiles": [ + "String" + ], + "contactedIps": [ + "String" + ], + "contactedUrls": [ + "String" + ] +} +``` + diff --git a/api-reference/beta/resources/security.md b/api-reference/beta/resources/security.md index 39d373bd30b..b19a31e6c4f 100644 --- a/api-reference/beta/resources/security.md +++ b/api-reference/beta/resources/security.md @@ -29,6 +29,7 @@ None. |alerts |[alert](../resources/alert.md) collection|Notifications for suspicious or potential security issues in a customer’s tenant.| |alerts_v2 | [microsoft.graph.security.alert](security-alert.md) collection | A collection of alerts in Microsoft 365 Defender.| |attackSimulation|[attackSimulationRoot](../resources/attacksimulationroot.md)|Provides tenants capability to launch a simulated and realistic phishing attack and learn from it.| +|collaboration|[microsoft.graph.security.collaborationRoot](../resources/security-collaborationroot.md)|Enables read and other actions on collaborative entities in Microsoft Defender.| |incidents | [microsoft.graph.security.incident](security-incident.md) collection | A collection of incidents in Microsoft 365 Defender, each of which is a set of correlated alerts and associated metadata that reflects the story of an attack.| |secureScores | [secureScore](securescores.md) collection | Measurements of tenants’ security posture to help protect them from threats. | |securityactions|[securityAction](../resources/securityaction.md) collection|Actions that respond to alerts to block malicious activities.| diff --git a/api-reference/beta/toc.yml b/api-reference/beta/toc.yml index 4c52fedb4b0..e181d2fa289 100644 --- a/api-reference/beta/toc.yml +++ b/api-reference/beta/toc.yml @@ -16917,6 +16917,17 @@ items: href: api/security-ediscoverycase-delete-tags.md - name: List tags as hierarchy href: api/security-ediscoveryreviewtag-ashierarchy.md + - name: Email and collaboration protection + items: + - name: Analyzed email (preview) + href: resources/security-analyzedemail.md + items: + - name: List + href: api/security-collaborationroot-list-analyzedemails.md + - name: Get + href: api/security-analyzedemail-get.md + - name: Remediate + href: api/security-analyzedemail-remediate.md - name: Information protection items: - name: Labels (deprecated) diff --git a/api-reference/docfx.json b/api-reference/docfx.json index 8690da833f8..bc48b169a36 100644 --- a/api-reference/docfx.json +++ b/api-reference/docfx.json @@ -221,9 +221,11 @@ "overwrite": [], "externalReference": [], "globalMetadata": { - "feedback_system": "GitHub", - "feedback_github_repo": "microsoftgraph/microsoft-graph-docs-contrib", + "feedback_system": "Standard", "feedback_product_url": "https://developer.microsoft.com/graph/support", + "feedback_help_link_url": "https://learn.microsoft.com/en-us/answers/tags/161/ms-graph", + "feedback_help_link_type": "get-help-at-qna", + "feedback_github_repo": "microsoftgraph/microsoft-graph-docs-contrib", "author": "MSGraphDocsVteam", "ms.author": "MSGraphDocsVteam", "ms.suite": "microsoft-graph", diff --git a/api-reference/v1.0/api/partners-billing-billedreconciliation-export.md b/api-reference/v1.0/api/partners-billing-billedreconciliation-export.md index 10a6623047c..9f81177aa6e 100644 --- a/api-reference/v1.0/api/partners-billing-billedreconciliation-export.md +++ b/api-reference/v1.0/api/partners-billing-billedreconciliation-export.md @@ -19,12 +19,8 @@ Export the billed invoice reconciliation data. One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). - -[!INCLUDE [permissions-table](../includes/permissions/partners-permissions.md)] + +[!INCLUDE [permissions-table](../includes/permissions/partners-billing-billedreconciliation-export-permissions.md)] ## HTTP request diff --git a/api-reference/v1.0/api/partners-billing-billedusage-export.md b/api-reference/v1.0/api/partners-billing-billedusage-export.md index 4c1569fafff..bf13866748a 100644 --- a/api-reference/v1.0/api/partners-billing-billedusage-export.md +++ b/api-reference/v1.0/api/partners-billing-billedusage-export.md @@ -21,12 +21,8 @@ Export the billed Azure usage data. One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Permissions](/graph/permissions-reference). - -[!INCLUDE [permissions-table](../includes/permissions/partners-permissions.md)] + +[!INCLUDE [permissions-table](../includes/permissions/partners-billing-billedusage-export-permissions.md)] ## HTTP request diff --git a/api-reference/v1.0/includes/permissions/partners-billing-billedreconciliation-export-permissions.md b/api-reference/v1.0/includes/permissions/partners-billing-billedreconciliation-export-permissions.md new file mode 100644 index 00000000000..a4c48b3ccf6 --- /dev/null +++ b/api-reference/v1.0/includes/permissions/partners-billing-billedreconciliation-export-permissions.md @@ -0,0 +1,12 @@ +--- +description: "Automatically generated file. DO NOT MODIFY" +ms.topic: include +ms.localizationpriority: medium +--- + +|Permission type|Least privileged permissions|Higher privileged permissions| +|:---|:---|:---| +|Delegated (work or school account)|PartnerBilling.Read.All|Not available.| +|Delegated (personal Microsoft account)|Not supported.|Not supported.| +|Application|PartnerBilling.Read.All|Not available.| + diff --git a/api-reference/v1.0/includes/permissions/partners-billing-billedusage-export-permissions.md b/api-reference/v1.0/includes/permissions/partners-billing-billedusage-export-permissions.md new file mode 100644 index 00000000000..a4c48b3ccf6 --- /dev/null +++ b/api-reference/v1.0/includes/permissions/partners-billing-billedusage-export-permissions.md @@ -0,0 +1,12 @@ +--- +description: "Automatically generated file. DO NOT MODIFY" +ms.topic: include +ms.localizationpriority: medium +--- + +|Permission type|Least privileged permissions|Higher privileged permissions| +|:---|:---|:---| +|Delegated (work or school account)|PartnerBilling.Read.All|Not available.| +|Delegated (personal Microsoft account)|Not supported.|Not supported.| +|Application|PartnerBilling.Read.All|Not available.| + diff --git a/api-reference/v1.0/resources/authenticationmethodconfiguration.md b/api-reference/v1.0/resources/authenticationmethodconfiguration.md index 2c7938d918c..0a336b20b95 100644 --- a/api-reference/v1.0/resources/authenticationmethodconfiguration.md +++ b/api-reference/v1.0/resources/authenticationmethodconfiguration.md @@ -20,7 +20,7 @@ The following authentication methods are derived from the **authenticationMethod + [voiceAuthenticationMethodConfiguration](voiceauthenticationmethodconfiguration.md) + [smsAuthenticationMethodConfiguration](smsauthenticationmethodconfiguration.md) + [softwareOathAuthenticationMethodConfiguration](softwareoathauthenticationmethodconfiguration.md) -+ [temporaryAccessPassAuthenticationMethodConfiguration](smsauthenticationmethodconfiguration.md) ++ [temporaryAccessPassAuthenticationMethodConfiguration](temporaryaccesspassauthenticationmethodconfiguration.md) + [x509CertificateAuthenticationMethodConfiguration](x509certificateauthenticationmethodconfiguration.md) ## Properties diff --git a/changelog/Microsoft.MDO.AnalyzedMessages.json b/changelog/Microsoft.MDO.AnalyzedMessages.json new file mode 100644 index 00000000000..5fee81bd60d --- /dev/null +++ b/changelog/Microsoft.MDO.AnalyzedMessages.json @@ -0,0 +1,270 @@ +{ + "changelog": [ + { + "ChangeList": [ + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Relationship", + "ChangedApiName": "collaboration", + "ChangeType": "Addition", + "Description": "Added the **collaboration** relationship to the [security](https://learn.microsoft.com/en-us/graph/api/resources/security?view=graph-rest-beta) resource.", + "Target": "security" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Enumeration", + "ChangedApiName": "antispamDirectionality", + "ChangeType": "Addition", + "Description": "Added the **antispamDirectionality** enumeration type.", + "Target": "antispamDirectionality" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Enumeration", + "ChangedApiName": "deliveryAction", + "ChangeType": "Addition", + "Description": "Added the **deliveryAction** enumeration type.", + "Target": "deliveryAction" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Member", + "ChangedApiName": "deliveredToJunk", + "ChangeType": "Addition", + "Description": "Added the `deliveredToJunk` member to the **deliveryAction** enumeration.", + "Target": "deliveryAction" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Member", + "ChangedApiName": "deliveredAsSpam", + "ChangeType": "Deletion", + "Description": "Removed the `deliveredAsSpam` member from the **deliveryAction** enumeration.", + "Target": "deliveryAction" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Enumeration", + "ChangedApiName": "deliveryLocation", + "ChangeType": "Addition", + "Description": "Added the **deliveryLocation** enumeration type.", + "Target": "deliveryLocation" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Member", + "ChangedApiName": "inbox_folder", + "ChangeType": "Addition", + "Description": "Added the `inbox_folder` member to the **deliveryLocation** enumeration.", + "Target": "deliveryLocation" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Member", + "ChangedApiName": "inbox", + "ChangeType": "Deletion", + "Description": "Removed the `inbox` member from the **deliveryLocation** enumeration.", + "Target": "deliveryLocation" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Member", + "ChangedApiName": "onprem_external", + "ChangeType": "Addition", + "Description": "Added the `onprem_external` member to the **deliveryLocation** enumeration.", + "Target": "deliveryLocation" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Member", + "ChangedApiName": "external", + "ChangeType": "Deletion", + "Description": "Removed the `external` member from the **deliveryLocation** enumeration.", + "Target": "deliveryLocation" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Member", + "ChangedApiName": "forwarded", + "ChangeType": "Deletion", + "Description": "Removed the `forwarded` member from the **deliveryLocation** enumeration.", + "Target": "deliveryLocation" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Member", + "ChangedApiName": "cloudMailBox", + "ChangeType": "Deletion", + "Description": "Removed the `cloudMailBox` member from the **deliveryLocation** enumeration.", + "Target": "deliveryLocation" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Enumeration", + "ChangedApiName": "remediationAction", + "ChangeType": "Addition", + "Description": "Added the **remediationAction** enumeration type.", + "Target": "remediationAction" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Member", + "ChangedApiName": "moveToDeletedItems", + "ChangeType": "Addition", + "Description": "Added the `moveToDeletedItems` member to the **remediationAction** enumeration.", + "Target": "remediationAction" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Enumeration", + "ChangedApiName": "remediationSeverity", + "ChangeType": "Addition", + "Description": "Added the **remediationSeverity** enumeration type.", + "Target": "remediationSeverity" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Enumeration", + "ChangedApiName": "threatType", + "ChangeType": "Addition", + "Description": "Added the **threatType** enumeration type.", + "Target": "threatType" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Resource", + "ChangedApiName": "analyzedEmailAttachment", + "ChangeType": "Addition", + "Description": "Added the [analyzedEmailAttachment](https://learn.microsoft.com/en-us/graph/api/resources/security-analyzedEmailAttachment?view=graph-rest-beta) resource.", + "Target": "analyzedEmailAttachment" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Resource", + "ChangedApiName": "analyzedEmailAuthenticationDetail", + "ChangeType": "Addition", + "Description": "Added the [analyzedEmailAuthenticationDetail](https://learn.microsoft.com/en-us/graph/api/resources/security-analyzedEmailAuthenticationDetail?view=graph-rest-beta) resource.", + "Target": "analyzedEmailAuthenticationDetail" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Resource", + "ChangedApiName": "analyzedEmailDeliveryDetail", + "ChangeType": "Addition", + "Description": "Added the [analyzedEmailDeliveryDetail](https://learn.microsoft.com/en-us/graph/api/resources/security-analyzedEmailDeliveryDetail?view=graph-rest-beta) resource.", + "Target": "analyzedEmailDeliveryDetail" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Resource", + "ChangedApiName": "analyzedEmailExchangeTransportRuleInfo", + "ChangeType": "Addition", + "Description": "Added the [analyzedEmailExchangeTransportRuleInfo](https://learn.microsoft.com/en-us/graph/api/resources/security-analyzedEmailExchangeTransportRuleInfo?view=graph-rest-beta) resource.", + "Target": "analyzedEmailExchangeTransportRuleInfo" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Resource", + "ChangedApiName": "analyzedEmailSenderDetail", + "ChangeType": "Addition", + "Description": "Added the [analyzedEmailSenderDetail](https://learn.microsoft.com/en-us/graph/api/resources/security-analyzedEmailSenderDetail?view=graph-rest-beta) resource.", + "Target": "analyzedEmailSenderDetail" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Resource", + "ChangedApiName": "analyzedEmailUrl", + "ChangeType": "Addition", + "Description": "Added the [analyzedEmailUrl](https://learn.microsoft.com/en-us/graph/api/resources/security-analyzedEmailUrl?view=graph-rest-beta) resource.", + "Target": "analyzedEmailUrl" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Resource", + "ChangedApiName": "detonationChain", + "ChangeType": "Addition", + "Description": "Added the [detonationChain](https://learn.microsoft.com/en-us/graph/api/resources/security-detonationChain?view=graph-rest-beta) resource.", + "Target": "detonationChain" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Resource", + "ChangedApiName": "detonationDetails", + "ChangeType": "Addition", + "Description": "Added the [detonationDetails](https://learn.microsoft.com/en-us/graph/api/resources/security-detonationDetails?view=graph-rest-beta) resource.", + "Target": "detonationDetails" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Property", + "ChangedApiName": "analysisDateTime", + "ChangeType": "Addition", + "Description": "Added the **analysisDateTime** property to the [detonationDetails](https://learn.microsoft.com/en-us/graph/api/resources/security-detonationDetails?view=graph-rest-beta) resource.", + "Target": "detonationDetails" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Property", + "ChangedApiName": "analysisTime", + "ChangeType": "Deletion", + "Description": "Removed the **analysisTime** property from the [detonationDetails](https://learn.microsoft.com/en-us/graph/api/resources/security-detonationDetails?view=graph-rest-beta) resource.", + "Target": "detonationDetails" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Property", + "ChangedApiName": "detonationObservables", + "ChangeType": "Addition", + "Description": "Added the **detonationObservables** property to the [detonationDetails](https://learn.microsoft.com/en-us/graph/api/resources/security-detonationDetails?view=graph-rest-beta) resource.", + "Target": "detonationDetails" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Property", + "ChangedApiName": "observables", + "ChangeType": "Deletion", + "Description": "Removed the **observables** property from the [detonationDetails](https://learn.microsoft.com/en-us/graph/api/resources/security-detonationDetails?view=graph-rest-beta) resource.", + "Target": "detonationDetails" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Resource", + "ChangedApiName": "detonationObservables", + "ChangeType": "Addition", + "Description": "Added the [detonationObservables](https://learn.microsoft.com/en-us/graph/api/resources/security-detonationObservables?view=graph-rest-beta) resource.", + "Target": "detonationObservables" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Resource", + "ChangedApiName": "analyzedEmail", + "ChangeType": "Addition", + "Description": "Added the [analyzedEmail](https://learn.microsoft.com/en-us/graph/api/resources/security-analyzedEmail?view=graph-rest-beta) resource.", + "Target": "analyzedEmail" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Resource", + "ChangedApiName": "collaborationRoot", + "ChangeType": "Addition", + "Description": "Added the [collaborationRoot](https://learn.microsoft.com/en-us/graph/api/resources/security-collaborationRoot?view=graph-rest-beta) resource.", + "Target": "collaborationRoot" + }, + { + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "ApiChange": "Method", + "ChangedApiName": "remediate", + "ChangeType": "Addition", + "Description": "Added the [remediate](https://learn.microsoft.com/en-us/graph/api/security-analyzedEmail-remediate?view=graph-rest-beta) method to the [analyzedEmail](https://learn.microsoft.com/en-us/graph/api/resources/security-analyzedEmail?view=graph-rest-beta) resource.", + "Target": "analyzedEmail" + } + ], + "Id": "74aeb56e-50d5-4b1f-942d-92b31766b579", + "Cloud": "Prod", + "Version": "beta", + "CreatedDateTime": "2024-03-07T04:00:25.443567Z", + "WorkloadArea": "Security", + "SubArea": "" + } + ] +} diff --git a/concepts/docfx.json b/concepts/docfx.json index a8d6f0ab1d2..90576334601 100644 --- a/concepts/docfx.json +++ b/concepts/docfx.json @@ -51,9 +51,11 @@ "overwrite": [], "externalReference": [], "globalMetadata": { - "feedback_system": "GitHub", - "feedback_github_repo": "microsoftgraph/microsoft-graph-docs-contrib", + "feedback_system": "Standard", "feedback_product_url": "https://developer.microsoft.com/graph/support", + "feedback_help_link_url": "https://learn.microsoft.com/en-us/answers/tags/161/ms-graph", + "feedback_help_link_type": "get-help-at-qna", + "feedback_github_repo": "microsoftgraph/microsoft-graph-docs-contrib", "breadcrumb_path": "/graph/breadcrumb/toc.json", "author": "MSGraphDocsVteam", "ms.author": "MSGraphDocsVteam", diff --git a/concepts/security-concept-overview.md b/concepts/security-concept-overview.md index 8560dbe0e1f..6e9b2017112 100644 --- a/concepts/security-concept-overview.md +++ b/concepts/security-concept-overview.md @@ -27,12 +27,15 @@ The [Microsoft Graph security API](/graph/api/resources/security-api-overview) m - [Connect using scripts](https://aka.ms/graphsecuritypowershellsampleblog) – Find [PowerShell samples](https://aka.ms/graphsecuritypowershellsample). - [Drag and drop into workflows and playbooks](https://aka.ms/graphsecurityconnectorsblogpost) – Use [Microsoft Graph security connectors](/azure/connectors/connectors-integrate-security-operations-create-api-microsoft-graph-security) for [Azure Logic Apps](/azure/logic-apps/logic-apps-overview), [Microsoft Flow](https://flow.microsoft.com/), and [Power Apps](https://powerapps.microsoft.com/). - [Get data into reports and dashboards](https://aka.ms/graphsecuritypowerbiconnectorblogpost) – Use the [Microsoft Graph security connector for Power BI](/power-bi/connect-data/desktop-connect-graph-security). -- [Connect using Jupyter notebooks](https://jupyter.org/) – Find [Jupyter notebook samples](https://aka.ms/graphsecurityjupyternotebooks). +- [Connect using Jupyter notebooks](https://jupyter.org/) – Find [Jupyter notebook samples](https://aka.ms/graphsecurityjupyternotebooks). ### Submit threats and trigger whole automation flow Submit threats across security solutions more easily with a unified security threat submission API. This allows you to not only submit threats but also get threat submission results and trigger downstream alert flows. The new unified security threat submission API supports both application and delegated permissions to help you build new security solutions. +### Investigate email and collaboration-related threats and trigger response action +Threat investigation and response capabilities provide detailed metadata and indicators about emails processed by Microsoft Defender for Office 365 and related response actions. These insights can help your organization's security team protect users from email- or file-based attacks. + ### Unify and standardize alert tracking Connect once to integrate alerts from any Microsoft Graph-integrated security solution and keep alert status and assignments in sync across all solutions. You can also stream alerts to security information and event management (SIEM) solutions, such as Splunk using Microsoft Graph security API connectors. For more info about solution integrations with the security API entities, see [Security solution integrations using the Microsoft Graph security API](security-integration.md). diff --git a/concepts/whats-new-overview.md b/concepts/whats-new-overview.md index bf5901fbb81..2a8015bb88e 100644 --- a/concepts/whats-new-overview.md +++ b/concepts/whats-new-overview.md @@ -11,7 +11,7 @@ Microsoft Graph provides a unified programmability model that you can use to acc For more detailed API-level updates, see the [Microsoft Graph API changelog](https://developer.microsoft.com/graph/changelog/). -For details about previous updates to Microsoft Graph, see [Microsoft Graph what's new history](whats-new-earlier.md). +For details about previous updates to Microsoft Graph, see [Microsoft Graph what's new history](whats-new-earlier.md). > [!IMPORTANT] > Features in _preview_ status are subject to change without notice, and might not be promoted to generally available (GA) status. Do not use preview features in production apps. @@ -32,6 +32,10 @@ Added the ability to list and get [Windows settings](/graph/api/resources/window Use the [federatedTokenValidationPolicy resource type](/graph/api/resources/federatedtokenvalidationpolicy?view=graph-rest-beta&preserve-view=true) and its associated methods to manage whether Microsoft Entra ID validates federation authentication tokens. +### Security | Email and collaboration protection + +Added the ability to list emails analyzed by Microsoft Defender for Office 365, get email related metadata, and perform response actions (soft delete, hard delete, move to junk, move to Inbox). + ## February 2024: New and generally available ### Microsoft Graph Toolkit @@ -46,6 +50,7 @@ Microsoft Graph Toolkit v4 is now available. For details about changes in the la ## February 2024: New in preview only + ### Calendars Use the **iCalUId** property on [event](/graph/api/resources/event?view=graph-rest-beta&preserve-view=true) to get the unique identifier for an event across calendars.