manual_readme_content.md

Playbook Backward Compatibility

• With version 3.0.0 of the connector, the 'group_id' parameter of the 'list group members' action has been removed and two new parameters are added in the same action as follows:

  • method - Method(Group ID or Group e-mail) using which you want to list group members, by default it is Group ID.
  • identificator - Value of group id or group e-mail based on the method selected.

  Hence, it is requested to please update the existing playbooks by re-inserting | modifying | deleting the corresponding action blocks to ensure the correct functioning of the playbooks created on the earlier versions of the app.

• The 'id' field of email artifact has been renamed to 'messageId'. Hence, it is requested to the end-user to please update their existing playbooks by re-inserting | modifying | deleting the corresponding action blocks to ensure the correct functioning of the playbooks created on the earlier versions of the app.

Authentication

This app requires registration of a Microsoft Graph Application. To do so, navigate to the URL https://portal.azure.com in a browser and log in with the Microsoft account, then, click App registrations .

On the next page, select New registration and give your app a name.

Once the app is created, follow the below-mentioned steps:

• Under Certificates & secrets select New client secret . Enter the Description and select the desired duration in Expires . Click on Add . Note down this value somewhere secure, as it cannot be retrieved after closing the window.

• Under Authentication , select Add a platform . In the Add a platform window, select Web . The Redirect URLs should be filled right here. We will get Redirect URLs from the Splunk SOAR asset we create below in the section titled Splunk SOAR Graph Asset .

• Under API Permissions Click on Add a permission .

• Under the Microsoft API section, select Microsoft Graph .

