Feature/docs/281 add documentation on advanced installation and confi…

…guration (#286)

Co-authored-by: Maarten de Kruijf <[email protected]>

docs/content/en/docs/_index.md

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

docs/content/en/docs/concepts/executable-playbooks.md

@@ -12,7 +12,7 @@ resources:
 SOARCA is build on top of the [CACAO Security Playbook Version 2.0](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html) standard.
 
 {{% alert title="Warning" color="warning" %}}
-SOARCA v1.0 only implements a part of the CACAO v2 spec. Only `start`, `end`, and `action` steps are supported at this time.
+SOARCA v1.0 only implements a part of the CACAO v2 spec. Only `start`, `end`, `action`, and `if/else` steps are supported at this time.
 {{% /alert %}}
 
 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.
@@ -390,4 +390,4 @@ This is de JSON data of the playbook used throughout this page.
     }
   }
 }
-```
+```

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

@@ -1,6 +1,6 @@
 ---
 title: Design
-weight: 5
+weight: 6
 description: >
   The design of SOARCA
   
@@ -12,7 +12,6 @@ SOARCA consists of several key components:
 2. **SOARCA Native Capabilities**: These are the functionalities explicitly defined in the Cacao v2 specification and are integral to the core. They are also represented in green.
 3. **Fins**: These are the extension capabilities, also known as Fins. They enhance the functionality and integration of SOARCA and are depicted in orange. These are not (yet) part of this repository, but may be implemented by partners or TNO in the future.
 
-
 ![core](/SOARCA/images/core_color.png)
 
 ## Core component overview

docs/content/en/docs/core-components/api-reporter.md

@@ -9,7 +9,7 @@ weight: 2
 
 # Endpoint description
 
-We will use HTTP status codes <https://en.wikipedia.org/wiki/List_of_HTTP_status_codes>
+We will use HTTP status codes https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
 
 ```plantuml
 @startuml

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

@@ -9,7 +9,7 @@ date: 2024-03-18
 
 ## Prerequisites
 
-Before you begin, you might need to install the following tools (Linux Ubuntu 22.04 adapt for your needs): 
+Before you begin, you might need to install the following tools (Linux Ubuntu 22.04 adapt for your needs):
 
 - [golang](https://go.dev/doc/install)
 - go gin `go get -u github.com/gin-gonic/gin`
@@ -34,9 +34,6 @@ cd docker/soarca && sudo docker compose up -d
 {{< /tab >}}
 {{< /tabpane >}}
 
-
-
-
 {{% alert title="Tip" %}}
 Output will be similar to:
 {{< tabpane langEqualsHeader=false  >}}
@@ -53,17 +50,18 @@ swag init
 {{< /tabpane >}}
 {{% /alert %}}
 
-Compiled binary files can be found under `/bin`. 
+Compiled binary files can be found under `/bin`.
 
 ### Playbook execution
 
 You can use the following commands to execute the example playbooks via the terminal while SOARCA is running assuming on localhost. Alternatively you can go to `http://localhost:8080/swagger/index.html` and use the trigger/playbook endpoint.
 
-
 Example playbooks:
 {{< tabpane langEqualsHeader=false  >}}
 {{< tab header="ssh" lang="sh" >}}
+
 # make sure an ssh server is running on adres 192.168.0.10
+
 curl -X POST -H "Content-Type: application/json" -d @./example/ssh-playbook.json localhost:8080/trigger/playbook
 {{< /tab >}}
 {{< tab header="http" lang="sh" >}}
@@ -74,14 +72,15 @@ curl -X POST -H "Content-Type: application/json" -d @./example/openc2-playbook.j
 {{< /tab >}}
 {{< /tabpane >}}
 
-
 ## Configuration
 
 SOARCA reads its configuration from the environment variables or a `.env` file. An example of a `.env` is given below:
 
 {{< tabpane langEqualsHeader=false  >}}
 {{< tab header="`.env`" lang="txt" >}}
 PORT: 8080
+SOARCA_ALLOWED_ORIGINS: "*"
+GIN_MODE: "release"
 MONGODB_URI: "mongodb://localhost:27017"
 DATABASE_NAME: "soarca"
 DB_USERNAME: "root"
