Feature/168 revise the action iexecutor interface to allow for passing of in args and out args #186

MaartendeKruijf · 2024-07-24T13:46:27Z

No description provided.

RabbITCybErSeC · 2024-07-25T08:16:00Z

docs/content/en/docs/core-components/modules.md

@@ -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 variabel` 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.


fix playbook variabel --> playbook variable

RabbITCybErSeC · 2024-07-25T08:42:00Z

test/integration/capability/http/http_integration_test.go

@@ -38,13 +38,22 @@ func TestHttpConnection(t *testing.T) {
 	playbookId, _ := uuid.Parse("playbook--d09351a2-a075-40c8-8054-0b7c423db83f")


please fix for variable1 the type to Type: cacao.VariableTypeString line 31

lucamrgs · 2024-07-25T11:03:28Z

docs/content/en/docs/core-components/modules.md

@@ -57,6 +64,9 @@ This module does not define specific variables as input, but variable interpolat
                    "type": "ssh",
                    "command": "ls -la"
                }
+            ],
+            "out_args": [


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

This comment applies to the rest of this document

lucamrgs

Explanation to myself: overall, this PR makes the variables handling in SOARCA more explicit and deterministic, as now the only way to use SOARCA is by defining output variables in your step in the way that is supported by SOARCA processing.

Comment: it looks good to me - I only have two major remark.

request changes/I am stupid remark: maybe I missed something, but I would expect these modifications to be pushed also for the playbook action step?
general remark: CACAO v2.1/v.3 will move the out_args property inside the command object for action steps, and it will leave it unchanged in the playbook action step. While we can still push these changes now, we need to be aware that we will have to change the logic accordingly, as we are floating in a grey area of SOARCA-specific functioning for automation, and automation-facilitation attempts in the specification.

lucamrgs · 2024-07-25T11:05:01Z

docs/content/en/docs/core-components/modules.md

@@ -57,6 +64,9 @@ This module does not define specific variables as input, but variable interpolat
                    "type": "ssh",
                    "command": "ls -la"
                }
+            ],
+            "out_args": [


This comment applies to the rest of this document

lucamrgs · 2024-07-25T11:08:49Z

docs/content/en/docs/core-components/modules.md

@@ -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.


Two points:

We say that the output variable defined in the step can be used in the next steps only because in SOARCA we use global scope for any defined variable, right? We should mention this, as it's not exactly adhering to the spec.

Besides than being the same type, it should also have the exact same name, right? Perhaps we can say that as well

lucamrgs · 2024-07-25T11:10:15Z

internal/capability/fin/fin.go

@@ -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,


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?

lucamrgs · 2024-07-25T11:16:52Z

internal/capability/openc2/openc2.go

@@ -16,6 +17,7 @@ type OpenC2Capability struct {
 type Empty struct{}

 const (
+	maxResultVariables       = 1


How/where is this used? I don't see it in the other capabilities or in the rest of the code of this capability but I haven't looked in depth

It is not used it remained of my first implementation so I will remove it good catch

lucamrgs · 2024-07-25T11:25:05Z

internal/capability/http/http.go

@@ -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,


Am I missing something, or are inputvariablekeys never used in the Execute function? This comment applies to all capabilities

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.

lucamrgs · 2024-07-25T11:27:30Z

internal/executors/action/action.go

 				metadata.Agent)

-			if len(metadata.Step.OutArgs) > 0 {


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

lucamrgs · 2024-07-25T11:48:06Z

utils/mapper/mapper.go

+	"soarca/models/cacao"
+)
+
+func Variables(variables cacao.Variables,


Just for clarity, readability, and debugging, I would rather call these arguments something like "variablesInScope", "outArgs", "returnedVariables", "capabilityReturnArgs"

MaartendeKruijf · 2024-07-25T16:00:35Z

I missed the Playbook Action step so we need to update it in there as well

lucamrgs

@MaartendeKruijf I have a couple notes for how the assignment of variable values to out_args maps.

lucamrgs · 2024-08-02T10:09:32Z

utils/mapper/mapper.go

+		if !found {
+			return cacao.NewVariables(), errors.New("key is not found in variables")
+		}
+		dataVariable, ok := returnedVariables.Find(capabilityReturnArgs[i])


This logic assumes that:

a capability/command can return more than one arg separately (which might not be the case if we indeed can practically just assign the output of a command to one variable)

the playbook implementer knows how many arguments the invocation of a command (capability) returns,

the arguments returned from the command (capability) are in an order consistent with the order of the variables in out_args

If we're fine with these assumptions, we should at least mention this functioning in the documentation.

These are documented in modules

MaartendeKruijf linked an issue Jul 24, 2024 that may be closed by this pull request

Revise the action IExecutor interface to allow for passing of in_args and out_args #168

Open

MaartendeKruijf requested review from RabbITCybErSeC and lucamrgs July 24, 2024 13:46

MaartendeKruijf self-assigned this Jul 24, 2024

MaartendeKruijf added breaking change This issue or pull request will lead to breaking changes enhancement New feature or request cacao OASIS cacao model related issue labels Jul 24, 2024

MaartendeKruijf marked this pull request as ready for review July 24, 2024 16:39

RabbITCybErSeC requested changes Jul 25, 2024

View reviewed changes

lucamrgs reviewed Jul 25, 2024

View reviewed changes

lucamrgs requested changes Jul 25, 2024

View reviewed changes

MaartendeKruijf force-pushed the feature/168-revise-the-action-iexecutor-interface-to-allow-for-passing-of-in_args-and-out_args branch from 46108da to 7d1a7e9 Compare August 2, 2024 08:54

MaartendeKruijf requested review from RabbITCybErSeC and lucamrgs August 2, 2024 08:59

MaartendeKruijf added this to the SOARCA 1.1 milestone Aug 2, 2024

MaartendeKruijf force-pushed the feature/168-revise-the-action-iexecutor-interface-to-allow-for-passing-of-in_args-and-out_args branch from be491f2 to 96385c5 Compare August 2, 2024 09:07

lucamrgs requested changes Aug 2, 2024

View reviewed changes

MaartendeKruijf force-pushed the feature/168-revise-the-action-iexecutor-interface-to-allow-for-passing-of-in_args-and-out_args branch from 0dccb59 to 02c5d99 Compare August 20, 2024 08:57

MaartendeKruijf added 10 commits August 27, 2024 09:47

Added output args mapper

29d3fd8

Added input and output variable keys to ICapability

a0f82d0

Updated openc2 capability

76a49d8

Updated http capability and tests

d0d8482

Extended http api capability test

eca6e94

Updates ssh capability

8b19d8f

Updated modules documentation on how to use out_args

749c3cc

Updated ssh object creation

2c786ca

Updated fin capability

be062fa

Fixed action executor test

15a216f

MaartendeKruijf added 7 commits August 27, 2024 09:47

Added named type to variable1 in integration test

680b46b

Fixed type variabel → variable in modules.md

bc01c10

Streamlined ICapability interface variable naming

d2583dd

Removed unused variable

d18a969

Updated naming to suggestions to be more clear and descriptive

00d0476

Added outarg filtering to playbook action step

23b2083

Updated playbook action step documentation

70cc0a3

MaartendeKruijf force-pushed the feature/168-revise-the-action-iexecutor-interface-to-allow-for-passing-of-in_args-and-out_args branch from 02c5d99 to 70cc0a3 Compare August 27, 2024 07:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feature/168 revise the action iexecutor interface to allow for passing of in args and out args #186

Feature/168 revise the action iexecutor interface to allow for passing of in args and out args #186

MaartendeKruijf commented Jul 24, 2024

RabbITCybErSeC Jul 25, 2024

RabbITCybErSeC Jul 25, 2024

lucamrgs Jul 25, 2024

lucamrgs Jul 25, 2024

lucamrgs left a comment •

edited

Loading

lucamrgs Jul 25, 2024

lucamrgs Jul 25, 2024

lucamrgs Jul 25, 2024

lucamrgs Jul 25, 2024

MaartendeKruijf Jul 25, 2024

lucamrgs Jul 25, 2024

MaartendeKruijf Jul 25, 2024

lucamrgs Jul 25, 2024

lucamrgs Jul 25, 2024

MaartendeKruijf commented Jul 25, 2024

lucamrgs left a comment

lucamrgs Aug 2, 2024

MaartendeKruijf Aug 2, 2024

		@@ -38,13 +38,22 @@ func TestHttpConnection(t *testing.T) {
		playbookId, _ := uuid.Parse("playbook--d09351a2-a075-40c8-8054-0b7c423db83f")

Feature/168 revise the action iexecutor interface to allow for passing of in args and out args #186

Are you sure you want to change the base?

Feature/168 revise the action iexecutor interface to allow for passing of in args and out args #186

Conversation

MaartendeKruijf commented Jul 24, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lucamrgs left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MaartendeKruijf commented Jul 25, 2024

lucamrgs left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lucamrgs left a comment •

edited

Loading