readme.html

<!-- File: readme.html
  Copyright (c) 2017-2022 Splunk Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
either express or implied. See the License for the specific language governing permissions
and limitations under the License.
-->

<h2>Playbook Backward Compatibility</h2>
<p>
  <ul>
    <li> 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.</li>
  </ul>
</p>

<p>
<h2>Authentication</h2>
This app requires registration of a Microsoft Graph Application. To do so, navigate to the URL <a href="https://portal.azure.com" target="_blank">https://portal.azure.com</a> in a browser and log in with the Microsoft account, then, click <b>App registrations</b>.
<br><br>
On the next page, select <b>New registration</b> and give your app a name.
<br><br>
Once the app is created, follow the below-mentioned steps:
<ul>
    <li>Under <b>Certificates & secrets</b> select <b>New client secret</b>. Enter the <b>Description</b> and select the desired duration in <b>Expires</b>. Click on <b>Add</b>. Note down this <b>value</b> somewhere secure, as it cannot be retrieved after closing the window.</li>
    <li>Under <b>Authentication</b>, select <b>Add a platform</b>. In the <b>Add a platform</b> window, select <b>Web</b>. The <b>Redirect URLs</b> should be filled right here. We will get <b>Redirect URLs</b> from the Splunk SOAR asset we create below in the section titled <b>Splunk SOAR Graph Asset</b>.</li>
    <li>Under <b>API Permissions</b> Click on <b>Add a permission</b>.</li>
    <li>Under the <b>Microsoft API</b> section, select <b>Microsoft Graph</b>.</li>
    <li>Provide the following Application permissions to the app:</li>
    <ul>
        <li>Mail.Read (https://graph.microsoft.com/Mail.Read)</li>
        <li>Mail.ReadWrite (https://graph.microsoft.com/Mail.ReadWrite)</li>
        <li>User.Read.All (https://graph.microsoft.com/User.Read.All)</li>
            <ul><li>For non-admin access, use User.Read (Delegated permission) instead (https://graph.microsoft.com/User.Read)</li></ul>
        <li>Group.Read.All (https://graph.microsoft.com/Group.Read.All) - It is required only if you want to run the <b>list events</b> action for the group's calendar and for the <b>list groups</b> and the <b>list group members</b> action.</li>
        <li>Calendar.Read (https://graph.microsoft.com/Calendars.Read) - It is required only if you want to run the <b>list events</b> action for the user's calendar.</li>
        <li>Calendars.ReadWrite (https://graph.microsoft.com/Calendars.ReadWrite) - It is required only if you want to run the <b>delete event</b> action from the user's calendar.</li></li>
        <li>MailboxSettings.Read (https://graph.microsoft.com/MailboxSettings.Read) - It is required only if you want to run the <b>oof status</b> action.</li>
    </ul>
</ul>
After making these changes, click <b>Add permissions</b>, then select <b>Grant admin consent for &lt;your_organization_name_as_on_azure_portal&gt;</b> at the bottom of the screen.
<h2>Splunk SOAR Graph Asset</h2>
When creating an asset for the <b>MS Graph for Office 365</b> app, place <b>Application ID</b> of the app created during the app registration on the Azure Portal in the <b>Application ID</b> field and place the client secret generated during the app registration process in the <b>Application Secret</b> field. Then, after filling out the <b>Tenant</b> field, click <b>SAVE</b>. Both the Application/Client ID and the Tenant ID can be found in the <b>Overview</b> tab on your app's Azure page.
<br><br>
After saving, a new field will appear in the <b>Asset Settings</b> tab. Take the URL found in the <b>POST incoming for MS Graph for Office 365 to this location</b> field and place it in the <b>Redirect URLs</b> field mentioned in the previous step. To this URL, add <b>/result</b>. After doing so the URL should look something like:
<br><br>
<p>
https://&lt;splunk_soar_host&gt;/rest/handler/msgraphforoffice365_0a0a4087-10e8-4c96-9872-b740ff26d8bb/&lt;asset_name&gt;/result
</p>
<br>
Once again, click SAVE at the bottom of the screen.
<br><br>
Additionally, updating the Base URL in the Company Settings is also required. Navigate to <b>Administration > Company Settings > Info</b> to configure the <b>Base URL For Splunk SOAR</b>. Then, select <b>Save Changes</b>.
<br><br>

<h2>User Permissions</h2>
To complete the authorization process, this app needs permission to view assets, which is not granted by default. First, navigate to <b>Asset Settings > Advanced</b>, to check which user is listed under <b>Select a user on behalf of which automated actions can be executed</b>. By default, the user will be <b>automation</b>, but this user can be changed by clicking <b>EDIT</b> at the bottom of the window. To give this user permission to view assets, follow these steps:
<ul>
    <li>In the main drop-down menu, select <b>Administration</b>, then select the <b>User Management</b>, and under that tab, select <b>Roles & Permissions</b>. Finally, click <b>+ ROLE</b>.</li>
    <li>In the <b>Add Role</b> wizard, give the role a name (e.g <b>Asset Viewer</b>), and provide a description. Subsequently, under the <b>Users tab</b>, click <b>ADD USERS</b> to add the user assigned to the asset viewed earlier. Then click the <b>Permissions</b> tab.</li>
    <li>In the permission tab, under <b>Basic Permissions</b>, give the role the <b>View Assets</b> privilege. Then click <b>SAVE</b>.</li>
</ul>

<h3>Test connectivity</h3>

<h4>Admin User Workflow</h4>
<ul>
  <li>Configure the asset with required details while keeping the <b>Admin Access Required</b> as checked.</li>
  <li>While configuring the asset for the first time, keep <b>Admin Consent Already Provided</b> as unchecked.</li>
  <li>The <b>Redirect URLs</b> must be configured before executing test connectivity. To configure <b>Redirect URLs</b>, checkout the section titled <b>Splunk SOAR Graph Asset</b> above.</li>
  <li>After setting up the asset and user, click the <b>TEST CONNECTIVITY</b> button.</li>
  <li>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.</li>
  <li>Log in to the Microsoft account with the admin user.</li>
  <li>You will be prompted to agree to the permissions requested by the App.</li>
  <li>Review the requested permissions listed, then click <b>Accept</b>.</li>
  <li>If all goes well the browser should instruct you to close the tab.</li>
  <li>Now go back and check the message on the Test Connectivity dialog box, it should say <b>Test Connectivity Passed</b>.</li>
  <li>For subsequent test connectivity or action runs, you can keep <b>Admin Consent Already Provided</b> config parameter as checked. This will skip the interactive flow and use the client credentials for generating tokens.
</ul>

<h4>Non-Admin User Workflow</h4>
<ul>
  <li>Configure the asset with required details while keeping the <b>Admin Access Required</b> as unchecked. <b>Admin Consent Already Provided</b> config parameter will be ignored in the non-admin workflow.</li>
  <li>Provide <b>Access Scope</b> parameter in the asset configuration. All the actions will get executed according to the scopes provided in the <b>Access Scope</b> config parameter.</li>
  <li>The <b>Redirect URLs</b> must be configured before executing test connectivity. To configure <b>Redirect URLs</b>, checkout the section titled <b>Splunk SOAR Graph Asset</b> above.</li>
  <li>After setting up the asset and user, click the <b>TEST CONNECTIVITY</b> button.</li>
  <li>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.</li>
  <li>Log in to the Microsoft account.</li>
  <li>You will be prompted to agree to the permissions requested by the App.</li>
  <li>Review the requested permissions listed, then click <b>Accept</b>.</li>
  <li>If all goes well the browser should instruct you to close the tab.</li>
  <li>Now go back and check the message on the Test Connectivity dialog box, it should say <b>Test Connectivity Passed</b>.</li>
</ul>
<br><br>
The app should now be ready to be used.
<br />
<h3>On-Poll</h3>
    <b>Configuration:</b><br>
    <ul>
      <li>email_address - Ingest from the provided email address. </li>
      <li>folder - To fetch the emails from the given folder name (must be provided if running ingestion) </li>
      <li>get_folder_id - Retrieve the folder ID for the provided folder name/folder path automatically and replace the folder parameter value.</li>
      <li>first_run_max_emails - Maximum containers to poll for the first scheduled polling (default - 1000).</li>
      <li>max_containers - Maximum containers to poll after the first scheduled poll completes (default - 100).</li>
      <li>extract_attachments - Extract all the attachments included in emails.</li>
      <li>extract_urls - Extracts the URLs present in the emails.</li>
      <li>extract_ips - Extracts the IP addresses present in the emails.</li>
      <li>extract_domains - Extract the domain names present in the emails.</li>
      <li>extract_hashes - Extract the hashes present in the emails (MD5).</li>
      <li>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.</li>
    </ul>
    <p>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.</p>
<h2>Guidelines to provide folder parameter value</h2>
<p>This is applicable to 'on poll', 'copy email', 'move email', and 'run query' actions.</p>
<ul>
  <li>
    The <b>get_folder_id</b> parameter should be enabled only when you have specified folder name/folder path in the <b>folder</b> parameter.
  </li>
  <li>
    If you provide folder ID in the <b>folder</b> parameter and set <b>get_folder_id</b> 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).
  </li>
  <li>
    The <b>folder</b> parameter must be either a (case sensitive) well-known name (<a href="https://docs.microsoft.com/en-us/graph/api/resources/mailfolder?view=graph-rest-1.0" target="_blank">https://docs.microsoft.com/en-us/graph/api/resources/mailfolder?view=graph-rest-1.0</a>) or the internal o365 folder ID.
  </li>
  <li>
    The folder parameter supports nested folder paths. To specify the complete folder path using the <b>'/'</b> (forward slash) as the separator.<br>e.g. to specify a folder named <i>phishing</i> which is nested within (is a child of) <i>Inbox</i>, set the value as <b>Inbox/phishing</b>. If a folder name has a literal forward slash('/') in the name escape it with a backslash('\\') to differentiate.
  </li>
</ul>

<h2>State file permissions</h2>
  <p>
    Please check the permissions for the state file as mentioned below.
    <h4>State file path</h4>
    <ul>
      <li>For Non-NRI instance: /opt/phantom/local_data/app_states/&lt;appid&gt;/&lt;asset_id&gt;_state.json</li>
      <li>For NRI instance: /&lt;PHANTOM_HOME_DIRECTORY&gt;/local_data/app_states/&lt;appid&gt;/&lt;asset_id&gt;_state.json</li>
    </ul>
    <h4>State file permissions</h4>
    <ul>
      <li>File rights: rw-rw-r-- (664) (The Splunk SOAR user should have read and write access for the state file)</li>
      <li>File owner: Appropriate Splunk SOAR user</li>
    </ul>
  </p>

<h3>Note</h3>
<ul>
    <li>An optional parameter <b>Admin Access Required</b> 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 <b>list events</b> functionality. If unchecked, the <b>Access scope</b> <em>must</em> be used. The default scope will work for listing calendar events. Additional information on scope can be found <a href="https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent#openid-connect-scopes" target="_blank">here.</a></li>
    <li>As per the Microsoft known issues for <b>Group.Read.All</b> permission (<a href="https://docs.microsoft.com/en-us/graph/known-issues#groups" target="_blank">here</a>), if you want to run the <b>list events</b> for fetching group's calendar events, you have to uncheck an optional parameter <b>Admin Access Required</b> and provide <b>Group.Read.All (https://graph.microsoft.com/Group.Read.All)</b> permission into the scope parameter in the asset configuration parameters. If an asset parameter <b>Admin Access Required</b> checked and configured the app with above mentioned all the application permissions (which includes <b>Group.Read.All</b> application permission), it throws an error like <b>Access is denied</b> while running <b>list events</b> action for fetching group's calendar events. Because of the known issue of <b>Group.Read.All</b> application permission, this permission required admin consent (on behalf of the user permission) to fetch the group's calendar events.</li>
    <li>If the parameter <b>Admin Access Required</b> is unchecked, you have to provide a <b>scope</b> parameter in the asset configuration. All the actions will get executed according to the scopes provided in the <b>scope</b> config parameter. The actions will throw an appropriate error if the scope of the corresponding permission is not provided by the end-user.</li>
    <li>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.</li>
    <li>The sensitive values are stored encrypted in the state file.</li>
</ul>
</p>

<h2>Port Details</h2>
<p>
  The app uses HTTP/ HTTPS protocol for communicating with the Office365 server. Below are the default ports used by the Splunk SOAR Connector.
  <table>
      <tr>
          <th>Service Name</th>
          <th>Transport Protocol</th>
          <th>Port</th>
      </tr>
      <tr>
          <td>http</td>
          <td>tcp</td>
          <td>80</td>
      </tr>
      <tr>
          <td>https</td>
          <td>tcp</td>
          <td>443</td>
      </tr>
  </table>
</p>