@@ -98,11 +97,14 @@ LOG_FORMAT: "json"
 ENABLE_FINS: false
 MQTT_BROKER: "localhost"
 MQTT_PORT: 1883
-VALIDATION_SCHEMA_URL: ""
+
+HTTP_SKIP_CERT_VALIDATION: false
 {{< /tab >}}
 {{< /tabpane >}}
 
-### Docker hub 
+
+For more custom and advanced deployment instructions go [here](/docs/installation-configuration/_index.md).
+### Docker hub
 
 `docker pull cossas/soarca`
 
@@ -114,23 +116,3 @@ make build
 cp .env.example .env
 ./build/soarca
 ```
-
-### Configuring SOARCA
-
-|variable |content |description
-|---|---|---|
-|PORT |port  |Set the exposed port of SOARCA the default is `8080`
-|DATABASE |true \| false   | Set if you want to run with external database default is `false`
-|MONGODB_URI |uri  |Set the Mongo DB uri default is `mongodb://localhost:27017`
-|DATABASE_NAME |name  |Set the Mongo DB database name when using docker default is `soarca`
-|DB_USERNAME |user  |Set the Mongo DB database user when using docker default is `root`
-|DB_PASSWORD |password  |Set the Mongo DB database users password when using docker default is `rootpassword`. IT IS RECOMMENDED TO CHANGE THIS IN PRODUCTION!
-|MAX_REPORTERS |number  |Set the maximum number of downstream reporters default is `5` 
-|LOG_GLOBAL_LEVEL |[Log levels]  |One of the specified log levels. Defaults to `info`
-|LOG_MODE |development \| production  |If production is chosen the `LOG_GLOBAL_LEVEL` is used for all modules defaults to `production`
-|LOG_FILE_PATH |filepath  |Path to the logfile you want to use for all logging. Defaults to `""` (empty string)
-|LOG_FORMAT |text \| json  |The logging can be in plain text format or in JSON format. Defaults to `json`
-|MQTT_BROKER | dns name or ip | The broker address for SOARCA to connect to, for communication with fins default is `localhost`
-|MQTT_PORT   | port | The broker address for SOARCA to connect to, for communication with fins default is `1883`
-|ENABLE_FINS| true \| false | Enable fins in SOARCA defaults to `false`
-|VALIDATION_SCHEMA_URL|url| Set a custom validation schema to be used to validate playbooks defaul is `""` to use internal. NOTE: changing this heavily impacts performance. 

docs/content/en/docs/installation-configuration/_index.md