• Provide the following Application permissions to the app:

  • Mail.Read (https://graph.microsoft.com/Mail.Read)

  • Mail.ReadWrite (https://graph.microsoft.com/Mail.ReadWrite)

  • User.Read.All (https://graph.microsoft.com/User.Read.All)

    • For non-admin access, use User.Read (Delegated permission) instead (https://graph.microsoft.com/User.Read)

  • Mail.Send (https://graph.microsoft.com/Mail.Send) - It is required only if you want to run the send email action.

  • Group.Read.All (https://graph.microsoft.com/Group.Read.All) - It is required only if you want to run the list events action for the group's calendar and for the list groups and the list group members action.

  • Calendar.Read (https://graph.microsoft.com/Calendars.Read) - It is required only if you want to run the list events action for the user's calendar.

  • Calendars.ReadWrite (https://graph.microsoft.com/Calendars.ReadWrite) - It is required only if you want to run the delete event action from the user's calendar.

  • MailboxSettings.Read (https://graph.microsoft.com/MailboxSettings.Read) - It is required only if you want to run the oof status , list rules and get rule actions.

After making these changes, click Add permissions , then select Grant admin consent for <your_organization_name_as_on_azure_portal> at the bottom of the screen.

Splunk SOAR Graph Asset

When creating an asset for the MS Graph for Office 365 app, place Application ID of the app created during the app registration on the Azure Portal in the Application ID field and place the client secret generated during the app registration process in the Application Secret field. Then, after filling out the Tenant field, click SAVE . Both the Application/Client ID and the Tenant ID can be found in the Overview tab on your app's Azure page.

After saving, a new field will appear in the Asset Settings tab. Take the URL found in the POST incoming for MS Graph for Office 365 to this location field and place it in the Redirect URLs field mentioned in the previous step. To this URL, add /result . After doing so the URL should look something like:

https://<splunk_soar_host>/rest/handler/msgraphforoffice365_0a0a4087-10e8-4c96-9872-b740ff26d8bb/<asset_name>/result

Once again, click SAVE at the bottom of the screen.

Additionally, updating the Base URL in the Company Settings is also required. Navigate to Administration > Company Settings > Info to configure the Base URL For Splunk SOAR . Then, select Save Changes .

User Permissions

To complete the authorization process, this app needs permission to view assets, which is not granted by default. First, navigate to Asset Settings > Advanced , to check which user is listed under Select a user on behalf of which automated actions can be executed . By default, the user will be automation , but this user can be changed by clicking EDIT at the bottom of the window. To give this user permission to view assets, follow these steps:

• In the main drop-down menu, select Administration , then select the User Management , and under that tab, select Roles & Permissions . Finally, click + ROLE .
• In the Add Role wizard, give the role a name (e.g Asset Viewer ), and provide a description. Subsequently, under the Users tab , click ADD USERS to add the user assigned to the asset viewed earlier. Then click the Permissions tab.
• In the permission tab, under Basic Permissions , give the role the View Assets privilege. Then click SAVE .

Test connectivity

Admin User Workflow

• Configure the asset with required details while keeping the Admin Access Required as checked.
• While configuring the asset for the first time, keep Admin Consent Already Provided as unchecked.
• The Redirect URLs must be configured before executing test connectivity. To configure Redirect URLs , checkout the section titled Splunk SOAR Graph Asset above.
• After setting up the asset and user, click the TEST CONNECTIVITY button.
• A window should pop up and display a URL. You will be asked to open the link in a new tab. Open the link in the same browser so that you are logged into Splunk SOAR for the redirect. If you wish to use a different browser, log in to the Splunk SOAR first, and then open the provided link. This new tab will redirect to the Microsoft login page.
• Log in to the Microsoft account with the admin user.
• You will be prompted to agree to the permissions requested by the App.
• Review the requested permissions listed, then click Accept .
• If all goes well the browser should instruct you to close the tab.
• Now go back and check the message on the Test Connectivity dialog box, it should say Test Connectivity Passed .
• For subsequent test connectivity or action runs, you can keep Admin Consent Already Provided config parameter as checked. This will skip the interactive flow and use the client credentials for generating tokens.

Non-Admin User Workflow

• Configure the asset with required details while keeping the Admin Access Required as unchecked. Admin Consent Already Provided config parameter will be ignored in the non-admin workflow.
• Provide Access Scope parameter in the asset configuration. All the actions will get executed according to the scopes provided in the Access Scope config parameter.
• The Redirect URLs must be configured before executing test connectivity. To configure Redirect URLs , checkout the section titled Splunk SOAR Graph Asset above.
• After setting up the asset and user, click the TEST CONNECTIVITY button.
• A window should pop up and display a URL. You will be asked to open the link in a new tab. Open the link in the same browser so that you are logged into Splunk SOAR for the redirect. If you wish to use a different browser, log in to the Splunk SOAR first, and then open the provided link. This new tab will redirect to the Microsoft login page.
• Log in to the Microsoft account.
• You will be prompted to agree to the permissions requested by the App.
• Review the requested permissions listed, then click Accept .
• If all goes well the browser should instruct you to close the tab.
• Now go back and check the message on the Test Connectivity dialog box, it should say Test Connectivity Passed .

The app should now be ready to be used.

On-Poll

Configuration:

• email_address - Ingest from the provided email address.
• folder - To fetch the emails from the given folder name (must be provided if running ingestion)
• get_folder_id - Retrieve the folder ID for the provided folder name/folder path automatically and replace the folder parameter value.
• first_run_max_emails - Maximum containers to poll for the first scheduled polling (default - 1000).
• max_containers - Maximum containers to poll after the first scheduled poll completes (default - 100).
• extract_attachments - Extract all the attachments included in emails.
• extract_urls - Extracts the URLs present in the emails.
• extract_ips - Extracts the IP addresses present in the emails.
• extract_domains - Extract the domain names present in the emails.
• extract_hashes - Extract the hashes present in the emails (MD5).
• ingest_eml - Fetch the EML file content for the 'item attachment' and ingest it into the vault. This will only ingest the first level 'item attachment' as an EML file. The nested item attachments will not be ingested into the vault. If the extract_attachments flag is set to false, then the application will also skip the EML file ingestion regardless of this flag value.
• extract_eml - When polling is on and extract_eml is enabled, it will add the eml files of the root email in the vault.

If extract_attachments is set to true, only fileAttachment will be ingested. If both ingest_eml and extract_attachments are set to true, then both fileAttachment and itemAttachment will be ingested.

Guidelines to provide folder parameter value

This is applicable to 'on poll', 'copy email', 'move email', and 'run query' actions.

• The get_folder_id parameter should be enabled only when you have specified folder name/folder path in the folder parameter.
• If you provide folder ID in the folder parameter and set get_folder_id parameter to true, it will throw an error of folder ID not found for given folder name (because the action considers folder parameter value as folder name/folder path).
• The folder parameter must be either a (case sensitive) well-known name ( https://docs.microsoft.com/en-us/graph/api/resources/mailfolder?view=graph-rest-1.0 ) or the internal o365 folder ID.
• The folder parameter supports nested folder paths. To specify the complete folder path using the '/' (forward slash) as the separator.
  e.g. to specify a folder named phishing which is nested within (is a child of) Inbox , set the value as Inbox/phishing . If a folder name has a literal forward slash('/') in the name escape it with a backslash('\\') to differentiate.

State file permissions

Please check the permissions for the state file as mentioned below.

State file path

• For unprivileged instance: /<PHANTOM_HOME_DIRECTORY>/local_data/app_states/<appid>/<asset_id>_state.json

State file permissions

• File rights: rw-rw-r-- (664) (The Splunk SOAR user should have read and write access for the state file)
• File owner: Appropriate Splunk SOAR user

Note

• An optional parameter Admin Access Required has been added to this app. In most cases, this should remain checked, as admin access is required for email use cases. If the desired integration is to integrate with only one user's calendar, you may consider unchecking this box. If unchecked, it allows a non-admin user to provide access to a specific account. This functionality will ONLY work with the list events functionality. If unchecked, the Access scope must be used. The default scope will work for listing calendar events. Additional information on scope can be found here.
• As per the Microsoft known issues for Group.Read.All permission ( here ), if you want to run the list events for fetching group's calendar events, you have to uncheck an optional parameter Admin Access Required and provide Group.Read.All (https://graph.microsoft.com/Group.Read.All) permission into the scope parameter in the asset configuration parameters. If an asset parameter Admin Access Required checked and configured the app with above mentioned all the application permissions (which includes Group.Read.All application permission), it throws an error like Access is denied while running list events action for fetching group's calendar events. Because of the known issue of Group.Read.All application permission, this permission required admin consent (on behalf of the user permission) to fetch the group's calendar events.
• If the parameter Admin Access Required is unchecked, you have to provide a scope parameter in the asset configuration. All the actions will get executed according to the scopes provided in the scope config parameter. The actions will throw an appropriate error if the scope of the corresponding permission is not provided by the end-user.
• There is an API limitation that will affect run_query action when providing Unicode values in the subject or in the body as parameters and if the result count exceeds 999, the action will fail.
• The sensitive values are stored encrypted in the state file.

Increase the maximum limit for ingestion

The steps are as follows:

1. Open the /opt/phantom/usr/nginx/conf/conf.d/phantom-nginx-server.conf file on the SOAR instance.
2. Change that value of the client_max_body_size variable as per your needs.
3. Save the configuration file.
4. Reload nginx service using service nginx reload or try restarting the nginx server from SOAR platform: Go to Administrator->System Health-> System Health then restart the nginx server.

Port Details

The app uses HTTP/ HTTPS protocol for communicating with the Office365 server. Below are the default ports used by the Splunk SOAR Connector.

Service Name	Transport Protocol	Port
http	tcp	80
https	tcp	443