API Documentation

Getting Started

TheHive exposes REST APIs through JSON over HTTP.

Request formats

TheHive accepts several parameter formats within a HTTP request. They can be used indifferently. Input data can be:

• a query string
• URL-encoded form
• multi-part
• JSON

Hence, the requests below are equivalent.

Query String

curl -XPOST 'http://127.0.0.1:9000/api/login?user=me&password=secret'

URL-encoded Form

curl -XPOST 'http://127.0.0.1:9000/api/login' -d user=me -d password=secret

JSON

curl -XPOST http://127.0.0.1:9000/api/login -H 'Content-Type: application/json' -d '{
  "user": "me",
  "password": "secret"
}'

Multi-part

curl -XPOST http://127.0.0.1:9000/api/login -F '_json=<-;type=application/json' << _EOF_
{
  "user": "me",
  "password": "secret"
}
_EOF_

Response Format

TheHive outputs JSON data.

Field Types

• string : textual data (example "malware").
• text : textual data. The difference between string and text is in the way content can be searched.string is searchable as-is whereas text, words (token) are searchable, not the whole content (example "Ten users have received this ransomware").
• date : date and time using ISO format (example: "20161122T104300+2000") From TheHive 2.10.0, the date use timestamps with milliseconds format. ISO format is still accepted as input but is considered deprecated.
• boolean : true or false
• number : numeric value
• metrics : JSON object that contains only numbers

Field can be prefixed with multi- in order to indicate that multiple values can be provided.

Authentication

Most API calls requires authentication. Credentials can be provided using a session cookie or directly using HTTP basic authentication. (API key is not usable in the current version of TheHive, due to a rethinking of service account TODO need issue reference).

Session cookie is suitable for browser authentication, not for a dedicated tool. The easiest solution if you want to write a tool that use TheHive API is to use basic authentication. For example, to list cases, use the following curl command:

curl -u mylogin:mypassword http://127.0.0.1:9000/api/cases

TheHive Backend

Model Definition

Common Attributes

All entities share the following attributes:

• createdBy (text) : login of the user who create the entity
• createdAt (date) : date and time of the creation
• updatedBy (text) : login of the user who do the last update of the entity
• upadtedAt (date) : date and time of the last update
• user (text) : same value as createdBy (this field is deprecated) This attributes are handled by back-end and can't be directly updated.

Case

Required attributes:

• title (text) : title of the case
• description (text) : description of the case
• severity (number) : severity of the case (0: not set; 1: low; 2: medium; 3: high) default=2
• startDate (date) : date and time of the begin of the case default=now
• flag (boolean) : flag of the case default=false
• tlp (number) : TLP (-1: unknown; 0: white; 1: green; 2: amber; 3: red) default=-1
• status (caseStatus) : status of the case (Open, Resolved or Deleted) default=Open

Optional attributes:

• tags (multi-string) : case tags
• resolutionStatus (caseResolutionStatus) : resolution status of the case (Indeterminate, FalsePositive, TruePositive, Other or Duplicated)
• impactStatus (caseImpactStatus) : impact status of the case (NoImpact, WithImpact or NotApplicable)
• summary (text) : summary of the case, to be provided when closing a case
• endDate (date) : resolution date
• metrics (metrics) : list of metrics

Attributes generated by the backend:

• caseId (number) : Id of the case (auto-generated)
• mergeInto (string) : ID of the case created by the merge
• mergeFrom (multi-string) : IDs of the cases that were merged

Task

Required attributes:

• title (text) : title of the task
• status (taskStatus) : status of the task (Waiting, InProgress, Completed or Cancel) default=Waiting
• flag (boolean) : flag of the task default=false

Optional attributes:

• owner (string) : user who owns the task. This is automatically set to current user when status is set to InProgress
• description (text) : task details
• startDate (date) : date of the beginning of the task. This is automatically set when status is set to Open
• endDate (date) : date of the end of the task. This is automatically set when status is set to Completed

Observable

Required attributes:

• data (string) : content of the observable (read only). An observable can't contain data and attachment attributes
• attachment (attachment) : observable file content (read-only). An observable can't contain data and attachment attributes
• dataType (enumeration) : type of the observable (read only)
• message (text) : description of the observable in the context of the case
• startDate (date) : date of the observable creation default=now
• tlp (number) : TLP (-1: unknown; 0: white; 1: green; 2: amber; 3: red) default=2
• ioc (boolean) : indicates if the observable is an IOC default=false
• status (artifactStatus) : status of the observable (Ok or Deleted) default=Ok

Optional attributes:

• tags (multi-string) : observable tags

Case Manipulation

Create a Case

A case can be created using the following url :

POST     /api/case

Required case attributes (cf. models) must be provided.

Examples

Creation of a simple case:

curl -XPOST -u myuser:mypassword -H 'Content-Type: application/json' http://127.0.0.1:9000/api/case -d '{
  "title": "My first case",
  "description": "This case have been created by my custom script"
}'

Creation of another case:

curl -XPOST -u myuser:mypassword -H 'Content-Type: application/json' http://127.0.0.1:9000/api/case -d '{
  "title": "My second case",
  "description": "This case have been created by my custom script, its severity is high, tlp is red and it contains tags",
  "severity": 3,
  "tlp": 3,
  "tags": ["automatic", "creation"]
}'

Observable manipulation

List Observables of a Case

Complete observable list of a case can be retrieve by performing a search:

POST     /api/case/artifact/_search

Parameters:

• query: { "_parent": { "_type": "case", "_query": { "_id": "<<caseId>>" } } }
• range: all

<<caseId>> must be replaced by case id (not the case number !)