Skip to content

Alert#

Model definition#

Required attributes: - title (text) : title of the alert - description (text) : description of the alert - severity (number) : severity of the alert (1: low; 2: medium; 3: high) default=2 - date (date) : date and time when the alert was raised default=now - tags (multi-string) : case tags default=empty - tlp (number) : TLP (0: white; 1: green; 2: amber; 3: red) default=2 - status (AlertStatus) : status of the alert (New, Updated, Ignored, Imported) default=New - type (string) : type of the alert (read only) - source (string) : source of the alert (read only) - sourceRef (string) : source reference of the alert (read only) - artifacts (multi-artifact) : artifact of the alert. It is a array of JSON object containing artifact attributes default=empty - follow (boolean) : if true, the alert becomes active when updated default=true

Optional attributes: - caseTemplate (string) : case template to use when a case is created from this alert. If the alert specifies a non-existent case template or doesn't supply one, TheHive will import the alert into a case using a case template that has the exact same name as the alert's type if it exists. For example, if you raise an alert with a type value of splunk and you do not provide the caseTemplate attribute or supply a non-existent one (for example splink), TheHive will import the alert using the case template called splunk if it exists. Otherwise, the alert will be imported using an empty case (i.e. from scratch).

Attributes generated by the backend: - lastSyncDate (date) : date of the last synchronization - case (string) : id of the case, if created

Alert ID is computed from type, source andsourceRef.

Alert Manipulation#

Alert methods#

HTTP Method URI Action
GET /api/alert List alerts
POST /api/alert/_search Find alerts
PATCH /api/alert/_bulk Update alerts in bulk
POST /api/alert/_stats Compute stats on alerts
POST /api/alert Create an alert
GET /api/alert/:alertId Get an alert
PATCH /api/alert/:alertId Update an alert
DELETE /api/alert/:alertId Delete an alert
POST /api/alert/:alertId/markAsRead Mark an alert as read
POST /api/alert/:alertId/markAsUnread Mark an alert as unread
POST /api/alert/:alertId/createCase Create a case from an alert
POST /api/alert/:alertId/follow Follow an alert
POST /api/alert/:alertId/unfollow Unfollow an alert
POST /api/alert/:alertId/merge/:caseId Merge an alert in a case
POST /api/alert/merge/_bulk Merge several alerts in one case

Get an alert#

An alert's details can be retrieve using the url: 

GET     /api/alert/:alertId
The alert ID is obtained by List alerts or Find alerts API.

If the parameter similarity is set to "1" or "true", this API returns information on cases which have similar observables. With this feature, output will contain the similarCases attribute which list case details with: - artifactCount: number of observables in the original case - iocCount: number of observables marked as IOC in original case - similarArtifactCount: number of observables which are in alert and in case - similarIocCount: number of IOCs which are in alert and in case

warning IOCs are observables

Examples#

Get alert without similarity data: 

curl -H 'Authorization: Bearer ***API*KEY***' http://127.0.0.1:9000/api/alert/ce2c00f17132359cb3c50dfbb1901810
It returns: 
{
    "_id": "ce2c00f17132359cb3c50dfbb1901810",
    "_type": "alert",
    "artifacts": [],
    "createdAt": 1495012062014,
    "createdBy": "myuser",
    "date": 1495012062016,
    "description": "N/A",
    "follow": true,
    "id": "ce2c00f17132359cb3c50dfbb1901810",
    "lastSyncDate": 1495012062016,
    "severity": 2,
    "source": "instance1",
    "sourceRef": "alert-ref",
    "status": "New",
    "title": "New Alert",
    "tlp": 2,
    "type": "external",
    "user": "myuser"
}

Get alert with similarity data: 

curl -H 'Authorization: Bearer ***API*KEY***' http://127.0.0.1:9000/api/alert/ce2c00f17132359cb3c50dfbb1901810?similarity=1
It returns: 
{
    "_id": "ce2c00f17132359cb3c50dfbb1901810",
    "_type": "alert",
    "artifacts": [],
    "createdAt": 1495012062014,
    "createdBy": "myuser",
    "date": 1495012062016,
    "description": "N/A",
    "follow": true,
    "id": "ce2c00f17132359cb3c50dfbb1901810",
    "lastSyncDate": 1495012062016,
    "severity": 2,
    "source": "instance1",
    "sourceRef": "alert-ref",
    "status": "New",
    "title": "New Alert",
    "tlp": 2,
    "type": "external",
    "user": "myuser",
    "similarCases": [
        {
            "_id": "AVwwrym-Rw5vhyJUfdJW",
            "artifactCount": 5,
            "endDate": null,
            "id": "AVwwrym-Rw5vhyJUfdJW",
            "iocCount": 1,
            "resolutionStatus": null,
            "severity": 1,
            "similarArtifactCount": 2,
            "similarIocCount": 1,
            "startDate": 1495465039000,
            "status": "Open",
            "tags": [
                "src:MISP"
            ],
            "caseId": 1405,
            "title": "TEST TheHive",
            "tlp": 2
        }
    ]
}

