Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Feature/151 manual step capability #153

Draft
wants to merge 5 commits into
base: development
Choose a base branch
from
Draft

Feature/151 manual step capability #153

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3be7b24
Added manual api description
MaartendeKruijf May 15, 2024
0f2fac1
Added manual step to documentation
MaartendeKruijf May 15, 2024
fa3b8f8
Updated manual step
MaartendeKruijf May 21, 2024
c6985d7
Added execution endpoind documentation for /manual step
MaartendeKruijf Jul 11, 2024
8492799
Fixed response from list to single object, added error section to docs
MaartendeKruijf Jul 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
223 changes: 223 additions & 0 deletions docs/content/en/docs/core-components/api-manual.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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" : "<execution-id>",
"playbook_id" : "<playbook-id>",
"step_id" : "<step-id>",
"command" : "<command here>",
"command_is_base64" : "false",
"targets" : {
"__target1__" : {
"type" : "<agent-target-type-ov>",
"name" : "<agent name>",
"description" : "<some description>",
"location" : "<.>",
"agent_target_extensions" : {}
}
},
"in_args": {
"<variable-name-1>" : {
"type": "<type>",
"name": "<variable-name>",
"description": "<description>",
"value": "<value>",
"constant": "<true/false>",
"external": "<true/false>"
}
},
"out_args": {
"<variable-name-1>" : {
"type": "<type>",
"name": "<variable-name>",
"description": "<description>",
"value": "<value>",
"constant": "<true/false>",
"external": "<true/false>"
}
}
}
]
@endjson
```

##### Error
400/BAD REQUEST with payload:
General error

---

#### GET `/manual/<execution-id>`
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" : "<execution-id>",
"playbook_id" : "<playbook-id>",
"step_id" : "<step-id>",
"command" : "<command here>",
"command_is_base64" : "false",
"targets" : {
"__target1__" : {
"type" : "<agent-target-type-ov>",
"name" : "<agent name>",
"description" : "<some description>",
"location" : "<.>",
"agent_target_extensions" : {}
}
},
"in_args": {
"<variable-name-1>" : {
"type": "<type>",
"name": "<variable-name>",
"description": "<description>",
"value": "<value>",
"constant": "<true/false>",
"external": "<true/false>"
}
},
"out_args": {
"<variable-name-1>" : {
"type": "<type>",
"name": "<variable-name>",
"description": "<description>",
"value": "<value>",
"constant": "<true/false>",
"external": "<true/false>"
}
}
}

@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" : "<execution-id>",
"playbook_id" : "<playbook-id>",
"step_id" : "<step-id>",
"response_status" : "success | failed",
"response_out_args": {
"<variable-name-1>" : {
"type": "<type>",
"name": "<variable-name>",
"description": "<description>",
"value": "<value>",
"constant": "<true/false>",
"external": "<true/false>"
}
}
}

@endjson
```

##### Response
200/OK with payload:

##### Error
400/BAD REQUEST with payload:
General error
12 changes: 8 additions & 4 deletions docs/content/en/docs/core-components/executer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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


Expand All @@ -74,6 +75,7 @@ ICapability <-up- Executor
ICapability <|.. ssh
ICapability <|.. openc2
ICapability <|.. api
ICapability <|.. manual
ICapability <|.. fin

playbookaction.IExecutor <|.. playbook
Expand Down Expand Up @@ -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
Expand All @@ -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

Expand Down
53 changes: 53 additions & 0 deletions docs/content/en/docs/core-components/modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]`.

Expand Down Expand Up @@ -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).


<!-- The manual capability will allow an operator to interact with a playbook. It could allow one to perform a manual step that could not be automated, enter a variable to the playbook execution or a combination of these operations.

The main way to interact with the manual step is through SOARCA's [manual api](/docs/core-components/api-manual). The manual step should provide a timeout SOARCA will by default use a timeout of 10 minutes. If a timeout occurs the step is considered as failed. -->





#### 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
Expand Down