TheHive
TheHive connector enables seamless integration with TheHive's incident response platform, facilitating the creation and management of security cases directly from Swimlane.
TheHive is a scalable, open-source and free Security Incident Response Platform designed to make life easier for SOCs, CSIRTs, CERTs, and any information security practitioner dealing with security incidents. The connector allows Swimlane Turbine users to automate incident response by integrating with TheHive's capabilities to create, update, and manage security cases and observables. By leveraging this integration, users can streamline their incident management process, reduce response times, and enhance collaboration among security teams. TheHive connector provides a direct link to manage incident data, add observables to cases, and synchronize case information, ensuring a comprehensive and efficient security operation workflow within Swimlane Turbine.
This connector integrates with Swimlane Turbine to manage cases in TheHive.
Prerequisites
To integrate TheHive with Swimlane Turbine, ensure you have the following:
- API Key Authentication with these parameters:
- URL: The base URL of your TheHive instance.
- API Key: Your personal API key for authentication.
- HTTP Basic Authentication with these parameters:
- URL: The base URL of your TheHive instance.
- Username: Your TheHive username.
- Password: Your TheHive password.
Capabilities
This connector provides the following capabilities:
- Add Observables to Case
- Create Case
- Get Case
- Get Case Observable
- List Cases
- Update Case
Asset Setup
- For apikey authentication, url and apikey are required.
- For http_basic authentication, username and password along with url are required.
Notes
Enable Basic authentication using a username and password instead of an API key by adding auth.method.basic=true in the configuration file.
Configurations
TheHive API Key Authentication
Authenticates using an API Key
Configuration Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
url | A URL to the target host. | string | Required |
apikey | API key | string | Required |
verify_ssl | Verify SSL certificate | boolean | Optional |
http_proxy | A proxy to route requests through. | string | Optional |
TheHive HTTP Basic Authentication
Authenticates using username and password.
Configuration Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
url | A URL to the target host. | string | Required |
username | Username | string | Required |
password | Password | string | Required |
verify_ssl | Verify SSL certificate | boolean | Optional |
http_proxy | A proxy to route requests through. | string | Optional |
Actions
Add Observable To Case
Add an observable to an existing case.
Endpoint
- URL: /api/case/{{caseId}}/artifact
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.caseId | string | Required | Parameters for the Add Observable To Case action |
parameters.dataType | string | Optional | Parameters for the Add Observable To Case action |
dataType | string | Optional | should be one registered observable type. |
data | array | Optional | Either data or attachment must be set depending on the dataType above. |
message | string | Optional | Response message |
startDate | number | Optional | The startDate has to be in datetime_ms. |
attachment | object | Optional | Attachment must be set if the observable dataType has isAttachment=true. |
attachment.name | string | Required | Name of the resource |
attachment.contentType | string | Required | Type of the resource |
attachment.id | string | Required | Unique identifier |
tlp | number | Optional | Parameter for Add Observable To Case |
pap | number | Optional | Parameter for Add Observable To Case |
tags | array | Optional | Parameter for Add Observable To Case |
ioc | boolean | Optional | Parameter for Add Observable To Case |
sighted | boolean | Optional | Parameter for Add Observable To Case |
sightedAt | number | Optional | Parameter for Add Observable To Case |
ignoreSimilarity | boolean | Optional | Parameter for Add Observable To Case |
isZip | boolean | Optional | If set to true, the file is unzipped using the zipPassword and each file in the zip is treated as an observable. |
zipPassword | string | Optional | Parameter for Add Observable To Case |
Input Example
{"parameters":{"dataType":""},"json_body":{"dataType":"","data":[""],"message":"","startDate":1640000000000,"attachment":{"name":"","contentType":"","id":""},"tlp":0,"pap":0,"tags":[""],"ioc":false,"sighted":false,"sightedAt":1640000000000,"ignoreSimilarity":false,"isZip":true,"zipPassword":""},"path_parameters":{"caseId":"~1802260584"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":201,"response_headers":{"Date":"Thu, 17 Aug 2023 09:54:59 GMT","Content-Type":"application/json","Content-Length":"343","Connection":"keep-alive","Server":"nginx/1.25.1","Request-Time":"537","Strict-Transport-Security":"max-age=31536000; includeSubDomains"},"reason":"Created","json_body":[{"_id":"~1802281096","id":"~1802281096","createdBy":"[email protected]","createdAt":1692266099282,"_type":"case_artifact","dataType":"hostname","data":"server.local","startDate":169...
Create Case
Create a new case. A Case Template can be used to provide tasks and custom fields.
Endpoint
- URL: /api/case
- Method: POST
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
title | string | Optional | Parameter for Create Case |
description | string | Optional | Parameter for Create Case |
severity | number | Optional | Parameter for Create Case |
startDate | number | Optional | The startDate has to be in datetime_ms. |
endDate | number | Optional | The endDate has to be in datetime_ms. |
tags | array | Optional | Parameter for Create Case |
flag | boolean | Optional | Parameter for Create Case |
tlp | number | Optional | Parameter for Create Case |
pap | number | Optional | Parameter for Create Case |
status | string | Optional | Status value |
summary | string | Optional | Parameter for Create Case |
assignee | string | Optional | Parameter for Create Case |
customFields | object | Optional | Parameter for Create Case |
caseTemplate | string | Optional | Parameter for Create Case |
tasks | array | Optional | Parameter for Create Case |
tasks.title | string | Required | Parameter for Create Case |
tasks.group | string | Optional | Parameter for Create Case |
tasks.description | string | Optional | Parameter for Create Case |
tasks.status | string | Optional | Status value |
tasks.flag | boolean | Optional | Parameter for Create Case |
tasks.startDate | number | Optional | The startDate has to be in datetime_ms. |
tasks.endDate | number | Optional | The endDate has to be in datetime_ms. |
tasks.order | number | Optional | Parameter for Create Case |
tasks.dueDate | number | Optional | The dueDate has to be in datetime_ms. |
tasks.assignee | string | Optional | Parameter for Create Case |
Input Example
{"json_body":{"title":"create case","description":"create first case","severity":1,"startDate":1640000000000,"endDate":1640000000000,"tags":[""],"flag":false,"tlp":0,"pap":0,"status":"New","summary":"create test case","assignee":"","customFields":{},"caseTemplate":"","tasks":[{"title":"create task","group":"","description":"create case task","status":"","flag":true,"startDate":1640000000000,"endDate":1640000000000,"order":0,"dueDate":1640000000000,"assignee":"","mandatory":true}],"pages":[{"title":"create task page","content":"","order":0,"category":""}],"sharingParameters":[{"organisation":"~354","share":true,"profile":"analyst","taskRule":"Sharing rule applied on the case","observableRule":"Sharing rule applied on the case"}],"taskRule":"","observableRule":""}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
_id | string | Unique identifier |
_type | string | Type of the resource |
_createdBy | string | Output field: _createdBy |
_createdAt | number | Output field: _createdAt |
number | number | Output field: number |
title | string | Output field: title |
description | string | Output field: description |
severity | number | Output field: severity |
severityLabel | string | Output field: severityLabel |
startDate | number | Date value |
endDate | number | Date value |
tags | array | Output field: tags |
tags.file_name | string | Name of the resource |
tags.file | string | Output field: tags.file |
flag | boolean | Output field: flag |
tlp | number | Output field: tlp |
tlpLabel | string | Output field: tlpLabel |
pap | number | Output field: pap |
papLabel | string | Output field: papLabel |
status | string | Status value |
stage | string | Output field: stage |
summary | string | Output field: summary |
assignee | string | Output field: assignee |
Output Example
{"status_code":201,"response_headers":{"Date":"Thu, 17 Aug 2023 09:08:40 GMT","Content-Type":"application/json","Content-Length":"682","Connection":"keep-alive","Server":"nginx/1.25.1","Request-Time":"434","Strict-Transport-Security":"max-age=31536000; includeSubDomains"},"reason":"Created","json_body":{"_id":"~1802260584","_type":"Case","_createdBy":"[email protected]","_createdAt":1692263319826,"number":99,"title":"create case","description":"create first case","severity":1,"seve...
Get Case
Get Case.
Endpoint
- URL: /api/case/{{idOrName}}
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.idOrName | string | Required | Parameters for the Get Case action |
Input Example
{"path_parameters":{"idOrName":"~1802260584"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
_id | string | Unique identifier |
_type | string | Type of the resource |
_createdBy | string | Output field: _createdBy |
_createdAt | number | Output field: _createdAt |
number | number | Output field: number |
title | string | Output field: title |
description | string | Output field: description |
severity | number | Output field: severity |
severityLabel | string | Output field: severityLabel |
startDate | number | Date value |
endDate | number | Date value |
tags | array | Output field: tags |
tags.file_name | string | Name of the resource |
tags.file | string | Output field: tags.file |
flag | boolean | Output field: flag |
tlp | number | Output field: tlp |
tlpLabel | string | Output field: tlpLabel |
pap | number | Output field: pap |
papLabel | string | Output field: papLabel |
status | string | Status value |
stage | string | Output field: stage |
summary | string | Output field: summary |
assignee | string | Output field: assignee |
Output Example
{"status_code":200,"response_headers":{"Date":"Thu, 17 Aug 2023 09:17:30 GMT","Content-Type":"application/json","Transfer-Encoding":"chunked","Connection":"keep-alive","Server":"nginx/1.25.1","Vary":"Accept-Encoding","Request-Time":"133","Strict-Transport-Security":"max-age=31536000; includeSubDomains","Content-Encoding":"gzip"},"reason":"OK","json_body":{"_id":"~1802260584","_type":"Case","_createdBy":"[email protected]","_createdAt":1692263319826,"number":99,"title":"create case"...
Get Case Observable
Get Case Observable
Endpoint
- URL: /api/case/artifact/{{observableId}}
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
data_body | object | Optional | Data Body |
headers | object | Optional | Request Headers |
Input Example
{"path_parameters":{},"parameters":{},"data_body":{},"headers":{}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
_id | string | Unique identifier |
id | string | Unique identifier |
createdBy | string | Output field: createdBy |
createdAt | number | Output field: createdAt |
_type | string | Type of the resource |
dataType | string | Response data |
data | string | Response data |
startDate | number | Date value |
tlp | number | Output field: tlp |
pap | number | Output field: pap |
tags | array | Output field: tags |
tags.file_name | string | Name of the resource |
tags.file | string | Output field: tags.file |
ioc | boolean | Output field: ioc |
sighted | boolean | Output field: sighted |
message | string | Response message |
reports | object | Output field: reports |
stats | object | Output field: stats |
ignoreSimilarity | boolean | Output field: ignoreSimilarity |
Output Example
{"status_code":200,"response_headers":{"Date":"Thu, 17 Aug 2023 10:00:05 GMT","Content-Type":"application/json","Transfer-Encoding":"chunked","Connection":"keep-alive","Server":"nginx/1.25.1","Vary":"Accept-Encoding","Request-Time":"116","Strict-Transport-Security":"max-age=31536000; includeSubDomains","Content-Encoding":"gzip"},"reason":"OK","json_body":{"_id":"~1802281096","id":"~1802281096","createdBy":"[email protected]","createdAt":1692266099282,"_type":"case_artifact","dataTy...
List Cases
Get list of cases
Endpoint
- URL: /api/case/{{id}}/links
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.id | string | Required | Parameters for the List Cases action |
Input Example
{"path_parameters":{"id":"~1802260584"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"response_headers":{"Date":"Thu, 17 Aug 2023 10:28:54 GMT","Content-Type":"application/json","Transfer-Encoding":"chunked","Connection":"keep-alive","Server":"nginx/1.25.1","Vary":"Accept-Encoding","Request-Time":"44","Strict-Transport-Security":"max-age=31536000; includeSubDomains","Content-Encoding":"gzip"},"reason":"OK","json_body":[{"_id":"~48144448","_type":"case","caseId":66,"createdAt":1618344529302,"createdBy":"[email protected]","customFields":{},"description":"N/A",...
Update Case
Updates an existing case in TheHive by ID or name.
Endpoint
- URL: /api/v1/case/{{idOrName}}
- Method: PATCH
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
path_parameters.idOrName | string | Required | Parameters for the Update Case action |
title | string | Optional | Parameter for Update Case |
description | string | Optional | Parameter for Update Case |
severity | number | Optional | Parameter for Update Case |
startDate | number | Optional | Date value |
endDate | number | Optional | Date value |
tags | array | Optional | Set the case tags to this array. |
flag | boolean | Optional | Parameter for Update Case |
tlp | number | Optional | Parameter for Update Case |
pap | number | Optional | Parameter for Update Case |
status | string | Optional | Status value |
summary | string | Optional | Parameter for Update Case |
assignee | string | Optional | Parameter for Update Case |
impactStatus | string | Optional | Status value |
customFields | object | Optional | Custom fields as object. |
taskRule | string | Optional | Parameter for Update Case |
observableRule | string | Optional | Parameter for Update Case |
addTags | array | Optional | Those tags will be added to the current case. |
removeTags | array | Optional | Those tags will be removed from the current case. |
Input Example
{"json_body":{"title":"string","description":"string","severity":1,"startDate":1640000000000,"endDate":1640000000000,"tags":["string"],"flag":true,"tlp":0,"pap":0,"status":"string","summary":"string","assignee":"string","impactStatus":"string","customFields":{"property1":null,"property2":null},"taskRule":"string","observableRule":"string","addTags":["string"],"removeTags":["string"]},"path_parameters":{"idOrName":"~354"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
response_text | string | Output field: response_text |
Output Example
{"status_code":204,"response_headers":{},"reason":"No Content","response_text":""}
Response Headers
Header | Description | Example |
|---|---|---|
Connection | HTTP response header: Connection | keep-alive |
Content-Encoding | HTTP response header: Content-Encoding | gzip |
Content-Length | The length of the response body in bytes | 343 |
Content-Type | The media type of the resource | application/json |
Date | The date and time at which the message was originated | Thu, 17 Aug 2023 09:08:40 GMT |
Request-Time | HTTP response header: Request-Time | 537 |
Server | Information about the software used by the origin server | nginx/1.25.1 |
Strict-Transport-Security | HTTP response header: Strict-Transport-Security | max-age=31536000; includeSubDomains |
Transfer-Encoding | HTTP response header: Transfer-Encoding | chunked |
Vary | HTTP response header: Vary | Accept-Encoding |