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, 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. Contributions of user-written functions are welcome.

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#

Functions in TheHive 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 the function can execute.

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. A list of available objects appears in the Functions Objects topic. Execute the function by invoking 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: Trigger these functions manually within the context of a specific case. Execute the function by running it manually.

  • Action: Alert: Trigger these functions manually within the context of a specific alert. Execute the function by running 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. Avoid manually creating functions of the feeder type. Instead, create an alert feeder with a function. The function automatically appears in the functions list. Updates to the function reflect in the alert feeder, and changes in the alert feeder update the function accordingly.

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