diff --git a/docs/content/en/docs/core-components/executer.md b/docs/content/en/docs/core-components/executer.md index 3b16a8d7..e6d1200f 100644 --- a/docs/content/en/docs/core-components/executer.md +++ b/docs/content/en/docs/core-components/executer.md @@ -10,12 +10,94 @@ description: > ## Components The executor consists of the following components. +- Action executor +- Playbook action executor +- if-condition executor +- while-condition executor +- parallel executor + +The decomposer interacts with every executor type. They all have separate interfaces to handle new step types in the future without changing the current interfaces. + +```plantuml + +package action{ + interface IExecutor { + ..., err Execute(...) + } +} + +package playbookaction{ + interface IExecutor { + ..., err Execute(...) + } +} + +package ifcondition{ + interface IExecutor { + ..., err Execute(...) + } +} + +package whilecondition{ + interface IExecutor { + ..., err Execute(...) + } +} + +package parallel{ + interface IExecutor { + ..., err Execute(...) + } +} + + +interface ICapability{ + variables, error Execute(Metadata, command, variable[], target, agent) + string GetModuleName() +} + +class "Decomposer" as decomposer +class "Action Executor" as Executor +class "Playbook Executor" as playbook +class "Parallel Executor" as parallelexecutor +class "While Executor" as while +class "If condition Executor" as condition + +class "Ssh" as ssh +class "OpenC2" as openc2 +class "HttpApi" as api +class "Fin" as fin + + +action.IExecutor <|.. Executor +ICapability <-up- Executor +ICapability <|.. ssh +ICapability <|.. openc2 +ICapability <|.. api +ICapability <|.. fin + +playbookaction.IExecutor <|.. playbook +ifcondition.IExecutor <|.. condition +whilecondition.IExecutor <|.. while +parallel.IExecutor <|.. parallelexecutor + +decomposer -down-> playbookaction.IExecutor +decomposer -down-> ifcondition.IExecutor +decomposer -down-> whilecondition.IExecutor +decomposer -down-> parallel.IExecutor +decomposer -down-> action.IExecutor + + +``` + +### Action executor + +The action executor consist of the following components + - The capability selector - Native capabilities (command executors) - MQTT capability to interact with: Fin capabilities (third-party executors) -### Capability selector (Executor) - The capability selector will select the implementation which is capable of executing the incoming command. There are native capabilities based on the CACAO `command-type-ov`: * **Currently implemented** @@ -33,15 +115,15 @@ The capability selector will select the implementation which is capable of execu * sigma * yara -### Native capabilities +#### Native capabilities The executor will select a module that is capable of executing the command and pass the details to it. The capability selection is performed based on the agent type (see [Agent and Target Common Properties](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256509) in the CACAO 2.0 spec). The convention is that the agent type must equal `soarca-`, e.g. `soarca-ssh` or `soarca-openc2-http`. 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 +#### 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] -### Component overview +#### Component overview ```plantuml @@ -64,54 +146,7 @@ parser -- Executor exe3 -- Fins : " MQTT topics" ``` - -## Executor classes - - -```plantuml - -interface IExecutor { - void Execute(ExecutionId, CommandData, variable[], target, module, completionCallback(variables[])) - void Pause(CommandData, module) - void Resume(CommandData, module) - void Kill(CommandData, module) -} - -struct State{ - stopped - running - paused -} - - -interface ICapability{ - void Execute(ExecutionId, CommandData, variable[], target, completionCallback(variables[])) - module GetModuleName() -} - - -class Executor - -class "Ssh" as ssh -class "OpenC2" as openc2 -class "HttpApi" as api - - -IExecutor <|.. Executor -Executor -> ICapability -ICapability <|.. ssh -ICapability <|.. openc2 -ICapability <|.. api - -``` - - - - - - - -## Sequences +#### Sequences Example execution for SSH commands with SOARCA native capability. @@ -135,3 +170,39 @@ else capability not available end ``` +### Playbook action executor +The playbook executor handles execution of playbook action steps. The variables from the top level playbook are injected into the be executed playbook. +It could happen that in the downstream playbook the variables `collide` with the top level playbook. In this case the top level playbook variables are `NOT` transferred to the downstream playbook. `Agents and Targets cannot be transferred` between playbooks at this time. Playbooks are only loaded in the executor and then a new Decomposer is created to execute the playbook. + +The result of the step execution will be returned to the decomposer. A result can be either output variables or error status. + +```plantuml +package playbookaction{ + interface IExecutor { + Variables, err Execute(meta, step, variables) + } +} +class "Decomposer" as decomposer +class "Action Executor" as exe +interface "IPlaybookController" as controller +interface "IDatabaseController" as database + +playbookaction.IExecutor <|.. exe +decomposer -> playbookaction.IExecutor +exe -> controller +database <- exe + +``` + +### If condition executor +The if-condition executor will process a cacao if-condition step and determine it's output. + +The result of the step comparison will be returned to the decomposer. A result can be either a next step id and/or error status. + +### While condition executor +The if-condition executor will process a cacao while-condition step and determine it's output. + +The result of the step comparison will be returned to the decomposer. A result can be either a next step id and/or error status. + +### Parallel step executor +The parallel executor will execute the parallel step. This wil be done in sequence to simplify implementation. As parallel steps must not be depended on each other sequential execution is possible. Later this will be changed. \ No newline at end of file