Added PowerShell capability basic implementation (#216)

docs/content/en/docs/_index.md

@@ -44,6 +44,12 @@ SOARCA currently supports the following transport mechanisms:
 {{< /cardpane >}}
 </div>
 
+{{% card header="PowerShell WinRM - Native" %}}
+[![PowerShell](/SOARCA/images/logos-external/powershell.svg)](/docs/soarca-extensions/native-capabilities/#powershell-capability)
+{{% /card %}}
+{{< /cardpane >}}
+</div>
+
 
 ## Features of SOARCA
 

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

@@ -104,6 +104,7 @@ The capability selector will select the implementation which is capable of execu
     * ssh
     * http-api
     * openc2-http
+    * powershell
 * **Coming soon**
     * manual
 * **Future (potentially)**

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

@@ -15,6 +15,7 @@ The following capability modules are currently defined in SOARCA:
 - ssh
 - http-api
 - openc2-http
+- powershell
 
 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,69 @@ The result of the step is stored in the following output variables:
 }
 ```
 
+
+
+### PowerShell capability
+
+This capability implements the [PowerShell Command](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256499), by sending [PowerShell commands](https://learn.microsoft.com/en-us/powershell/scripting/overview?view=powershell-7.4) using the [WinRM transport method](https://learn.microsoft.com/en-us/windows/win32/winrm/portal).
+
+It supports the username, password authentication mechanism.
+
+#### Success and failure
+
+Any successful command will have a `__soarca_powershell_result__`. If an error occurs on the target a `__soarca_powershell_error__` populated will be returned and Error will be set.
+
+#### Variables
+
+It supports variable interpolation in the command, headers, and target definitions.
+
+The result of the step is stored in the following output variables:
+
+```json
+{
+    "__soarca_powershell_result__": {
+        "type": "string",
+        "value": "<raw powershell output>"
+    }, 
+    "__soarca_powershell_error__": {
+        "type": "string",
+        "value": "<raw powershell error output>"
+    },
+}
+```
+
+#### Example
+
+```json
+{
+    "workflow": {
+        "action--aa1470d8-57cc-4164-ae07-05745bef24f4": {
+            "type": "action",
+            "agent": "soarca--00040001-1000-1000-a000-000100010001",
+            "targets": ["net-address--d42d6731-791d-41af-8fa4-7b5699dfe402"],
+            "commands": [{
+                "type": "powershell",
+                "command": "pwd"
+            }]
+        }
+    },
+    "agent_definitions": {
+        "soarca--00040001-1000-1000-a000-000100010001": {
+            "type": "soarca",
+            "name": "soarca-powershell"
+        }
+    },
+    "target_definitions": {
+        "net-address--d42d6731-791d-41af-8fa4-7b5699dfe402": {
+            "type": "net-address",
+            "name": "Windows Server or Client with WinRM enabled",
+            "address": { "ipv4": ["187.0.2.12"] }
+        }
+    }
+}
+```
+
+
 ---
 
 ## MQTT fin module

docs/content/en/docs/soarca-extensions/native-capabilities.md

@@ -27,4 +27,10 @@ CACAO documentation: [HTTP API Command](https://docs.oasis-open.org/cacao/securi
 
 The SSH capability allows executing commands on systems running an SSH-server.
 
-CACAO documentation: [SSH Command](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256500)
+CACAO documentation: [SSH Command](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256500)
+
+## Powershell capability
+
+The PowerShell capability allows executing commands on systems running an WinRM server.
+
+CACAO documentation: [PowerShell Command](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256499)

example/powershell-playbook.json

@@ -0,0 +1,62 @@
+{
+    "type": "playbook",
+    "spec_version": "cacao-2.0",
+    "id": "playbook--6673b5cb-d9e9-408e-ab50-2fbb9abe91f5",
+    "name": "SOARCA PowerShell playbook",
+    "description": "This playbook demonstrates the powershell capability",
+    "created_by": "identity--691f1eb6-2a1e-495b-8f5e-18f44380c26a",
+    "created": "2024-08-27T09:28:36.611Z",
+    "modified": "2024-08-27T11:26:01.205Z",
+    "revoked": false,
+    "workflow_start": "start--baccd71d-5a22-4999-8cba-ff3d634971fa",
+    "workflow": {
+        "start--baccd71d-5a22-4999-8cba-ff3d634971fa": {
+            "on_completion": "action--010b0420-db3e-4810-ba75-08a10f473214",
+            "type": "start"
+        },
+        "action--010b0420-db3e-4810-ba75-08a10f473214": {
+            "name": "PowerShell example",
+            "on_completion": "end--28cd6cb6-b0e5-4445-8e4b-dfa9e0eab79a",
+            "type": "action",
+            "commands": [
+                {
+                    "type": "powershell",
+                    "command": "pwd"
+                }
+            ],
+            "agent": "soarca--00040001-1000-1000-a000-000100010001",
+            "targets": [
+                "net-address--0115a514-7a79-4c3f-8d87-77d5e52fabab"
+            ]
+        },
+        "end--28cd6cb6-b0e5-4445-8e4b-dfa9e0eab79a": {
+            "type": "end"
+        }
+    },
+    "authentication_info_definitions": {
+        "authentication-info--5a9c4caa-734b-4bd4-bbe1-fef0d426cf5a": {
+            "type": "authentication-info",
+            "name": "Server",
+            "username": "admin",
+            "password": "Password1234!"
+        }
+    },
+    "agent_definitions": {
+        "soarca--00040001-1000-1000-a000-000100010001": {
+            "type": "soarca",
+            "name": "soarca-powershell"
+        }
+    },
+    "target_definitions": {
+        "net-address--0115a514-7a79-4c3f-8d87-77d5e52fabab": {
+            "type": "net-address",
+            "name": "Windows",
+            "address": {
+                "ipv4": [
+                    "192.168.1.2"
+                ]
+            },
+            "port": "5985"
+        }
+    }
+}

go.mod

@@ -10,6 +10,7 @@ require (
 	github.com/go-playground/validator/v10 v10.19.0
 	github.com/google/uuid v1.3.1
 	github.com/joho/godotenv v1.5.1
+	github.com/masterzen/winrm v0.0.0-20240702205601-3fad6e106085
 	github.com/santhosh-tekuri/jsonschema/v5 v5.3.1
 	github.com/santhosh-tekuri/jsonschema/v6 v6.0.1
 	github.com/sirupsen/logrus v1.9.3
@@ -18,53 +19,69 @@ require (
 	github.com/swaggo/gin-swagger v1.6.0
 	github.com/swaggo/swag v1.16.1
 	go.mongodb.org/mongo-driver v1.12.1
-	golang.org/x/crypto v0.21.0
+	golang.org/x/crypto v0.24.0
 )
 
 require (
+	github.com/Azure/go-ntlmssp v0.0.0-20221128193559-754e69321358 // indirect
+	github.com/ChrisTrenkamp/goxpath v0.0.0-20210404020558-97928f7e12b6 // indirect
 	github.com/KyleBanks/depth v1.2.1 // indirect
 	github.com/PuerkitoBio/purell v1.1.1 // indirect
 	github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 // indirect
+	github.com/bodgit/ntlmssp v0.0.0-20240506230425-31973bb52d9b // indirect
+	github.com/bodgit/windows v1.0.1 // indirect
 	github.com/bytedance/sonic v1.11.3 // indirect
 	github.com/chenzhuoyu/base64x v0.0.0-20230717121745-296ad89f973d // indirect
 	github.com/chenzhuoyu/iasm v0.9.1 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.3 // indirect
 	github.com/gin-contrib/sse v0.1.0 // indirect
+	github.com/go-logr/logr v1.4.1 // indirect
 	github.com/go-openapi/jsonpointer v0.19.5 // indirect
 	github.com/go-openapi/jsonreference v0.19.6 // indirect
 	github.com/go-openapi/spec v0.20.4 // indirect
 	github.com/go-openapi/swag v0.19.15 // indirect
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/goccy/go-json v0.10.2 // indirect
+	github.com/gofrs/uuid v4.4.0+incompatible // indirect
 	github.com/golang/snappy v0.0.1 // indirect
 	github.com/gorilla/websocket v1.5.0 // indirect
+	github.com/hashicorp/go-cleanhttp v0.5.2 // indirect
+	github.com/hashicorp/go-uuid v1.0.3 // indirect
+	github.com/jcmturner/aescts/v2 v2.0.0 // indirect
+	github.com/jcmturner/dnsutils/v2 v2.0.0 // indirect
+	github.com/jcmturner/gofork v1.7.6 // indirect
+	github.com/jcmturner/goidentity/v6 v6.0.1 // indirect
+	github.com/jcmturner/gokrb5/v8 v8.4.4 // indirect
+	github.com/jcmturner/rpc/v2 v2.0.3 // indirect
 	github.com/josharian/intern v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/klauspost/compress v1.13.6 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.7 // indirect
 	github.com/leodido/go-urn v1.4.0 // indirect
 	github.com/mailru/easyjson v0.7.6 // indirect
+	github.com/masterzen/simplexml v0.0.0-20190410153822-31eea3082786 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/montanaflynn/stats v0.0.0-20171201202039-1bf9dbcd8cbe // indirect
 	github.com/pelletier/go-toml/v2 v2.2.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/stretchr/objx v0.5.2 // indirect
+	github.com/tidwall/transform v0.0.0-20201103190739-32f242e2dbde // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.2.12 // indirect
 	github.com/xdg-go/pbkdf2 v1.0.0 // indirect
 	github.com/xdg-go/scram v1.1.2 // indirect
 	github.com/xdg-go/stringprep v1.0.4 // indirect
 	github.com/youmark/pkcs8 v0.0.0-20181117223130-1be2e3e5546d // indirect
 	golang.org/x/arch v0.7.0 // indirect
-	golang.org/x/net v0.22.0 // indirect
-	golang.org/x/sync v0.1.0 // indirect
-	golang.org/x/sys v0.18.0 // indirect
-	golang.org/x/text v0.14.0 // indirect
-	golang.org/x/tools v0.7.0 // indirect
+	golang.org/x/net v0.25.0 // indirect
+	golang.org/x/sync v0.7.0 // indirect
+	golang.org/x/sys v0.21.0 // indirect
+	golang.org/x/text v0.16.0 // indirect
+	golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d // indirect
 	google.golang.org/protobuf v1.33.0 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect