diff --git a/documentation/Dockerfile b/docs/Dockerfile similarity index 100% rename from documentation/Dockerfile rename to docs/Dockerfile diff --git a/documentation/LICENSE b/docs/LICENSE similarity index 100% rename from documentation/LICENSE rename to docs/LICENSE diff --git a/documentation/README.md b/docs/README.md similarity index 100% rename from documentation/README.md rename to docs/README.md diff --git a/documentation/assets/icons/favicon.ico b/docs/assets/icons/favicon.ico similarity index 100% rename from documentation/assets/icons/favicon.ico rename to docs/assets/icons/favicon.ico diff --git a/documentation/assets/icons/logo.svg b/docs/assets/icons/logo.svg similarity index 100% rename from documentation/assets/icons/logo.svg rename to docs/assets/icons/logo.svg diff --git a/documentation/assets/icons/logo_2.svg b/docs/assets/icons/logo_2.svg similarity index 100% rename from documentation/assets/icons/logo_2.svg rename to docs/assets/icons/logo_2.svg diff --git a/documentation/assets/icons/soarca_logo.ico b/docs/assets/icons/soarca_logo.ico similarity index 100% rename from documentation/assets/icons/soarca_logo.ico rename to docs/assets/icons/soarca_logo.ico diff --git a/documentation/assets/scss/_adopters.scss b/docs/assets/scss/_adopters.scss similarity index 100% rename from documentation/assets/scss/_adopters.scss rename to docs/assets/scss/_adopters.scss diff --git a/documentation/assets/scss/_nav.scss b/docs/assets/scss/_nav.scss similarity index 100% rename from documentation/assets/scss/_nav.scss rename to docs/assets/scss/_nav.scss diff --git a/documentation/assets/scss/_page.scss b/docs/assets/scss/_page.scss similarity index 100% rename from documentation/assets/scss/_page.scss rename to docs/assets/scss/_page.scss diff --git a/documentation/assets/scss/_variables_project.scss b/docs/assets/scss/_variables_project.scss similarity index 100% rename from documentation/assets/scss/_variables_project.scss rename to docs/assets/scss/_variables_project.scss diff --git a/documentation/config.yaml b/docs/config.yaml similarity index 100% rename from documentation/config.yaml rename to docs/config.yaml diff --git a/documentation/content/en/_index.md b/docs/content/en/_index.md similarity index 95% rename from documentation/content/en/_index.md rename to docs/content/en/_index.md index 921b821e..8a5a5367 100644 --- a/documentation/content/en/_index.md +++ b/docs/content/en/_index.md @@ -6,7 +6,7 @@ title: Soarca }}"> Learn More - + Download

