Describe the Caldera capability in documentation

COSSAS · Jan 23, 2025 · 12f1dd2 · 12f1dd2
1 parent 17e2b27
commit 12f1dd2
Show file tree

Hide file tree

Showing 4 changed files with 67 additions and 3 deletions.
diff --git a/docs/content/en/docs/core-components/executer.md b/docs/content/en/docs/core-components/executer.md
@@ -67,6 +67,7 @@ class "Ssh" as ssh
 class "OpenC2" as openc2
 class "HttpApi" as api
 class "Manual" as manual
+class "CalderaCmd" as calderacmd
 class "Fin" as fin
 
 
@@ -209,4 +210,4 @@ Note only [Comparison Expression](http://docs.oasis-open.org/cti/stix/v2.0/cs01/
 {{% /alert %}}
 
 ### 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. 
+The parallel executor will execute the parallel step. This will be done in sequence to simplify implementation. As parallel steps must not depend on each other, sequential execution is possible. Later this will be changed.
diff --git a/docs/content/en/docs/core-components/modules.md b/docs/content/en/docs/core-components/modules.md
@@ -262,6 +262,63 @@ The result of the step is stored in the following output variables:
 }
 ```
 
+### Caldera capability
+
+This capability executes [Caldera Abilities](https://caldera.readthedocs.io/en/latest/Learning-the-terminology.html#abilities-and-adversaries) on the specified targets by creating an operation on a separate Caldera server. 
+The server is packaged in the docker build of SOARCA, but can also be provided separably as a stand-alone server.
+
+#### Success and failure
+
+The Caldera step is considered successful if a connection to the Caldera server can be established, the ability, if supplied as b64command, can be created on the server, an operation can be started on the specified group and adversary, and the operation finished without errors.
+
+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:
+
+```json
+{
+    "__soarca_caldera_cmd_result__": {
+        "type": "string",
+        "value": ""
+    }
+}
+```
+
+#### Example
+
+This example will start an operation that executes the ability with ID `36eecb80-ede3-442b-8774-956e906aff02` on the Caldera agent group `infiltrators`.
+```json
+{
+    "workflow": {
+        "action--7777c6b6-e275-434e-9e0b-d68f72e691c1": {
+            "type": "action",
+            "agent": "soarca--00010001-1000-1000-a000-000100010001",
+            "targets": ["security-category--c7e6af1b-9e5a-4055-adeb-26b97e1c4db7"],
+            "commands": [
+                {
+                    "type": "caldera",
+                    "command": "36eecb80-ede3-442b-8774-956e906aff02"
+                }
+            ]
+        }
+    },
+    "agent_definitions": {
+        "soarca--00010001-1000-1000-a000-000100010001": {
+            "type": "soarca",
+            "name": "soarca-caldera-cmd"
+        }
+    },
+    "target_definitions": {
+        "linux--c7e6af1b-9e5a-4055-adeb-26b97e1c4db7": {
+            "type": "security-category",
+            "name": "infiltrators"
+            "category": ["caldera"],
+        }
+    }
+}
+```
 
 ### 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).

diff --git a/docs/content/en/docs/soarca-extensions/_index.md b/docs/content/en/docs/soarca-extensions/_index.md
@@ -10,7 +10,7 @@ date: 2023-01-05
 
 
 {{% alert title="Warning" color="warning" %}}
-SOARCA V.1.0.X implements currently the following native capalities: **HTTP capability**, **OpenC2 capability**, **SSH capability**, and **PowerShell (WINRM)**. Other core capabilities are part of our milestones which can be found [here](https://github.com/COSSAS/SOARCA/milestones).
+SOARCA V.1.0.X implements currently the following native capabilities: **HTTP capability**, **OpenC2 capability**, **SSH capability**, **PowerShell (WINRM)** and **Caldera capability**. Other core capabilities are part of our milestones which can be found [here](https://github.com/COSSAS/SOARCA/milestones).
 {{% /alert %}}
 
 SOARCA features a set of [native capabilities](/docs/soarca-extensions/native-capabilities). The HTTP, OpenC2 HTTP, and SSH transport mechanisms are supported by the first release of SOARCA. SOARCA's capabilities can be extended with custom implementations, which is further discussed on this page.

diff --git a/docs/content/en/docs/soarca-extensions/native-capabilities.md b/docs/content/en/docs/soarca-extensions/native-capabilities.md
@@ -33,4 +33,10 @@ CACAO documentation: [SSH Command](https://docs.oasis-open.org/cacao/security-pl
 
 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)
+CACAO documentation: [PowerShell Command](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256499)
+
+## Caldera capability
+
+The Caldera capability allows for interoperability between SOARCA and [Caldera](https://caldera.mitre.org/).
+
+Caldera documentation: [caldera Command](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256493)