Create an alert#

An alert can be created using the following url: 

POST     /api/alert
Required case attributes (cf. models) must be provided.

If an alert with the same tuple type, source and sourceRef already exists, TheHive will refuse to create it.

This call returns attributes of the created alert.

Examples#

Creation of a simple alert: 

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/api/alert -d '{
  "title": "New Alert",
  "description": "N/A",
  "type": "external",
  "source": "instance1",
  "sourceRef": "alert-ref"
}'
It returns: 
{
    "_id": "ce2c00f17132359cb3c50dfbb1901810",
    "_type": "alert",
    "artifacts": [],
    "createdAt": 1495012062014,
    "createdBy": "myuser",
    "date": 1495012062016,
    "description": "N/A",
    "follow": true,
    "id": "ce2c00f17132359cb3c50dfbb1901810",
    "lastSyncDate": 1495012062016,
    "severity": 2,
    "source": "instance1",
    "sourceRef": "alert-ref",
    "status": "New",
    "title": "New Alert",
    "tlp": 2,
    "type": "external",
    "user": "myuser"
}

Creation of another alert: 

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/api/alert -d '{
  "title": "Other alert",
  "description": "alert description",
  "type": "external",
  "source": "instance1",
  "sourceRef": "alert-ref",
  "severity": 3,
  "tlp": 3,
  "artifacts": [
    { "dataType": "ip", "data": "127.0.0.1", "message": "localhost" },
    { "dataType": "domain", "data": "thehive-project.org", "tags": ["home", "TheHive"] },
    { "dataType": "file", "data": "logo.svg;image/svg+xml;PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhLS0gR2VuZXJhdG9yOiBBZG9iZSBJbGx1c3RyYXRvciAxOC4wLjAsIFNWRyBFeHBvcnQgUGx1Zy1JbiAuIFNWRyBWZXJzaW9uOiA2LjAwIEJ1aWxkIDApICAtLT4NCjwhRE9DVFlQRSBzdmcgUFVCTElDICItLy9XM0MvL0RURCBTVkcgMS4xLy9FTiIgImh0dHA6Ly93d3cudzMub3JnL0dyYXBoaWNzL1NWRy8xLjEvRFREL3N2ZzExLmR0ZCI+DQo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4Ig0KCSB2aWV3Qm94PSIwIDAgNjI0IDIwMCIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgNjI0IDIwMCIgeG1sOnNwYWNlPSJwcmVzZXJ2ZSI+DQo8Zz4NCgk8Zz4NCgkJPHBhdGggZmlsbD0iIzE1MTYzMiIgZD0iTTE3Mi4yLDczdjY2LjRoLTIwLjdWNzNoLTI3LjRWNTQuOGg3NS41VjczSDE3Mi4yeiIvPg0KCQk8cGF0aCBmaWxsPSIjMTUxNjMyIiBkPSJNMjcyLjgsMTAwLjV2MzguOWgtMjAuMXYtMzQuNmMwLTcuNC00LjQtMTIuNS0xMS0xMi41Yy03LjgsMC0xMyw1LjQtMTMsMTcuN3YyOS40aC0yMC4yVjQ4LjVoMjAuMlY4Mg0KCQkJYzQuOS01LDExLjUtNy45LDE5LjYtNy45QzI2Myw3NC4xLDI3Mi44LDg0LjYsMjcyLjgsMTAwLjV6Ii8+DQoJCTxwYXRoIGZpbGw9IiMxNTE2MzIiIGQ9Ik0zNTYuMywxMTIuOGgtNDYuNGMxLjYsNy42LDYuOCwxMi4yLDEzLjYsMTIuMmM0LjcsMCwxMC4xLTEuMSwxMy41LTcuM2wxNy45LDMuNw0KCQkJYy01LjQsMTMuNC0xNi45LDE5LjgtMzEuNCwxOS44Yy0xOC4zLDAtMzMuNC0xMy41LTMzLjQtMzMuNmMwLTE5LjksMTUuMS0zMy42LDMzLjYtMzMuNmMxNy45LDAsMzIuMywxMi45LDMyLjcsMzMuNlYxMTIuOHoNCgkJCSBNMzEwLjMsMTAwLjVoMjYuMWMtMS45LTYuOC02LjktMTAtMTIuNy0xMEMzMTgsOTAuNSwzMTIuMiw5NCwzMTAuMywxMDAuNXoiLz4NCgkJPHBhdGggZmlsbD0iI0YzRDAyRiIgZD0iTTQ0NS41LDEzOS4zaC0yMC43di0zMy40aC0zNS42djMzLjRoLTIwLjhWNTQuOGgyMC44djMyLjloMzUuNlY1NC44aDIwLjdWMTM5LjN6Ii8+DQoJCTxwYXRoIGZpbGw9IiNGM0QwMkYiIGQ9Ik00NzguNiw1Ny4zYzAsNi40LTQuOSwxMS4yLTExLjcsMTEuMmMtNi44LDAtMTEuNi00LjgtMTEuNi0xMS4yYzAtNi4yLDQuOC0xMS41LDExLjYtMTEuNQ0KCQkJQzQ3My43LDQ1LjgsNDc4LjYsNTEuMSw0NzguNiw1Ny4zeiBNNDU2LjgsMTM5LjNWNzZoMjAuMnY2My4zSDQ1Ni44eiIvPg0KCQk8cGF0aCBmaWxsPSIjRjNEMDJGIiBkPSJNNTI4LjUsMTM5LjNoLTIwLjZsLTI2LjItNjMuNUg1MDNsMTUuMywzOS4xbDE1LjEtMzkuMWgyMS4zTDUyOC41LDEzOS4zeiIvPg0KCQk8cGF0aCBmaWxsPSIjRjNEMDJGIiBkPSJNNjE4LjMsMTEyLjhoLTQ2LjRjMS42LDcuNiw2LjgsMTIuMiwxMy42LDEyLjJjNC43LDAsMTAuMS0xLjEsMTMuNS03LjNsMTcuOSwzLjcNCgkJCWMtNS40LDEzLjQtMTYuOSwxOS44LTMxLjQsMTkuOGMtMTguMywwLTMzLjQtMTMuNS0zMy40LTMzLjZjMC0xOS45LDE1LjEtMzMuNiwzMy42LTMzLjZjMTcuOSwwLDMyLjMsMTIuOSwzMi43LDMzLjZWMTEyLjh6DQoJCQkgTTU3Mi4yLDEwMC41aDI2LjFjLTEuOS02LjgtNi45LTEwLTEyLjctMTBDNTc5LjksOTAuNSw1NzQuMSw5NCw1NzIuMiwxMDAuNXoiLz4NCgk8L2c+DQoJPGc+DQoJCTxnPg0KCQkJPHBhdGggZmlsbD0iI0YzRDAyRiIgZD0iTTU3LDcwLjNjNi42LDAsMTIuMiw2LjQsMTIuMiwxMS41YzAsNi4xLTEwLDYuNi0xMiw2LjZsMCwwYy0yLjIsMC0xMi0wLjMtMTItNi42DQoJCQkJQzQ0LjgsNzYuNyw1MC40LDcwLjMsNTcsNzAuM0w1Nyw3MC4zeiBNNDQuMSwxMzMuNmwyNS4yLDAuMWwyLjIsNS42bC0yOS42LTAuMUw0NC4xLDEzMy42eiBNNDcuNiwxMjUuNmwyLjItNS42bDE0LjIsMGwyLjIsNS42DQoJCQkJTDQ3LjYsMTI1LjZ6IE01MywxMTIuMWwzLjktOS41bDMuOSw5LjVMNTMsMTEyLjF6IE0yMy4zLDE0My42Yy0xLjcsMC0zLjItMC4zLTQuNi0xYy02LjEtMi43LTkuMy05LjgtNi41LTE1LjkNCgkJCQljNi45LTE2LjYsMjcuNy0yOC41LDM5LTMwLjJsLTcuNCwxOC4xbDAsMEwzOC4zLDEyOGwwLDBsLTMuNSw4LjFDMzIuNiwxNDAuNywyOC4yLDE0My42LDIzLjMsMTQzLjZMMjMuMywxNDMuNnogTTU2LjcsMTYxLjgNCgkJCQljLTguMSwwLTE0LjctNS45LTE3LjMtMTVsMzQuNywwLjFDNzEuNCwxNTYuMiw2NC44LDE2MS44LDU2LjcsMTYxLjhMNTYuNywxNjEuOHogTTk1LDE0Mi45Yy0xLjUsMC43LTMuMiwxLTQuNiwxDQoJCQkJYy00LjksMC05LjMtMy0xMS4yLTcuNmwtMy40LTguMWwwLDBsLTUuMS0xMi43YzAtMC41LTAuMi0xLTAuNS0xLjVsLTctMTcuNmMxMS4yLDIsMzIsMTQsMzguOCwzMC41DQoJCQkJQzEwNC4zLDEzMy4zLDEwMS4zLDE0MC40LDk1LDE0Mi45TDk1LDE0Mi45eiIvPg0KCQkJDQoJCQkJPGxpbmUgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjRjNEMDJGIiBzdHJva2Utd2lkdGg9IjUuMjE0NiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbWl0ZXJsaW1pdD0iMTAiIHgxPSI0Ny44IiB5MT0iNjcuNSIgeDI9IjQzLjciIHkyPSI1OC45Ii8+DQoJCQkNCgkJCQk8bGluZSBmaWxsPSJub25lIiBzdHJva2U9IiNGM0QwMkYiIHN0cm9rZS13aWR0aD0iNS4yMTQ2IiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1taXRlcmxpbWl0PSIxMCIgeDE9IjY2LjEiIHkxPSI2Ny41IiB4Mj0iNzAuMSIgeTI9IjU4LjkiLz4NCgkJPC9nPg0KCQkNCgkJCTxwb2x5bGluZSBmaWxsPSJub25lIiBzdHJva2U9IiNGM0QwMkYiIHN0cm9rZS13aWR0aD0iNS4yMTQ2IiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIHN0cm9rZS1taXRlcmxpbWl0PSIxMCIgcG9pbnRzPSINCgkJCTk0LjgsMTAzLjUgMTA1LjUsODQuMiA4MS4xLDQyLjEgMzIuNyw0Mi4xIDguMyw4NC4yIDIwLDEwMy41IAkJIi8+DQoJPC9nPg0KPC9nPg0KPC9zdmc+DQo=", "message": "logo" }
  ],
  "caseTemplate": "external-alert"
}'

