From 2cac77bd5c14d69834b35b88e16c4eb174641574 Mon Sep 17 00:00:00 2001 From: To-om Date: Wed, 17 May 2017 11:24:51 +0200 Subject: [PATCH] Add doc to create an alert --- .gitignore | 1 + api/alert.md | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++ api/case.md | 4 +- 3 files changed, 119 insertions(+), 2 deletions(-) create mode 100644 .gitignore create mode 100644 api/alert.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..146752e --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +TheHiveDocs.iml diff --git a/api/alert.md b/api/alert.md new file mode 100644 index 0000000..0835a9b --- /dev/null +++ b/api/alert.md @@ -0,0 +1,116 @@ +# Alert + +## Model definition + +Required attributes: + - `title` (text) : title of the alert + - `description` (text) : description of the alert + - `severity` (number) : severity of the alert (0: not set; 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](https://www.us-cert.gov/tlp) (`-1`: `unknown`; `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) : cate template to use when case is created from this alert + +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` and`sourceRef`. + +## Alert Manipulation + +### Alert methods + +|HTTP Mehod |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](#Create-a-case) | +|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 | + + +### Create a Case + +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 refuses to create it. + +This call returns attributes of the created alert. + +#### Examples +Creation of a simple alert: +``` +curl -XPOST -u myuser:mypassword -H 'Content-Type: application/json' http://127.0.0.1:9000/api/case -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 -u myuser:mypassword -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" }, + { "dataType": "domain", "data": "thehive-project.org" }, + { "dataType": "file", "data": "logo.svg;image/svg+xml;PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhLS0gR2VuZXJhdG9yOiBBZG9iZSBJbGx1c3RyYXRvciAxOC4wLjAsIFNWRyBFeHBvcnQgUGx1Zy1JbiAuIFNWRyBWZXJzaW9uOiA2LjAwIEJ1aWxkIDApICAtLT4NCjwhRE9DVFlQRSBzdmcgUFVCTElDICItLy9XM0MvL0RURCBTVkcgMS4xLy9FTiIgImh0dHA6Ly93d3cudzMub3JnL0dyYXBoaWNzL1NWRy8xLjEvRFREL3N2ZzExLmR0ZCI+DQo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4Ig0KCSB2aWV3Qm94PSIwIDAgNjI0IDIwMCIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgNjI0IDIwMCIgeG1sOnNwYWNlPSJwcmVzZXJ2ZSI+DQo8Zz4NCgk8Zz4NCgkJPHBhdGggZmlsbD0iIzE1MTYzMiIgZD0iTTE3Mi4yLDczdjY2LjRoLTIwLjdWNzNoLTI3LjRWNTQuOGg3NS41VjczSDE3Mi4yeiIvPg0KCQk8cGF0aCBmaWxsPSIjMTUxNjMyIiBkPSJNMjcyLjgsMTAwLjV2MzguOWgtMjAuMXYtMzQuNmMwLTcuNC00LjQtMTIuNS0xMS0xMi41Yy03LjgsMC0xMyw1LjQtMTMsMTcuN3YyOS40aC0yMC4yVjQ4LjVoMjAuMlY4Mg0KCQkJYzQuOS01LDExLjUtNy45LDE5LjYtNy45QzI2Myw3NC4xLDI3Mi44LDg0LjYsMjcyLjgsMTAwLjV6Ii8+DQoJCTxwYXRoIGZpbGw9IiMxNTE2MzIiIGQ9Ik0zNTYuMywxMTIuOGgtNDYuNGMxLjYsNy42LDYuOCwxMi4yLDEzLjYsMTIuMmM0LjcsMCwxMC4xLTEuMSwxMy41LTcuM2wxNy45LDMuNw0KCQkJYy01LjQsMTMuNC0xNi45LDE5LjgtMzEuNCwxOS44Yy0xOC4zLDAtMzMuNC0xMy41LTMzLjQtMzMuNmMwLTE5LjksMTUuMS0zMy42LDMzLjYtMzMuNmMxNy45LDAsMzIuMywxMi45LDMyLjcsMzMuNlYxMTIuOHoNCgkJCSBNMzEwLjMsMTAwLjVoMjYuMWMtMS45LTYuOC02LjktMTAtMTIuNy0xMEMzMTgsOTAuNSwzMTIuMiw5NCwzMTAuMywxMDAuNXoiLz4NCgkJPHBhdGggZmlsbD0iI0YzRDAyRiIgZD0iTTQ0NS41LDEzOS4zaC0yMC43di0zMy40aC0zNS42djMzLjRoLTIwLjhWNTQuOGgyMC44djMyLjloMzUuNlY1NC44aDIwLjdWMTM5LjN6Ii8+DQoJCTxwYXRoIGZpbGw9IiNGM0QwMkYiIGQ9Ik00NzguNiw1Ny4zYzAsNi40LTQuOSwxMS4yLTExLjcsMTEuMmMtNi44LDAtMTEuNi00LjgtMTEuNi0xMS4yYzAtNi4yLDQuOC0xMS41LDExLjYtMTEuNQ0KCQkJQzQ3My43LDQ1LjgsNDc4LjYsNTEuMSw0NzguNiw1Ny4zeiBNNDU2LjgsMTM5LjNWNzZoMjAuMnY2My4zSDQ1Ni44eiIvPg0KCQk8cGF0aCBmaWxsPSIjRjNEMDJGIiBkPSJNNTI4LjUsMTM5LjNoLTIwLjZsLTI2LjItNjMuNUg1MDNsMTUuMywzOS4xbDE1LjEtMzkuMWgyMS4zTDUyOC41LDEzOS4zeiIvPg0KCQk8cGF0aCBmaWxsPSIjRjNEMDJGIiBkPSJNNjE4LjMsMTEyLjhoLTQ2LjRjMS42LDcuNiw2LjgsMTIuMiwxMy42LDEyLjJjNC43LDAsMTAuMS0xLjEsMTMuNS03LjNsMTcuOSwzLjcNCgkJCWMtNS40LDEzLjQtMTYuOSwxOS44LTMxLjQsMTkuOGMtMTguMywwLTMzLjQtMTMuNS0zMy40LTMzLjZjMC0xOS45LDE1LjEtMzMuNiwzMy42LTMzLjZjMTcuOSwwLDMyLjMsMTIuOSwzMi43LDMzLjZWMTEyLjh6DQoJCQkgTTU3Mi4yLDEwMC41aDI2LjFjLTEuOS02LjgtNi45LTEwLTEyLjctMTBDNTc5LjksOTAuNSw1NzQuMSw5NCw1NzIuMiwxMDAuNXoiLz4NCgk8L2c+DQoJPGc+DQoJCTxnPg0KCQkJPHBhdGggZmlsbD0iI0YzRDAyRiIgZD0iTTU3LDcwLjNjNi42LDAsMTIuMiw2LjQsMTIuMiwxMS41YzAsNi4xLTEwLDYuNi0xMiw2LjZsMCwwYy0yLjIsMC0xMi0wLjMtMTItNi42DQoJCQkJQzQ0LjgsNzYuNyw1MC40LDcwLjMsNTcsNzAuM0w1Nyw3MC4zeiBNNDQuMSwxMzMuNmwyNS4yLDAuMWwyLjIsNS42bC0yOS42LTAuMUw0NC4xLDEzMy42eiBNNDcuNiwxMjUuNmwyLjItNS42bDE0LjIsMGwyLjIsNS42DQoJCQkJTDQ3LjYsMTI1LjZ6IE01MywxMTIuMWwzLjktOS41bDMuOSw5LjVMNTMsMTEyLjF6IE0yMy4zLDE0My42Yy0xLjcsMC0zLjItMC4zLTQuNi0xYy02LjEtMi43LTkuMy05LjgtNi41LTE1LjkNCgkJCQljNi45LTE2LjYsMjcuNy0yOC41LDM5LTMwLjJsLTcuNCwxOC4xbDAsMEwzOC4zLDEyOGwwLDBsLTMuNSw4LjFDMzIuNiwxNDAuNywyOC4yLDE0My42LDIzLjMsMTQzLjZMMjMuMywxNDMuNnogTTU2LjcsMTYxLjgNCgkJCQljLTguMSwwLTE0LjctNS45LTE3LjMtMTVsMzQuNywwLjFDNzEuNCwxNTYuMiw2NC44LDE2MS44LDU2LjcsMTYxLjhMNTYuNywxNjEuOHogTTk1LDE0Mi45Yy0xLjUsMC43LTMuMiwxLTQuNiwxDQoJCQkJYy00LjksMC05LjMtMy0xMS4yLTcuNmwtMy40LTguMWwwLDBsLTUuMS0xMi43YzAtMC41LTAuMi0xLTAuNS0xLjVsLTctMTcuNmMxMS4yLDIsMzIsMTQsMzguOCwzMC41DQoJCQkJQzEwNC4zLDEzMy4zLDEwMS4zLDE0MC40LDk1LDE0Mi45TDk1LDE0Mi45eiIvPg0KCQkJDQoJCQkJPGxpbmUgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjRjNEMDJGIiBzdHJva2Utd2lkdGg9IjUuMjE0NiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbWl0ZXJsaW1pdD0iMTAiIHgxPSI0Ny44IiB5MT0iNjcuNSIgeDI9IjQzLjciIHkyPSI1OC45Ii8+DQoJCQkNCgkJCQk8bGluZSBmaWxsPSJub25lIiBzdHJva2U9IiNGM0QwMkYiIHN0cm9rZS13aWR0aD0iNS4yMTQ2IiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1taXRlcmxpbWl0PSIxMCIgeDE9IjY2LjEiIHkxPSI2Ny41IiB4Mj0iNzAuMSIgeTI9IjU4LjkiLz4NCgkJPC9nPg0KCQkNCgkJCTxwb2x5bGluZSBmaWxsPSJub25lIiBzdHJva2U9IiNGM0QwMkYiIHN0cm9rZS13aWR0aD0iNS4yMTQ2IiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIHN0cm9rZS1taXRlcmxpbWl0PSIxMCIgcG9pbnRzPSINCgkJCTk0LjgsMTAzLjUgMTA1LjUsODQuMiA4MS4xLDQyLjEgMzIuNyw0Mi4xIDguMyw4NC4yIDIwLDEwMy41IAkJIi8+DQoJPC9nPg0KPC9nPg0KPC9zdmc+DQo=" } + ], + "caseTemplate": "external-alert" +}' +``` \ No newline at end of file diff --git a/api/case.md b/api/case.md index f95b4d8..08a5373 100644 --- a/api/case.md +++ b/api/case.md @@ -10,11 +10,11 @@ Required attributes: - `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](https://www.us-cert.gov/tlp) (`-1`: `unknown`; `0`: `white`; `1`: `green`; `2: amber`; - `3: red`) **default=-1** + `3: red`) **default=2** - `status` (caseStatus) : status of the case (*Open*, *Resolved* or *Deleted*) **default=Open** + - `tags` (multi-string) : case tags **default=empty** 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*)