diff --git a/documentation/content/en/blog/_index.md b/docs/content/en/blog/_index.md similarity index 100% rename from documentation/content/en/blog/_index.md rename to docs/content/en/blog/_index.md diff --git a/documentation/content/en/blog/news/_index.md b/docs/content/en/blog/news/_index.md similarity index 100% rename from documentation/content/en/blog/news/_index.md rename to docs/content/en/blog/news/_index.md diff --git a/documentation/content/en/blog/news/first-post/featured-sunset-get.png b/docs/content/en/blog/news/first-post/featured-sunset-get.png similarity index 100% rename from documentation/content/en/blog/news/first-post/featured-sunset-get.png rename to docs/content/en/blog/news/first-post/featured-sunset-get.png diff --git a/documentation/content/en/blog/news/first-post/index.md b/docs/content/en/blog/news/first-post/index.md similarity index 100% rename from documentation/content/en/blog/news/first-post/index.md rename to docs/content/en/blog/news/first-post/index.md diff --git a/documentation/content/en/blog/releases/_index.md b/docs/content/en/blog/releases/_index.md similarity index 100% rename from documentation/content/en/blog/releases/_index.md rename to docs/content/en/blog/releases/_index.md diff --git a/documentation/content/en/blog/releases/in-depth-monoliths-detailed-spec.md b/docs/content/en/blog/releases/in-depth-monoliths-detailed-spec.md similarity index 100% rename from documentation/content/en/blog/releases/in-depth-monoliths-detailed-spec.md rename to docs/content/en/blog/releases/in-depth-monoliths-detailed-spec.md diff --git a/documentation/content/en/community/_index.md b/docs/content/en/community/_index.md similarity index 100% rename from documentation/content/en/community/_index.md rename to docs/content/en/community/_index.md diff --git a/documentation/content/en/docs/FAQ.md b/docs/content/en/docs/FAQ.md similarity index 100% rename from documentation/content/en/docs/FAQ.md rename to docs/content/en/docs/FAQ.md diff --git a/docs/content/en/docs/_index.md b/docs/content/en/docs/_index.md new file mode 100644 index 00000000..7a268c01 --- /dev/null +++ b/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: + +
+{{< 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 >}} +
+ + +## 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 %}} diff --git a/documentation/content/en/docs/about/_index.md b/docs/content/en/docs/about/_index.md similarity index 100% rename from documentation/content/en/docs/about/_index.md rename to docs/content/en/docs/about/_index.md diff --git a/documentation/content/en/docs/concepts/Slide2.jpg b/docs/content/en/docs/concepts/Slide2.jpg similarity index 100% rename from documentation/content/en/docs/concepts/Slide2.jpg rename to docs/content/en/docs/concepts/Slide2.jpg diff --git a/documentation/content/en/docs/concepts/_index.md b/docs/content/en/docs/concepts/_index.md similarity index 61% rename from documentation/content/en/docs/concepts/_index.md rename to docs/content/en/docs/concepts/_index.md index bafee945..4f5193ce 100644 --- a/documentation/content/en/docs/concepts/_index.md +++ b/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 diff --git a/documentation/content/en/docs/contribution-guidelines/_index.md b/docs/content/en/docs/contribution-guidelines/_index.md similarity index 97% rename from documentation/content/en/docs/contribution-guidelines/_index.md rename to docs/content/en/docs/contribution-guidelines/_index.md index 583d6aec..227f9497 100644 --- a/documentation/content/en/docs/contribution-guidelines/_index.md +++ b/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. diff --git a/documentation/content/en/docs/contribution-guidelines/code_of_conduct.md b/docs/content/en/docs/contribution-guidelines/code_of_conduct.md similarity index 100% rename from documentation/content/en/docs/contribution-guidelines/code_of_conduct.md rename to docs/content/en/docs/contribution-guidelines/code_of_conduct.md diff --git a/documentation/content/en/docs/core-components/_index.md b/docs/content/en/docs/core-components/_index.md similarity index 85% rename from documentation/content/en/docs/core-components/_index.md rename to docs/content/en/docs/core-components/_index.md index 593ce554..fefbb61d 100644 --- a/documentation/content/en/docs/core-components/_index.md +++ b/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: diff --git a/documentation/content/en/docs/core-components/api-design.md b/docs/content/en/docs/core-components/api-design.md similarity index 99% rename from documentation/content/en/docs/core-components/api-design.md rename to docs/content/en/docs/core-components/api-design.md index f54881d1..06693334 100644 --- a/documentation/content/en/docs/core-components/api-design.md +++ b/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 diff --git a/documentation/content/en/docs/core-components/database.md b/docs/content/en/docs/core-components/database.md similarity index 99% rename from documentation/content/en/docs/core-components/database.md rename to docs/content/en/docs/core-components/database.md index 6429599a..308a054a 100644 --- a/documentation/content/en/docs/core-components/database.md +++ b/docs/content/en/docs/core-components/database.md @@ -1,5 +1,5 @@ --- -title: SOARCA Database +title: Database weight: 7 categories: [architecture] tags: [database] diff --git a/documentation/content/en/docs/core-components/decomposer.md b/docs/content/en/docs/core-components/decomposer.md similarity index 92% rename from documentation/content/en/docs/core-components/decomposer.md rename to docs/content/en/docs/core-components/decomposer.md index 4e0e225a..42b41d87 100644 --- a/documentation/content/en/docs/core-components/decomposer.md +++ b/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 --- diff --git a/documentation/content/en/docs/core-components/executer.md b/docs/content/en/docs/core-components/executer.md similarity index 75% rename from documentation/content/en/docs/core-components/executer.md rename to docs/content/en/docs/core-components/executer.md index ee0dbde9..2a6a863a 100644 --- a/documentation/content/en/docs/core-components/executer.md +++ b/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-`, 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] diff --git a/documentation/content/en/docs/core-components/log.md b/docs/content/en/docs/core-components/log.md similarity index 99% rename from documentation/content/en/docs/core-components/log.md rename to docs/content/en/docs/core-components/log.md index c654f436..35623404 100644 --- a/documentation/content/en/docs/core-components/log.md +++ b/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. diff --git a/docs/content/en/docs/core-components/modules.md b/docs/content/en/docs/core-components/modules.md new file mode 100644 index 00000000..4bc696e4 --- /dev/null +++ b/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-`. + +### 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: "" + } +} +``` + +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: "" + } +} +``` + +## 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: "" + } +} +``` + +--- + +## MQTT fin module +This module is used by SOARCA to communicate with fins (capabilities) see [fin documentation](/docs/soarca-extentions/) for more information diff --git a/documentation/content/en/docs/core-components/soarca-application-design.md b/docs/content/en/docs/core-components/soarca-application-design.md similarity index 96% rename from documentation/content/en/docs/core-components/soarca-application-design.md rename to docs/content/en/docs/core-components/soarca-application-design.md index 87ba16ca..c8ce38d4 100644 --- a/documentation/content/en/docs/core-components/soarca-application-design.md +++ b/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 diff --git a/documentation/content/en/docs/getting-started/_index.md b/docs/content/en/docs/getting-started/_index.md similarity index 98% rename from documentation/content/en/docs/getting-started/_index.md rename to docs/content/en/docs/getting-started/_index.md index 1bc22412..0bd0e59c 100644 --- a/documentation/content/en/docs/getting-started/_index.md +++ b/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 --- diff --git a/documentation/content/en/docs/release-notes/_index.md b/docs/content/en/docs/release-notes/_index.md similarity index 100% rename from documentation/content/en/docs/release-notes/_index.md rename to docs/content/en/docs/release-notes/_index.md diff --git a/docs/content/en/docs/soarca-api/_index.md b/docs/content/en/docs/soarca-api/_index.md new file mode 100644 index 00000000..7d7354dc --- /dev/null +++ b/docs/content/en/docs/soarca-api/_index.md @@ -0,0 +1,14 @@ +--- +title: REST API +description: > + The SOARCA REST Api +categories: [API] +tags: [protocol, http, rest, api, swagger] +weight: 4 +type: swagger +date: 2023-01-05 +--- + +This page contains the [Swagger](https://swagger.io/) documentation of the SOARCA REST API. + +{{< swaggerui src="openapi/swagger.json" >}} \ No newline at end of file diff --git a/docs/content/en/docs/soarca-extentions/_index.md b/docs/content/en/docs/soarca-extentions/_index.md new file mode 100644 index 00000000..d75186b1 --- /dev/null +++ b/docs/content/en/docs/soarca-extentions/_index.md @@ -0,0 +1,27 @@ +--- +title: Extensions & Capabilities +description: > + Extending SOARCA is done by developing a SOARCA-Fin. +categories: [extensions, architecture, capabilities] +tags: [fin] +weight: 5 +date: 2023-01-05 +--- + + +{{% alert title="Warning" color="warning" %}} +SOARCA V.1.0.X implements currently the following native capalities: **HTTP capability**, **OpenC2 capability**, and **SSH capability**. Other core capabilities are part of our milestones which can be found [here](). +{{% /alert %}} + +SOARCA features a set of [native capabilities](/docs/soarca-extensions/native-capabilities). The HTTP, OpenC2 HTTP, and the SSH transport mechanisms are support by the first release of SOARCA. SOARCA's capabilities can be extented with custom implementations which is further discussed on this page. + +## Extending the native capabilities + +The native capabilities supported by SOARCA can be extended through a mechanism we named Fins. Your capability can be integrated with SOARCA by implementing the Fin protocol. This protocol regulates communication between SOARCA and the extension capabilities over an MQTT-bus. + +MQTT is a light-weight messaging protocol with libraries written in various programming languages. To integrate with SOARCA, can write your own implementation of the Fin protocol, or use our [python]() or [golang]() libraries for easier integration. + +## Fin protocol + +The underlying protocol for the SOARCA fins can be [here](/docs/soarca-extentions/fin-protocol). + diff --git a/doc/fin-protocol.md b/docs/content/en/docs/soarca-extentions/fin-protocol.md similarity index 96% rename from doc/fin-protocol.md rename to docs/content/en/docs/soarca-extentions/fin-protocol.md index eaf4c087..fd74fc51 100644 --- a/doc/fin-protocol.md +++ b/docs/content/en/docs/soarca-extentions/fin-protocol.md @@ -1,5 +1,12 @@ -# Fin protocol documentation -The TNO SOARCA Fin protocol +--- +title: Fin protocol +description: > + Specification of the SOARCA Fin protocol +categories: [extensions, architecture] +tags: [fin] +weight: 2 +date: 2023-01-05 +--- ## Goals The goal of the protocol is to provide a simple and robust way to communicate between the SOARCA orchestrator and the capabilities (Fins) that can provide extra functions. @@ -92,7 +99,7 @@ The message is used to register a fin to SOARCA. It has the following payload. | ----------------- | ------------- | ------ | ----------- | |capability_id |UUID |string |Capability id to identify the unique capability a fin can have multiple |type |action | [workflow-step-type-enum](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256479) | Most common is action -|name |name |string |message id +|name |name |string |capability name |version |version |string |Version information of the Fin implementation used in [semantic version](https://semver.org) schema e.g. 1.2.4-beta |step |step structure |[step structure](#step-structure) |Step to specify an example for the step so it can be queried in the SOARCA API |agent |agent structure|[agent structure](#agent-structure) |Agent to specify the agent definition to match in playbooks for SOARCA @@ -192,7 +199,7 @@ The message is used to send a command from SOARCA. It has the following payload. |field |content |type | description | | ----------------- | ------------- | ------ | ----------- | -|type |unregister |string |Unregister message type +|type |command |string |Command message type |message_id |UUID |string |Message UUID |command |command |[command substructure](#command-substructure) |command structure |meta |meta dict |[Meta](#meta) |Meta information for the fin protocol structure @@ -493,9 +500,9 @@ participant Capability as fin soarca -> soarca : create [soarca] topic -fin -> fin : create [UUID] topic +fin -> fin : create [fin UUID] topic soarca <- fin : [soarca] register -soarca --> fin : [UUID] ack +soarca --> fin : [fin UUID] ack @enduml ``` @@ -508,12 +515,12 @@ soarca --> fin : [UUID] ack participant "SOARCA" as soarca participant Capability as fin -soarca -> fin : [UUID] command -soarca <-- fin : [UUID] ack +soarca -> fin : [capability UUID] command +soarca <-- fin : [capability UUID] ack .... processing .... -soarca <- fin : [UUID] result +soarca <- fin : [capability UUID] result soarca --> fin: ack @enduml @@ -565,8 +572,8 @@ participant "SOARCA" as soarca participant Capability as fin -soarca -> fin : [UUID] control message -soarca <-- fin : [UUID] status +soarca -> fin : [fin UUID] control message +soarca <-- fin : [fin UUID] status @enduml ``` diff --git a/docs/content/en/docs/soarca-extentions/native-capabilities.md b/docs/content/en/docs/soarca-extentions/native-capabilities.md new file mode 100644 index 00000000..69b3d813 --- /dev/null +++ b/docs/content/en/docs/soarca-extentions/native-capabilities.md @@ -0,0 +1,29 @@ +--- +title: Native capabilities +description: > + Capabilities and transport mechanisms baked right into SOARCA +categories: [capabilities] +tags: [native] +weight: 2 +date: 2023-01-05 +--- + +This page contains a list of capabilities that are natively implemented in SOARCA. For MQTT-message based capabilities, check [here](/docs/soarca-extentions/). + +## OpenC2 capability + +The OpenC2 HTTP capability uses the http(s) transport layer as specified in [OpenC2 HTTPS](https://docs.oasis-open.org/openc2/open-impl-https/v1.0/open-impl-https-v1.0.html). It allows executing actions on an OpenC2-compatible security actuator. + +CACAO documentation: [OpenC2 HTTP Command](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256498) + +## HTTP API capability + +The HTTP capability allows sending arbitrary HTTP requests to other servers. + +CACAO documentation: [HTTP API Command](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256495) + +## SSH capability + +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) \ No newline at end of file diff --git a/documentation/content/en/featured-background.jpg b/docs/content/en/featured-background.jpg similarity index 100% rename from documentation/content/en/featured-background.jpg rename to docs/content/en/featured-background.jpg diff --git a/documentation/content/en/search.md b/docs/content/en/search.md similarity index 100% rename from documentation/content/en/search.md rename to docs/content/en/search.md diff --git a/documentation/content/fileList.txt b/docs/content/fileList.txt similarity index 100% rename from documentation/content/fileList.txt rename to docs/content/fileList.txt diff --git a/documentation/docker-compose.yaml b/docs/docker-compose.yaml similarity index 100% rename from documentation/docker-compose.yaml rename to docs/docker-compose.yaml diff --git a/documentation/docsy.work b/docs/docsy.work similarity index 100% rename from documentation/docsy.work rename to docs/docsy.work diff --git a/documentation/docsy.work.sum b/docs/docsy.work.sum similarity index 100% rename from documentation/docsy.work.sum rename to docs/docsy.work.sum diff --git a/documentation/go.mod b/docs/go.mod similarity index 100% rename from documentation/go.mod rename to docs/go.mod diff --git a/documentation/go.sum b/docs/go.sum similarity index 100% rename from documentation/go.sum rename to docs/go.sum diff --git a/documentation/hugo.toml b/docs/hugo.toml similarity index 92% rename from documentation/hugo.toml rename to docs/hugo.toml index e707665a..da7bae5f 100644 --- a/documentation/hugo.toml +++ b/docs/hugo.toml @@ -62,7 +62,7 @@ languageName ="English" weight = 1 [languages.en.params] title = "SOARCA" -description = "An open-source Security Orchestrator" +description = "An open-source Security Orchestrator based on the Cacao playbook specification" [params.plantuml] enable = true @@ -109,19 +109,19 @@ version = "0.0" # A link to latest version of the docs. Used in the "version-banner" partial to # point people to the main doc site. -url_latest_version = "https://example.com" +url_latest_version = "https://cossas.github.io/SOARCA/" # Repository configuration (URLs for in-page links to opening issues and suggesting changes) -github_repo = "https://github.com/google/docsy-example" +github_repo = "https://github.com/COSSAS/SOARCA/issues" # An optional link to a related project repo. For example, the sibling repository where your product code lives. -github_project_repo = "https://github.com/google/docsy" +github_project_repo = "https://github.com/COSSAS/SOARCA/" # Specify a value here if your content directory is not in your repo's root directory # github_subdir = "" # Uncomment this if your GitHub repo does not have "main" as the default branch, # or specify a new value if you want to reference another branch in your GitHub links -github_branch= "main" +github_branch= "master" # Google Custom Search Engine ID. Remove or comment out to disable search. #gcs_engine_id = "d72aa9b2712488cc3" @@ -154,8 +154,8 @@ sidebar_menu_foldable = true [params.ui.feedback] enable = true # The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful). -yes = 'Glad to hear it! Please tell us how we can improve.' -no = 'Sorry to hear that. Please tell us how we can improve.' +yes = 'Glad to hear it! Please tell us how we can improve.' +no = 'Sorry to hear that. Please tell us how we can improve.' # Adds a reading time to the top of each doc. # If you want this feature, but occasionally need to remove the Reading time from a single page, @@ -183,7 +183,7 @@ enable = false # Developer relevant links. These will show up on right side of footer and in the community page if you have one. [[params.links.developer]] name = "GitHub" - url = "https://github.com/google/docsy" + url = "https://github.com/COSSAS/SOARCA" icon = "fab fa-github" desc = "Development takes place here!" # [[params.links.developer]] diff --git a/documentation/layouts/404.html b/docs/layouts/404.html similarity index 100% rename from documentation/layouts/404.html rename to docs/layouts/404.html diff --git a/documentation/layouts/home.html b/docs/layouts/home.html similarity index 100% rename from documentation/layouts/home.html rename to docs/layouts/home.html diff --git a/documentation/layouts/partials/head.html b/docs/layouts/partials/head.html similarity index 100% rename from documentation/layouts/partials/head.html rename to docs/layouts/partials/head.html diff --git a/documentation/layouts/partials/hooks/body-end.html b/docs/layouts/partials/hooks/body-end.html similarity index 100% rename from documentation/layouts/partials/hooks/body-end.html rename to docs/layouts/partials/hooks/body-end.html diff --git a/documentation/layouts/partials/hooks/head-end.html b/docs/layouts/partials/hooks/head-end.html similarity index 100% rename from documentation/layouts/partials/hooks/head-end.html rename to docs/layouts/partials/hooks/head-end.html diff --git a/documentation/layouts/shortcodes/alert.html b/docs/layouts/shortcodes/alert.html similarity index 100% rename from documentation/layouts/shortcodes/alert.html rename to docs/layouts/shortcodes/alert.html diff --git a/documentation/layouts/shortcodes/blocks/cover.html b/docs/layouts/shortcodes/blocks/cover.html similarity index 100% rename from documentation/layouts/shortcodes/blocks/cover.html rename to docs/layouts/shortcodes/blocks/cover.html diff --git a/documentation/layouts/shortcodes/card-code.html b/docs/layouts/shortcodes/card-code.html similarity index 100% rename from documentation/layouts/shortcodes/card-code.html rename to docs/layouts/shortcodes/card-code.html diff --git a/documentation/layouts/shortcodes/card.html b/docs/layouts/shortcodes/card.html similarity index 100% rename from documentation/layouts/shortcodes/card.html rename to docs/layouts/shortcodes/card.html diff --git a/documentation/layouts/shortcodes/cardpane.html b/docs/layouts/shortcodes/cardpane.html similarity index 100% rename from documentation/layouts/shortcodes/cardpane.html rename to docs/layouts/shortcodes/cardpane.html diff --git a/documentation/layouts/shortcodes/conditional-text.html b/docs/layouts/shortcodes/conditional-text.html similarity index 100% rename from documentation/layouts/shortcodes/conditional-text.html rename to docs/layouts/shortcodes/conditional-text.html diff --git a/documentation/layouts/shortcodes/figure.html b/docs/layouts/shortcodes/figure.html similarity index 100% rename from documentation/layouts/shortcodes/figure.html rename to docs/layouts/shortcodes/figure.html diff --git a/documentation/layouts/shortcodes/iframe.html b/docs/layouts/shortcodes/iframe.html similarity index 100% rename from documentation/layouts/shortcodes/iframe.html rename to docs/layouts/shortcodes/iframe.html diff --git a/documentation/layouts/shortcodes/imgproc.html b/docs/layouts/shortcodes/imgproc.html similarity index 100% rename from documentation/layouts/shortcodes/imgproc.html rename to docs/layouts/shortcodes/imgproc.html diff --git a/documentation/layouts/shortcodes/pageinfo.html b/docs/layouts/shortcodes/pageinfo.html similarity index 100% rename from documentation/layouts/shortcodes/pageinfo.html rename to docs/layouts/shortcodes/pageinfo.html diff --git a/documentation/layouts/shortcodes/readfile.html b/docs/layouts/shortcodes/readfile.html similarity index 100% rename from documentation/layouts/shortcodes/readfile.html rename to docs/layouts/shortcodes/readfile.html diff --git a/documentation/layouts/shortcodes/redoc.html b/docs/layouts/shortcodes/redoc.html similarity index 100% rename from documentation/layouts/shortcodes/redoc.html rename to docs/layouts/shortcodes/redoc.html diff --git a/documentation/layouts/shortcodes/swaggerui.html b/docs/layouts/shortcodes/swaggerui.html similarity index 100% rename from documentation/layouts/shortcodes/swaggerui.html rename to docs/layouts/shortcodes/swaggerui.html diff --git a/documentation/layouts/shortcodes/tab.html b/docs/layouts/shortcodes/tab.html similarity index 100% rename from documentation/layouts/shortcodes/tab.html rename to docs/layouts/shortcodes/tab.html diff --git a/documentation/layouts/shortcodes/tabpane.html b/docs/layouts/shortcodes/tabpane.html similarity index 100% rename from documentation/layouts/shortcodes/tabpane.html rename to docs/layouts/shortcodes/tabpane.html diff --git a/documentation/layouts/swagger/baseof.html b/docs/layouts/swagger/baseof.html similarity index 100% rename from documentation/layouts/swagger/baseof.html rename to docs/layouts/swagger/baseof.html diff --git a/documentation/layouts/swagger/list.html b/docs/layouts/swagger/list.html similarity index 100% rename from documentation/layouts/swagger/list.html rename to docs/layouts/swagger/list.html diff --git a/documentation/layouts/swagger/single.html b/docs/layouts/swagger/single.html similarity index 100% rename from documentation/layouts/swagger/single.html rename to docs/layouts/swagger/single.html diff --git a/documentation/netlify.toml b/docs/netlify.toml similarity index 100% rename from documentation/netlify.toml rename to docs/netlify.toml diff --git a/documentation/package.json b/docs/package.json similarity index 100% rename from documentation/package.json rename to docs/package.json diff --git a/documentation/static/agones.cast b/docs/static/agones.cast similarity index 100% rename from documentation/static/agones.cast rename to docs/static/agones.cast diff --git a/documentation/static/css/asciinema-player.css b/docs/static/css/asciinema-player.css similarity index 100% rename from documentation/static/css/asciinema-player.css rename to docs/static/css/asciinema-player.css diff --git a/documentation/static/favicons/android-chrome-192x192.png b/docs/static/favicons/android-chrome-192x192.png similarity index 100% rename from documentation/static/favicons/android-chrome-192x192.png rename to docs/static/favicons/android-chrome-192x192.png diff --git a/documentation/static/favicons/android-chrome-512x512.png b/docs/static/favicons/android-chrome-512x512.png similarity index 100% rename from documentation/static/favicons/android-chrome-512x512.png rename to docs/static/favicons/android-chrome-512x512.png diff --git a/documentation/static/favicons/apple-touch-icon.png b/docs/static/favicons/apple-touch-icon.png similarity index 100% rename from documentation/static/favicons/apple-touch-icon.png rename to docs/static/favicons/apple-touch-icon.png diff --git a/documentation/static/favicons/browserconfig.xml b/docs/static/favicons/browserconfig.xml similarity index 100% rename from documentation/static/favicons/browserconfig.xml rename to docs/static/favicons/browserconfig.xml diff --git a/documentation/static/favicons/favicon-16x16.png b/docs/static/favicons/favicon-16x16.png similarity index 100% rename from documentation/static/favicons/favicon-16x16.png rename to docs/static/favicons/favicon-16x16.png diff --git a/documentation/static/favicons/favicon-32x32.png b/docs/static/favicons/favicon-32x32.png similarity index 100% rename from documentation/static/favicons/favicon-32x32.png rename to docs/static/favicons/favicon-32x32.png diff --git a/documentation/static/favicons/favicon.ico b/docs/static/favicons/favicon.ico similarity index 100% rename from documentation/static/favicons/favicon.ico rename to docs/static/favicons/favicon.ico diff --git a/documentation/static/favicons/mstile-150x150.png b/docs/static/favicons/mstile-150x150.png similarity index 100% rename from documentation/static/favicons/mstile-150x150.png rename to docs/static/favicons/mstile-150x150.png diff --git a/documentation/static/favicons/safari-pinned-tab.svg b/docs/static/favicons/safari-pinned-tab.svg similarity index 100% rename from documentation/static/favicons/safari-pinned-tab.svg rename to docs/static/favicons/safari-pinned-tab.svg diff --git a/documentation/static/favicons/site.webmanifest b/docs/static/favicons/site.webmanifest similarity index 100% rename from documentation/static/favicons/site.webmanifest rename to docs/static/favicons/site.webmanifest diff --git a/documentation/static/images/core_color.png b/docs/static/images/core_color.png similarity index 100% rename from documentation/static/images/core_color.png rename to docs/static/images/core_color.png diff --git a/documentation/static/images/logo.svg b/docs/static/images/logo.svg similarity index 100% rename from documentation/static/images/logo.svg rename to docs/static/images/logo.svg diff --git a/documentation/static/images/logos-external/http.svg b/docs/static/images/logos-external/http.svg similarity index 100% rename from documentation/static/images/logos-external/http.svg rename to docs/static/images/logos-external/http.svg diff --git a/documentation/static/images/logos-external/openc2.svg b/docs/static/images/logos-external/openc2.svg similarity index 100% rename from documentation/static/images/logos-external/openc2.svg rename to docs/static/images/logos-external/openc2.svg diff --git a/docs/static/images/logos-external/ssh.svg b/docs/static/images/logos-external/ssh.svg new file mode 100644 index 00000000..01d06480 --- /dev/null +++ b/docs/static/images/logos-external/ssh.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/documentation/static/images/soarca_name.ico b/docs/static/images/soarca_name.ico similarity index 100% rename from documentation/static/images/soarca_name.ico rename to docs/static/images/soarca_name.ico diff --git a/documentation/static/js/asciinema-player.min.js b/docs/static/js/asciinema-player.min.js similarity index 100% rename from documentation/static/js/asciinema-player.min.js rename to docs/static/js/asciinema-player.min.js diff --git a/documentation/static/openapi/swagger.json b/docs/static/openapi/swagger.json similarity index 100% rename from documentation/static/openapi/swagger.json rename to docs/static/openapi/swagger.json diff --git a/documentation/static/openapi/swagger.yaml b/docs/static/openapi/swagger.yaml similarity index 100% rename from documentation/static/openapi/swagger.yaml rename to docs/static/openapi/swagger.yaml diff --git a/documentation/content/en/docs/_index.md b/documentation/content/en/docs/_index.md deleted file mode 100644 index adaf1b9e..00000000 --- a/documentation/content/en/docs/_index.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -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 active development aimed at expanding its integration capabilities and enhancing its functionalities. You can track our progress and upcoming milestones at the provided location. - -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 to be vendor-agnostic, allowing integrate with various systems and technologies. SOARCA is the first SOAR to be fully compliant to the the latest [CACAO v2.0](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/security-playbooks-v2.0.html) standard. - -The SOARCA SOAR enables cyber defenders to coordinate and automate cyber operations. SOARCA aims to achieve the following goals: - -Introducing a distinctive SOAR tool that addresses current market gaps: - -- **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. - - -Are you interested in the vision and concepts of SOARCA? Check the SOARCA vision and concepts [page](/docs/concepts/). - - -## SOARCA Currently integrates with - -
-{{< cardpane >}} -{{% card header="[OpenC2 - Native capability](https://openc2.org/)" %}} -[![OpenC2](/images/logos-external/openc2.svg)](/flux/guides/monitoring/) -{{% /card %}} - -{{% card header="[HTTP - Native capability](https://openc2.org/)" %}} -[![Http](/images/logos-external/http.svg)](/flux/guides/monitoring/) -{{% /card %}} -{{< /cardpane >}} -
- - -## 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 %}} diff --git a/documentation/content/en/docs/core-components/modules.md b/documentation/content/en/docs/core-components/modules.md deleted file mode 100644 index fd9d0fa4..00000000 --- a/documentation/content/en/docs/core-components/modules.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: SOARCA Executer Modules -weight: 6 -categories: [architecture] -tags: [components] -description: > - SOARCA is extendable by modules. Modules allow for new steps in playbook and added capability. ---- - -## Requirements -Modules should be build in GO or Python and contain the following components. - -. CACAO template to allow their capability to extend coarse of actions playbooks. -. MQTT protocol implementation to communicate with the SOARCA executor. -. Module specifies which `variables` it exposes for return types. These `variables` should be defined when submitting a module. - - -## Native modules in SOARCA -The following capability modules are defined in SOARCA: - -- SSH -- HTTP-API -- OPEN-C2 - -All modules have an well known GUID for there target definition. SOARCA will also extent the `agent-target-type-ov` with the following vocab for `ssh`, `http-api` and `openc2` respectively. - -- soarca--00010001-1000-1000-a000-000100010001 -- soarca--00020001-1000-1000-a000-000100010001 -- soarca--00030001-1000-1000-a000-000100010001 - -The capability will be selected on the capability name and it must be unique. - - -### SSH capability -Well know guid: `soarca--00010001-1000-1000-a000-000100010001` - -This module is defined in a playbook with the following TargetAgent definition: - -```json -"agent_definitons": { - "soarca--00010001-1000-1000-a000-000100010001": { - "type": "soarca", - "name": "soarca-ssh-capability" - } - }, -``` - -This modules does not define variables as input. I will have the following output variables: - -```json -{ - "__soarca_ssh_result__": { - Type: "string", - Name: "result", - Value: "" - } -} -``` - -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 -Well know guid: `soarca--00020001-1000-1000-a000-000100010001` - -This module is defined in a playbook with the following TargetAgent definition: - -```json -"agent_definitons": { - "soarca--00020001-1000-1000-a000-000100010001": { - "type": "soarca", - "name": "soarca-http-api-capability" - }, - }, -``` - -```json -{ - "__soarca_http_result__": { - Type: "string", - Name: "result", - Value: "" - } -} -``` - -## OPEN-C2 capabilty -Well know guid: `soarca--00030001-1000-1000-a000-000100010001` - -This module is defined in a playbook with the following TargetAgent definition: - -```json -"agent_definitons": { - "soarca--00030001-1000-1000-a000-000100010001": { - "type": "soarca", - "name": "soarca-open-c2-capability" - }, - }, -``` - ---- - -## MQTT fin module -This module is used by SOARCA to communicate with fins (capabilities) see [fin documentation](/docs/soarca-extentions/) for more information diff --git a/documentation/content/en/docs/soarca-api/_index.md b/documentation/content/en/docs/soarca-api/_index.md deleted file mode 100644 index ee2dd7eb..00000000 --- a/documentation/content/en/docs/soarca-api/_index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: SOARCA REST API -description: > - This document describes the SOARCA Rest API of the various endpoint that can be called. -categories: [API] -tags: [protocol, http, rest, api, swagger] -weight: 4 -type: swagger -date: 2023-01-05 ---- - -{{< swaggerui src="openapi/swagger.json" >}} \ No newline at end of file diff --git a/documentation/content/en/docs/soarca-extentions/_index.md b/documentation/content/en/docs/soarca-extentions/_index.md deleted file mode 100644 index 2dd7bf22..00000000 --- a/documentation/content/en/docs/soarca-extentions/_index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: SOARCA Extensions -description: > - Extending SOARCA is done by developing a SOARCA-Fin. -categories: [extensions, architecture] -tags: [fin] -weight: 5 -date: 2023-01-05 ---- - -The native capabilities support by the SOARCA core can be extended through a mechanism known as FINS. Whether you’re working directly with our system or utilizing a third-party library, the key lies in implementing the Fin protocol. This protocol provides for communication between the SOARCA core and the extension capabilities via an MQTT-bus. - -The choice of MQTT as the communication protocol allows for seamless integration with libraries written in various programming languages while maintaining a relatively straightforward approach. - -## SOARCA Python Fin library - -As part of the SOARCA suite there is currently an library that implement the Fin protocol and which can be used within your project. - -## Loading your module -Once you have developed your module you need to load it so SOARCA can use it for the playbooks it executes. You can load your modules in two ways via docker or stand alone. - -### Docker -The Docker engine allows for easy loading but requires you to package your capability into a docker container. Once that is done you can add your container to a docker compose file and it will register itself to SOARCA once started. The Fin MUST be loaded after SOARCA's main components otherwise the Fin might not work correctly. - -### Stand alone -SOARCA can be used without Docker. To use it whit your module you need to start it and have an MQTT broker running already before starting your Fin. *The method is for more complex setups and not recommended for first use.* - -First set up SOARCA [stand alone](setup.md). - - -## Protocol - -The underlying protocol for the SOARCA fins can be [here](/docs/soarca-extentions/fin-protocol). - diff --git a/documentation/content/en/docs/soarca-extentions/fin-protocol.md b/documentation/content/en/docs/soarca-extentions/fin-protocol.md deleted file mode 100644 index 5f9aff65..00000000 --- a/documentation/content/en/docs/soarca-extentions/fin-protocol.md +++ /dev/null @@ -1,585 +0,0 @@ ---- -title: Fin protocol documentation -description: > - The SOARCA Fin protocol -categories: [extensions, architecture] -tags: [fin] -weight: 2 -date: 2023-01-05 ---- - -## Goals -The goal of the protocol is to provide a simple and robust way to communicate between the SOARCA orchestrator and the capabilities (Fins) that can provide extra functions. - -## MQTT -To allow for dynamic communication MQTT is used to provide the backbone for the fin communication. SOARCA can be configured using the environment to use MQTT or just run stand alone. - -The Fin will use the protocol to register itself to SOARCA via the register message. Once register it will communicate over the channel new channel designated by the capability UUID. - -## Messages -Messages defined in the protocol - -- `ack` -- `nack` -- `register` -- `unregister` -- `command` -- `pause` -- `resume` -- `stop` - -### legend - -|field |content |type |description -|field name have the `(optional)` key if the field is not required |content indication |type of the value could be string, int etc. |A description for the field to provide extra information and context - - - -### ack -The ack message is used to acknowledge messages. - - -|field | content | type | description | -| ---- | ------- | ---- | ----------- | -|type |ack |string |The ack message type -|message_id |UUID |string |message id that the ack is referring to - - -```plantuml -@startjson -{ - "type": "ack", - "message_id": "uuid" -} -@endjson -``` - -### nack -The nack message is used to non acknowledgements, message was unimplemented or unsuccessful. - - -|field | content | type | description | -| ---- | ------- | ---- | ----------- | -|type |nack |string |The ack message type -|message_id |UUID |string |message id that the nack is referring to - - -```plantuml -@startjson -{ - "type": "nack", - "message_id": "uuid" -} -@endjson -``` - - - - -### register -The message is used to register a fin to SOARCA. It has the following payload. - - -|field |content |type | description | -| ----------------- | --------------------- | ----------------- | ----------- | -|type |register |string |The register message type -|message_id |UUID |string |Message UUID -|fin_id |UUID |string |Fin uuid of the separate form the capability -|protocol_version |version |string |Version information of the protocol in [semantic version](https://semver.org) schema e.g. 1.2.4-beta -|security |security information |<> |ecurity information for protocol see security structure -|capabilities |list of capability structure |list of <> |Capability structure information for protocol see security structure -|meta |meta dict |<> |Meta information for the fin protocol structure - - - - -#### capability structure - -|field |content |type | description | -| ----------------- | ------------- | ------ | ----------- | -|capability_id |UUID |string |Capability id to identify the unique capability a fin can have multiple -|type |action | [workflow-step-type-enum](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256479) | Most common is action -|name |name |string |message id -|version |version |string |Version information of the Fin implementation used in [semantic version](https://semver.org) schema e.g. 1.2.4-beta -|step |step structure |<> |Step to specify an example for the step so it can be queried in the SOARCA API -|agent |agent structure|<> |Agent to specify the agent definition to match in playbooks for SOARCA - - -#### step structure -|field |content | type | description | -| ----------------- | ------------- | ----------------- | ----------- | -|type |action |string |Action type -|name |name |string |message id -|description |description |string |Description of the step -|external_references| |[external reference](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256542) |References to external recourses to further enhance the step also see CACAO V2 10.9. -|command |command |string |Command to execute -|target |UUID |string |Target UUID cto execute command against - - -#### agent structure - -|field |content | type | description | -| ----------------- | ------------- | ----------------- | ----------- | -|type |soarca-fin |string |SOARCA Fin type, a custom type used to specify Fins -|name |name |string |SOARCA Fin name in the following form: soarca-fin--, this grantees the fin is unique - -```plantuml -@startjson -{ - "type": "register", - "message_id": "uuid", - "fin_id" : "uuid", - "protocol_version": "", - "security": { - "version": "0.0.0", - "channel_security": "plaintext" - }, - "capabilities": [ - { - "capability_id": "uuid", - "name": "ssh executer", - "version": "0.1.0", - "step": { - "type": "action", - "name": "", - "description": "", - "external_references": { - "name": "", - "...": "..." - }, - "command": "", - "target": "" - }, - "agent" : { - "soarca-fin--": { - "type": "soarca-fin", - "name": "soarca-fin---" - } - } - - } - ], - "meta": { - - "timestamp": "string: ", - "sender_id": "uuid" - } -} -@endjson -``` - - - - -### unregister -The message is used to unregister a fin to SOARCA. It has the following payload. - -|field |content |type | description | -| ----------------- | ------------- | ------ | ----------- | -|type |unregister |string |Unregister message type -|message_id |UUID |string |Message UUID -|capability_id |UUID |string |Capability id or null (either capability_id != null, fin_id != null or all == true need to be set) -|fin_id |UUID |string |Fin id or null (either capability_id != null, fin_id != null or all == true need to be set) -|all |bool |bool |True to address all fins to unregister otherwise false (either capability_id != null, fin_id != null or all == true need to be set) - -```plantuml -@startjson -{ - "type": "unregister", - "message_id": "uuid", - "capability_id" : "capability uuid", - "fin_id" : "fin uuid", - "all" : "true | false" -} -@endjson -``` - -### command -The message is used to send a command from SOARCA. It has the following payload. - -|field |content |type | description | -| ----------------- | ------------- | ------ | ----------- | -|type |unregister |string |Unregister message type -|message_id |UUID |string |Message UUID -[Authentication information] |Additional authentication information the field is optional -|command |command |<> |command structure -|meta |meta dict |<> |Meta information for the fin protocol structure -|=== - -#### command substructure -|field |content |type | description | -| ----------------- | ------------- | ------ | ----------- | -|command |command |string |The command to be executed -|authentication `(optional)` |authentication information | [authentication information](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256503) | CACAO authentication information -|context |cacao context |<> | Context form the playbook -|variables |dict of variables |dict of <> | From the playbook - - -```plantuml -@startjson -{ - "type": "command", - "message_id": "uuid", - "command": { - "command": "command", - "authentication": {"auth-uuid": "", - "timeout": "string: ", - "step_id": "uuid", - "playbook_id": "uuid", - "execution_id": "uuid" - }, - "variables": { - "____": { - "type": "", - "description": "", - "value": "", - "constant": "", - "external": "" - }, - "____": { - "type": "", - "description": "", - "value": "", - "constant": "", - "external": "" - } - } - }, - "meta": { - "timestamp": "string: ", - "sender_id": "uuid" - } -} -@endjson -``` - -### result -The message is used to send response from the Fin to SOARCA. It has the following payload. - -|field |content |type | description | -| ----------------- | ------------- | ------ | ----------- | -|type |result |string |Unregister message type -|message_id |UUID |string |Message UUID -|result |result structure |<> | The result of the execution -|return |dict of variables |<> |command structure - - -#### result structure -|context |cacao context |<> | Context form the playbook - -|field |content |type | description | -| ----------------- | ------------- | ------ | ----------- | -|type |result |string |Unregister message type -|result |result structure |<> | The result of the execution - -|return |dict of variables |<> |command structure - - -```plantuml -@startjson -{ - "type": "result", - "message_id": "uuid", - "result": { - "state": "enum(success | failure)", - "context": { - "generated_on": "string: ", - "timeout": "string: ", - "step_id": "uuid", - "playbook_id": "uuid", - "execution_id": "uuid" - }, - "return": { - "____": { - "type": "", - "description": "", - "value": "", - "constant": "", - "external": "" - }, - "____": { - "type": "", - "description": "", - "value": "", - "constant": "", - "external": "" - } - } - }, - "meta": { - "timestamp": "string: ", - "sender_id": "uuid" - } -} -@endjson -``` - - - -### control -|field |content |type | description | -| ----------------- | ------------- | ------ | ----------- | -|type |pause or resume or stop or progress |string |Message type -|message_id |UUID |string |message uuid -|capability_id |UUID |string |Capability uuid to control - -#### pause -The message is used to halt the further execution of the Fin. Following command will be responded to with nack, unless it is resume or stop. - -```plantuml -@startjson -{ - "type": "pause", - "message_id" : "uuid", - "capability_id": "uuid" -} -@endjson -``` - - -#### resume -The message is used to resume a paused Fin, the response will be ack if ok or nack when the Fin could not be resumed. - -```plantuml -@startjson -{ - "type": "resume", - "message_id" : "uuid", - "capability_id": "uuid" -} -@endjson -``` - -#### stop -The message is used to shutdown the Fin. this will be responded to by ack, after that there will follow an unregister. - -```plantuml -@startjson -{ - "type": "stop", - "message_id" : "uuid", - "capability_id": "uuid" -} -@endjson -``` - -#### progress -Ask for the progress of the execution of the -```plantuml -@startjson -{ - "type": "progress", - "message_id" : "uuid", - "capability_id": "uuid" -} -@endjson -``` - -### Status response -|field |content |type | description | -| ----------------- | ------------- | ------ | ----------- | -|type |status |string |Message type -|message_id |UUID |string |message uuid -|capability_id |UUID |string |Capability uuid to control -|progress |ready, working, paused, stopped |string |Progress of the execution or state it's in. - -Report the progress of the execution of the capability - -```plantuml -@startjson -{ - "type": "status", - "message_id" : "uuid", - "capability_id": "uuid", - "progress": "" -} -@endjson -``` - -### Common -These contain command parts that are used in different messages. - -#### Security -|field |content |type | description | -| ----------------- | ------------- | ------ | ----------- | -|version |version |string |Version information of the protocol in [semantic version](https://semver.org) schema e.g. 1.2.4-beta -|channel_security |plaintext |string |Security mechanism used for encrypting the channel and topic, plaintext is only supported at this time - - -```plantuml -@startjson -{ - "security": { - "version": "0.0.0", - "channel_security": "plaintext" - } -} -``` - -#### Variables -Variables information structure - -|field |content |type | description | -| ----------------- | ------------- | ------ | ----------- | -|type |variable type |[variable-type-ov](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256556) | The cacao variable type see CACAO V2 chapter 10.18, 10.18.4 Variable Type Vocabulary -|description |description |string |Description of the step -|value |value |string |Value of the variable -|constant |true or false |bool |whether it is constant -|external |true or false |bool |whether it is external to the playbook - - -```plantuml -@startjson -{ - "____": { - "type": "", - "description": "", - "value": "", - "constant": "", - "external": "" - } -} -@endjson -``` - -#### Context -CACAO playbook context information structure - -|field |content |type | description | -| ----------------- | ------------- | ------ | ----------- | -|completed_on `(optional)` |timestamp |string | -|generated_on `(optional)` |timestamp |string | -|timeout `(optional)` |duration |string | -|step_id |UUID |string |Step uuid that is referred to -|playbook_id |UUID |string |Playbook uuid that is referred to -|execution_id |UUID |string |SOARCA execution uuid - -```plantuml -@startjson -{ - "context": { - "completed_on": "string: ", - "generated_on": "string: ", - "timeout": "string: ", - "step_id": "uuid", - "playbook_id": "uuid", - "execution_id": "uuid" - } -} -@endjson -``` - -#### Meta -Meta information for the fin protocol structure - -|field |content |type | description | -| ----------------- | ------------- | ------ | ----------- | -|timestamp |timestamp |string | -|sender_id |UUID |string |Step uuid that is referred to - - -```plantuml -@startjson -{ - "meta": { - "timestamp": "string: ", - "sender_id": "uuid" - } -} -@endjson -``` - -## Sequences - -### Registering a capability - -```plantuml -@startuml - -participant "SOARCA" as soarca -participant Capability as fin - -soarca -> soarca : create [soarca] topic - -fin -> fin : create [UUID] topic -soarca <- fin : [soarca] register -soarca --> fin : [UUID] ack - -@enduml -``` - -### Sending command - -```plantuml -@startuml - -participant "SOARCA" as soarca -participant Capability as fin - -soarca -> fin : [UUID] command -soarca <-- fin : [UUID] ack - -.... processing .... - -soarca <- fin : [UUID] result -soarca --> fin: ack - -@enduml -``` - -### Unregistering a capability - - -```plantuml -@startuml - -participant "SOARCA" as soarca -participant Capability as fin -participant "Second capability" as fin2 - -... SOARCA initiate unregistering one fin ... - -soarca -> fin : [SOARCA] unregister fin-id -soarca <-- fin : [SOARCA] ack -note right fin2 - This capability does not respond to this message -end note - -... Fin initiate unregistering ... - -soarca <- fin : [SOARCA] unregister fin-id -soarca --> fin : [SOARCA] ack -note right fin2 - This capability does not respond to this message -end note - -... SOARCA unregister all ... - -soarca -> fin : [SOARCA] unregister all == true -soarca <-- fin : [SOARCA] ack -soarca <-- fin2 : [SOARCA] ack -note over soarca, fin2 - soarca will go down after this command -end note -@enduml -``` - -### Control - -```plantuml -@startuml - -participant "SOARCA" as soarca -participant Capability as fin - - -soarca -> fin : [UUID] control message -soarca <-- fin : [UUID] status - -@enduml -``` - - -