Skip to content

Commit 92330b0

Browse files
AnneLaure1307AnneLaure1307
authored
DOC-433 (#120)
* Improved email intake pages and added a tutorial * Added permission * Rendering checks
1 parent 7c327bc commit 92330b0

5 files changed

Lines changed: 86 additions & 34 deletions

File tree

‎docs/thehive/administration/email-intake-connector/about-email-intake-connectors.md‎

Lines changed: 12 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -2,40 +2,19 @@
22

33
<!-- md:license Gold --> <!-- md:license Platinum -->
44

5-
Organizations that receive alert data by email can use email intake connectors to automate the creation of alerts in TheHive.
5+
Organizations that receive alert data by email can use email intake connectors to automate alert creation in TheHive.
66

77
## Usage
88

9-
Email intake connectors integrate mailboxes that receive alerts.
10-
11-
It automatically processes incoming emails, extracts relevant information, and creates alerts within TheHive platform. The email itself, its sender, and any attached files are automatically added as observables within the respective alerts.
12-
13-
!!! tip "Parsing emails"
14-
The content of the email itself isn't automatically parsed when creating the alert. To enable observable extraction, a [notification](../../user-guides/organization/configure-organization/manage-notifications/create-a-notification.md) must trigger [a FilteredEvent](../../user-guides/organization/configure-organization/manage-notifications/write-filtered-event-trigger.md) that [runs the *EmlParser* analyzer](../../user-guides/organization/configure-organization/manage-notifications/notifiers/analyzers.md).
15-
16-
Below is an example of the FilteredEvent trigger:
17-
18-
```json
19-
{
20-
"_and": [
21-
{
22-
"_is": {
23-
"action": "create"
24-
}
25-
},
26-
{
27-
"_is": {
28-
"objectType": "Observable"
29-
}
30-
},
31-
{
32-
"_is": {
33-
"object.alert.type": "email-intake"
34-
}
35-
}
36-
]
37-
}
38-
```
9+
Email intake connectors automatically processes incoming emails and creates alerts in TheHive.
10+
11+
Each alert includes the following observables:
12+
13+
* The email file (`.eml`)
14+
* The sender's email address
15+
* Any file attachments
16+
17+
The email body isn't parsed for observables by default. To extract them, run the *EmlParser* analyzer manually, or [automate extraction using a notification](../../user-guides/automate-extraction-observables-from-emails.md).
3918

4019
## Data mapping
4120

@@ -89,4 +68,5 @@ Only users with an admin-type profile that has the `managePlatform` permission c
8968

9069
* [Connect a Mailbox](connect-a-mailbox.md)
9170
* [Delete a Mailbox](delete-a-mailbox-connection.md)
92-
* [Manually Trigger Email Fetch in a Mailbox](fetch-emails.md)
71+
* [Manually Trigger Email Fetch in a Mailbox](fetch-emails.md)
72+
* [Automate Extraction of Observables from Emails](../../user-guides/automate-extraction-observables-from-emails.md)

‎docs/thehive/administration/email-intake-connector/connect-a-mailbox.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -499,4 +499,5 @@ Connect a [mailbox](about-email-intake-connectors.md) if your organization recei
499499
<h2>Next steps</h2>
500500

501501
* [Delete a Mailbox Connection](delete-a-mailbox-connection.md)
502-
* [Manually Trigger Email Fetch in a Mailbox](fetch-emails.md)
502+
* [Manually Trigger Email Fetch in a Mailbox](fetch-emails.md)
503+
* [Automate Extraction of Observables from Emails](../../user-guides/automate-extraction-observables-from-emails.md)

‎docs/thehive/administration/email-intake-connector/fetch-emails.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,5 @@ Manually trigger email fetch in a [mailbox](about-email-intake-connectors.md) in
1919
<h2>Next steps</h2>
2020

2121
* [Connect a Mailbox](connect-a-mailbox.md)
22-
* [Delete a Mailbox](delete-a-mailbox-connection.md)
22+
* [Delete a Mailbox](delete-a-mailbox-connection.md)
23+
* [Automate Extraction of Observables from Emails](../../user-guides/automate-extraction-observables-from-emails.md)

‎docs/thehive/user-guides/automate-extraction-observables-from-emails.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Tutorial: Automate Extraction of Observables from Emails
2+
3+
<!-- md:permission `manageConfig` --> <!-- md:license Gold --> <!-- md:license Platinum -->
4+
5+
When an [email intake connector](../administration/email-intake-connector/about-email-intake-connectors.md) processes an incoming email, it creates an alert in TheHive with several observables, including the email file itself. However, the email body isn't parsed for observables by default—you need to run the *EmlParser* analyzer to extract them.
6+
7+
In this tutorial, we're going to set up an automation in TheHive that runs the *EmlParser* analyzer automatically each time an email intake alert is created.
8+
9+
!!! warning "Prerequisites"
10+
This tutorial assumes you've already [configured an email intake connector](../administration/email-intake-connector/connect-a-mailbox.md) for your TheHive instance.
11+
12+
By the end, you'll have a working configuration that:
13+
14+
* Detects when an observable is created from an email intake connector alert
15+
* Automatically runs the *EmlParser* analyzer to extract observables from the email body
16+
17+
This eliminates the need to manually run the analyzer for each email alert.
18+
19+
## Step 1: Create a notification triggered by email intake alerts
20+
21+
1. {% include-markdown "includes/organization-view-go-to.md" %}
22+
23+
2. {% include-markdown "includes/notifications-tab-go-to.md" %}
24+
25+
3. Select :fontawesome-solid-plus:.
26+
27+
4. In the **Add notification** drawer, enter the name of the notification: `EmailObservableExtractionNotification`
28+
29+
5. Select the *FilteredEvent* trigger.
30+
31+
6. Enter the following custom filter to match observable creation events from email intake alerts:
32+
33+
```json
34+
{
35+
"_and": [
36+
{
37+
"_is": {
38+
"action": "create"
39+
}
40+
},
41+
{
42+
"_is": {
43+
"objectType": "Observable"
44+
}
45+
},
46+
{
47+
"_is": {
48+
"object.alert.type": "email-intake"
49+
}
50+
}
51+
]
52+
}
53+
```
54+
55+
## Step 2: Configure a *RunAnalyzer* notifier
56+
57+
1. In your current notification, select the [*RunAnalyzer* notifier](./organization/configure-organization/manage-notifications/notifiers/analyzers.md).
58+
59+
2. In the **RunAnalyzer** drawer, select **EmlParser**.
60+
61+
3. Select **Confirm**.
62+
63+
That's it—every time a new email intake observable is created, TheHive will automatically run the *EmlParser* analyzer to extract observables from the email content.
64+
65+
<h2>Next steps</h2>
66+
67+
* [About Email Intake Connectors](../administration/email-intake-connector/about-email-intake-connectors.md)
68+
* [Connect a Mailbox](../administration/email-intake-connector/connect-a-mailbox.md)
69+
* [Manually Trigger Email Fetch in a Mailbox](../administration/email-intake-connector/fetch-emails.md)

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -698,6 +698,7 @@ nav:
698698
- 'Automation Hacks':
699699
- 'Tutorial: Automate Tracking of Pending Alerts': thehive/user-guides/automate-tracking-pending-alerts.md
700700
- 'Tutorial: Automate Monitoring of Tasks Approaching Their Due Date': thehive/user-guides/automate-monitoring-tasks-approaching-due-date.md
701+
- 'Tutorial: Automate Extraction of Observables from Emails': thehive/user-guides/automate-extraction-observables-from-emails.md
701702
- 'Analyst Corner':
702703
- 'Alerts Management':
703704
- 'About Alerts': thehive/user-guides/analyst-corner/alerts/about-alerts.md

0 commit comments

Comments
 (0)