Feature/68 docs update (#3)

Co-authored-by: Hidde-Jan Jongsma <hidde-jan.jongsma@tno.nl>
Co-authored-by: Maarten de Kruijf <maarten.dekruijf@tno.nl>

documentation/content/en/_index.md → docs/content/en/_index.md

@@ -6,7 +6,7 @@ title: Soarca
 <a class="btn btn-lg btn-primary me-3 mb-4" href="{{< relref "/docs" >}}">
   Learn More <i class="fas fa-arrow-alt-circle-right ms-2"></i>
 </a>
-<a class="btn btn-lg btn-secondary me-3 mb-4" href="https://github.com/google/docsy-example">
+<a class="btn btn-lg btn-secondary me-3 mb-4" href="https://github.com/COSSAS/SOARCA">
   Download <i class="fab fa-github ms-2 "></i>
 </a>
 <p class="lead mt-5"></p>

docs/content/en/docs/_index.md

@@ -0,0 +1,58 @@
+---
+title: SOARCA Documentation
+linkTitle: Docs
+menu: {main: {weight: 20}}
+weight: 20
+---
+
+
+{{% alert title="Warning" color="warning" %}}
+SOARCA is currently in its **alpha release**, with ongoing evelopment aimed at expanding its capabilities, improving integration, and enhancing its functionalities. You can track our progress and upcoming milestones at [LINK TO ROADMAP].
+
+We warmly welcome contributions to our repository. You can find the guidelines for contributing [here](/docs/contribution-guidelines).
+{{% /alert %}}
+
+SOARCA, an open-source SOAR (Security Orchestration, Automation and Response) tool developed by TNO, is designed be vendor-agnostic, allowing it to orchestrate various security actuators and systems. SOARCA is the first SOAR that aims to be compliant with the [CACAO v2.0](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/security-playbooks-v2.0.html) standard.
+
+SOARCA enables cyber defenders to coordinate and automate their cyber operations, by using executable CACAO playbooks.
+
+SOARCA aims to achieve the following goals:
+
+- **Standard Compliance**: Adhering to the latest standards, including [CACAO v2.0](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/security-playbooks-v2.0.html) and [OpenC2](https://openc2.org/), allows for interopability with a wide range of technologies.
+- **Extensibility with Open Interfaces**: Enjoy the flexibility of an extensible tool featuring open and well-defined interfaces, promoting adaptability, customization, and experimentation.
+- **Open-Source**: Embrace an open-source model that not only offers cost-effective solutions but also supports unrestricted use and adaptation for research purposes.
+
+
+Interested in the vision and concepts of SOARCA? Then check the [SOARCA vision and concepts](/docs/concepts/).
+
+
+## SOARCA capabilities
+
+SOARCA currently supports the following transport mechanisms:
+
+<div class="works-well-with">
+{{< cardpane >}}
+{{% card header="OpenC2 - Native" %}}
+[![OpenC2](/images/logos-external/openc2.svg)](/docs/soarca-extentions/native-capabilities/#openc2-capability)
+{{% /card %}}
+
+{{% card header="HTTP - Native" %}}
+[![Http](/images/logos-external/http.svg)](/docs/soarca-extentions/native-capabilities/#http-api-capability)
+{{% /card %}}
+
+{{% card header="SSH - Native" %}}
+[![Ssh](/images/logos-external/ssh.svg)](/docs/soarca-extentions/native-capabilities/#ssh-capability)
+{{% /card %}}
+{{< /cardpane >}}
+</div>
+
+
+## Features of SOARCA
+
+
+
+## Where do I start?
+
+{{% alert title="primary" color="primary" %}}
+Following our [Getting started](/docs/getting-started/) guide will help you setup SOARCA and configure the SOAR for your internal security tooling. For more custom requirement 
+{{% /alert %}}

documentation/content/en/docs/concepts/_index.md → docs/content/en/docs/concepts/_index.md

@@ -1,8 +1,8 @@
 ---
-title: SOARCA vision & Concepts
+title: Vision & Concepts
 weight: 3
 description: >
-  Why SOARCA?
+  The what and why of SOARCA
 resources:
 - src: "*Slide2.jpg"
   params:
@@ -13,9 +13,11 @@ resources:
 
 **S**ecurity **O**rchestrator for **A**dvanced **R**esponse to **C**yber **A**ttacks​ - SOARCA
 
-SOARCA is [TNO’s](https://www.tno.nl/nl/) new Open Source SOAR (Security Orchestration, Automation and Response) tool, which has been developed for research and demonstration purposes. With SOARCA, TNO’s goal is to realise and stimulate advanced cyber security innovations and empower end users and organizations by providing a vendor-agnostic, extensible, and standards-compliant solution for security orchestration. SOARCA will be open sourced  on COSSAS (Community for Open Source Security Automation Software – see also [COSSAS](https://cossas-project.org/) with the [Apache 2.0 licence](https://www.apache.org/licenses/LICENSE-2.0).​ 
+SOARCA is [TNO’s](https://www.tno.nl/nl/) new open-source SOAR (Security Orchestration, Automation and Response) tool, which is developed for research and demonstration purposes. With SOARCA, TNO’s goal is to realise and stimulate advanced cyber security innovations and empower end users and organizations by providing a vendor-agnostic, extensible, and standards-compliant solution for security orchestration. SOARCA is made available on [COSSAS](https://cossas-project.org/) (Community for Open Source Security Automation Software) under the [Apache 2.0 licence](https://www.apache.org/licenses/LICENSE-2.0).​
 
-While there are already several mature SOAR tools available on the market, many of them are commercial closed-source products, and none of them complies with the new emerging OASIS Open standards. TNO’s easily accessible “SOARCA” bridges this gap to let end users and organisations get hands-on experience with SOAR tooling and enable new innovations: it is vendor-agnostic, extensible and has open and well-defined interfaces. SOARCA will be available Open Source and in it's first phase can be used and adapted freely for research, demonstrations and PoC purposes. The goal is to grow the SOARCA community and getting SOARCA more mature. SOARCA is designed to fully comply with the newest standards [CACAO v2.0](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/security-playbooks-v2.0.html) and [OpenC2](https://openc2.org/).​
+While there are already several mature SOAR tools available on the market, many of them are commercial closed-source products, and none complies with the new emerging OASIS Open standards. SOARCA is designed to fully comply with the newest standards [CACAO v2.0](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/security-playbooks-v2.0.html) and [OpenC2](https://openc2.org/).
+
+TNO’s SOARCA bridges this gap to let end users and organisations get hands-on experience with SOAR tooling and enable new innovations: it is vendor-agnostic, extensible and has open and well-defined interfaces. SOARCA will freely available and geared toward research and demonstrations. The goal is to foster a healthy community around SOARCA. ​
 
 Note that that open and accessible SOAR functionality is relevant not only for automation in cyber incident response handling, but also attack & defense simulations, cyber ranges, digital twinning and other growing innovation topics that have a strong dependence on the orchestration of complex workflows.
 
@@ -34,7 +36,7 @@ Both inside and outside of TNO there is a strong need for interoperable workflow
 - **Vendor-Agnostic Compatibility**: Our solution ensures seamless integration with various vendors, eliminating reliance on a single provider.
 - **Standard Compliance**: Adhering to the latest standards, including [CACAO v2.0](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/security-playbooks-v2.0.html) and [OpenC2](https://openc2.org/), guarantees up-to-date and secure operations.
 - **Extensibility with Open Interfaces**: Enjoy the flexibility of an extensible tool featuring open and well-defined interfaces, promoting adaptability and customization.
-- **Open-Source Affordability**: Embrace an open-source model that not only offers cost-effective solutions but also supports unrestricted use and adaptation for research purposes.
+- **Open-Source**: Embrace an open-source model that not only offers cost-effective solutions but also supports unrestricted use and adaptation for research purposes.
 
 
 SOAR functionality is relevant not only for automation in incident response handling, but also attack & defense simulations, cyber ranges, digital twinning and other (TNO research) topics that have a strong dependence on the orchestration of complex workflows. 
@@ -46,21 +48,24 @@ At present, SOARCA is in an Alpha release phase and is intended for Proof of Con
 ### Why making Soarca open-source?
 
 - SOARCA has been publicly funded and should therefore ideally be made publicly available.
-- The target audience of SOC, CERT/CSIRT and CTI teams has a very strong affinity with Open Source solutions and embraces them to a great extent. (see also the success of MISP, OpenCTI, The-Hive...)
-- OS SOARCA software provides a low barrier for partner organisations to collaborate with TNO and contribute to further development.
-- Open Source software and tooling can easily be brought in as background into projects and partnerships such as HEU, EDF, TKI projects and others. The use of Open Source tooling is explicitly encouraged by the European Commission.
+- The target audience of SOC, CERT/CSIRT and CTI teams has a very strong affinity with open-source solutions and embraces them to a great extent. (see also the success of MISP, OpenCTI, The-Hive, ...)
+- Open-source software provides a low barrier for partner organisations to collaborate with TNO and contribute to further development.
+- Open Source software and tooling can easily be brought in as background into projects and partnerships such as HEU, EDF, TKI projects and others. The use of open-source tooling is explicitly encouraged by the European Commission.
 
 
 ## Core Concepts
 
-There are several concepts within SOARCA that might be important to know. 
+There are several concepts within SOARCA that might be important to know.
 
-### SoC Playbooks
+### Coarse of Action
 
-`to be added`
+A course of action (CoA) refers to a planned sequence of steps or activities taken to achieve a specific cyber security goal. These steps are often collected into "playbooks". Usually in the form of prose in PDFs, internal wikis, or even scattered throughout emails.
 
 ### CACAO Playbooks: Streamlining Cybersecurity Operations
-A CACAO playbook is a structured and standardized document that outlines a series of orchestrated actions to address specific security events, incidents, or other security-related activities. These playbooks allow for the automation of security steps.
+
+The [CACAO Security Playbooks Version 2.0 specification](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/security-playbooks-v2.0.html) provides a standard for writing _executable_ playbooks. These playbooks are stored in a machine-readable form, allowing them to be (semi-)automatically executed by an orchestration tool.
+
+A CACAO playbook is a structured document that outlines a series of orchestrated actions to address specific security events, incidents, or other security-related activities. These playbooks allow for the automation of security steps.
 
 Example of repetive tasks that might be automated using a CACAO Playbook might be:
 
@@ -70,15 +75,11 @@ Example of repetive tasks that might be automated using a CACAO Playbook might b
 
 By following CACAO playbooks specification, organizations can enhance their automated response capabilities, foster collaboration, and ensure consistentcy of playbooks across diverse technological solutions.
 
-Learn more about CACAO and its schema in the [CACAO Security Playbooks Version 2.0 specification](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/security-playbooks-v2.0.html).
-
-### SOARCA Fin(s): Extending the core Soarca capabilities
+### SOARCA Fin(s): Extending the core capabilities
 
 SOARCA can be extended with custom extensions or rather so-called FIN (inspired by the majestic orca). A fin can integrate with the SOARCA core. (Technical descriptions of the components can be found [here]()). Fins communicate with our SOARCA core using pre-defined MQTT protocol. 
 
-### Coarse of Action
 
-A course of action step refers to a planned sequence of steps or activities taken to achieve a specific cyber security goal.
 
 ## Join the SOARCA Community
 

documentation/content/en/docs/contribution-guidelines/_index.md → docs/content/en/docs/contribution-guidelines/_index.md

@@ -4,7 +4,7 @@ weight: 7
 description: How to contribute to SOARCA
 ---
 
-SOARCA is an open source project written in [Golang](https://go.dev/) and we love getting patches and contributions, and feature suggestions to make SOARCA and its docs even better. We welcome participation from anyone, regardless of their affiliation with OASIS. We invite constructive contributions and feedback from all contributors, following the [standard practices](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) for participation in GitHub public repository projects.
+SOARCA is an open-source project written in [Golang](https://go.dev/) and we love getting patches and contributions, and feature suggestions to make SOARCA and its docs even better. We welcome participation from anyone, regardless of their affiliation with OASIS. We invite constructive contributions and feedback from all contributors, following the [standard practices](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) for participation in GitHub public repository projects.
 
 We expect everyone to follow our [Code of Conduct](/docs/contribution-guidelines/code_of_conduct/), the licenses for each repository, and agree to our Contributor License Agreement when you make your first contribution.
 

documentation/content/en/docs/core-components/_index.md → docs/content/en/docs/core-components/_index.md

@@ -1,8 +1,9 @@
 ---
-title: Core Components
+title: Design
 weight: 5
 description: >
-  SOARCA under the water consists of the following core components:
+  The design of SOARCA
+  
 ---
 
 SOARCA consists of several key components:

documentation/content/en/docs/core-components/api-design.md → docs/content/en/docs/core-components/api-design.md

@@ -1,7 +1,7 @@
 ---
-title: SOARCA API Description
+title: API Description
 description: >
-    This document describes the SOARCA Rest API of the various endpoint that can be called. 
+    Descriptions for the SOARCA REST API endpoints 
 categories: [API]
 tags: [protocol, http, rest, api]
 weight: 2

documentation/content/en/docs/core-components/database.md → docs/content/en/docs/core-components/database.md

@@ -1,5 +1,5 @@
 ---
-title: SOARCA Database
+title: Database
 weight: 7
 categories: [architecture]
 tags: [database]

documentation/content/en/docs/core-components/decomposer.md → docs/content/en/docs/core-components/decomposer.md

@@ -1,10 +1,10 @@
 ---
-title: SOARCA Decomposer
+title: Decomposer
 weight: 4
 categories: [architecture]
 tags: []
 description: >
-  The decomposer will parse playbook objects to individual steps. This allows it to schedule new executor tasks. 
+  Playbook deconstructor architecture
 ---
 
 

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

@@ -1,31 +1,31 @@
 ---
-title: SOARCA Executer
+title: Executer
 weight: 5
 categories: [architecture]
 tags: []
 description: >
-    The document contains the design considerations of the executer of SOARCA
+    Design of the SOARCA step executer
 ---
 
 ## Components
 
 The executer consists of the following components. 
 
-. The capability selector
-. Native capabilities (command executors)
-. MQTT capability to interact with: Fin capabilities (third party executors)
+- The capability selector
+- Native capabilities (command executors)
+- MQTT capability to interact with: Fin capabilities (third party executors)
 
 ### Capability selector (Executor)
 
 The capability selector will select the implementation which is capable of executing the incoming command. There are native capabilities which are based on the CACAO `command-type-ov`:
 
-* Currently implemented:
+* **Currently implemented**
     * ssh
     * http-api
-    * open-C2
-* Coming soon:
+    * openc2-http
+* **Coming soon**
     * manual
-* Future:
+* **Future (potentially)**
     * bash
     * caldera-cmd
     * elastic
@@ -35,7 +35,9 @@ The capability selector will select the implementation which is capable of execu
     * yara
 
 ### Native capabilities
-The Executor will select a module which is capable of execution the command and pass the detail to it. The results will be returned to the decomposer. Result can be output variables or error status.
+The Executor will select a module which is capable of execution the command and pass the detail to it. The capability selection is performed on the basis of the agent-type (see [Agent and Target Common Properties](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256509) in the CACAO 2.0 spec). The convention is that the agent type must equal `soarca-<capability identifier>`, e.g. `soarca-ssh` or `soarca-openc2-http`.
+
+The result of the step execution will be returned to the decomposer. Result can be 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]

documentation/content/en/docs/core-components/log.md → docs/content/en/docs/core-components/log.md

@@ -1,5 +1,5 @@
 ---
-title: SOARCA Logging
+title: Logging
 weight: 10
 description: >
     SOARCA support extensive logging. Logging is based on the [logrus](https://github.com/sirupsen/logrus) framework. 

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

@@ -0,0 +1,105 @@
+---
+title: Executer Modules
+weight: 6
+categories: [architecture]
+tags: [components]
+description: >
+    Native executer modules 
+---
+
+## Requirements
+Executer modules are part of the SOARCA core. Executer modules perform the actual commands in CACAO playbook steps.
+
+
+## Native modules in SOARCA
+The following capability modules are defined in SOARCA:
+
+- ssh
+- http-api
+- openc2-http
+
+The capability will be selected on the type of the agent in the CACAO playbook step. This type must be equal to `soarca-<capability identifier>`.
+
+### SSH capability
+
+This module is defined in a playbook with the following TargetAgent definition:
+
+```json
+"agent_definitions": {
+        "soarca--00010001-1000-1000-a000-000100010001": {
+            "type": "soarca-ssh"
+        }
+    },
+```
+
+This modules does not define specific variables as input, but of course variable interpolation is supported in the command and target definitions. It has the following output variables:
+
+```json
+{
+    "__soarca_ssh_result__": {
+        Type: "string",
+        Name: "result",
+        Value: "<output from command here>"
+    }
+}
+```
+
+If the connection to the target fail the structure will be set but be empty and an error will be returned. If no error occurred nil is returned.
+
+
+## HTTP-API capability
+
+This module is defined in a playbook with the following TargetAgent definition:
+
+```json
+"agent_definitions": {
+        "soarca--00020001-1000-1000-a000-000100010001": {
+            "type": "soarca-http-api"
+        },
+    },
+```
+
+It supports variable interpolation in the command, port, authentication info, and target definitions.
+
+The result of the step is stored in the following output variables:
+
+```json
+{
+    "__soarca_http_api_result__": {
+        Type: "string",
+        Name: "result",
+        Value: "<response from http-api here>"
+    }
+}
+```
+
+## OPEN-C2 capabilty
+
+This module is defined in a playbook with the following TargetAgent definition:
+
+```json
+"agent_definitions": {
+        "soarca--00030001-1000-1000-a000-000100010001": {
+            "type": "soarca-openc2-http"
+        },
+    },
+```
+
+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_openc2_http_result__": {
+        Type: "string",
+        Name: "result",
+        Value: "<response from openc2-http here>"
+    }
+}
+```
+
+---
+
+## MQTT fin module
+This module is used by SOARCA to communicate with fins (capabilities) see [fin documentation](/docs/soarca-extentions/) for more information

documentation/content/en/docs/core-components/soarca-application-design.md → docs/content/en/docs/core-components/soarca-application-design.md

@@ -1,10 +1,10 @@
 ---
-title: SOARCA Application design
+title: Application design
 weight: 1
 categories: [architecture]
 tags: [components]
 description: >
-    The application consist of the endpoint which control the playbooks/ Coarse of Actions and steps that are available.
+    Details of the application architecture for SOARCA
 ---
 
 ##  Design decisions and core dependencies

documentation/content/en/docs/getting-started/_index.md → docs/content/en/docs/getting-started/_index.md

@@ -2,7 +2,7 @@
 title: Getting Started
 description: Getting SOARCA quickly setup
 categories: [documentation, getting-started]
-tags: [docker, bash, ]
+tags: [docker, bash]
 weight: 2
 date: 2023-01-05
 ---