-
Notifications
You must be signed in to change notification settings - Fork 10
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.
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
Feature/151 manual step capability #153
base: development
Are you sure you want to change the base?
Changes from all commits
3be7b24
0f2fac1
fa3b8f8
c6985d7
8492799
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I would discurage in any case the use and reporting of in_args, as I don't think there's really any way to use them. They should be already resolved in the |
||
|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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. As above |
||
|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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I am thinking whether we should also expect, as part of the out_arg info, anything else besides the arg (variable) name, and its value. |
||
|
||
|
||
|
||
```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>", | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. By definition of a variable type, there is no |
||
"description": "<description>", | ||
"value": "<value>", | ||
"constant": "<true/false>", | ||
"external": "<true/false>" | ||
} | ||
} | ||
} | ||
|
||
@endjson | ||
``` | ||
|
||
##### Response | ||
200/OK with payload: | ||
|
||
##### Error | ||
400/BAD REQUEST with payload: | ||
General error |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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). | ||
|
||
|
||
<!-- 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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
due to ambiguity of |
||
|
||
#### 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"], | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We might also want to mention better how we interpret agents and targets for a manual step. By CACAO specification, one would argue that the But it makes sense to also see SOARCA as So yeah overall we might want to explain this interpretation of agents/targets/division of responsibilities in the documentation. |
||
"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 | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a list of manual command action steps right? The return payload as presented is only for one such steps? I see that in the example it's indeed a list, but maybe we should mention it here in this response bit too