diff --git a/docs/content/en/docs/core-components/api-manual.md b/docs/content/en/docs/core-components/api-manual.md new file mode 100644 index 00000000..68be5d74 --- /dev/null +++ b/docs/content/en/docs/core-components/api-manual.md @@ -0,0 +1,223 @@ +--- +title: Manual API Description +description: > + Descriptions for the SOARCA manual interaction REST API endpoints +categories: [API] +tags: [protocol, http, rest, api] +weight: 3 +date: 2024-05-21 +--- + +## Endpoint descriptions + +We will use HTTP status codes https://en.wikipedia.org/wiki/List_of_HTTP_status_codes + + +```plantuml +@startuml +protocol Reporter { + GET /manual + POST /manual/continue +} +@enduml +``` + + +### /manual +The manual interaction endpoint for SOARCA + +#### GET `/manual` +Get all pending manual actions objects that are currently waiting in SOARCA. + +##### Call payload +None + +##### Response +200/OK with payload: + + + +|field |content |type | description | +| ----------------- | --------------------- | ----------------- | ----------- | +|type |execution-status |string |The type of this content +|execution_id |UUID |string |The id of the execution +|playbook_id |UUID |string |The id of the CACAO playbook executed by the execution +|step_id |UUID |string |The id of the step executed by the execution +|description |description of the step|string |The description from the workflow step +|command |command |string |The command for the agent either command +|command_is_base64 |true \| false |bool |Indicate the command is in base 64 +|targets |cacao agent-target |dictionary |Map of [cacao agent-target](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256509) with the target(s) of this command +|in_args |cacao variables |dictionary |Map of [cacao variables](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256555) handled in the step in args with current values and definitions +|out_args |cacao variables |dictionary |Map of [cacao variables](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256555) handled in the step out args with current values and definitions + + + +```plantuml +@startjson +[ + { + "type" : "manual-step-information", + "execution_id" : "", + "playbook_id" : "", + "step_id" : "", + "command" : "", + "command_is_base64" : "false", + "targets" : { + "__target1__" : { + "type" : "", + "name" : "", + "description" : "", + "location" : "<.>", + "agent_target_extensions" : {} + } + }, + "in_args": { + "" : { + "type": "", + "name": "", + "description": "", + "value": "", + "constant": "", + "external": "" + } + }, + "out_args": { + "" : { + "type": "", + "name": "", + "description": "", + "value": "", + "constant": "", + "external": "" + } + } + } +] +@endjson +``` + +##### Error +400/BAD REQUEST with payload: +General error + +--- + +#### GET `/manual/` +Get pending manual actions objects that are currently waiting in SOARCA for specific execution. + +##### Call payload +None + +##### Response +200/OK with payload: + + + +|field |content |type | description | +| ----------------- | --------------------- | ----------------- | ----------- | +|type |execution-status |string |The type of this content +|execution_id |UUID |string |The id of the execution +|playbook_id |UUID |string |The id of the CACAO playbook executed by the execution +|step_id |UUID |string |The id of the step executed by the execution +|description |description of the step|string |The description from the workflow step +|command |command |string |The command for the agent either command +|command_is_base64 |true \| false |bool |Indicate the command is in base 64 +|targets |cacao agent-target |dictionary |Map of [cacao agent-target](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256509) with the target(s) of this command +|in_args |cacao variables |dictionary |Map of [cacao variables](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256555) handled in the step in args with current values and definitions +|out_args |cacao variables |dictionary |Map of [cacao variables](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256555) handled in the step out args with current values and definitions + + + +```plantuml +@startjson + + { + "type" : "manual-step-information", + "execution_id" : "", + "playbook_id" : "", + "step_id" : "", + "command" : "", + "command_is_base64" : "false", + "targets" : { + "__target1__" : { + "type" : "", + "name" : "", + "description" : "", + "location" : "<.>", + "agent_target_extensions" : {} + } + }, + "in_args": { + "" : { + "type": "", + "name": "", + "description": "", + "value": "", + "constant": "", + "external": "" + } + }, + "out_args": { + "" : { + "type": "", + "name": "", + "description": "", + "value": "", + "constant": "", + "external": "" + } + } + } + +@endjson +``` + +##### Error +404/Not found with payload: +General error + +#### POST `/manual/continue` +Respond to manual command pending in SOARCA, if out_args are defined they must be filled in and returned in the payload body + +##### Call payload +|field |content |type | description | +| ----------------- | --------------------- | ----------------- | ----------- | +|type |execution-status |string |The type of this content +|execution_id |UUID |string |The id of the execution +|playbook_id |UUID |string |The id of the CACAO playbook executed by the execution +|step_id |UUID |string |The id of the step executed by the execution +|response_status |enum |string |Can be either `success` or `failed` +|response_out_args |cacao variables |dictionary |Map of [cacao variables](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256555) handled in the step out args with current values and definitions + + + +```plantuml +@startjson + + { + "type" : "manual-step-response", + "execution_id" : "", + "playbook_id" : "", + "step_id" : "", + "response_status" : "success | failed", + "response_out_args": { + "" : { + "type": "", + "name": "", + "description": "", + "value": "", + "constant": "", + "external": "" + } + } + } + +@endjson +``` + +##### Response +200/OK with payload: + +##### Error +400/BAD REQUEST with payload: +General error \ No newline at end of file diff --git a/docs/content/en/docs/core-components/executer.md b/docs/content/en/docs/core-components/executer.md index 0ccd56d5..1e679d13 100644 --- a/docs/content/en/docs/core-components/executer.md +++ b/docs/content/en/docs/core-components/executer.md @@ -66,6 +66,7 @@ class "If condition Executor" as condition class "Ssh" as ssh class "OpenC2" as openc2 class "HttpApi" as api +class "Manual" as manual class "Fin" as fin @@ -74,6 +75,7 @@ ICapability <-up- Executor ICapability <|.. ssh ICapability <|.. openc2 ICapability <|.. api +ICapability <|.. manual ICapability <|.. fin playbookaction.IExecutor <|.. playbook @@ -104,12 +106,12 @@ The capability selector will select the implementation which is capable of execu * ssh * http-api * openc2-http -* **Coming soon** * manual -* **Future (potentially)** +* **Coming soon** * bash - * caldera-cmd * elastic + * caldera-cmd +* **Future (potentially)** * jupyter * kestrel * sigma @@ -120,8 +122,10 @@ The executor will select a module that is capable of executing the command and p The result of the step execution will be returned to the decomposer. A result can be either output variables or error status. + + #### MQTT executor -> Fin capabilities -The Executor will put the command on the MQTT topic that is offered by the module. How a module handles this is described in the link:modules.adoc[module documentation] +The Executor will put the command on the MQTT topic that is offered by the module. How a module handles this is described in the [module documentation](/docs/core-components/modules) and in the [fin documentation](/docs/soarca-extensions/). #### Component overview diff --git a/docs/content/en/docs/core-components/modules.md b/docs/content/en/docs/core-components/modules.md index a68755a9..44554584 100644 --- a/docs/content/en/docs/core-components/modules.md +++ b/docs/content/en/docs/core-components/modules.md @@ -15,6 +15,7 @@ The following capability modules are currently defined in SOARCA: - ssh - http-api - openc2-http +- manual The capability will be selected based on the agent in the CACAO playbook step. The agent should be of type `soarca` and have a name corresponding to `soarca-[capability name]`. @@ -198,6 +199,58 @@ The result of the step is stored in the following output variables: } ``` +### Manual capability +This capability executes [manual Commands](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256491) and provides them through the [SOARCA api](/docs/core-components/api-manual). + + + + + + + + +#### Success and failure + +The manual step is considered successful if a response is made through the [manual api](/docs/core-components/api-manual). The manual command can specify a timeout but if none is specified SOARCA will use a default timeout of 10 minutes. If a timeout occurs the step is considered as failed. + +#### Variables + +This module does not define specific variables as input, but it requires one to use out_args if an operator want to provide a response to be used later in the playbook. + +#### Example + +```json +{ + "workflow": { + "action--7777c6b6-e275-434e-9e0b-d68f72e691c1": { + "type": "action", + "agent": "soarca--00010001-1000-1000-a000-000100010001", + "targets": ["linux--c7e6af1b-9e5a-4055-adeb-26b97e1c4db7"], + "commands": [ + { + "type": "manual", + "command": "Reset the firewall by unplugging it" + } + ] + } + }, + "agent_definitions": { + "soarca--00040001-1000-1000-a000-000100010001": { + "type": "soarca", + "name": "soarca-manual" + } + }, + "target_definitions": { + "linux--c7e6af1b-9e5a-4055-adeb-26b97e1c4db7": { + "type": "linux", + "name": "target", + "address": { "ipv4": ["10.0.0.1"] } + } + } +} +``` --- ## MQTT fin module