O365 - EWS - Extension
EWS Pack.#
This Integration is part of theSupported versions
Supported Cortex XSOAR versions: 5.5.0 and later.
This integration enables you to manage and interact with Microsoft O365 - Exchange Online from within XSOAR. This integration was integrated and tested with version V1 of Exchange Online PowerShell.
#
Enable or disable access to Exchange Online PowerShellExchange Online PowerShell enables you to manage your Exchange Online organization from the command line. By default, all accounts you create in Microsoft 365 are allowed to use Exchange Online PowerShell. Administrators can use Exchange Online PowerShell to enable or disable a user's ability to connect to Exchange Online PowerShell. Note that access to Exchange Online PowerShell doesn't give users extra administrative powers in your organization. A user's capabilities in Exchange Online PowerShell are still defined by a role based access control (RBAC) and the roles that are assigned to them.
For more info
#
Configure O365 - EWS - Extension on Cortex XSOARNavigate to Settings > Integrations > Servers & Services.
Search for O365 - EWS - Extension.
Authentication / Authorization methods:
OAuth2.0 authorization (recommended):
Click Add an instance to create and configure a new integration instance.
Parameter Description Required url Echange online URL True credentials Fill only Email (aka UPN), Password should be empty. False insecure Trust any certificate (not secure) False Open playground - War-room:
- Run the !ews-auth-start command and follow the instructions. Expected output is:
#
EWS extension - Authorize instructions- To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code XXXXXXX to authenticate.
- Run the command !ews-auth-complete command in the War Room.
- Test - OAuth2.0 authorization, Run the !ews-auth-test command.
Basic authentication (Not recommended):
Click Add an instance to create and configure a new integration instance.
Parameter Description Required url Search and Compliance URL True credentials Fill Email (aka UPN) and password False insecure Trust any certificate (not secure) False Click Test to validate the URLs, token, and connection.
#
CommandsYou 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.
#
ews-auth-startOAuth2.0 - Start authorization.
#
Base Commandews-auth-start
#
InputThere are no input arguments for this command.
#
Context OutputThere is no context output for this command.
#
Command Example!ews-auth-start
#
Human Readable Output#
EWS extension - Authorize instructions
- To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code XXXXXXX to authenticate.
- Run the !ews-auth-complete command in the War Room.
#
ews-auth-completeCompletes the OAuth2.0 authorization process.
#
Base Commandews-auth-complete
#
InputThere are no input arguments for this command.
#
Context OutputThere is no context output for this command.
#
Command Example!ews-auth-complete
#
Human Readable OutputYour account successfully authorized!
#
ews-auth-testTests the OAuth2.0 authorization process.
#
Base Commandews-auth-test
#
InputThere are no input arguments for this command.
#
Context OutputThere is no context output for this command.
#
Command Example!ews-auth-test
#
Human Readable OutputTest ok!
#
ews-junk-rules-getGets junk rules for the specified mailbox.
#
Base Commandews-junk-rules-get
#
InputArgument Name | Description | Required |
---|---|---|
mailbox | ID of the mailbox for which to get junk rules. | Required |
#
Context OutputPath | Type | Description |
---|---|---|
EWS.Rule.Junk.BlockedSendersAndDomains | String | Blocked senders and domains list. |
EWS.Rule.Junk.ContactsTrusted | Boolean | If true, contacts are trusted by default. |
EWS.Rule.Junk.Email | String | Junk rule mailbox. |
EWS.Rule.Junk.Enabled | Boolean | If true, junk rule is enabled. |
EWS.Rule.Junk.Identity | String | Junk rule identity. |
EWS.Rule.Junk.MailboxOwnerId | String | Mail box owner ID. |
EWS.Rule.Junk.TrustedListsOnly | Boolean | If true, only a list defined in the trusted lists are trusted. |
EWS.Rule.Junk.TrustedRecipientsAndDomains | String | List of trusted recipients and domains. |
EWS.Rule.Junk.TrustedSendersAndDomains | String | List of trusted senders and domains. |
#
Command Example!ews-junk-rules-get mailbox="xsoar@dev.onmicrosoft.com"
#
Context Example#
Human Readable Outputxsoar@dev.onmicrosoft.com' Junk rules#
EWS extension - '
BlockedSendersAndDomains ContactsTrusted Enabled TrustedListsOnly TrustedSendersAndDomains ["user1@gmail.com","user2@gmail.com"] False False False ["user1@gmail.com","user2@gmail.com"]
#
ews-junk-rules-setSets junk rules for the specified mailbox.
#
Base Commandews-junk-rules-set
#
InputArgument Name | Description | Required |
---|---|---|
mailbox | ID of the mailbox for which to set junk rules. | Required |
add_blocked_senders_and_domains | Comma-separated list of blocked senders and domains to add to the mailbox. | Optional |
remove_blocked_senders_and_domains | Comma-separated list of blocked senders and domains to remove from the mailbox. | Optional |
add_trusted_senders_and_domains | Comma-separated list of trusted senders and domains to add to the mailbox. | Optional |
remove_trusted_senders_and_domains | Comma-separated list of trusted senders and domains to remove from the mailbox. | Optional |
trusted_lists_only | If true, trust only lists defined in the trusted lists. Can be "true" or "false". Possible values are: true, false. | Optional |
contacts_trusted | If true, contacts are trusted by default. Can be "true" or "false". Possible values are: true, false. | Optional |
enabled | If true, the junk rule is enabled. Can be "true" or "false". Possible values are: true, false. | Optional |
#
Context OutputThere is no context output for this command.
#
Command Example!ews-junk-rules-set mailbox="xsoar@dev.onmicrosoft.com" add_blocked_senders_and_domains="test@gmail.com" add_trusted_senders_and_domains="dev.onmicrosoft.com"
#
Human Readable OutputEWS extension - 'xsoar@dev.onmicrosoft.com' Junk rules modified!
#
ews-global-junk-rules-setSets junk rules in all managed accounts.
#
Base Commandews-global-junk-rules-set
#
InputArgument Name | Description | Required |
---|---|---|
add_blocked_senders_and_domains | Comma-separated list of blocked senders and domains to add to the mailbox. | Optional |
remove_blocked_senders_and_domains | Comma-separated list of blocked senders and domains to remove from the mailbox. | Optional |
add_trusted_senders_and_domains | Comma-separated list of trusted senders and domains to add to the mailbox. | Optional |
remove_trusted_senders_and_domains | Comma-separated list of trusted senders and domains to remove from the mailbox. | Optional |
trusted_lists_only | If true, trust only lists defined in the trusted lists. Can be "true" or "false". Possible values are: true, false. | Optional |
contacts_trusted | If true, contacts are trusted by default. Can be "true" or "false". Possible values are: true, false. | Optional |
enabled | If true, the junk rule is enabled. Can be "true" or "false". Possible values are: true, false. | Optional |
#
Context OutputThere is no context output for this command.
#
Command Example!ews-global-junk-rules-set add_blocked_senders_and_domains="test@demisto.com" add_trusted_senders_and_domains="demisto.com"
#
Human Readable OutputEWS extension - Junk rules globally modified!
#
ews-message-trace-getSearches message data for the last 10 days. If you run this command without any arguments, only data from the last 48 hours is returned. If you enter a start date that is older than 10 days, you will receive an error and the command will return no results. This command returns a maximum of 1,000,000 results, and will timeout on very large queries. If your query returns too many results, consider splitting it up using shorter start_date and end_date intervals.
#
Base Commandews-message-trace-get
#
InputArgument Name | Description | Required |
---|---|---|
sender_address | The sender_address parameter filters the results by the sender's email address. You can specify multiple values separated by commas. . | Optional |
recipient_address | The recipient_address parameter filters the results by the recipient's email address. You can specify multiple values separated by commas. . | Optional |
from_ip | The from_ip parameter filters the results by the source IP address. For incoming messages, the value of from_ip is the public IP address of the SMTP email server that sent the message. For outgoing messages from Exchange Online, the value is blank. . | Optional |
to_ip | The to_ip parameter filters the results by the destination IP address. For outgoing messages, the value of to_ip is the public IP address in the resolved MX record for the destination domain. For incoming messages to Exchange Online, the value is blank. . | Optional |
message_id | The message_id parameter filters the results by the Message-ID header field of the message. This value is also known as the Client ID. The format of the Message-ID depends on the messaging server that sent the message. The value should be unique for each message. However, not all messaging servers create values for the Message-ID in the same way. Be sure to include the full Message ID string (which may include angle brackets) and enclose the value in quotation marks (for example,"d9683b4c-127b-413a-ae2e-fa7dfb32c69d@DM3NAM06BG401.Eop-nam06.prod.protection.outlook.com"). . | Optional |
message_trace_id | The message_trace_id parameter can be used with the recipient address to uniquely identify a message trace and obtain more details. A message trace ID is generated for every message that's processed by the system. . | Optional |
page | The page number of the results you want to view. Can be an integer between 1 and 1000. The default value is 1. . Default is 1. | Optional |
page_size | The maximum number of entries per page. Can be an integer between 1 and 5000. The default value is 100. . Default is 100. | Optional |
start_date | The start date of the date range. Use the short date format that's defined in the Regional Options settings on the computer where you're running the command. For example, if the computer is configured to use the short date format mm/dd/yyyy, enter 09/01/2018 to specify September 1, 2018. You can enter the date only, or you can enter the date and time of day. If you enter the date and time of day, enclose the value in quotation marks ("), for example, "09/01/2018 5:00 PM". Valid input for this parameter is from 10 days - now ago. The default value is 48 hours ago. . | Optional |
end_date | The end date of the date range. Use the short date format that's defined in the Regional Options settings on the computer where you're running the command. For example, if the computer is configured to use the short date format mm/dd/yyyy, enter 09/01/2018 to specify September 1, 2018. You can enter the date only, or you can enter the date and time of day. If you enter the date and time of day, enclose the value in quotation marks ("), for example, "09/01/2018 5:00 PM". Valid input for this parameter is from start_date - now. The default value is now. . | Optional |
status | The status of the message. Can be one of the following: GettingStatus: The message is waiting for status update. Failed: Message delivery was attempted and it failed or the message was filtered as spam or malware, or by transport rules. Pending: Message delivery is underway or was deferred and is being retried. Delivered: The message was delivered to its destination. Expanded: There was no message delivery because the message was addressed to a distribution group and the membership of the distribution was expanded. Quarantined: The message was quarantined. * FilteredAsSpam: The message was marked as spam. . Possible values are: GettingStatus, Failed, Pending, Delivered, Expanded, Quarantined, FilteredAsSpam. | Optional |
#
Context OutputPath | Type | Description |
---|---|---|
EWS.MessageTrace.FromIP | String | The public IP address of the SMTP email server that sent the message. |
EWS.MessageTrace.ToIP | String | The public IP address in the resolved MX record for the destination domain. For incoming messages to Exchange Online, the value is blank. |
EWS.MessageTrace.Index | Number | Message index in pagination. (Index starts from 0) |
EWS.MessageTrace.MessageId | String | Message-ID header field of the message. |
EWS.MessageTrace.MessageTraceId | String | Message trace ID of the message. |
EWS.MessageTrace.Organization | String | Message trace organization source. |
EWS.MessageTrace.Received | Date | Message receive time. |
EWS.MessageTrace.RecipientAddress | String | Message recipients address. |
EWS.MessageTrace.SenderAddress | String | Message sender address. |
EWS.MessageTrace.Size | Number | Message size in bytes. |
EWS.MessageTrace.StartDate | Date | Message trace start date. |
EWS.MessageTrace.EndDate | Date | Message trace end date. |
EWS.MessageTrace.Status | String | Message status. |
EWS.MessageTrace.Subject | String | Message subject. |
#
Command Example!ews-message-trace-get
#
Context Example#
Human Readable Output#
EWS extension - Messages trace
EndDate FromIP Index MessageId MessageTraceId Organization Received RecipientAddress SenderAddress Size StartDate Status Subject ToIP 1/3/2021 6:14:14 AM 8.8.8.8 0 xxx xxxx microsoft.com 1/3/2021 4:45:36 AM xsoar@dev.microsoft.com xsoar@dev.onmicrosoft.com 6975 1/1/2021 6:14:14 AM Delivered Test mail 1/3/2021 6:15:14 AM 8.8.8.8 1 xxx xxxx microsoft.com 1/3/2021 4:46:36 AM xsoar@dev.microsoft.com xsoar@dev.onmicrosoft.com 6975 1/1/2021 6:15:14 AM Delivered Test mail