Skip to content

API Documentation

Jump to bottom
To-om edited this page Mar 7, 2017 · 6 revisions

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
  • owner (string) : user to whom the case has been assigned default=use who create the case
  • 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

### Log

Required attributes:

  • message (text) : content of the Log
  • startDate (date) : date of the log submission default=now
  • status (logStatus) : status of the log (Ok or Deleted) default=Ok

Optional attributes:

  • attachment (attachment) : file attached to the log

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.

This call returns attributes of the created case.

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"
}'

It returns:

{
  "severity": 3,
  "createdBy": "myuser",
  "createdAt": 1488918582777,
  "caseId": 1,
  "title": "My first case",
  "startDate": 1488918582836,
  "owner": "myuser",
  "status": "Open",
  "description": "This case have been created by my custom script",
  "user": "myuser",
  "tlp": 2,
  "flag": false,
  "id": "AVqqdpY2yQ6w1DNC8aDh",
  "type":"case"
}

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 !)

Task manipulation

Create a task

The URL used to create a task is:

POST /api/case/<<caseId>>/task

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

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

This call returns attributes of the created task.

Examples

Creation of a simple task in case AVqqdpY2yQ6w1DNC8aDh:

curl -XPOST -u myuser:mypassword -H 'Content-Type: application/json' http://127.0.0.1:9000/api/case/AVqqdpY2yQ6w1DNC8aDh/task -d '{
  "title": "Do something"
}'

It returns:

{
  "createdAt": 1488918771513,
  "status": "Waiting",
  "createdBy": "myuser",
  "title": "Do something",
  "order": 0,
  "user": "myuser",
  "flag": false,
  "id":"AVqqeXc9yQ6w1DNC8aDj",
  "type":"case_task"
}

Creation of another task:

curl -XPOST -u myuser:mypassword -H 'Content-Type: application/json' http://127.0.0.1:9000/api/case/AVqqdpY2yQ6w1DNC8aDh/task -d '{
  "title": "Analyze the malware",
  "description": "The malware XXX is analyzed using sandbox ...",
  "owner": "Joe",
  "status": "InProgress"
}'

Log manipulation

Create a log

The URL used to create a task is:

POST /api/case/task/<<taskId>>/log

<<taskId>> must be replaced by task id

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

This call returns attributes of the created log.

Examples

Creation of a simple log in task AVqqeXc9yQ6w1DNC8aDj:

curl -XPOST -u myuser:mypassword -H 'Content-Type: application/json' http://127.0.0.1:9000/api/case/task/AVqqeXc9yQ6w1DNC8aDj/log -d '{
  "message": "Some message"
}'

It returns:

{
  "startDate": 1488919949497,
  "createdBy": "admin",
  "createdAt": 1488919949495,
  "user": "myuser",
  "message":"Some message",
  "status": "Ok",
  "id": "AVqqi3C-yQ6w1DNC8aDq",
  "type":"case_task_log"
}

If log contain attachment, request must be in multipart format: Creation of another log, with attachment:

curl -XPOST -u myuser:mypassword http://127.0.0.1:9000/api/case/AVqqdpY2yQ6w1DNC8aDh/task -F '_json={"message": "Screenshot of fake site"};type=application/json' -F '[email protected];type=image/png'

It returns:

{
  "createdBy": "myuser",
  "message": "Screenshot of fake site",
  "createdAt": 1488920587391,
  "startDate": 1488920587394,
  "user": "myuser",
  "status": "Ok",
  "attachment": {
    "name": "screenshot1.png",
    "hashes": [
      "086541e99743c6752f5fd4931e256e6e8d5fc7afe47488fb9e0530c390d0ca65",
      "8b81e038ae0809488f20b5ec7dc91e488ef601e2",
      "c5883708f42a00c3ab1fba5bbb65786c"
    ],
    "size": 15296,
    "contentType": "image/png",
    "id": "086541e99743c6752f5fd4931e256e6e8d5fc7afe47488fb9e0530c390d0ca65"
  },
  "id": "AVqqlSy0yQ6w1DNC8aDx",
  "type": "case_task_log"
}

Documentation has been moved here

Clone this wiki locally