From 9dd0e26525812ad22d2e00d9d0efcb656fb96ead Mon Sep 17 00:00:00 2001
From: Maarten de Kruijf <maarten.dekruijf@tno.nl>
Date: Wed, 15 May 2024 11:26:25 +0200
Subject: [PATCH] Added manual step to documentation

---
 .../en/docs/core-components/executer.md       | 12 +++--
 .../en/docs/core-components/modules.md        | 53 +++++++++++++++++++
 2 files changed, 61 insertions(+), 4 deletions(-)

diff --git a/docs/content/en/docs/core-components/executer.md b/docs/content/en/docs/core-components/executer.md
index 0ccd56d5..1e679d13 100644
--- a/docs/content/en/docs/core-components/executer.md
+++ b/docs/content/en/docs/core-components/executer.md
@@ -66,6 +66,7 @@ class "If condition Executor" as condition
 class "Ssh" as ssh
 class "OpenC2" as openc2
 class "HttpApi" as api
+class "Manual" as manual
 class "Fin" as fin
 
 
@@ -74,6 +75,7 @@ ICapability <-up- Executor
 ICapability <|.. ssh
 ICapability <|.. openc2
 ICapability <|.. api
+ICapability <|.. manual
 ICapability <|.. fin
 
 playbookaction.IExecutor <|.. playbook
@@ -104,12 +106,12 @@ The capability selector will select the implementation which is capable of execu
     * ssh
     * http-api
     * openc2-http
-* **Coming soon**
     * manual
-* **Future (potentially)**
+* **Coming soon**
     * bash
-    * caldera-cmd
     * elastic
+    * caldera-cmd
+* **Future (potentially)**
     * jupyter
     * kestrel
     * sigma
@@ -120,8 +122,10 @@ The executor will select a module that is capable of executing the command and p
 
 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
-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]
+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 [module documentation](/docs/core-components/modules) and in the [fin documentation](/docs/soarca-extensions/).
 
 #### Component overview
 
diff --git a/docs/content/en/docs/core-components/modules.md b/docs/content/en/docs/core-components/modules.md
index 4ef88399..b586f069 100644
--- a/docs/content/en/docs/core-components/modules.md
+++ b/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
+- manual
 
 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,58 @@ The result of the step is stored in the following output variables:
 }
 ```
 
+### 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).
+
+
+<!-- The manual capability will allow an operator to interact with a playbook. It could allow one to perform a manual step that could not be automated, enter a variable to the playbook execution or a combination of these operations.
+
+The main way to interact with the manual step is through SOARCA's [manual api](/docs/core-components/api-manual). The manual step should provide a timeout SOARCA will by default use a timeout of 10 minutes. If a timeout occurs the step is considered as failed. -->
+
+
+
+
+
+#### Success and failure
+
+The manual step is considered successful if a response is made through the [manual api](/docs/core-components/api-manual). The manual command can specify a timeout but if none is specified SOARCA will use a default timeout of 10 minutes. If a timeout occurs the step is considered as failed.
+
+#### Variables
+
+This module does not define specific variables as input, but it requires one to use out_args if an operator want to provide a response to be used later in the playbook.
+
+#### Example
+
+```json
+{
+    "workflow": {
+        "action--7777c6b6-e275-434e-9e0b-d68f72e691c1": {
+            "type": "action",
+            "agent": "soarca--00010001-1000-1000-a000-000100010001",
+            "targets": ["linux--c7e6af1b-9e5a-4055-adeb-26b97e1c4db7"],
+            "commands": [
+                {
+                    "type": "manual",
+                    "command": "Reset the firewall by unplugging it"
+                }
+            ]
+        }
+    },
+    "agent_definitions": {
+        "soarca--00040001-1000-1000-a000-000100010001": {
+            "type": "soarca",
+            "name": "soarca-manual"
+        }
+    },
+    "target_definitions": {
+        "linux--c7e6af1b-9e5a-4055-adeb-26b97e1c4db7": {
+            "type": "linux",
+            "name": "target",
+            "address": { "ipv4": ["10.0.0.1"] }
+        }
+    }
+}
+```
 ---
 
 ## MQTT fin module