EWS v2
EWS Pack.#
This Integration is part of theExchange Web Services (EWS) provides the functionality to enable client applications to communicate with the Exchange server. EWS provides access to much of the same data that is made available through Microsoft OfficeOutlook.
The EWS v2 integration implants EWS leading services. The integration allows getting information on emails and activities in a target mailbox, and some active operations on the mailbox such as deleting emails and attachments or moving emails from folder to folder.
Note:
EWS v2 does not support Multi-Factor Authentication (MFA). If using MFA, use EWS O365 (see
https://xsoar.pan.dev/docs/reference/integrations/ewso365
) or if you have Graph Outlook use O365 Outlook Mail (Using Graph API) (see
https://xsoar.pan.dev/docs/reference/integrations/microsoft-graph-mail
) or O365 Outlook Mail Single User (Using Graph API) (see
https://xsoar.pan.dev/docs/reference/integrations/microsoft-graph-mail-single-user
).
EWS v2 Playbook
- Office 365 Search and Delete
- Search And Delete Emails - EWS
- Get Original Email - EWS
- Process Email - EWS
Use Cases
The EWS integration can be used for the following use cases.
-
Monitor a specific email account and create incidents from incoming emails to the defined folder.
Follow the instructions in the Fetched Incidents Data section. -
Search for an email message across mailboxes and folders.
This can be achieved in the following ways:-
Use the
ews-search-mailboxes
command to search for all emails in a specific scope of mailboxes.
Use the filter argument to narrow the search for emails sent from a specific account and more. -
Use the
ews-search-mailbox
command to search for all emails in a specific folder within the target mailbox.
Use the query argument to narrow the search for emails sent from a specific account and more.
-
Both of these commands retrieve the
ItemID
field for each email item listed in the results. The
ItemID
can be used in theews-get-items
command in order to get more information about the email item itself. -
For instance, use the
ews-search-mailboxes
command to hunt for emails that were marked as malicious in prior investigations, across organization mailboxes. Focus your hunt on emails sent from a specific mail account, emails with a specific subject and more.
-
Use the
-
Get email attachment information.
Use theews-get-attachment
command to retrieve information on one attachment or all attachments of a message at once. It supports both file attachments and item attachments (e.g., email messages). -
Delete email items from a mailbox.
First, make sure you obtain the email item ID. The item ID can be obtained with one of the integrationβs search commands.
Use theews-delete-items
command to delete one or more items from the target mailbox in a single action.
A less common use case is to remove emails that were marked as malicious from a userβs mailbox.
You can delete the items permanently (hard delete), or delete the items (soft delete), so they can be recovered by running theews-recover-messages
command.
Configure EWS v2 on Cortex XSOAR
- Navigate to Settings > Integrations > Servers & Services .
- Search for EWS v2.
-
Click
Add instance
to create and configure a new integration instance.
- Name : a textual name for the integration instance.
- Email address The email address
- Password The password of the account.
-
Email address from which to fetch incidents
This argument can take various user accounts in your organization. Usually is used as phishing mailbox.
Note: To use this functionality, your account must have impersonation rights or delegation for the account specified. In the case of impersonation, make sure to check theHas impersonation rights
checkbox in the instance settings. For more information on impersonation rights see βAdditional Infoβ section below. - Name of the folder from which to fetch incidents (supports Exchange Folder ID and sub-folders e.g. Inbox/Phishing)
- Public Folder
- Has impersonation rights
- Use system proxy settings
- Fetch incidents
- First fetch timestamp
- Mark fetched emails as read
-
Incident type
ββββββββββββββββββββββββ
β Manual Mode
In case the auto-discovery process failed, you will need to configure manually the exchange server endpoint, domain\username for exchange on-premise and enter exchange server version
-
Exchange Server Hostname or IP address
For office 365 use
https://outlook.office365.com/EWS/Exchange.asmx/
and for exchange on-premisehttps://<ip>/EWS/Exchange.asmx/
- DOMAIN\USERNAME (e.g. XSOAR.INT\admin)
- Exchange Server Version (On-Premise only. Supported versions: 2007, 2010, 2010_SP2, 2013, and 2016)
-
Trust any certificate (not secure)
ββββββββββββββββββββββββ
β Advanced Mode
Override Authentication Type (NTLM, Basic, or Digest)._ - Timeout (in seconds) for HTTP requests to Exchange Server
- Click Test to validate the URLs, token, and connection.
Fetched Incidents Data
The integration imports email messages from the destination folder in the target mailbox as incidents. If the message contains any attachments, they are uploaded to the War Room as files. If the attachment is an email, Cortex XSOAR fetches information about the attached email and downloads all of its attachments (if there are any) as files.
To use Fetch incidents, configure a new instance and select the
Fetches incidents
option in the instance settings.
IMPORTANT: The initial fetch interval is the previous 10 minutes. If no emails were fetched before from the destination folder- all emails from 10 minutes prior to the instance configuration and up to the current time will be fetched. Additionally moving messages manually to the destination folder will not trigger fetch incident. Define rules on phishing/target mailbox instead of moving messages manually.
You can configure the ``First fetch timestamp`` field to determine how much time back you want to fetch incidents.
Notice that it might required to set the ``Timeout`` field to a higher value.
Pay special attention to the following fields in the instance settings:
Email address from which to fetch incidents
β mailbox to fetch incidents from.
Name of the folder from which to fetch incidents
β use this field to configure the destination folder from where emails should be fetched. The default is Inbox folder. Please note, if Exchange is configured with an international flavor `Inbox` will be named according to the configured language.
Has impersonation rights
β mark this option if you set the target mailbox to an account different than your personal account. Otherwise Delegation access will be used instead of Impersonation.
Find more information on impersonation or delegation rights at βAdditional Infoβ section below.
Commands
You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.
- Get the attachments of an item: ews-get-attachment
- Delete the attachments of an item: ews-delete-attachment
- Get a list of searchable mailboxes: ews-get-searchable-mailboxes
- Search mailboxes: ews-search-mailboxes
- Move an item to a different folder: ews-move-item
- Delete an item from a mailbox: ews-delete-items
- Search a single mailbox: ews-search-mailbox
- Get the contacts for a mailbox: ews-get-contacts
- Get the out-of-office status for a mailbox: ews-get-out-of-office
- Recover soft-deleted messages: ews-recover-messages
- Create a folder: ews-create-folder
- Mark an item as junk: ews-mark-item-as-junk
- Search for folders: ews-find-folders
- Get items of a folder: ews-get-items-from-folder
- Get items: ews-get-items
- Move an item to a different mailbox: ews-move-item-between-mailboxes
- Get a folder: ews-get-folder
- Initiate a compliance search: ews-o365-start-compliance-search
- Get the status and results of a compliance search: ews-o365-get-compliance-search
- Purge compliance search results: ews-o365-purge-compliance-search-results
- Remove a compliance search: ews-o365-remove-compliance-search
- Get the purge status of a compliance search: ews-o365-get-compliance-search-purge-status
- Get auto-discovery information: ews-get-autodiscovery-config
- Expand a distribution list: ews-expand-group
- Mark items as read: ews-mark-items-as-read
1. Get the attachments of an item
Retrieves the actual attachments from an item (email message). To get all attachments for a message, only specify the item-id argument.
Required Permissions
Impersonation rights required. In order to perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
Base Command
ews-get-attachment
Input
Argument Name | Description | Required |
---|---|---|
item-id | The ID of the email message for which to get the attachments. | Required |
target-mailbox | The mailbox in which this attachment was found. If empty, the default mailbox is used. Otherwise, the user might require impersonation rights to this mailbox. | Optional |
attachment-ids | The attachments ids to get. If none - all attachments will be retrieved from the message. Support multiple attachments with comma-separated value or array. | Optional |
Context Output
Path | Type | Description |
---|---|---|
EWS.Items.FileAttachments.attachmentId | string | The attachment ID. Used for file attachments only. |
EWS.Items.FileAttachments.attachmentName | string | The attachment name. Used for file attachments only. |
EWS.Items.FileAttachments.attachmentSHA256 | string | The SHA256 hash of the attached file. |
EWS.Items.FileAttachments.attachmentLastModifiedTime | date | The attachment last modified time. Used for file attachments only. |
EWS.Items.ItemAttachments.datetimeCreated | date | The created time of the attached email. |
EWS.Items.ItemAttachments.datetimeReceived | date | The received time of the attached email. |
EWS.Items.ItemAttachments.datetimeSent | date | The sent time of the attached email. |
EWS.Items.ItemAttachments.receivedBy | string | The received by address of the attached email. |
EWS.Items.ItemAttachments.subject | string | The subject of the attached email. |
EWS.Items.ItemAttachments.textBody | string | The body of the attached email (as text). |
EWS.Items.ItemAttachments.headers | Unknown | The headers of the attached email. |
EWS.Items.ItemAttachments.hasAttachments | boolean | Whether the attached email has attachments. |
EWS.Items.ItemAttachments.itemId | string | The attached email item ID. |
EWS.Items.ItemAttachments.toRecipients | Unknown | A list of recipient email addresses for the attached email. |
EWS.Items.ItemAttachments.body | string | The body of the attached email (as HTML). |
EWS.Items.ItemAttachments.attachmentSHA256 | string | SHA256 hash of the attached email (as EML file). |
EWS.Items.ItemAttachments.FileAttachments.attachmentSHA256 | string | SHA256 hash of the attached files inside of the attached email. |
EWS.Items.ItemAttachments.ItemAttachments.attachmentSHA256 | string | SHA256 hash of the attached emails inside of the attached email. |
EWS.Items.ItemAttachments.isRead | String | The read status of the attachment. |
Command Example
!ews-get-attachment item-id=BBFDShfdafFSDF3FADR3434DFASDFADAFDADFADFCJebinpkUAAAfxuiVAAA= target-mailbox=test@demistodev.onmicrosoft.com
Context Example
{ "EWS": { "Items": { "ItemAttachments": { "originalItemId": "BBFDShfdafFSDF3FADR3434DFASDFADAFDADFADFCJebinpkUAAAfxuiVAAA=", "attachmentSize": 2956, "receivedBy": "test@demistodev.onmicrosoft.com", "size": 28852, "author": "test2@demistodev.onmicrosoft.com", "attachmentLastModifiedTime": "2019-08-11T15:01:30+00:00", "subject": "Moving Email between mailboxes", "body": "Some text inside", "datetimeCreated": "2019-08-11T15:01:47Z", "importance": "Normal", "attachmentType": "ItemAttachment", "toRecipients": [ "test@demistodev.onmicrosoft.com" ], "mailbox": "test@demistodev.onmicrosoft.com", "isRead": false, "attachmentIsInline": false, "datetimeSent": "2019-08-07T12:50:19Z", "lastModifiedTime": "2019-08-11T15:01:30Z", "sender": "test2@demistodev.onmicrosoft.com", "attachmentName": "Moving Email between mailboxes", "datetimeReceived": "2019-08-07T12:50:20Z", "attachmentSHA256": "119e27b28dc81bdfd4f498d44bd7a6d553a74ee03bdc83e6255a53", "hasAttachments": false, "headers": [ { "name": "Subject", "value": "Moving Email between mailboxes" } ... ], "attachmentId": "BBFDShfdafFSDF3FADR3434DFASDFADAFDADFADFCJebinpkUAAAfxuiVAAABEgAQAOpEfpzDB4dFkZ+/K4XSj44=", "messageId": "<message_id>" } } }
2. Delete the attachments of an item
Deletes the attachments of an item (email message).
Required Permissions
Impersonation rights required. In order to perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
Base Command
ews-delete-attachment
Input
Argument Name | Description | Required |
---|---|---|
item-id | The ID of the email message for which to delete attachments. | Required |
target-mailbox | The mailbox in which this attachment was found. If empty, the default mailbox is used. Otherwise, the user might require impersonation rights to this mailbox. | Optional |
attachment-ids | A CSV list (or array) of attachment IDs to delete. If empty, all attachments will be deleted from the message. | Optional |
Context Output
Path | Type | Description |
---|---|---|
EWS.Items.FileAttachments.attachmentId | string | The ID of the deleted attachment, in case of file attachment. |
EWS.Items.ItemAttachments.attachmentId | string | The ID of the deleted attachment, in case of other attachment (for example, "email"). |
EWS.Items.FileAttachments.action | string | The deletion action in case of file attachment. This is a constant value: 'deleted'. |
EWS.Items.ItemAttachments.action | string | The deletion action in case of other attachment (for example, "email"). This is a constant value: 'deleted'. |
Command Example
!ews-delete-attachment item-id=AAMkADQ0NmwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJjfaljfAFDVSDinpkUAAAfxxd9AAA= target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
action | attachmentId |
---|---|
deleted | AAMkADQ0NmwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJjfaljfAFDVSDinpkUAAAfxxd9AAABEgAQAIUht2vrOdErec33= |
Context Example
{ "EWS": { "Items": { "FileAttachments": { "action": "deleted", "attachmentId": "AAMkADQ0NmwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJjfaljfAFDVSDinpkUAAAfxxd9AAABEgAQAIUht2vrOdErec33=" } } } }
3. Get a list of searchable mailboxes
Returns a list of searchable mailboxes.
Note: We recommend that you do not run this command if you have over 1M mailboxes.
Required Permissions
Requires eDiscovery permissions to the Exchange Server. For more information see the Microsoft documentation .
Base Command
ews-get-searchable-mailboxes
Input
There are no input arguments for this command.
Context Output
Path | Type | Description |
---|---|---|
EWS.Mailboxes.mailbox | string | Addresses of the searchable mailboxes. |
EWS.Mailboxes.mailboxId | string | IDs of the searchable mailboxes. |
EWS.Mailboxes.displayName | string | The email display name. |
EWS.Mailboxes.isExternal | boolean | Whether the mailbox is external. |
EWS.Mailboxes.externalEmailAddress | string | The external email address. |
Command Example
!ews-get-searchable-mailboxes
Human Readable Output
displayName | isExternal | mailbox | mailboxId |
---|---|---|---|
test | false | test@demistodev.onmicrosoft.com | /o=Exchange***/ou=Exchange Administrative Group ()/cn= /cn= -** |
Context Example
{ "EWS": { "Mailboxes": [ { "mailbox": "test@demistodev.onmicrosoft.com", "displayName": "test", "mailboxId": "/o=Exchange***/ou=Exchange Administrative Group ()/cn=**/cn=**-**", "isExternal": "false" } ... ] } }
4. Search mailboxes
Searches over multiple mailboxes or all Exchange mailboxes. The maximum number of mailboxes that can be searched is 20,000. Use either the mailbox-search-scope command or the email-addresses command to search specific mailboxes.
Required Permissions
Requires eDiscovery permissions to the Exchange Server. For more information, see the Microsoft documentation .
Note: If you have over 1M mailboxes, you should limit the number of mailboxes to search by defining the mailbox-search-scope argument before running this command.
Base Command
ews-search-mailboxes
Input
Argument Name | Description | Required |
---|---|---|
filter | The filter query to search. | Required |
mailbox-search-scope | The mailbox IDs to search. If empty, all mailboxes are searched. | Optional |
limit | Maximum number of results to return. | Optional |
email_addresses | CSV list or array of email addresses. | Optional |
Context Output
Path | Type | Description |
---|---|---|
EWS.Items.itemId | string | The item ID. |
EWS.Items.mailbox | string | The mailbox address where the item was found. |
EWS.Items.subject | string | The subject of the email. |
EWS.Items.toRecipients | Unknown | List of recipient email addresses. |
EWS.Items.sender | string | Sender email address. |
EWS.Items.hasAttachments | boolean | Whether the email has attachments? |
EWS.Items.datetimeSent | date | Sent time of the email. |
EWS.Items.datetimeReceived | date | Received time of the email. |
Command Example
!ews-search-mailboxes filter="subject:Test" limit=1
Human Readable Output
datetimeReceived | datetimeSent | hasAttachments | itemId | mailbox | sender | subject | toRecipients |
---|---|---|---|---|---|---|---|
2019-08-11T11:00:28Z | 2019-08-11T11:00:28Z | false | AAMkAGY3OTQyMzMzLWYxNjktNDE0My05NmZhLWQ5MGY1YjIyNzBkNABGACASFAACYCKjWAnXDFrfsdhdnfkanpAAA= | test2@demistodev.onmicrosoft.com | John Smith | test report | dem@demistodev.onmicrosoft.com |
Context Example
{ "EWS": { "Items": { "itemId": "AAMkAGY3OTQyMzMzLWYxNjktNDE0My05NmZhLWQ5MGY1YjIyNzBkNABGACASFAACYCKjWAnXDFrfsdhdnfkanpAAA=", "sender": "John Smith", "datetimeReceived": "2019-08-11T11:00:28Z", "hasAttachments": "false", "toRecipients": [ "dem@demistodev.onmicrosoft.com" ], "mailbox": "test2@demistodev.onmicrosoft.com", "datetimeSent": "2019-08-11T11:00:28Z", "subject": "test report " } } }
5. Move an item to a different folder
Move an item to a different folder in the mailbox.
Required Permissions
Impersonation rights required. In order to perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
Base Command
ews-move-item
Input
Argument Name | Description | Required |
---|---|---|
item-id | The ID of the item to move. | Required |
target-folder-path | The path to the folder to which to move the item. Complex paths are supported, for example, "Inbox\Phishing". | Required |
target-mailbox | The mailbox on which to run the command. | Optional |
is-public | Whether the target folder is a public folder. | Optional |
Context Output
Path | Type | Description |
---|---|---|
EWS.Items.newItemID | string | The item ID after the move. |
EWS.Items.messageID | string | The item message ID. |
EWS.Items.itemId | string | The original item ID. |
EWS.Items.action | string | The action taken. The value will be "moved". |
Command Example
!ews-move-item item-id=VDAFNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU34cSCSSSfBJebinpkUAAAAAAEMAACyyVyFtlsUQZfBJebinpkUAAAfxuiRAAA= target-folder-path=Moving target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
action | itemId | messageId | newItemId |
---|---|---|---|
moved | VDAFNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU34cSCSSSfBJebinpkUAAAAAAEMAACyyVyFtlsUQZfBJebinpkUAAAfxuiRAAA | <message_id> | AAVAAAVN2NkLThmZjdmNTZjNTMxFFFFJTJPMPXU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAAa2bUBAACyyVfafainpkUAAAfxxd+AAA= |
Context Example
{
"EWS": {
"Items": {
"action": "moved",
"itemId": "VDAFNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU34cSCSSSfBJebinpkUAAAAAAEMAACyyVyFtlsUQZfBJebinpkUAAAfxuiRAAA",
"newItemId": "AAVAAAVN2NkLThmZjdmNTZjNTMxFFFFJTJPMPXU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAAa2bUBAACyyVfafainpkUAAAfxxd+AAA=",
"messageId": "<message_id>"
}
}
}
6. Delete an item from a mailbox
Delete items from mailbox.
Required Permissions
Impersonation rights required. In order to perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
Base Command
ews-delete-items
Input
Argument Name | Description | Required |
---|---|---|
item-ids | The item IDs to delete. | Required |
delete-type | Deletion type. Can be "trash", "soft", or "hard". | Required |
target-mailbox | The mailbox on which to run the command. | Optional |
Context Output
Path | Type | Description |
---|---|---|
EWS.Items.itemId | string | The deleted item ID. |
EWS.Items.messageId | string | The deleted message ID. |
EWS.Items.action | string | The deletion action. Can be 'trash-deleted', 'soft-deleted', or 'hard-deleted'. |
Command Example
!ews-delete-items item-ids=VWAFA3hmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMGAACyw+kAAA= delete-type=soft target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
action | itemId | messageId |
---|---|---|
soft-deleted | VWAFA3hmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMGAACyw+kAAA= | <message_id> |
Context Example
{ "EWS": { "Items": { "action": "soft-deleted", "itemId": "VWAFA3hmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMGAACyw+kAAA=", "messageId": "<messaage_id>" } } }
7. Search a single mailbox
Searches for items in the specified mailbox. Specific permissions are needed for this operation to search in a target mailbox other than the default.
Required Permissions
Impersonation rights required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
Base Command
ews-search-mailbox
Input
Argument Name | Description | Required |
---|---|---|
query | The search query string. For more information about the query syntax, see the Microsoft documentation . | Optional |
folder-path | The folder path in which to search. If empty, searches all the folders in the mailbox. | Optional |
limit | Maximum number of results to return. | Optional |
target-mailbox | The mailbox on which to apply the search. | Optional |
is-public | Whether the folder is a Public Folder? | Optional |
message-id | The message ID of the email. This will be ignored if a query argument is provided. | Optional |
Context Output
Path | Type | Description |
---|---|---|
EWS.Items.itemId | string | The email item ID. |
EWS.Items.hasAttachments | boolean | Whether the email has attachments. |
EWS.Items.datetimeReceived | date | Received time of the email. |
EWS.Items.datetimeSent | date | Sent time of the email. |
EWS.Items.headers | Unknown | Email headers (list). |
EWS.Items.sender | string | Sender email address of the email. |
EWS.Items.subject | string | Subject of the email. |
EWS.Items.textBody | string | Body of the email (as text). |
EWS.Items.size | number | Email size. |
EWS.Items.toRecipients | Unknown | List of email recipients addresses. |
EWS.Items.receivedBy | Unknown | Email received by address. |
EWS.Items.messageId | string | Email message ID. |
EWS.Items.body | string | Body of the email (as HTML). |
EWS.Items.FileAttachments.attachmentId | unknown | Attachment ID of the file attachment. |
EWS.Items.ItemAttachments.attachmentId | unknown | Attachment ID of the item attachment. |
EWS.Items.FileAttachments.attachmentName | unknown | Attachment name of the file attachment. |
EWS.Items.ItemAttachments.attachmentName | unknown | Attachment name of the item attachment. |
EWS.Items.isRead | String | The read status of the email. |
Command Example
!ews-search-mailbox query="subject:"Get Attachment Email" target-mailbox=test@demistodev.onmicrosoft.com limit=1
Human Readable Output
sender | subject | hasAttachments | datetimeReceived | receivedBy | author | toRecipients |
---|---|---|---|---|---|---|
test2@demistodev.onmicrosoft.com | Get Attachment Email | true | 2019-08-11T10:57:37Z | test@demistodev.onmicrosoft.com | test2@demistodev.onmicrosoft.com | test@demistodev.onmicrosoft.com |
Context Example
{ "EWS": { "Items": { "body": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<style type=\"text/css\" style=\"display:none;\"><!-- P {margin-top:0;margin-bottom:0;} --></style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<div id=\"divtagrapper\" style=\"font-size:12pt;color:#000000;font-family:Calibri,Helvetica,sans-serif;\" dir=\"ltr\">\r\n<p style=\"margin-top:0;margin-bottom:0\">Some text inside email</p>\r\n</div>\r\n</body>\r\n</html>\r\n", "itemId": "AAMkADQ0NmFFijer3FFmNTZjNTMxNwBGAAAAAAFSAAfxw+jAAA=", "toRecipients": [ "test@demistodev.onmicrosoft.com" ], "datetimeCreated": "2019-08-11T10:57:37Z", "datetimeReceived": "2019-08-11T10:57:37Z", "author": "test2@demistodev.onmicrosoft.com", "hasAttachments": true, "size": 30455, "subject": "Get Attachment Email", "FileAttachments": [ { "attachmentName": "atta1.rtf", "attachmentSHA256": "csfd81097bc049fbcff6e637ade0407a00308bfdfa339e31a44a1c4e98f28ce36e4f", "attachmentType": "FileAttachment", "attachmentSize": 555, "attachmentId": "AAMkADQ0NmFkODFkLWQ4MDEtNDE4Mi1hN2NkLThmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMGAACyyVyFtlsUQZfBJebinpkUAAAfxw+jAAABEgAQAEyq1TB2nKBLpKUiFUJ5Geg=", "attachmentIsInline": false, "attachmentLastModifiedTime": "2019-08-11T11:06:02+00:00", "attachmentContentLocation": null, "attachmentContentType": "text/rtf", "originalItemId": "AAMkADQ0NmFFijer3FFmNTZjNTMxNwBGAAAAAAFSAAfxw+jAAA=", "attachmentContentId": null } ], "headers": [ { "name": "Subject", "value": "Get Attachment Email" }, ... ], "isRead": true, "messageId": "<mesage_id>", "receivedBy": "test@demistodev.onmicrosoft.com", "datetimeSent": "2019-08-11T10:57:36Z", "lastModifiedTime": "2019-08-11T11:13:59Z", "mailbox": "test@demistodev.onmicrosoft.com", "importance": "Normal", "textBody": "Some text inside email\r\n", "sender": "test2@demistodev.onmicrosoft.com" } } }
8. Get the contacts for a mailbox
Retrieves contacts for a specified mailbox.
Required Permissions
Impersonation rights required. In order to perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
Base Command
ews-get-contacts
Input
Argument Name | Description | Required |
---|---|---|
target-mailbox | The mailbox for which to retrieve the contacts. | Optional |
limit | Maximum number of results to return. | Optional |
Context Output
Path | Type | Description |
---|---|---|
Account.Email.EwsContacts.displayName | Unknown | The contact name. |
Account.Email.EwsContacts.lastModifiedTime | Unknown | The time that the contact was last modified. |
Account.Email.EwsContacts.emailAddresses | Unknown | Phone numbers of the contact. |
Account.Email.EwsContacts.physicalAddresses | Unknown | Physical addresses of the contact. |
Account.Email.EwsContacts.phoneNumbers.phoneNumber | Unknown | Email addresses of the contact. |
Command Example
!ews-get-contacts limit="1"
Human Readable Output
changekey | culture | datetimeCreated | datetimeReceived | datetimeSent | displayName | emailAddresses | fileAs | fileAsMapping | givenName | id | importance | itemClass | lastModifiedName | lastModifiedTime | postalAddressIndex | sensitivity | subject | uniqueBody | webClientReadFormQueryString |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EABYACAADcsxRwRjq/zTrN6vWSzKAK1Dl3N | en-US | 2019-08-05T12:35:36Z | 2019-08-05T12:35:36Z | 2019-08-05T12:35:36Z | Contact Name | some@dev.microsoft.com | Contact Name | LastCommaFirst | Contact Name | AHSNNK3NQNcasnc3SAS/zTrN6vWSzK4OWAAAAAAEOAADrxRwRjq/zTrNFSsfsfVWAAK1KsF3AAA= | Normal | IPM.Contact | John Smith | 2019-08-05T12:35:36Z | None | Normal | Contact Name | https://outlook.office365.com/owa/?ItemID=*** |
Context Example
{ "Account.Email": [ { "itemClass": "IPM.Contact", "lastModifiedName": "John Smith", "displayName": "Contact Name", "datetimeCreated": "2019-08-05T12:35:36Z", "datetimeReceived": "2019-08-05T12:35:36Z", "fileAsMapping": "LastCommaFirst", "importance": "Normal", "sensitivity": "Normal", "postalAddressIndex": "None", "webClientReadFormQueryString": "https://outlook.office365.com/owa/?ItemID=***", "uniqueBody": "<html><body></body></html>", "fileAs": "Contact Name", "culture": "en-US", "changekey": "EABYACAADcsxRwRjq/zTrN6vWSzKAK1Dl3N", "lastModifiedTime": "2019-08-05T12:35:36Z", "datetimeSent": "2019-08-05T12:35:36Z", "emailAddresses": [ "some@dev.microsoft.com" ], "givenName": "Contact Name", "id": "AHSNNK3NQNcasnc3SAS/zTrN6vWSzK4OWAAAAAAEOAADrxRwRjq/zTrNFSsfsfVWAAK1KsF3AAA=", "subject": "Contact Name" } ] }
9. Get the out-of-office status for a mailbox
Retrieves the out-of-office status for a specified mailbox.
Required Permissions
Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part the ApplicationImpersonation role.
Base Command
ews-get-out-of-office
Input
Argument Name | Description | Required |
---|---|---|
target-mailbox | The mailbox for which to get the out-of-office status. | Required |
Context Output
Path | Type | Description |
---|---|---|
Account.Email.OutOfOffice.state | Unknown | Out-of-office state. The result can be: "Enabled", "Scheduled", or "Disabled". |
Account.Email.OutOfOffice.externalAudience | Unknown | Out-of-office external audience. Can be "None", "Known", or "All". |
Account.Email.OutOfOffice.start | Unknown | Out-of-office start date. |
Account.Email.OutOfOffice.end | Unknown | Out-of-office end date. |
Account.Email.OutOfOffice.internalReply | Unknown | Out-of-office internal reply. |
Account.Email.OutOfOffice.externalReply | Unknown | Out-of-office external reply. |
Account.Email.OutOfOffice.mailbox | Unknown | Out-of-office mailbox. |
Command Example
!ews-get-out-of-office target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
end | externalAudience | mailbox | start | state |
---|---|---|---|---|
2019-08-12T13:00:00Z | All | test@demistodev.onmicrosoft.com | 2019-08-11T13:00:00Z | Disabled |
Context Example
{ "Account": { "Email": { "OutOfOffice": { "start": "2019-08-11T13:00:00Z", "state": "Disabled", "mailbox": "test@demistodev.onmicrosoft.com", "end": "2019-08-12T13:00:00Z", "externalAudience": "All" } } } }
10. Recover soft-deleted messages
Recovers messages that were soft-deleted.
Required Permissions
Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
Base Command
ews-recover-messages
Input
Argument Name | Description | Required |
---|---|---|
message-ids | A CSV list of message IDs. Run the py-ews-delete-items command to retrieve the message IDs | Required |
target-folder-path | The folder path to recover the messages to. | Required |
target-mailbox | The mailbox in which the messages found. If empty, will use the default mailbox. If you specify a different mailbox, you might need impersonation rights to the mailbox. | Optional |
is-public | Whether the target folder is a Public Folder. | Optional |
Context Output
Path | Type | Description |
---|---|---|
EWS.Items.itemId | Unknown | The item ID of the recovered item. |
EWS.Items.messageId | Unknown | The message ID of the recovered item. |
EWS.Items.action | Unknown | The action taken on the item. The value will be 'recovered'. |
Command Example
!ews-recover-messages message-ids=<DFVDFmvsCSCS.com> target-folder-path=Moving target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
action | itemId | messageId |
---|---|---|
recovered | AAVCSVS1hN2NkLThmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed33wX3aBwCyyVyFtlsUQZfBJebinpkUAAAa2bUBAACyyVyFtlscfxxd/AAA= | <DFVDFmvsCSCS.com> |
Context Example
{ "EWS": { "Items": { "action": "recovered", "itemId": "AAVCSVS1hN2NkLThmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed33wX3aBwCyyVyFtlsUQZfBJebinpkUAAAa2bUBAACyyVyFtlscfxxd/AAA=", "messageId": "<DFVDFmvsCSCS.com>" } } }
11. Create a folder
Creates a new folder in a specified mailbox.
Required Permissions
Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
Base Command
ews-create-folder
Input
Argument Name | Description | Required |
---|---|---|
new-folder-name | The name of the new folder. | Required |
folder-path | Path to locate the new folder. Exchange folder ID is also supported. | Required |
target-mailbox | The mailbox in which to create the folder. | Optional |
Context Output
There is no context output for this command.
Command Example
!ews-create-folder folder-path=Inbox new-folder-name="Created Folder" target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
Folder Inbox\Created Folder created successfully
12. Mark an item as junk
Marks an item as junk. This is commonly used to block an email address. For more information, see the Microsoft documentation .
Required Permissions
Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
Base Command
ews-mark-item-as-junk
Input
Argument Name | Description | Required |
---|---|---|
item-id | The item ID to mark as junk. | Required |
move-items | Whether to move the item from the original folder to the junk folder. | Optional |
target-mailbox | If empty, will use the default mailbox. If you specify a different mailbox, you might need impersonation rights to the mailbox. | Optional |
Context Output
There is no context output for this command.
Command Example
!ews-mark-item-as-junk item-id=AAMkcSQ0NmFkOhmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUcsBJebinpkUAAAAAAEMASFDkUAAAfxuiSAAA= move-items=yes target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
action | itemId |
---|---|
marked-as-junk | AAMkcSQ0NmFkOhmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUcsBJebinpkUAAAAAAEMASFDkUAAAfxuiSAAA= |
Context Example
{ "EWS": { "Items": { "action": "marked-as-junk", "itemId": "AAMkcSQ0NmFkOhmZjdmNTZjNTMxNwBGAAAAAAA4kxh+ed3JTJPMPXU3wX3aBwCyyVyFtlsUcsBJebinpkUAAAAAAEMASFDkUAAAfxuiSAAA=" } } }
13. Search for folders
Retrieves information for the folders of the specified mailbox. Only folders with read permissions will be returned. Your visual folders on the mailbox, such as "Inbox", are under the folder "Top of Information Store".
Required Permissions
Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
Base Command
ews-find-folders
Input
Argument Name | Description | Required |
---|---|---|
target-mailbox | The mailbox on which to apply the command. | Optional |
is-public | Whether to find Public Folders. | Optional |
Context Output
Path | Type | Description |
---|---|---|
EWS.Folders.name | string | Folder name. |
EWS.Folders.id | string | Folder ID. |
EWS.Folders.totalCount | Unknown | Number of items in the folder. |
EWS.Folders.unreadCount | number | Number of unread items in the folder. |
EWS.Folders.changeKey | number | Folder change key. |
EWS.Folders.childrenFolderCount | number | Number of sub-folders. |
Command Example
!ews-find-folders target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
root βββ AllContacts βββ AllItems βββ Common Views βββ Deferred Action βββ ExchangeSyncData βββ Favorites βββ Freebusy Data βββ Location βββ MailboxAssociations βββ My Contacts βββ MyContactsExtended βββ People I Know βββ PeopleConnect βββ Recoverable Items β βββ Calendar Logging β βββ Deletions β ββ Purges β βββ Versions βββ Reminders βββ Schedule βββ Sharing βββ Shortcuts βββ Spooler Queue βββ System βββ To-Do Search βββ Top of Information Store β βββ Calendar β βββ Contacts β β βββ GAL Contacts β β βββ Recipient Cache β βββ Conversation Action Settings β βββ Deleted Items β β βββ Create1 β βββ Drafts β βββ Inbox ...
Context Example
{ "EWS": { "Folders": [ { "unreadCount": 1, "name": "Inbox", "childrenFolderCount": 1, "totalCount": 44, "changeKey": "**********fefsduQi0", "id": "*******VyFtlFDSAFDSFDAAA=" } ... ] } }
14. Get items of a folder
Retrieves items from a specified folder in a mailbox. The items are ordered by the item created time, most recent is first.
Required Permissions
Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
Base Command
ews-get-items-from-folder
Input
Argument Name | Description | Required |
---|---|---|
folder-path | The folder path from which to get the items. | Required |
limit | Maximum number of items to return. | Optional |
target-mailbox | The mailbox on which to apply the command. | Optional |
is-public | Whether the folder is a Public Folder. Default is 'False'. | Optional |
get-internal-items | If the email item contains another email as an attachment (EML or MSG file), whether to retrieveΒ the EML/MSG file attachment. Can be "yes" or "no". Default is "no". | Optional |
Context Output
Path | Type | Description |
---|---|---|
EWS.Items.itemId | string | The item ID of the email. |
EWS.Items.hasAttachments | boolean | Whether the email has attachments. |
EWS.Items.datetimeReceived | date | Received time of the email. |
EWS.Items.datetimeSent | date | Sent time of the email. |
EWS.Items.headers | Unknown | Email headers (list). |
EWS.Items.sender | string | Sender mail address of the email. |
EWS.Items.subject | string | Subject of the email. |
EWS.Items.textBody | string | Body of the email (as text). |
EWS.Items.size | number | Email size. |
EWS.Items.toRecipients | Unknown | Email recipients addresses (list). |
EWS.Items.receivedBy | Unknown | Received by address of the email. |
EWS.Items.messageId | string | Email message ID. |
EWS.Items.body | string | Body of the email (as HTML). |
EWS.Items.FileAttachments.attachmentId | unknown | Attachment ID of file attachment. |
EWS.Items.ItemAttachments.attachmentId | unknown | Attachment ID of the item attachment. |
EWS.Items.FileAttachments.attachmentName | unknown | Attachment name of the file attachment. |
EWS.Items.ItemAttachments.attachmentName | unknown | Attachment name of the item attachment. |
Email.Items.ItemAttachments.attachmentName | unknown | Attachment name of the item attachment. |
EWS.Items.isRead | String | The read status of the email. |
Command Example
!ews-get-items-from-folder folder-path=Test target-mailbox=test@demistodev.onmicrosoft.com limit=1
Human Readable Output
sender | subject | hasAttachments | datetimeReceived | receivedBy | author | toRecipients | itemId |
---|---|---|---|---|---|---|---|
test2@demistodev.onmicrosoft.com | Get Attachment Email | true | 2019-08-11T10:57:37Z | test@demistodev.onmicrosoft.com | test2@demistodev.onmicrosoft.com | test@demistodev.onmicrosoft.com | AAFSFSFFtlsUQZfBJebinpkUAAABjKMGAACyyVyFtlsUQZfBJebinpkUAAAsfw+jAAA= |
Context Example
{ "EWS": { "Items": { "body": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<style type=\"text/css\" style=\"display:none;\"><!-- P {margin-top:0;margin-bottom:0;} --></style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt;color:#000000;font-family:Calibri,Helvetica,sans-serif;\" dir=\"ltr\">\r\n<p style=\"margin-top:0;margin-bottom:0\">Some text inside email</p>\r\n</div>\r\n</body>\r\n</html>\r\n", "itemId": "AAFSFSFFtlsUQZfBJebinpkUAAABjKMGAACyyVyFtlsUQZfBJebinpkUAAAsfw+jAAA=", "toRecipients": [ "test@demistodev.onmicrosoft.com" ], "datetimeCreated": "2019-08-11T10:57:37Z", "datetimeReceived": "2019-08-11T10:57:37Z", "author": "test2@demistodev.onmicrosoft.com", "hasAttachments": true, "size": 21435, "subject": "Get Attachment Email", "FileAttachments": [ { "attachmentName": "atta1.rtf", "attachmentSHA256": "cd81097bcvdiojf3407a00308b48039e31a44a1c4fdnfkdknce36e4f", "attachmentType": "FileAttachment", "attachmentSize": 535, "attachmentId": "AAFSFSFFtlsUQZfBJebinpkUAAABjKMGAACyyVyFtlsUQZfBJebinpkUAAAsfw+jAAABEgAQAEyq1TB2nKBLpKUiFUJ5Geg=", "attachmentIsInline": false, "attachmentLastModifiedTime": "2019-08-11T11:06:02+00:00", "attachmentContentLocation": null, "attachmentContentType": "text/rtf", "originalItemId": "AAFSFSFFtlsUQZfBJebinpkUAAABjKMGAACyyVyFtlsUQZfBJebinpkUAAAsfw+jAAA=", "attachmentContentId": null } ], "headers": [ { "name": "Subject", "value": "Get Attachment Email" }, ... ], "isRead": true, "messageId": "<message_id>", "receivedBy": "test@demistodev.onmicrosoft.com", "datetimeSent": "2019-08-11T10:57:36Z", "lastModifiedTime": "2019-08-11T11:13:59Z", "mailbox": "test@demistodev.onmicrosoft.com", "importance": "Normal", "textBody": "Some text inside email\r\n", "sender": "test2@demistodev.onmicrosoft.com" } } }
15. Get items
Retrieves items by item ID.
Required Permissions
Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
Base Command
ews-get-items
Input
Argument Name | Description | Required |
---|---|---|
item-ids | A CSV list of item IDs. | Required |
target-mailbox | The mailbox on which to run the command on. | Optional |
Context Output
Path | Type | Description |
---|---|---|
EWS.Items.itemId | string | The email item ID. |
EWS.Items.hasAttachments | boolean | Whether the email has attachments. |
EWS.Items.datetimeReceived | date | Received time of the email. |
EWS.Items.datetimeSent | date | Sent time of the email. |
EWS.Items.headers | Unknown | Email headers (list). |
EWS.Items.sender | string | Sender mail address of the email. |
EWS.Items.subject | string | Subject of the email. |
EWS.Items.textBody | string | Body of the email (as text). |
EWS.Items.size | number | Email size. |
EWS.Items.toRecipients | Unknown | Email recipients addresses (list). |
EWS.Items.receivedBy | Unknown | Received by address of the email. |
EWS.Items.messageId | string | Email message ID. |
EWS.Items.body | string | Body of the email (as HTML). |
EWS.Items.FileAttachments.attachmentId | unknown | Attachment ID of the file attachment. |
EWS.Items.ItemAttachments.attachmentId | unknown | Attachment ID of the item attachment. |
EWS.Items.FileAttachments.attachmentName | unknown | Attachment name of the file attachment. |
EWS.Items.ItemAttachments.attachmentName | unknown | Attachment name of the item attachment. |
EWS.Items.isRead | String | The read status of the email. |
Email.CC | String | Email addresses CC'ed to the email. |
Email.BCC | String | Email addresses BCC'ed to the email. |
Email.To | String | The recipient of the email. |
Email.From | String | The sender of the email. |
Email.Subject | String | The subject of the email. |
Email.Text | String | The plain-text version of the email. |
Email.HTML | String | The HTML version of the email. |
Email.HeadersMap | String | The headers of the email. |
Command Example
!ews-get-items item-ids=AAMkADQ0NmFkODFkLWQ4MDEtNDFDFZjNTMxNwBGAAAAAAA4kxhFFAfxw+jAAA= target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
Identical outputs to
ews-get-items-from-folder
command.
16. Move an item to a different mailbox
Moves an item from one mailbox to a different mailbox.
Required Permissions
Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
Base Command
ews-move-item-between-mailboxes
Input
Argument Name | Description | Required |
---|---|---|
item-id | The item ID to move. | Required |
destination-folder-path | The folder in the destination mailbox to which to move the item. You can specify a complex path, for example, "Inbox\Phishing". | Required |
destination-mailbox | The mailbox to which to move the item. | Required |
source-mailbox | The mailbox from which to move the item (conventionally called the "target-mailbox", the target mailbox on which to run the command). | Optional |
is-public | Whether the destination folder is a Public Folder. Default is "False". | Optional |
Context Output
Path | Type | Description |
---|---|---|
EWS.Items.movedToMailbox | string | The mailbox to which the item was moved. |
EWS.Items.movedToFolder | string | The folder to which the item was moved. |
EWS.Items.action | string | The action taken on the item. The value will be "moved". |
Command Example
!ews-move-item-between-mailboxes item-id=AAMkAGY3OTQyMzMzLWYxNjktNDE0My05NFSFSyNzBkNABGAAAAAACYCKjWAjq/zTrN6vWSzK4OWAAK2ISFSA= destination-folder-path=Moving destination-mailbox=test@demistodev.onmicrosoft.com source-mailbox=test2@demistodev.onmicrosoft.com
Human Readable Output
Item was moved successfully.
Context Example
{ "EWS": { "Items": { "movedToMailbox": "test@demistodev.onmicrosoft.com", "movedToFolder": "Moving" } } }
17. Get a folder
Retrieves a single folder.
Required Permissions
Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
Base Command
ews-get-folder
Input
Argument Name | Description | Required |
---|---|---|
target-mailbox | The mailbox on which to apply the search. | Optional |
folder-path | The path of the folder to retrieve. If empty, will retrieve the folder "AllItems". | Optional |
is-public | Whether the folder is a Public Folder. Default is "False". | Optional |
Context Output
Path | Type | Description |
---|---|---|
EWS.Folders.id | string | Folder ID. |
EWS.Folders.name | string | Folder name. |
EWS.Folders.changeKey | string | Folder change key. |
EWS.Folders.totalCount | number | Total number of emails in the folder. |
EWS.Folders.childrenFolderCount | number | Number of sub-folders. |
EWS.Folders.unreadCount | number | Number of unread emails in the folder. |
Command Example
!ews-get-folder folder-path=demistoEmail target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
changeKey | childrenFolderCount | id | name | totalCount | unreadCount |
---|---|---|---|---|---|
***yFtCdJSH | 0 | AAMkADQ0NmFkODFkLWQ4MDEtNDE4Mi1hN2NlsjflsjfSF= | demistoEmail | 1 | 0 |
Context Example
{ "EWS": { "Folders": { "unreadCount": 0, "name": "demistoEmail", "childrenFolderCount": 0, "totalCount": 1, "changeKey": "***yFtCdJSH", "id": "AAMkADQ0NmFkODFkLWQ4MDEtNDE4Mi1hN2NlsjflsjfSF=" } } }
18. Initiate a compliance search
Starts a new compliance search. For additional information about new compliance searches, see the Additional Information section.
Required Permissions
You need to be assigned permissions in the Office 365 Security & Compliance Center before you can use these commands. For more information, see Permissions in Office 365 Security & Compliance Center .
Base Command
ews-o365-start-compliance-search
Input
Argument Name | Description | Required |
---|---|---|
query | Query to use to find emails. | Required |
Context Output
Path | Type | Description |
---|---|---|
EWS.ComplianceSearch.Name | string | The name of the compliance search. |
EWS.ComplianceSearch.Status | string | The status of the compliance search. |
Command Example
!ews-o365-start-compliance-search query="subject:"Wanted Email""
Human Readable Output
Search started: DemistoSearch67e67371d0004c46bebfa3219b5a14bf
Context Example
{ "EWS": { "ComplianceSearch": { "Status": "Starting", "Name": "DemistoSearch67e67371d0004c46bebfa3219b5a14bf" } } }
19. Get the status and results of a compliance search
Returns the status and results of a compliance search. For additional information about new compliance searches, see the Additional Information section.
Required Permissions
You need to be assigned permissions in the Office 365 Security & Compliance Center before you can use this cmdlet. For more information, see Permissions in Office 365 Security & Compliance Center .
Base Command
ews-o365-get-compliance-search
Input
Argument Name | Description | Required |
---|---|---|
search-name | The name of the compliance search. | Required |
Context Output
Path | Type | Description |
---|---|---|
EWS.ComplianceSearch.Status | Unknown | The status of the compliance search. |
Command Example
!ews-o365-get-compliance-search search-name=DemistoSearch67e67371d0004c46bebfa3219b5a14bf
Human Readable Output
Location | Item count | Total size |
---|---|---|
test@demistodev.onmicrosoft.com | 0 | 0 |
... |
Context Example
{ "EWS": { "ComplianceSearch": { "Status": "Completed", "Name": "DemistoSearch67e67371d0004c46bebfa3219b5a14bf" } } }
20. Purge compliance search results
Purges the results found in the compliance search. For additional information about new compliance searches, see the Additional Information section.
Required Permissions
You need to be assigned permissions in the Office 365 Security & Compliance Center before you can use this cmdlet. For more information, see Permissions in Office 365 Security & Compliance Center .
Base Command
ews-o365-purge-compliance-search-results
Input
Argument Name | Description | Required |
---|---|---|
search-name | The name of the compliance search. | Required |
Context Output
Path | Type | Description |
---|---|---|
EWS.ComplianceSearch.Status | string | The status of the compliance search. |
Command Example
!ews-o365-purge-compliance-search-results search-name=DemistoSearch67e67371d0004c46bebfa3219b5a14bf
Human Readable Output
Search DemistoSearch67e67371d0004c46bebfa3219b5a14bf status: Purging
Context Example
{ "EWS": { "ComplianceSearch": { "Status": "Purging", "Name": "DemistoSearch67e67371d0004c46bebfa3219b5a14bf" } } }
21. Remove a compliance search
Removes the compliance search. For additional information about new compliance searches, see the Additional Information section.
Required Permissions
You need to be assigned permissions in the Office 365 Security & Compliance Center before you can use this cmdlet. For more information, see Permissions in Office 365 Security & Compliance Center .
Base Command
ews-o365-remove-compliance-search
Input
Argument Name | Description | Required |
---|---|---|
search-name | The name of the compliance search. | Required |
Context Output
Path | Type | Description |
---|---|---|
EWS.ComplianceSearch.Status | string | The status of the compliance search. |
Command Example
!ews-o365-remove-compliance-search search-name=DemistoSearch67e67371d0004c46bebfa3219b5a14bf
Human Readable Output
Search DemistoSearch67e67371d0004c46bebfa3219b5a14bf status: Removed
Context Example
{ "EWS": { "ComplianceSearch": { "Status": "Removed", "Name": "DemistoSearch67e67371d0004c46bebfa3219b5a14bf" } } }
22. Get the purge status of a compliance search
Checks the status of the purge operation on the compliance search. For additional information about new compliance searches, see the Additional Information section.
Required Permissions
You need to be assigned permissions in the Office 365 Security & Compliance Center before you can use this cmdlet. For more information, see Permissions in Office 365 Security & Compliance Center .
Base Command
ews-o365-get-compliance-search-purge-status
Input
Argument Name | Description | Required |
---|---|---|
search-name | The name of the compliance search. | Required |
Context Output
Path | Type | Description |
---|---|---|
EWS.ComplianceSearch.Status | Unknown | The status of the compliance search. |
Command Example
!ews-o365-get-compliance-search-purge-status search-name=DemistoSearch67e67371d0004c46bebfa3219b5a14bf
Human Readable Output
Search DemistoSearch67e67371d0004c46bebfa3219b5a14bf status: Purged
Context Example
{ "EWS": { "ComplianceSearch": { "Status": "Purged", "Name": "DemistoSearch67e67371d0004c46bebfa3219b5a14bf" } } }
23. Get auto-discovery information
Returns the auto-discovery information. Can be used to manually configure the Exchange Server.
Base Command
ews-get-autodiscovery-config
Input
There are no input arguments for this command.
Context Output
There is no context output for this command.
Command Example
!ews-get-autodiscovery-config
Human Readable Output
api_version | auth_type | build | service_endpoint |
---|---|---|---|
Exchange2016 | ### | . .****.** | https://outlook.office365.com/EWS/Exchange.asmx |
24. Expand a distribution list
Expands a distribution list to display all members. By default, expands only the first layer of the distribution list. If recursive-expansion is "True", the command expands nested distribution lists and returns all members.
Required Permissions
Impersonation rights required. In order to perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
Base Command
ews-expand-group
Input
Argument Name | Description | Required |
---|---|---|
email-address | Email address of the group to expand. | Required |
recursive-expansion | Whether to enable recursive expansion. Default is "False". | Optional |
Context Output
There is no context output for this command.
Command Example
!ews-expand-group email-address="TestPublic" recursive-expansion="False"
Human Readable Output
displayName | mailbox | mailboxType |
---|---|---|
John Wick | john@wick.com | Mailbox |
Context Example
{ "EWS.ExpandGroup": { "name": "TestPublic", "members": [ { "mailboxType": "Mailbox", "displayName": "John Wick", "mailbox": "john@wick.com" } ] } }
25. Mark items as read
Marks items as read or unread.
Required Permissions
Impersonation rights are required. To perform actions on the target mailbox of other users, the service account must be part of the ApplicationImpersonation role.
Base Command
ews-mark-items-as-read
Input
Argument Name | Description | Required |
---|---|---|
item-ids | A CSV list of item IDs. | Required |
operation | How to mark the item. Can be "read" or "unread". Default is "read". | Optional |
target-mailbox | The mailbox on which to run the command. If empty, the command will be applied on the default mailbox. | Optional |
Context Output
Path | Type | Description |
---|---|---|
EWS.Items.action | String | The action that was performed on the item. |
EWS.Items.itemId | String | The ID of the item. |
EWS.Items.messageId | String | The message ID of the item. |
Command Example
!ews-mark-items-as-read item-ids=AAMkADQ0NFSffU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMnpkUAAAfxw+jAAA= operation=read target-mailbox=test@demistodev.onmicrosoft.com
Human Readable Output
action | itemId | messageId |
---|---|---|
marked-as-read | AAMkADQ0NFSffU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMnpkUAAAfxw+jAAA= | <message_id> |
Context Example
{ "EWS": { "Items": { "action": "marked-as-read", "itemId": "AAMkADQ0NFSffU3wX3aBwCyyVyFtlsUQZfBJebinpkUAAABjKMnpkUAAAfxw+jAAA= ", "messageId": "<message_id>" } } }### ews-get-items-as-eml *** Retrieves items by item ID and uploads it's content as eml file. #### Base Command `ews-get-items-as-eml` #### Input | **Argument Name** | **Description** | **Required** | | --- | --- | --- | | item-id | The item ID of item to upload as and EML file. | Required | | target-mailbox | The mailbox in which this email was found. If empty, the default mailbox is used. Otherwise the user might require impersonation rights to this mailbox. | Optional | #### Context Output | **Path** | **Type** | **Description** | | --- | --- | --- | | File.Size | String | The size of the file. | | File.SHA1 | String | The SHA1 hash of the file. | | File.SHA256 | String | The SHA256 hash of the file. | | File.SHA512 | String | The SHA512 hash of the file. | | File.Name | String | The name of the file. | | File.SSDeep | String | The SSDeep hash of the file. | | File.EntryID | String | EntryID of the file | | File.Info | String | Information about the file. | | File.Type | String | The file type. | | File.MD5 | String | The MD5 hash of the file. | | File.Extension | String | The extension of the file. |
Additional Information
EWS Permissions
To perform actions on mailboxes of other users, and to execute searches on the Exchange server, you need specific permissions. For a comparison between Delegate and Impersonation permissions, see the Microsoft documentation .
Permission | Use Case | How to Configure |
---|---|---|
Delegate | One-to-one relationship between users. | Read more here . |
Impersonation | A single account needs to access multiple mailboxes. | Read more here . |
eDiscovery | Search the Exchange server. | Read more here . |
Compliance Search | Perform searches across mailboxes and get an estimate of the results. | Read more here . |
New-Compliance Search
The EWS v2 integration uses remote ps-session to run commands of compliance search as part of Office 365. To check if your account can connect to Office 365 Security & Compliance Center via powershell, check the following
steps
. New-Compliance search is a long-running task which has no limitation of searched mailboxes and therefore the suggestion is to use
Office 365 Search and Delete
playbook. New-Compliance search returns statistics of matched content search query and doesn't return preview of found emails in contrast to
ews-search-mailboxes
command.