You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This feature is available with TheHive versions 5.1 and higher.
3
+
## Overview
5
4
6
-
Functions enable you to integrate external applications directly into TheHive processing.
5
+
A Function in TheHive is a custom JavaScript code block that runs within the platform, accepting inputs from external sources, processing data, and interacting directly with TheHive's APIs to seamlessly integrate external applications into its workflow.
7
6
8
-
A Function is a piece of custom Javascript code that runs inside TheHive. The function can receive inputs from the outside, treat it and call TheHive APIs directly.
7
+
For example, you can use a Function to create alerts within TheHive without the need for an additional Python service to convert the data.
9
8
10
-
This can be used for instance to create alerts inside TheHive without a python glue service that transforms the data.
9
+
This feature is supported in TheHive starting from version 5.1 and later.
11
10
12
-
## Create a function
11
+
---
13
12
14
-
Let's imagine that when an event occurs in your system, you want to create an alert in TheHive. Your external system has its own schema for the events, something like:
13
+
## Function Usages
15
14
16
-
!!! Example ""
15
+
In real-life use, a Function in TheHive automates tasks like processing data from external systems, triggering alerts, or updating cases. It streamlines workflows by connecting TheHive to other tools, reducing manual work and improving incident management efficiency.
This format is not the same as TheHive, so you need to transform the data to match TheHive alert format.
19
+
## Function Types
33
20
34
-
As an `org-admin`, you can create new functions for your organisation that can take this input, transform it into TheHive format and create an alert from it.
21
+
Below are the different types of functions supported in TheHive. The function type you select determines the scope where the function can be executed:
35
22
36
-
The code of the function would be something like this:
23
+
1.**API**: These functions are triggered by an external service through TheHive's public API, allowing automated workflows initiated from outside the platform.
37
24
38
-
!!! Example ""
25
+
2.**Notification**: Notification functions act as notifiers and are triggered when certain events occur, such as alerts or case updates, automating the notification process based on predefined conditions.
"tags": [`name:${data.name}`] // use a tag for the data name
56
-
}
57
-
})
58
-
};
59
-
// call TheHive APIs, here alert creation
60
-
return context.alert.create(theHiveAlert);
61
-
}
62
-
```
27
+
3.**Action: Case**: Functions of the `action:case` type are manually triggered within the context of a specific case, allowing users to perform actions related to case management.
28
+
29
+
4.**Action: Alert**: The `action:alert` type refers to functions manually executed in the context of an alert, enabling users to process and act on alerts within TheHive.
A function in TheHive can operate in one of three modes:
67
36
68
-
A function can be in one of three modes:
37
+
-**Enabled**: The function will run as expected when triggered.
38
+
-**Disabled**: The function will not run when triggered.
39
+
-**Dry-Run**: The function will execute, but no entities will be created or modified in TheHive. Entity creation attempts will return `null`, making this mode ideal for testing integrations before going live.
69
40
70
-
-`Enabled`: The function will be executed when called
71
-
-`Disabled`: The function will not be executed when called
72
-
-`Dry-Run`: The function will be executed but no entity will be created or modified in TheHive. Entity creations will return `null` instead. This can be useful to test your integration before setting it live.
41
+
---
73
42
74
-
The creation page allows you to test your function and see what it would return once executed.
75
-
In `dry-run` mode, the function will be executed but no resource creation or modification will be executed.
43
+
## Create a Function
76
44
77
-
<figuremarkdown>
78
-
{ width="500" }
79
-
</figure>
45
+
Follow the steps below to create a function in TheHive:
80
46
81
-
<figuremarkdown>
82
-
{ width="500" }
83
-
</figure>
47
+
1.**Navigate to the Organization Tab**: On the left side of the interface, go to the "Organization" tab.
48
+
2.**Access Functions**: In the navigation options, locate "Functions" and click on it.
49
+
3.**Create a New Function**: Click on the **+ Create a function** button.
50
+
4.**Fill Out the Create Function Form**: You will be presented with the "Create Function" form. Fill out the following details:
51
+
-**Name**: Enter a name for the function.
52
+
-**Mode**: Select the mode (Enabled, Disabled, or Dry-Run).
53
+
-**Type**: Choose the function type (API, Notification, Action: Case, Action: Alert).
54
+
-**Description**: Provide a brief description of the function’s purpose.
55
+
-**Definition**: Write or paste the function's JavaScript code.
56
+
-**Test Function**: You can test the function using input data.
57
+
-**How to Call the Function**: Provides an example command for calling the function.
58
+
5.**Save the Function**: After completing the form, click **Save** to create the function.
84
59
85
-
## Call a function
60
+
61
+
62
+
63
+
64
+
---
65
+
66
+
## Call a Function
86
67
87
68
Once saved, the function can then be called with an http call from your system:
88
69
@@ -105,13 +86,63 @@ Once saved, the function can then be called with an http call from your system:
105
86
```
106
87
107
88
TheHive will take your input (the body of the http call), the definition of your function and execute the function with the input.
108
-
It will respond to the http call with the data returned by the function.
109
-
110
-
## Example: Create an alert from a Splunk alert
111
-
112
-
When creating a Splunk alert, you can define a [webhook as an action](https://docs.splunk.com/Documentation/Splunk/9.0.0/Alert/Webhooks). So when the alert is triggered the webhook is called with a payload. But the payload is defined by splunk and can't be changed.
113
-
114
-
It should look a bit like:
89
+
It will respond to the HTTP call with the data returned by the function.
90
+
91
+
---
92
+
93
+
## Example 1: Function Use Case
94
+
95
+
Suppose you want to create an alert in TheHive when an event occurs in your system. Your external system may have its own event schema, similar to the example below:
Because this format differs from TheHive's alert schema, the data needs to be transformed into the correct format.
112
+
113
+
As an org-admin, you can create a new function for your organization to convert this input into TheHive's alert format and generate an alert. The function might look like this:
114
+
115
+
```javascript
116
+
functionhandle(input, context) {
117
+
consttheHiveAlert= {
118
+
"type":"event",
119
+
"source":"my-system",
120
+
"sourceRef":input.eventId,
121
+
"title":input.title,
122
+
"description":input.details,
123
+
"date": (newDate(input.date)).getTime(),
124
+
"observables":input.data.map(data=> {
125
+
// map event data kind to TheHive Observable type
126
+
constdataType=data.kind==="ip"?"ip":"other";
127
+
return {
128
+
"dataType": dataType,
129
+
"data":data.value,
130
+
"tags": [`name:${data.name}`] // use a tag for the data name
131
+
};
132
+
})
133
+
};
134
+
// call TheHive APIs, here alert creation
135
+
returncontext.alert.create(theHiveAlert);
136
+
}
137
+
```
138
+
139
+
Creating and testing this function allows you to effortlessly convert your external event data into a format that TheHive can process as an alert.
140
+
141
+
---
142
+
143
+
## Example 2: Creating an Alert Based on a Splunk Alert
144
+
145
+
When setting up a Splunk alert, you can configure a [webhook as an action](https://docs.splunk.com/Documentation/Splunk/9.0.0/Alert/Webhooks). When the alert is triggered, the webhook will be invoked with a predefined payload, which cannot be modified. The payload will resemble something like this:
115
146
116
147
!!! Example ""
117
148
@@ -149,7 +180,7 @@ It should look a bit like:
149
180
}
150
181
```
151
182
152
-
To transform this splunk alert into a TheHive alert, a function like this can be used:
183
+
To convert this Splunk alert into a TheHive alert, you can use a function like the following:
153
184
154
185
!!! Example ""
155
186
@@ -172,14 +203,16 @@ To transform this splunk alert into a TheHive alert, a function like this can be
172
203
}
173
204
```
174
205
175
-
In splunk, you will need to set the webhook url to TheHive function url.
206
+
In Splunk, you'll need to configure the webhook URL to point to the TheHive function URL.
176
207
177
-
## Example: Cold case automation
208
+
---
178
209
179
-
When called, this function will:
210
+
## Example 3: Cold Case Automation Process
180
211
181
-
- find all cases that are `New` or `InProgress` and were not updated in the last month
182
-
- to each of those cases, add a tag `cold-case`
212
+
When invoked, this function will:
213
+
214
+
- Identify all cases marked as `New` or `InProgress` that haven't been updated in the past month.
215
+
- Add a `cold-case` tag to each of these cases.
183
216
184
217
!!! Example ""
185
218
@@ -214,6 +247,7 @@ When called, this function will:
214
247
});
215
248
}
216
249
```
250
+
---
217
251
218
252
## Context API
219
253
@@ -412,3 +446,5 @@ When called, this function will:
0 commit comments