Merge an alert#

An alert can be merge in a case using the URL: 

POST     /api/alert/:alertId/merge/:caseId
Each observable of the alert will be added to the case if it doesn't exist in the case. The description of the alert will be appended to the case's description.

The HTTP response contains the updated case.

Example#

Merge the alert ce2c00f17132359cb3c50dfbb1901810 in case AVXeF-pZmeHK_2HEYj2z: 

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' http://127.0.0.1:9000/api/alert/ce2c00f17132359cb3c50dfbb1901810/merge/AVXeF-pZmeHK_2HEYj2z
The call returns: 
{
  "severity": 3,
  "createdBy": "myuser",
  "createdAt": 1488918582777,
  "caseId": 1,
  "title": "My first case",
  "startDate": 1488918582836,
  "owner": "myuser",
  "status": "Open",
  "description": "This case has been created by my custom script

  ### Merged with alert #10 my alert title

  This is my alert description",
  "user": "myuser",
  "tlp": 2,
  "flag": false,
  "id": "AVXeF-pZmeHK_2HEYj2z",
  "_id": "AVXeF-pZmeHK_2HEYj2z",
  "_type":"case"
}

Bulk merge alert#

This API merge several alerts with one case: 

POST     /api/alert/merge/_bulk
The observable of each alert listed in alertIds field will be imported into the case (identified by caseId field). The description of the case is not modified.

The HTTP response contains the case.

Example#

Merge the alerts ce2c00f17132359cb3c50dfbb1901810 and a97148693200f731cfa5237ff2edf67b in case AVXeF-pZmeHK_2HEYj2z: 

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/api/alert/merge/_bulk -d '{
  "caseId": "AVXeF-pZmeHK_2HEYj2z",
  "alertIds": ["ce2c00f17132359cb3c50dfbb1901810", "a97148693200f731cfa5237ff2edf67b"]
}'
The call returns: 
{
  "severity": 3,
  "createdBy": "myuser",
  "createdAt": 1488918582777,
  "caseId": 1,
  "title": "My first case",
  "startDate": 1488918582836,
  "owner": "myuser",
  "status": "Open",
  "description": "This case has been created by my custom script",
  "user": "myuser",
  "tlp": 2,
  "flag": false,
  "id": "AVXeF-pZmeHK_2HEYj2z",
  "_id": "AVXeF-pZmeHK_2HEYj2z",
  "_type":"case"
}

Last update: March 2, 2021 11:39:03