@@ -0,0 +1,69 @@
+
+---
+
+description: Everything you need to install and configure SOARCA
+title: Advanced Installation and Configuration
+categories: [documentation, configuration]
+tags: [extension, security]
+weight: 4
+---
+
+After completing the [Getting Started](/docs/getting-started/_index.md) setup for SOARCA, you may find that certain advanced configurations or customizations are necessary to optimize SOARCA for your specific use cases, for example integrating with The Hive. This section provides in-depth guidance on additional steps you can take to enhance, secure, and integrate SOARCA with your infrastructure, ensuring it meets your unique operational needs.
+
+### Configuring SOARCA
+
+| Variable                   | Content                          | Description                                                                 |
+|----------------------------|-----------------------------------|-----------------------------------------------------------------------------|
+| PORT                       | `8080`                           | Set the exposed port of SOARCA. Default is `8080`.                          |
+| ENABLE_TLS                 | `false`                          | Enable TLS for secure communication. Default is `false`.                    |
+| CERT_FILE                  | `"/certs/server.crt"`            | Path to the TLS certificate file. Default is `"/certs/server.crt"`.         |
+| CERT_KEY_FILE              | `"/certs/server.key"`            | Path to the TLS certificate key file. Default is `"/certs/server.key"`.     |
+| MAX_EXECUTIONS             | `1000`                           | The number of historical executions saved, including the current one. Default is `1000`. |
+| SOARCA_ALLOWED_ORIGINS     | `*`                              | Set allowed origins for cross-origin requests. Default is `*`.              |
+| GIN_MODE                   | `release`                        | Set the GIN mode. Default is `release`.                                     |
+| DATABASE                   | `false`                          | Set if you want to run with an external database. Default is `false`.       |
+| MONGODB_URI                | `mongodb://localhost:27017`      | Set the MongoDB URI. Default is `mongodb://localhost:27017`.                |
+| DATABASE_NAME              | `soarca`                         | Set the MongoDB database name when using Docker. Default is `soarca`.       |
+| DB_USERNAME                | `root`                           | Set the MongoDB database user when using Docker. Default is `root`.         |
+| DB_PASSWORD                | `rootpassword`                   | Set the MongoDB database user password when using Docker. **Change this in production!** Default is `rootpassword`. |
+| PLAYBOOK_API_LOG_LEVEL     | `trace`                          | Set the log level for the playbook API. Default is `trace`.                 |
+| MAX_REPORTERS              | `5`                              | Set the maximum number of downstream reporters. Default is `5`.             |
+| LOG_GLOBAL_LEVEL           | `info`                           | One of the specified log levels. Default is `info`.                         |
+| LOG_MODE                   | `development`                    | Set the logging mode. If `production`, `LOG_GLOBAL_LEVEL` is used for all modules. Default is `development`. |
+| LOG_FILE_PATH              | `""`                             | Path to the logfile for all logging. Default is `""` (empty string).        |
+| LOG_FORMAT                 | `json`                           | Set the logging format. Either `text` or `json`. Default is `json`.         |
+| ENABLE_FINS                | `false`                          | Enable FINS in SOARCA. Default is `false`.                                  |
+| MQTT_BROKER                | `localhost`                      | The broker address for SOARCA to connect to for communication with FINS. Default is `localhost`. |
+| MQTT_PORT                  | `1883`                           | The port for the MQTT broker. Default is `1883`.                            |
+| HTTP_SKIP_CERT_VALIDATION  | `false`                          | Set whether to skip certificate validation for HTTP connections. Default is `false`. |
+| VALIDATION_SCHEMA_URL      | `""`                             | Set a custom validation schema to validate playbooks. Default is `""` to use the internal schema. **Note:** Changing this can heavily impact performance. |
+
+-----
+
+### Integrations
+
+#### The Hive
+
+| Variable             | Content                          | Description                                             |
+|----------------------|-----------------------------------|---------------------------------------------------------|
+| THEHIVE_ACTIVATE     | `false`                          | Enable integration with The Hive. Default is `false`.   |
+| THEHIVE_API_TOKEN    | `your_token`                     | Set the API token for The Hive integration.             |
+| THEHIVE_API_BASE_URL | `http://your.thehive.instance/api/v1/` | Set the base URL for The Hive API. Default is `""`.      |
+
+-----
+
+### Authentication
+
+{{% alert title="Note" color="primary" %}}
+More information on setting up authentication can be found [here](/docs/installation-configuration/authentication.md).
+{{% /alert %}}
+| Variable               | Content                                    | Description                                                                                 |
+|------------------------|---------------------------------------------|---------------------------------------------------------------------------------------------|
+| AUTH_ENABLED           | `false`                                    | Enable authentication. Default is `false`.                                                  |
+| OIDC_ISSUER            | `https://localhost:9443/application/u/test/` | The OIDC issuer URL.                                                                         |
+| OIDC_CLIENT_ID         | `SOME_CLIENT_ID`                           | Set the OIDC client ID.                                                                     |
+| OIDC_CLIENT_SECRET     | `SOME_CLIENT_SECRET`                       | Set the OIDC client secret.                                                                 |
+| OIDC_REDIRECT_URL      | `http://localhost:8081/auth/soarca_gui/callback` | Set the OIDC redirect URL.                                                                 |
+| COOKIE_SECRET_KEY      | `SOME_COOKIE_SECRET`                       | Optional: Secret key for cookies. Generate using `openssl rand -base64 32` or `head -c 32 /dev/urandom | base64`. |
+| OIDC_SKIP_TLS_VERIFY   | `true`                                     | Set whether to skip TLS verification. Default is `true`.                                    |
+| AUTH_GROUP             | `soarca_admin`                             | Specify the group users must belong to for authentication against SOARCA.                  |