Skip to content

About Functions#

5.1 Platinum

A function in TheHive is a controlled JavaScript code block that must be written within TheHive’s interface and runs securely within the platform. This code operates on a restricted set of predefined features, ensuring that it can't access the full JavaScript language or execute arbitrary code outside the platform's security boundaries.

It accepts inputs from external sources, processes data, and interacts with TheHive's API to integrate external applications into its workflow.

For example, you can use a function to create alerts within TheHive without requiring an additional Python service for data conversion.

Contribute!

Examples of function use cases are available in a dedicated GitHub repository. You can contribute by sharing functions you’ve written.

This topic provides details on the different types and uses of functions in TheHive.

Function endpoints#

Creating a function in TheHive automatically adds a new public endpoint to the TheHive public API, making it easy to call from an external system.

Trigger sources#

Various sources can trigger functions in TheHive:

  • User actions in TheHive: Triggered by specific actions performed within TheHive

  • Automation: Triggered to automate manual or repetitive tasks, either on a schedule or based on predefined conditions

  • Notifications: Triggered by an event in TheHive that generates a notification

  • External systems (push method): Triggered when an external system, such as a detection tool, pushes data to TheHive

  • 5.5 External systems (pull method): Triggered when TheHive retrieves data from an external system using an alert feeder

Common use cases#

You can use functions in TheHive to automate workflows, process data, and enhance case management.

Below are some common use cases, each with a link to the corresponding JavaScript function:

User actions#

  • Deleting observables of type IP from an alert: Code
  • Changing the assignee of a case and all its associated tasks to the user who runs the function: Code

Automation#

Identifying New and In progress cases that haven't been updated in the last month and tagging them with cold-case: Code

Notifications#

  • Assigning high or critical alerts to a specific user when they're created via a notification: Code
  • Updating the status of alerts merged into a case that was closed via a notification: Code

External systems (push method)#

Ingesting Splunk alerts and converting them into TheHive alerts: Code

External systems (pull method)#

5.5

  • Creating alerts from an Airtable database via an alert feeder while applying data transformations: Code
  • Creating alerts from Jira via an alert feeder while applying data transformations: Code

Function types#

The function type defines the scope in which you can execute the function.

Multiple types allowed

A function can have one or multiple types.

Below are the different types of functions supported in TheHive:

  • API: An external service triggers these functions through TheHive's public API, enabling automated workflows from outside the platform. You can find a list of available objects in the Functions Objects topic. To execute the function, you must first revoke it via an HTTP call.

  • Notification: These functions act as notifiers and trigger when specific events occur, such as alerts or case updates. They automate the notification process based on predefined conditions.

  • Action: Case: Users manually trigger these functions within the context of a specific case. To execute the function, they must run it manually.

  • Action: Alert: Users manually trigger these functions within the context of a specific alert. To execute the function, they must run it manually.

  • 5.5 Feeder: A feeder function transforms data retrieved from the HTTP API call and converts it into the expected TheHive format to create alerts. You should not manually create functions of the feeder type. Instead, create an alert feeder with a function. The function will be automatically added to the list of functions. From there, you can update it, and any changes will be reflected in the alert feeder, and vice-versa.

Function modes#

A function in TheHive can operate in one of three modes:

  • Enabled: The function executes normally when triggered.
  • Disabled: The function doesn't execute when triggered.
  • Dry-run: The function runs, but it doesn't create or modify cases, alerts, or other entities in TheHive. Instead, creation attempts return null, making this mode ideal for testing integrations before going live.

Permissions#

Required permissions

  • Only users with the manageFunction/create permission can create a function in TheHive.
  • Only users with the manageFunction/invoke permission can invoke a function in TheHive.
  • Only users with the manageAction permission can run a function in TheHive.

Next steps