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.
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
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}