Tutorial: Automate Tracking of Pending Alerts#

5.5 Platinum

In this tutorial, we're going to set up an automation in TheHive to monitor alerts that stay in the New status and remain unassigned for too long.

By the end, you'll have a working configuration that:

Detects alerts that remain unassigned and in New status for more than four hours
Flags them with a custom status to indicate they need review
Sends an email notification to the manager

This helps ensure no alert gets left behind without action.

Customize criteria for your needs

The status and wait time criteria used in this tutorial are just a starting point. Feel free to adjust them based on your team’s triage and escalation practices.

Step 1: Create a custom alert status to flag pending alerts#

To highlight alerts needing review, start by creating a new alert status in TheHive.

Go to the Entities management view from the sidebar menu.
Select the Case status tab or the Alert status tab.
Select .
In the Add a custom status drawer, enter the following information:

- Visibility: Display

- Stage: New

- Value: TOREVIEW

- Color: Enter a hex color code in the format #RRGGBB, or select to open the color picker.
Verify that the preview looks correct.
Select Confirm custom status creation.

Step 2: Set up an email notification for TOREVIEW alerts#

Next, configure TheHive to send an email notification to the manager when an alert status changes to TOREVIEW.

Go to the Organization view from the sidebar menu.
Select the Notifications tab.
Select .
In the Add notification drawer, enter the name of your notification.

Unique name

This name must be unique, as two notifications can't have the same name.
Select the FilteredEvent trigger.

Enter the following custom filter:

{
    "_and": [
        {
            "_is": {
                "objectType": "Alert"
            }
        },
        {
            "_is": {
                "action": "update"
            }
        },
        {
            "_contains": {
                "_field": "details.status",
                "_value": "TOREVIEW"
            }
        }
    ]
}

Select the EmailerToAddr notifier.

In the EmailerToAddr drawer, enter the required email information.

Available variables

You can use variables in certain fields by selecting Add variable. Refer to the Variable Usage Examples topic for detailed examples.

Helpers using Mustache syntax

Data transformation helpers#

Helper	Description	Usage	Output
`tlpLabel`	Format the `tlp` field of the object	`{{ tlpLabel object.tlp }}`	`Amber`
`papLabel`	Format the `pap` field of the object	`{{ papLabel object.pap }}`	`Amber`
`severityLabel`	Format the `severity` field of the object	`{{ severityLabel object.severity }}`	`Critical`
`dateFormat`	Format a date field of the object using Java date time patterns	`{{dateFormat audit._createdAt "EEEEE dd MMMMM yyyy" "fr" }}`	`jeudi 01 septembre 2022`

Standard string helpers can be found in the official Handlebars documentation.

Conditional helpers#

Examples:

Displays Medium if case.severity equals 2, otherwise displays Other:

{{#if (eq case.severity 2) }}
    Medium
{{else}}
    Other 
{{/if}}

Displays the threat actor value only if case.customFieldValues.threat-actor is defined:

{{#if case.customFieldValues.threat-actor}}
    Threat Actor: {{case.customFieldValues.threat-actor}}
{{/if}}

Find additional supported operators in the official Handlebars documentation.

Email template example:

Hello,

The following alert has been pending for a while and requires your priority review:

* ID: {{audit.objectId}}
* Title: {{audit.object.title}}

You can access the full alert details here: https://<thehive_url>/alerts/{{audit.objectId}}/details

Replace <thehive_url> with your actual TheHive URL.

Select Confirm.
Select Confirm again to save the notification.

To verify that your notification works as expected, manually change the status of an alert to TOREVIEW. This action should trigger an email to the configured recipient. If the email arrives, you're all set to move on to the final step!

Step 3: Automate status updates using an alert feeder#

Create an alert feeder that automatically updates the status of unassigned new alerts older than four hours.

This alert feeder will periodically search for alerts that meet the criteria and update their status to TOREVIEW

Go to the Organization view from the sidebar menu.
Select the Connectors tab.
In the General settings section, enter the following information:

- Name: A unique name for the alert feeder. You can’t change this name later.

- Interval: How often the alert feeder sends requests to the external system.

Define the interval carefully based on your reactivity requirements

Make sure the interval is shorter than the processing time to avoid potential issues, but not too short to prevent excessive requests to the API.

- Request timeout time: The maximum time, in seconds, the alert feeder waits for a response before timing out.

- Request response max size: The maximum response size, in megabytes, that the alert feeder accepts from the external system.

- Description: A description to provide additional context or notes about the alert feeder configuration.
In the HTTP request section, enter the following information:

- Method: GET

- URL: https://<thehive_url>/api/v1/status/public/

Replace <thehive_url> with your actual TheHive URL.
Select Test connection to verify the connection to the external system.

In the Create function section, enter the following information:

Feeder function

Once created, the function is automatically added to the functions list with the type feeder.

- Function name: ChangePendingAlertStatus

- Description: This function retrieves all alerts with status New that are unassigned and were created more than four hours ago, then updates their status to TOREVIEW

- Definition

Use this function definition:

// Name: ChangePendingAlertStatus 
// Type: Feeder
// Desc: This function retrieves all alerts with status New that are unassigned and were created more than four hours ago, then updates their status to TOREVIEW.

function handle(input, context) {

    // Retrieve all alerts where status is New, assignee is empty, and creation date is older than four hours
    const query = [
        {
            "_name":"listAlert",
        },
        {
            "_name":"filter",
            "_eq":
                { 
            "_field":"status", 
            "_value":"New" 
                }
        },
        {
            "_name":"filter",
            "_not":
            {
                "_has":
                {
                    "_field":"assignee"
                }
            }
        },
        {
            "_name":"filter",
            "_lte":
            {
                "_field": "_createdAt",
                "_value": 
                {
                    "amount": 4,
                    "unit": "hours",
                    "look": "behind" 
                }
            } 
        }
    ];

    // Execute the search to get the targeted alerts
    const alertList = context.query.execute(query);

    // Update the status to TOREVIEW for all matching alerts
    alertList.map((alrt) => {
        context.alert.update(alrt._id, {status: "TOREVIEW"});
    });
}

In the Test function section, you can test your function as follows:
- Enter input data by selecting input.
- Select one of the following:
  - Run function (dry-run) to simulate the function without sending data.
  - Run function to execute the function with actual data.
- After running the function, select one of the following to view results:
  - result to view the function’s output
  - stdout to display standard output from the function
  - stderr to display errors and warnings
Select Confirm.

That’s it—your automation is now fully set up and ready to ensure no pending alert goes unnoticed.

Next steps

Create a Dashboard