Email Intake Connector#

This documentation outlines the utilization of the Email Intake Connector for automatically generating alerts from a designated mailbox.

The Email Intake Connector facilitates the connection of mailboxes used to receive cybersecurity alerts. It automatically transforms new emails into alerts within TheHive platform. Presently, the primary function supported is the creation of alerts regardless of the received email content.

Configuration#

Global Configuration#

The only parameter that requires adjustment is the refresh interval. By default, the connector polls mailboxes every 5 minutes. Adjust the frequency by increasing or decreasing the value.

Adding a Mailbox#

Configuration options are available for Microsoft 365 (OAuth2) and Google Workspace (OAuth2). If you use another email provider service, configuration through IMAP is necessary.

Microsoft MS365Google WorkspaceIMAP Mailbox

Setting up Microsoft365 for TheHive#

This section provides detailed instructions to configure Microsoft 365 to allow TheHive access to a shared mailbox. Please follow these steps to ensure proper integration.

Prerequisites#

Administrator account on Microsoft 365.
PowerShell installed and configured.
A shared mailbox already created in Microsoft 365 (e.g., test-shared-mailbox@strangebee.com).

Step-by-Step Configuration#

Create a Mail-Enabled Security Group
- Create a security group that includes the shared mailbox. This group will be used to restrict access to the application for the shared mailbox only.
- Navigate to Admin > Exchange Admin Center, and create a Mail-Enabled Security Group.
- Add the shared mailbox as a member of the security group.
Register a New Application in Microsoft Entra
- As an administrator, navigate to Microsoft Entra admin center.
- Go to Admin > Identity > Applications > App registrations.
- Gather the following information:
  - Tenant ID
  - Client ID (App ID)
  - Object ID of the enterprise application
Create a Secret for the Application
- In the registered application page, go to Certificates & Secrets.
- Create a new secret, which will be used as an OAuth2 input to authenticate the service.
- Save the secret value securely for later use.
Assign API Permissions
- In the registered application page, go to API Permissions.
- Ensure the application has the following permissions:
  - Office 365 Exchange Online / IMAP.AccessAsApp

Configure PowerShell Access

Define the necessary values for the configuration:

$AppID = '{ClientID}'
$TenantID = '{TenantID}'
$ObjectID = '{ObjectID}'
$SecurityGroup = '{SecurityGroup}'  # The mail-enabled security group
$MailBox = '{MailBox}'  # The shared mailbox

Run the following PowerShell commands to configure access:

Define App Permissions:

New-ServicePrincipal -AppId $AppID -ServiceId $ObjectID

Grant Security Group Full Access to the Mailbox:

Add-MailboxPermission -Identity $MailBox -User $SecurityGroup -AccessRights FullAccess

Restrict Access to Members of the Security Group Only:

New-ApplicationAccessPolicy -AppId $AppID -PolicyScopeGroupId $SecurityGroup -AccessRight RestrictAccess -Description "Restrict this app to members of distribution group {$SecurityGroup}"

Test the Configuration
- Run the following command to test if the application access policy is properly configured:
```
Test-ApplicationAccessPolicy -AppId $AppID -Identity $MailBox
```
- The expected output should be similar to:
```
AppId             : 9367xxxx
Mailbox           : test-shared-mailbox20231107190659
AccessCheckResult : Granted
```
- Running the command with a different mailbox should return AccessCheckResult: Denied.
Configure Intake Connector Settings in TheHive

To integrate TheHive with Microsoft 365, you will need the following information:
- Mailbox address
- Tenant ID
- Client ID
- Secret Value
- Authority: https://login.microsoftonline.com
- Scope: https://outlook.office365.com/.default

Setting up Google Workspace for TheHive#

This section describes the necessary steps to configure Google Workspace to allow TheHive access to a mailbox. Please follow these steps to ensure proper integration.

Prerequisites#

Access to the Google Cloud Admin Console.
Proper permissions to create projects and configure OAuth credentials.

Step-by-Step Configuration#

Access Google Cloud Admin Console
Navigate to the Google Cloud Admin Console at https://console.cloud.google.com/welcome.
Create a New Project
- Click on API & Services.
- Select Create a Project.
- Provide a meaningful name for the project and click Create.
Configure OAuth Consent Screen
- In the left-hand menu, select OAuth consent screen.
- Choose User Type as Internal and click Create.
- Assign a name to the app and specify a mailbox for support contact.
- Provide a developer contact email address, then click Save and Continue.
Add Gmail API Scope
- In Step 2, click on Add or Remove Scopes.
- In the search bar, type the following scope: https://mail.google.com/.
- Click Add to Table to add the scope.
- Ensure that the new scope is checked, then click Update.
- Scroll down to verify that the Gmail scope exists, and click Save and Continue.
Return to Dashboard
- On the summary page, click Back to Dashboard to complete the OAuth consent configuration.
Create OAuth Credentials
- In the left-hand menu, select Credentials.
- Click on Create Credentials and choose OAuth Client ID.
- Set the application type as Web application.
- Provide a name for the OAuth client ID.
- Under Authorized JavaScript origins, add the appropriate URI.
- Under Authorized redirect URIs, add the necessary URIs and click Create.
Obtain Client ID and Secret
- A dialog will appear with the Client ID and Client Secret.
- Copy these values or download the JSON file for future reference.
Configure Intake Connector Settings in TheHive

Set up the intake settings in TheHive by filling in the following values:
- Email
- clientId
- secret

For IMAP configuration, you'll need to input the following information:

Host: host
Port: port (default: 993)

Additionally, provide your mailbox credentials. We recommend enabling SSL Check Certificate Authority.

Settings#

After testing your mailbox configuration, select the organization to connect, determining where alerts will be created. Define the mailbox folder to monitor (typically INBOX). Finally, specify the action to take on incoming emails: archive, mark as read, or no action.

Generated Alerts and Observables#

Following configuration, alerts and observables are generated in the selected organization.

Alerts#

Each alert will contain the following details:

Mapping of email data in the Alert

Title: The email subject or "no subject"
Type: email-intake
Source: The configuration name is formatted as Google Workspace @strangebee.com => googleworkspace-strangebee
Source reference: {message-id} or {lastUidValidity}.{uidEmail} if the message-id is inaccessible
Last sync date: The date the email was received
Severity: low
TLP: amber
PAP: amber
Follow: False
Tags: [email-intake, {source}, {Provider Name}, {Inbox Folder Name}]
Status: new
Description: The content of the email
Summary: [Summary of Alert]
Custom Fields: [Custom Fields]
Eternal link: [Link to External Source]

Observables#

The email itself is included as a .eml file, along with its sender and all attached files, which are added to the alert as observables, with the following parameters:

Observables metadata added with the email data

Message: The pre-formatted message
TLP: {alert.tlp}
PAP: {alert.pap}
IOC: false
Sighted: false
Sighted at: [Timestamp]
Ignore similarity: false
dataType: file if it's an attachment; otherwise, mail for the .eml file
Tags: {alert.tags}
attachment Id: {attachment.id}