From c27c5fd553c962988049fcb0feba0a26303aa43f Mon Sep 17 00:00:00 2001 From: To-om Date: Mon, 6 Sep 2021 11:52:26 +0200 Subject: [PATCH] #12 Add task doc --- docs/thehive/api/task/.pages | 12 ++- docs/thehive/api/task/create-log.md | 84 +++++++++++++++++ docs/thehive/api/task/delete-log.md | 21 +++++ docs/thehive/api/task/get.md | 65 ++++++++++++++ docs/thehive/api/task/index.md | 6 +- docs/thehive/api/task/list.md | 2 +- docs/thehive/api/task/log-responder-jobs.md | 54 +++++++++++ docs/thehive/api/task/log-run-responder.md | 82 +++++++++++++++++ docs/thehive/api/task/responder-jobs.md | 54 +++++++++++ docs/thehive/api/task/run-responder.md | 82 +++++++++++++++++ docs/thehive/api/task/waiting-tasks.md | 99 +++++++++++++++++++++ 11 files changed, 556 insertions(+), 5 deletions(-) diff --git a/docs/thehive/api/task/.pages b/docs/thehive/api/task/.pages index 0f8455ed..baadc2c8 100644 --- a/docs/thehive/api/task/.pages +++ b/docs/thehive/api/task/.pages @@ -1,3 +1,13 @@ nav: - create.md - - update.md \ No newline at end of file + - update.md + - get.md + - list.md + - run-responder.md + - responder-jobs.md + - create-log.md + - delete-lod.md + - log-run-responder.md + - log-responder-jobs.md + - logs.md + - waiting-tasks.md diff --git a/docs/thehive/api/task/create-log.md b/docs/thehive/api/task/create-log.md index e69de29b..62da33f0 100644 --- a/docs/thehive/api/task/create-log.md +++ b/docs/thehive/api/task/create-log.md @@ -0,0 +1,84 @@ +# Add log + +Add a *Log* to an existing task (requires `manageTask` permission). + +## Query + +```plain +POST /api/case/task/{id}/log +``` + +With: + +- `id`: Task identifier + +## Request Body Example + +!!! Example "" + + ```json + { + "message": "The sandbox hasn't detected any suspicious activity", + "startDate": 1630683608000, + } + ``` + +The only required field is `message`. + + +If you want to attach a file to the log, you need to use a multipart request + +!!! Example "" + + + ``` + curl -XPOST http://THEHIVE/api/v0/case/task/{taskId}/log -F attachment=@report.pdf -F _json=' + { + "message": "The sandbox report" + } + ' + ``` + +## Response + +### Status codes + +- `201`: if *Log* is created successfully +- `401`: Authentication error +- `403`: Authorization error + +### Response Body Example + +!!! Example "" + + === "201" + + ```json + { + "id": "~4264", + "_id": "~4264", + "createdBy": "jerome@strangebee.com", + "createdAt": 1630684502715, + "_type": "case_taskçlog", + "message": "The sandbox hasn't detected any suspicious activity", + "startDate": 1630683608000 + } + ``` + + === "401" + + ```json + { + "type": "AuthenticationError", + "message": "Authentication failure" + } + ``` + + === "403" + + ```json + { + "type": "AuthorizationError", + "message": "Your are not authorized to create Log, you haven't the permission manageTask" + } + ``` \ No newline at end of file diff --git a/docs/thehive/api/task/delete-log.md b/docs/thehive/api/task/delete-log.md index e69de29b..1c05b479 100644 --- a/docs/thehive/api/task/delete-log.md +++ b/docs/thehive/api/task/delete-log.md @@ -0,0 +1,21 @@ +# Add log + +Add a *Log* to an existing task (requires `manageTask` permission). + +## Query + +```plain +DELETE /api/case/task/log/{id} +``` + +With: + +- `id`: Log identifier + +## Response + +### Status codes + +- `204`: if *Log* is created successfully +- `401`: Authentication error +- `403`: Authorization error \ No newline at end of file diff --git a/docs/thehive/api/task/get.md b/docs/thehive/api/task/get.md index e69de29b..0192facb 100644 --- a/docs/thehive/api/task/get.md +++ b/docs/thehive/api/task/get.md @@ -0,0 +1,65 @@ +# List + +List *Task*s of a case. + +## Query + +```plain +GET /api/case/task/{id} +``` + +with: + +- `id`: id of the task. + +## Response + +### Status codes + +- `200`: if query is run successfully +- `401`: Authentication error +- `404`: The *Task* is not found + +### ResponseBody Example + +!!! Example "" + + === "201" + + ```json + { + "id": "~4264", + "_id": "~4264", + "createdBy": "jerome@strangebee.com", + "createdAt": 1630684502715, + "_type": "case_task", + "title": "Malware analysis", + "group": "identification", + "description": "Analysis of the file to identify the malware", + "owner": "jerome@strangebee.com", + "status": "InProgress", + "flag": false, + "startDate": 1630683608000, + "endDate": 1630684608000, + "order": 3, + "dueDate": 1630694608000 + } + ``` + + === "401" + + ```json + { + "type": "AuthenticationError", + "message": "Authentication failure" + } + ``` + + === "404" + + ```json + { + "type": "AuthenticationError", + "message": "Task not found" + } + ``` diff --git a/docs/thehive/api/task/index.md b/docs/thehive/api/task/index.md index d744628d..8d563b3c 100644 --- a/docs/thehive/api/task/index.md +++ b/docs/thehive/api/task/index.md @@ -11,12 +11,12 @@ ## Case task log oprations -- [List task logs](logs.md) +- [List task logs](logs.md) TODO - [Create task log](create-log.md) - [delete task log](delete-log.md) - [Run responder on log](log-run-responder.md) -- [List responder jobs on log](log-responder-jobs.md) +- [List responder jobs on log](log-responder-jobs.md) TODO ## Global task operations -- [List waiting tasks](waiting-tasks.md) \ No newline at end of file +- [List waiting tasks](waiting-tasks.md) TODO \ No newline at end of file diff --git a/docs/thehive/api/task/list.md b/docs/thehive/api/task/list.md index da942499..e7fbbfac 100644 --- a/docs/thehive/api/task/list.md +++ b/docs/thehive/api/task/list.md @@ -41,7 +41,7 @@ POST /api/v0/query ### Status codes -- `200`: if *Task* is updated successfully +- `200`: if query is run successfully - `401`: Authentication error ### ResponseBody Example diff --git a/docs/thehive/api/task/log-responder-jobs.md b/docs/thehive/api/task/log-responder-jobs.md index e69de29b..975a763d 100644 --- a/docs/thehive/api/task/log-responder-jobs.md +++ b/docs/thehive/api/task/log-responder-jobs.md @@ -0,0 +1,54 @@ +# List responder actions + +List actions run on a log. + +## Query + +```plain +GET /api/connector/cortex/action/case_task_log/{id} +``` + +With: + +- `id`: Log identifier + +## Response + +### Status codes + +- `200`: if query is run successfully +- `401`: Authentication error + +### Response Body Example + +!!! Example "" + + === "200" + + ```json + [ + { + "responderId": "25dcbbb69d50dd5a5ae4bd55f4ca5903", + "responderName": "reponderName_1_0", + "responderDefinition": "reponderName_1_0", + "cortexId": "local-cortex", + "cortexJobId": "408-unsB3SwW9-eEPXXW", + "objectType": "Log", + "objectId": "~25313328", + "status": "Success", + "startDate": 1630917246993, + "endDate": 1630917254406, + "operations": "[]", + "report": "{\"summary\":{\"taxonomies\":[]},\"full\":null,\"success\":true,\"artifacts\":[],\"operations\":[],\\\"message\\\":\\\"Ok\\\",\\\"parameters\\\":{\\\"organisation\\\":\\\"StrangeBee\\\",\\\"user\\\":\\\"jerome@strangebee.com\\\"},\\\"config\\\":{\\\"proxy_https\\\":null,\\\"cacerts\\\":null,\\\"check_tlp\\\":false,\\\"max_tlp\\\":2,\\\"check_pap\\\":false,\\\"max_pap\\\":2,\\\"jobTimeout\\\":30,\\\"proxy_http\\\":null}}\"}" + } + ] + ``` + + === "401" + + ```json + { + "type": "AuthenticationError", + "message": "Authentication failure" + } + ``` diff --git a/docs/thehive/api/task/log-run-responder.md b/docs/thehive/api/task/log-run-responder.md index e69de29b..872209d9 100644 --- a/docs/thehive/api/task/log-run-responder.md +++ b/docs/thehive/api/task/log-run-responder.md @@ -0,0 +1,82 @@ +# Run responder + +Run a responder on a *Log* (requires `manageAction` permission). + +## Query + +```plain +POST /api/connector/cortex/action +``` + +## Request Body Example + +!!! Example "" + + ```json + { + "responderId": "25dcbbb69d50dd5a5ae4bd55f4ca5903", + "cortexId": "local-cortex", + "objectType": "case_task_log", + "objectId": "~11123" + } + ``` + +The required fields are `responderId`, `objectType` and `objectId`. + +## Response + +### Status codes + +- `201`: if responder is started successfully +- `401`: Authentication error +- `403`: Authorization error +- `404`: Log is not found + +### Response Body Example + +!!! Example "" + + === "201" + + ```json + { + "responderId": "25dcbbb69d50dd5a5ae4bd55f4ca5903", + "responderName": "reponderName_1_0", + "responderDefinition": "reponderName_1_0", + "cortexId": "local-cortex", + "cortexJobId": "408-unsB3SwW9-eEPXXW", + "objectType": "Log", + "objectId": "~25313328", + "status": "Waiting", + "startDate": 1630917246993, + "operations": "[]", + "report": "{}" + } + ``` + + === "401" + + ```json + { + "type": "AuthenticationError", + "message": "Authentication failure" + } + ``` + + === "403" + + ```json + { + "type": "AuthorizationError", + "message": "Your are not authorized to create action, you haven't the permission manageTask" + } + ``` + + === "404" + + ```json + { + "type": "AuthenticationError", + "message": "Log not found" + } + ``` diff --git a/docs/thehive/api/task/responder-jobs.md b/docs/thehive/api/task/responder-jobs.md index e69de29b..cd8ad8a0 100644 --- a/docs/thehive/api/task/responder-jobs.md +++ b/docs/thehive/api/task/responder-jobs.md @@ -0,0 +1,54 @@ +# List responder actions + +List actions run on a task. + +## Query + +```plain +GET /api/connector/cortex/action/case_task/{id} +``` + +With: + +- `id`: Task identifier + +## Response + +### Status codes + +- `200`: if query is run successfully +- `401`: Authentication error + +### Response Body Example + +!!! Example "" + + === "201" + + ```json + [ + { + "responderId": "25dcbbb69d50dd5a5ae4bd55f4ca5903", + "responderName": "reponderName_1_0", + "responderDefinition": "reponderName_1_0", + "cortexId": "local-cortex", + "cortexJobId": "408-unsB3SwW9-eEPXXW", + "objectType": "Task", + "objectId": "~25313328", + "status": "Success", + "startDate": 1630917246993, + "endDate": 1630917254406, + "operations": "[]", + "report": "{\"summary\":{\"taxonomies\":[]},\"full\":null,\"success\":true,\"artifacts\":[],\"operations\":[],\\\"message\\\":\\\"Ok\\\",\\\"parameters\\\":{\\\"organisation\\\":\\\"StrangeBee\\\",\\\"user\\\":\\\"jerome@strangebee.com\\\"},\\\"config\\\":{\\\"proxy_https\\\":null,\\\"cacerts\\\":null,\\\"check_tlp\\\":false,\\\"max_tlp\\\":2,\\\"check_pap\\\":false,\\\"max_pap\\\":2,\\\"jobTimeout\\\":30,\\\"proxy_http\\\":null}}\"}" + } + ] + ``` + + === "401" + + ```json + { + "type": "AuthenticationError", + "message": "Authentication failure" + } + ``` diff --git a/docs/thehive/api/task/run-responder.md b/docs/thehive/api/task/run-responder.md index e69de29b..1be7a88f 100644 --- a/docs/thehive/api/task/run-responder.md +++ b/docs/thehive/api/task/run-responder.md @@ -0,0 +1,82 @@ +# Run responder + +Run a responder on a *Task* (requires `manageAction` permission). + +## Query + +```plain +POST /api/connector/cortex/action +``` + +## Request Body Example + +!!! Example "" + + ```json + { + "responderId": "25dcbbb69d50dd5a5ae4bd55f4ca5903", + "cortexId": "local-cortex", + "objectType": "case_task", + "objectId": "~11123" + } + ``` + +The required fields are `responderId`, `objectType` and `objectId`. + +## Response + +### Status codes + +- `201`: if responder is started successfully +- `401`: Authentication error +- `403`: Authorization error +- `404`: Task is not found + +### Response Body Example + +!!! Example "" + + === "201" + + ```json + { + "responderId": "25dcbbb69d50dd5a5ae4bd55f4ca5903", + "responderName": "reponderName_1_0", + "responderDefinition": "reponderName_1_0", + "cortexId": "local-cortex", + "cortexJobId": "408-unsB3SwW9-eEPXXW", + "objectType": "Task", + "objectId": "~25313328", + "status": "Waiting", + "startDate": 1630917246993, + "operations": "[]", + "report": "{}" + } + ``` + + === "401" + + ```json + { + "type": "AuthenticationError", + "message": "Authentication failure" + } + ``` + + === "403" + + ```json + { + "type": "AuthorizationError", + "message": "Your are not authorized to create action, you haven't the permission manageTask" + } + ``` + + === "404" + + ```json + { + "type": "AuthenticationError", + "message": "Task not found" + } + ``` diff --git a/docs/thehive/api/task/waiting-tasks.md b/docs/thehive/api/task/waiting-tasks.md index e69de29b..098a1dcc 100644 --- a/docs/thehive/api/task/waiting-tasks.md +++ b/docs/thehive/api/task/waiting-tasks.md @@ -0,0 +1,99 @@ +# List + +List all waiting *Task*s. + +## Query + +```plain +POST /api/v0/query +``` + +## Request Body Example + +!!! Example "" + + List 15 waiting tasks, sorted by `flag` and `startDate`. + + ```json + { + "query": [ + { + "_name": "waitingTasks" + }, + { + "_name": "sort", + "_fields": [ + { + "flag": "desc" + }, + { + "startDate": "desc" + } + ] + }, + { + "_name": "page", + "from": 0, + "to": 15 + } + ] + } + ``` + +## Response + +### Status codes + +- `200`: if query is run successfully +- `401`: Authentication error + +### ResponseBody Example + +!!! Example "" + + === "201" + + ```json + [ + { + "id": "~4264", + "_id": "~4264", + "createdBy": "jerome@strangebee.com", + "createdAt": 1630684502715, + "_type": "case_task", + "title": "Malware analysis", + "group": "identification", + "description": "Analysis of the file to identify the malware", + "owner": "jerome@strangebee.com", + "status": "Waiting", + "flag": false, + "startDate": 1630683608000, + "endDate": 1630684608000, + "order": 3, + "dueDate": 1630694608000 + }, + { + "id": "~8360", + "_id": "~8360", + "createdBy": "jerome@strangebee.com", + "updatedBy": "jerome@strangebee.com", + "createdAt": 1630687291729, + "updatedAt": 1630687323936, + "_type": "case_task", + "title": "Block malware URLs in proxy", + "group": "containment", + "description": "Add identified malicious URLs in proxy black list", + "status": "Waiting", + "flag": false, + "order": 0 + } + ``` + + === "401" + + ```json + { + "type": "AuthenticationError", + "message": "Authentication failure" + } + ```