-
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/168 revise the action iexecutor interface to allow for passing of in args and out args #186
base: development
Are you sure you want to change the base?
Changes from all commits
29d3fd8
a0f82d0
76a49d8
d0d8482
eca6e94
8b19d8f
749c3cc
2c786ca
be062fa
15a216f
680b46b
bc01c10
d2583dd
d18a969
00d0476
23b2083
70cc0a3
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 |
---|---|---|
|
@@ -32,7 +32,7 @@ In every other circumstance the step is considered to have failed. | |
|
||
#### Variables | ||
|
||
This module does not define specific variables as input, but variable interpolation is supported in the command and target definitions. It has the following output variables: | ||
This module does not define specific variables as input, but variable interpolation is supported in the command and target definitions. It has `one` output variable of type string (see the `__soarca_ssh_result__`). If you want to use the output variable in your next step you will need to define a variable in your playbook as `step or playbook variable` that is of the same type. Also you need to specify an `out_args` key see `__your_step_output_variable__` in the example. Note you can only use `one out_arg key` for this capability. | ||
|
||
```json | ||
{ | ||
|
@@ -43,12 +43,19 @@ This module does not define specific variables as input, but variable interpolat | |
} | ||
``` | ||
|
||
#### Example | ||
#### Example with step variable | ||
|
||
```json | ||
{ | ||
"workflow": { | ||
"action--7777c6b6-e275-434e-9e0b-d68f72e691c1": { | ||
"step_variables": { | ||
"__your_step_output_variable__": { | ||
"type": "string", | ||
"constant": false, | ||
"external": false | ||
} | ||
}, | ||
"type": "action", | ||
"agent": "soarca--00010001-1000-1000-a000-000100010001", | ||
"targets": ["linux--c7e6af1b-9e5a-4055-adeb-26b97e1c4db7"], | ||
|
@@ -57,6 +64,9 @@ This module does not define specific variables as input, but variable interpolat | |
"type": "ssh", | ||
"command": "ls -la" | ||
} | ||
], | ||
"out_args": [ | ||
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. The agreed-upon, upcoming change in CACAO v2.1 (or v3), is to set out_args as a common property of the command. So if we want to anticipate this very reasonable change, we should set out_args within a command in commands. This also changes the description that we would have to provide 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. This comment applies to the rest of this document |
||
"__your_step_output_variable__" | ||
] | ||
} | ||
}, | ||
|
@@ -92,8 +102,7 @@ The command is considered to have successfully completed if a successful HTTP re | |
#### Variables | ||
|
||
This capability supports variable interpolation in the command, port, authentication info, and target definitions. | ||
|
||
The result of the step is stored in the following output variables: | ||
It has `one` output variable of type string (see the `__soarca_http_api_result__`). If you want to use the output variable in your next step you will need to define a variable in your playbook as `step or playbook variable` that is of the same type. Also you need to specify an `out_args` key see `__your_step_output_variable__` in the example. Note you can only use `one out_arg key` for this capability. | ||
|
||
```json | ||
{ | ||
|
@@ -104,11 +113,18 @@ The result of the step is stored in the following output variables: | |
} | ||
``` | ||
|
||
#### Example | ||
#### Example with playbook variable | ||
|
||
```json | ||
{ | ||
"workflow": { | ||
"playbook_variables": { | ||
"__your_step_output_variable__": { | ||
"type": "string", | ||
"constant": false, | ||
"external": false | ||
} | ||
}, | ||
"action--8baa7c78-751b-4de9-81d4-775806cee0fb": { | ||
"type": "action", | ||
"agent": "soarca--00020001-1000-1000-a000-000100010001", | ||
|
@@ -119,6 +135,9 @@ The result of the step is stored in the following output variables: | |
"command": "GET /overview HTTP/1.1", | ||
"port": "8080" | ||
} | ||
], | ||
"out_args": [ | ||
"__your_step_output_variable__" | ||
] | ||
} | ||
}, | ||
|
@@ -150,7 +169,7 @@ Any successful HTTP response from an OpenC2 compliant endpoint (with a status co | |
|
||
#### Variables | ||
|
||
It supports variable interpolation in the command, headers, and target definitions. | ||
This capability does not define specific variables as input, but variable interpolation is supported in the command and target definitions. It has `one` output variable of type string (see the `__soarca_openc2_http_result__`). If you want to use the output variable in your next step you will need to define a variable in your playbook as `step or playbook variable` that is of the same type. Also you need to specify an `out_args` key see `__your_step_output_variable__` in the example. Note you can only use `one out_arg key` for this capability. | ||
|
||
The result of the step is stored in the following output variables: | ||
|
||
|
@@ -163,12 +182,19 @@ The result of the step is stored in the following output variables: | |
} | ||
``` | ||
|
||
#### Example | ||
#### Example with step variables | ||
|
||
```json | ||
{ | ||
"workflow": { | ||
"action--aa1470d8-57cc-4164-ae07-05745bef24f4": { | ||
"step_variables": { | ||
"__your_step_output_variable__": { | ||
"type": "string", | ||
"constant": false, | ||
"external": false | ||
} | ||
}, | ||
"type": "action", | ||
"agent": "soarca--00030001-1000-1000-a000-000100010001", | ||
"targets": ["http-api--5a274b6d-dc65-41f7-987e-9717a7941876"], | ||
|
@@ -179,7 +205,10 @@ The result of the step is stored in the following output variables: | |
"headers": { | ||
"Content-Type": ["application/openc2+json;version=1.0"] | ||
} | ||
}] | ||
}], | ||
"out_args": [ | ||
"__your_step_output_variable__" | ||
] | ||
} | ||
}, | ||
"agent_definitions": { | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -33,7 +33,9 @@ func (finCapability *FinCapability) Execute( | |
command cacao.Command, | ||
authentication cacao.AuthenticationInformation, | ||
target cacao.AgentTarget, | ||
variables cacao.Variables) (cacao.Variables, error) { | ||
variables cacao.Variables, | ||
inputVariableKeys []string, | ||
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. is the difference in the property names "inputVariable" in the interface, and "inputVariableKeys" in the capabilities, on purpose? If not, I would name them the same way, just for consistency? |
||
outputVariablesKeys []string) (cacao.Variables, error) { | ||
|
||
finCommand := finModel.NewCommand() | ||
finCommand.CommandSubstructure.Command = command.Command | ||
|
@@ -44,5 +46,6 @@ func (finCapability *FinCapability) Execute( | |
finCommand.CommandSubstructure.Context.StepId = metadata.StepId | ||
|
||
log.Trace("created command ", finCommand) | ||
|
||
return finCapability.finProtocol.SendCommand(finCommand) | ||
} |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -6,6 +6,7 @@ import ( | |
"soarca/models/cacao" | ||
"soarca/models/execution" | ||
"soarca/utils/http" | ||
"soarca/utils/mapper" | ||
) | ||
|
||
// Receive HTTP API command data from decomposer/executer | ||
|
@@ -44,7 +45,9 @@ func (httpCapability *HttpCapability) Execute( | |
command cacao.Command, | ||
authentication cacao.AuthenticationInformation, | ||
target cacao.AgentTarget, | ||
variables cacao.Variables) (cacao.Variables, error) { | ||
variables cacao.Variables, | ||
inputVariableKeys []string, | ||
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. Am I missing something, or are inputvariablekeys never used in the Execute function? This comment applies to all capabilities 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. That is true as there is no use for it in the spec at this point. We will need to see how we can implement this for now I wanted to include it in the interface as changing it again is a lot of work. |
||
outputVariablesKeys []string) (cacao.Variables, error) { | ||
|
||
soarca_http_options := http.HttpOptions{ | ||
Target: &target, | ||
|
@@ -57,11 +60,14 @@ func (httpCapability *HttpCapability) Execute( | |
log.Error(err) | ||
return cacao.NewVariables(), err | ||
} | ||
respString := string(responseBytes) | ||
variable := cacao.Variable{Type: cacao.VariableTypeString, | ||
|
||
response := string(responseBytes) | ||
|
||
results := cacao.NewVariables(cacao.Variable{Type: cacao.VariableTypeString, | ||
Name: httpApiResultVariableName, | ||
Value: respString} | ||
Value: string(response)}) | ||
log.Trace("Finished https execution, will return the variables: ", results) | ||
|
||
return cacao.NewVariables(variable), nil | ||
return mapper.Variables(variables, outputVariablesKeys, results, []string{httpApiResultVariableName}) | ||
|
||
} |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -68,13 +68,9 @@ func (executor *Executor) Execute(meta execution.Metadata, metadata PlaybookStep | |
auth, | ||
target, | ||
metadata.Variables, | ||
metadata.Step, | ||
metadata.Agent) | ||
|
||
if len(metadata.Step.OutArgs) > 0 { | ||
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. If we move the out_args in the CACAO v3 position (inside a command object) then I think we will need to rethink where these checks will be performed |
||
// If OutArgs is set, only update execution args that are explicitly referenced | ||
outputVariables = outputVariables.Select(metadata.Step.OutArgs) | ||
} | ||
|
||
returnVariables.Merge(outputVariables) | ||
|
||
if err != nil { | ||
|
@@ -87,6 +83,10 @@ func (executor *Executor) Execute(meta execution.Metadata, metadata PlaybookStep | |
} | ||
} | ||
executor.reporter.ReportStepEnd(meta.ExecutionId, metadata.Step, returnVariables, nil) | ||
if len(metadata.Step.OutArgs) > 0 { | ||
// If OutArgs is set, only update execution args that are explicitly referenced | ||
returnVariables = returnVariables.Select(metadata.Step.OutArgs) | ||
} | ||
return returnVariables, nil | ||
} | ||
|
||
|
@@ -95,6 +95,7 @@ func (executor *Executor) ExecuteActionStep(metadata execution.Metadata, | |
authentication cacao.AuthenticationInformation, | ||
target cacao.AgentTarget, | ||
variables cacao.Variables, | ||
step cacao.Step, | ||
agent cacao.AgentTarget) (cacao.Variables, error) { | ||
|
||
if capability, ok := executor.capabilities[agent.Name]; ok { | ||
|
@@ -117,7 +118,14 @@ func (executor *Executor) ExecuteActionStep(metadata execution.Metadata, | |
authentication.OauthHeader = variables.Interpolate(authentication.OauthHeader) | ||
authentication.PrivateKey = variables.Interpolate(authentication.PrivateKey) | ||
|
||
returnVariables, err := capability.Execute(metadata, command, authentication, target, variables) | ||
returnVariables, err := capability.Execute(metadata, | ||
command, | ||
authentication, | ||
target, | ||
variables, | ||
step.InArgs, | ||
step.OutArgs) | ||
|
||
return returnVariables, err | ||
} else { | ||
empty := cacao.NewVariables() | ||
|
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.
Two points: