diff --git a/.gitignore b/.gitignore index fd4efa1f..85c0365d 100644 --- a/.gitignore +++ b/.gitignore @@ -15,9 +15,10 @@ test/cacao/flatfile-db-example.json test/routes/__debug_bin2988553005 -documentation/public -documentation/resources/ -documentation/node_modules/ -documentation/package-lock.json -documentation/.hugo_build.lock -**.hugo_build.lock \ No newline at end of file +docs/public +docs/resources/ +docs/node_modules/ +docs/package-lock.json +docs/.hugo_build.lock +**.hugo_build.lock + diff --git a/README.md b/README.md index 97f2ca0b..7d58d639 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,10 @@ Security Orchestrator for Advanced Response to Cyber Attacks SOARCA the TNO orchestrator for Open-C2, CACAO and STIX -## building / starting / stopping +## Building / starting / stopping Install go via https://go.dev/doc/install -Install go plugin in VSCode +Install the go plugin in VSCode project layout https://github.com/golang-standards/project-layout @@ -21,7 +21,7 @@ make run ## Documentation -For documentation we use Markdown + [plantUML](https://plantuml.com/). +For documentation, we use Markdown + [plantUML](https://plantuml.com/). Documentation will be stored in the [doc](doc/) folder. @@ -31,7 +31,7 @@ To get started with plantUML in Markdown please install the following components Markdown Kroki VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=pomdtr.markdown-kroki -Once you installed them please enable Kroki in the settings, and add the following to use a non public Kroki server: +Once you installed them please enable Kroki in the settings, and add the following to use a non-public Kroki server: diff --git a/docs/content/en/blog/_index.md b/docs/content/en/blog/_index.md index 95ccb91d..5f875d2b 100644 --- a/docs/content/en/blog/_index.md +++ b/docs/content/en/blog/_index.md @@ -3,6 +3,4 @@ title: Blog menu: {main: {weight: 30}} --- -This is the **blog** section. It has two categories: News and Releases. -Files in these directories will be listed in reverse chronological order. diff --git a/docs/content/en/blog/news/first-post/index.md b/docs/content/en/blog/news/first-post/index.md index 37e8be5a..4dcaf6ee 100644 --- a/docs/content/en/blog/news/first-post/index.md +++ b/docs/content/en/blog/news/first-post/index.md @@ -4,7 +4,7 @@ title: SOARCA First release linkTitle: Announcing SOARCA description: > -author: Maarten de Kruijf, and Jan-Paul Konijn +author: authors resources: - src: "**.{png,jpg}" title: "Image #:counter" @@ -12,36 +12,4 @@ resources: byline: "Photo: any / CC-BY-CA" --- -**This is a typical blog post that includes images.** - -The front matter specifies the date of the blog post, its title, a short description that will be displayed on the blog landing page, and its author. - -## Including images - -Here's an image (`featured-sunset-get.png`) that includes a byline and a caption. - -{{< imgproc sunset Fill "600x300" >}} -Fetch and scale an image in the upcoming Hugo 0.43. -{{< /imgproc >}} - -The front matter of this post specifies properties to be assigned to all image resources: - -``` -resources: -- src: "**.{png,jpg}" - title: "Image #:counter" - params: - byline: "Photo: Riona MacNamara / CC-BY-CA" -``` - -To include the image in a page, specify its details like this: - -``` -{{< imgproc sunset Fill "600x300" >}} -Fetch and scale an image in the upcoming Hugo 0.43. -{{< /imgproc >}} -``` - -The image will be rendered at the size and byline specified in the front matter. - diff --git a/docs/content/en/blog/releases/in-depth-monoliths-detailed-spec.md b/docs/content/en/blog/releases/in-depth-monoliths-detailed-spec.md index 2fe5ff33..bfef0cdc 100644 --- a/docs/content/en/blog/releases/in-depth-monoliths-detailed-spec.md +++ b/docs/content/en/blog/releases/in-depth-monoliths-detailed-spec.md @@ -2,6 +2,5 @@ title: SOARCA V1.0 date: 2023-01-04 description: > - A short lead description about this content page. Text here can also be - **bold** or _italic_ and can even be split over multiple paragraphs. + --- diff --git a/docs/content/en/docs/FAQ.md b/docs/content/en/docs/FAQ.md index 4ff63de6..e5807dc0 100644 --- a/docs/content/en/docs/FAQ.md +++ b/docs/content/en/docs/FAQ.md @@ -9,5 +9,5 @@ weight: 21 ### Does SOARCA have a GUI? -SOARCA currently does not feature a GUI for tracking the progress on playbook execution. Too edit [CACAO v2.0](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/security-playbooks-v2.0.html) playbooks, consider using the [CACAO Roaster](https://github.com/opencybersecurityalliance/cacao-roaster) project. +SOARCA currently does not feature a GUI for tracking the progress of playbook execution. To edit [CACAO v2.0](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/security-playbooks-v2.0.html) playbooks, consider using the [CACAO Roaster](https://github.com/opencybersecurityalliance/cacao-roaster) project. diff --git a/docs/content/en/docs/_index.md b/docs/content/en/docs/_index.md index 8122644f..6a361fcf 100644 --- a/docs/content/en/docs/_index.md +++ b/docs/content/en/docs/_index.md @@ -7,18 +7,16 @@ 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]. +SOARCA is currently in its **alpha release**, with ongoing development 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, 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. It is the first open-source 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 enables cyber defenders to coordinate and automate their cyber operations, by using executable CACAO playbooks, and aims to achieve the following goals: -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. +- **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 interoperability 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. @@ -33,15 +31,15 @@ SOARCA currently supports the following transport mechanisms:
{{< cardpane >}} {{% card header="OpenC2 - Native" %}} -[![OpenC2](/SOARCA/images/logos-external/openc2.svg)](/docs/soarca-extentions/native-capabilities/#openc2-capability) +[![OpenC2](/SOARCA/images/logos-external/openc2.svg)](/docs/soarca-extensions/native-capabilities/#openc2-capability) {{% /card %}} {{% card header="HTTP - Native" %}} -[![Http](/SOARCA/images/logos-external/http.svg)](/docs/soarca-extentions/native-capabilities/#http-api-capability) +[![Http](/SOARCA/images/logos-external/http.svg)](/docs/soarca-extensions/native-capabilities/#http-api-capability) {{% /card %}} {{% card header="SSH - Native" %}} -[![Ssh](/SOARCA/images/logos-external/ssh.svg)](/docs/soarca-extentions/native-capabilities/#ssh-capability) +[![Ssh](/SOARCA/images/logos-external/ssh.svg)](/docs/soarca-extensions/native-capabilities/#ssh-capability) {{% /card %}} {{< /cardpane >}}
@@ -54,5 +52,5 @@ SOARCA currently supports the following transport mechanisms: ## Where do I start? {{% alert title="Follow our getting started!" 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 +Following our [Getting started](/docs/getting-started/) guide will help you set up SOARCA and configure the SOAR for your internal security tooling. For more custom requirement {{% /alert %}} diff --git a/docs/content/en/docs/about/_index.md b/docs/content/en/docs/about/_index.md index 99d121ec..19eabf19 100644 --- a/docs/content/en/docs/about/_index.md +++ b/docs/content/en/docs/about/_index.md @@ -6,15 +6,32 @@ description: ## About COSSAS -SOARCA finds its home within the Community for Open Source Security Automation Software (COSSAS). [COSSAS](https://cossas-project.org/') offers a continuously expanding base of novel software components for cyber security automation that SOC, CERT and CTI professionals can deploy and trial in their own operational environments. COSSAS is an initiative of the TNO. +SOARCA finds its home within the Community for Open Source Security Automation Software (COSSAS). [COSSAS](https://cossas-project.org/') offers a continuously expanding base of novel software components for cyber security automation that SOC, CERT and CTI professionals can deploy and trial in their operational environments. COSSAS is an initiative of TNO. ## About TNO -SOARCA is an project initiated and support by [TNO](https://tno.nl), the Netherlands Organisation for Applied Scientific Research. TNO, an independent research, development, and consultancy organization in the Netherlands, is dedicated to driving innovation for a safer, healthier, and more sustainable life. TNO focuses on areas such as sustainability, health, safety, and digital transformation. The mission is to make knowledge serve the common good, connecting expertise to create impactful innovations. TNO actively engages with society, aiming for positive impact through its work and insights. Learn more about TNO on their official website . +SOARCA is a project initiated and supported by [TNO](https://tno.nl), the Netherlands Organisation for Applied Scientific Research. TNO, an independent research, development, and consultancy organization in the Netherlands, is dedicated to driving innovation for a safer, healthier, and more sustainable life. TNO focuses on areas such as sustainability, health, safety, and digital transformation. Its mission is to make knowledge serve the common good, connecting expertise to create impactful innovations. TNO actively engages with society, aiming for a positive impact through its work and insights. Learn more about TNO on their official [website](https://tno.nl). -## Developers +## Core Team +- Maarten de Kruijf (TNO) +- Jan-Paul Konijn (TNO) +- Hidde-Jan Jongsma (TNO) +- Luca Morgese (TNO) +- Richard Kerkdijk (TNO) +- Frank Fransen (TNO) +- Shari Finner (TNO) +## Special Thanks -## Special Thanks \ No newline at end of file +A special thanks to: + +- Sebastiaan Huskins for laying the initial and technical foundation for SOARCA. +- Myla Fransen for the logo designs. + +## About SOARCA + +This work has received funding from the European Union’s Horizon Europe Energy Research and Innovation programme under Grant Agreement No. 101075665 ([eFORT](https://efort-project.eu/) project) and the European Defence Fund (EDF) under Grant Agreement No. 101103385 ([AInception](https://www.ainception.eu/) project). Views and opinions expressed in this documentation are those of the authors only and do not necessarily reflect those of the European Union. Neither the European Union nor the granting authority can be held responsible for them. + +![eu-funded](/SOARCA/images/eu-funded-logo.png) diff --git a/docs/content/en/docs/concepts/_index.md b/docs/content/en/docs/concepts/_index.md index 16adc896..20d8f300 100644 --- a/docs/content/en/docs/concepts/_index.md +++ b/docs/content/en/docs/concepts/_index.md @@ -9,55 +9,33 @@ resources: byline: "*Slide*: © 2024 TNO" --- -## Background of SOARCA +## Context and Background **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 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 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/). +Organisations are increasingly automating threat and incident response through playbook driven security workflow orchestration. The essence of this concept is that specific security events trigger a predefined series of response actions that are executed with no or only limited human intervention. These automated workflows are captured in machine-readable security playbooks, which are typically executed by a so called Security Orchestration, Automation and Response (SOAR) tool. The market for SOAR solutions has matured significantly over the past years and present day products support sophisticated automation workflows and a wide array of integrations with external security tools and data resources. Typically, however, the technology employed is proprietary and not easily adaptable for research and experimentation purposes. SOARCA aims to offer an open-source alternative for such solutions that is free of vendor dependencies and supports standardized formats and technologies where applicable. -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. ​ +SOARCA, TNO’s open-source SOAR, was developed for research and innovation purposes and allows SOC, CERT and CTI professionals to experiment with the concept of playbook driven security automation. It is open and extensible and its interfaces are well-defined and elaborately documented. It also offers native support for two emerging technology standards, both developed and maintained by OASIS Open: -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. +- [CACAOv2](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/security-playbooks-v2.0.html). The Collaborative Automated Course of Action Operations (CACAO) standard provides a common framework and machine-processable schema for security playbooks that are natively interoperable and can be shared and executed across technological and organizational boundaries. +- [OpenC2](https://openc2.org/). A standardized language for the command and control of cyber defense technologies. In essence it provides a vendor agnostic language and interface through which so called security actuators (e.g. firewalls or IAM solutions) can be reconfigured automatically. +SOARCA is available through [TNO’s](https://www.tno.nl/nl/) community platform [COSSAS](https://cossas-project.org/) (Community for Open Source Security Automation Software) under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0). With its release, TNO aims to drive both the adoption and further development of novel technologies for cyber security automation forward. Here we note that open and accessible SOAR functionality is not only relevant for automation in threat and incident response but also for attack & defense simulations, cyber ranges, digital twinning and other emerging innovations that require orchestration of complex (security oriented) workflows. +--- {{% imgproc Slide2 Fill "1280x720" %}} {{% /imgproc %}} -## Vision of SOARCA - -### Why Soarca? - -Both inside and outside of TNO there is a strong need for interoperable workflow orchestration tooling that aids (cybersecurity) innovation. High-quality SOAR (Security Orchestration, Automation and Response) tools are widely available in the market, however these are commercial products with significant license costs and that employ proprietary technologies rather than the emerging innovative standards. - - -- **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**: 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. - ### Current state of SOARCA At present, SOARCA is in an Alpha release phase and is intended for Proof of Concepts (PoCs) and research purposes, serving as a platform for demonstrations. The objective of the SOARCA team is to evolve SOARCA into a more mature SOAR orchestration tool suitable for operational environments. For potential applications of SOARCA, please refer to the ‘Use-Cases’ section of our documentation. -### 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, ...) -- Open-source software provides a low barrier for partner organisations to collaborate and contribute. -- Open Source software and tooling can easily be brought in as background into projects and partnerships such as HEU, EDF, or National funded projects and others. The use of open-source tooling is explicitly encouraged by the European Commission. - - ## Core Concepts +Several concepts within SOARCA might be important to know. -There are several concepts within SOARCA that might be important to know. - -### Coarse of Action +### Course of Action 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. @@ -67,23 +45,25 @@ The [CACAO Security Playbooks Version 2.0 specification](https://docs.oasis-open 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: +Examples of repetitive tasks that might be automated using a CACAO Playbook might be: - Investigate the cause of security events. - Mitigate threats effectively. - Remediate vulnerabilities. -By following CACAO playbooks specification, organizations can enhance their automated response capabilities, foster collaboration, and ensure consistentcy of playbooks across diverse technological solutions. +By following CACAO playbook specifications, organizations can enhance their automated response capabilities, foster collaboration, and ensure consistency of playbooks across diverse technological solutions. + +More information can be found in our [primer on playbooks](/docs/concepts/executable-playbooks). ### 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. +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 a pre-defined MQTT protocol. ## Join the SOARCA Community -The SOARCA team invites cybersecurity professionals, researchers, and enthusiasts to join our community. Explore, adapt, and contribute to SOARCA’s growth. Let’s fortify cyber defenses together! See our [contribution guidelines](/contribution-guidelines/) on how to make contributions. 🛡️🌐 +The SOARCA team invites cybersecurity professionals, researchers, and enthusiasts to join our community. Explore, adapt, and contribute to SOARCA’s growth. Let’s fortify cyber defenses together! See our [contribution guidelines](/docs/contribution-guidelines/) on how to make contributions. 🛡️🌐 ## Key Details - Project Name: SOARCA (Security Orchestrator for Advanced Response to Cyber Attacks) diff --git a/docs/content/en/docs/concepts/executable-playbooks.md b/docs/content/en/docs/concepts/executable-playbooks.md new file mode 100644 index 00000000..8116430e --- /dev/null +++ b/docs/content/en/docs/concepts/executable-playbooks.md @@ -0,0 +1,393 @@ +--- +title: Executable playbooks +weight: 3 +description: > + A playbook primer +resources: +- src: "*Slide.png" + params: + byline: "*Slide*: © 2024 TNO" +--- + +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. +{{% /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. + +SOARCA is a _security orchestrator_ that reads the steps defined in a CACAO playbook and performs the necessary actions to execute the commands they contain. This makes a CACAO document an _executable playbook_. + +SOARCA's development is ongoing, and at this time, it only partly supports the entire CACAO specification. On this page we'll go over the general concepts in a CACAO playbooks and the parts of the standard that are supported by SOARCA. + +## A CACAO playbook + +Here, we have an example of a relatively simple CACAO playbook that demonstrates [SOARCA's capabilities](/docs/soarca-extensions). The flow of steps is depicted in the following image: + +![Example playbook flow](/SOARCA/images/example-playbook.svg) + +The JSON of this CACAO playbook can be found [at the bottom of this page](#example-playbook). + +As you can see, this playbook contains a mix of logical steps (`if-condition` and `while-condition`) and `action` steps that perform commands on a target system. + +### Agents and targets + +In CACAO playbooks, entities that execute commands are called agents, and the entities against which the commands are executed are called targets (see [Agents and Targets](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256509) in the spec). + +Every action step in a CACAO playbook must have a single agent, and one or more targets. Both agents and targets are defined on the playbook level, in the `agent_definitions` and `target_definitions` properties. SOARCA will execute action steps that have an agent of the type `soarca`. The capability that will be selected to execute the step is determined by the `name` property of the agent. For more information, [read the documentation on components](/docs/core-components/modules). + +```json +"target_definitions": { + "linux--b49069c2-0b69-4a46-8509-80196c4a9bf8": { + "type": "linux", + "name": "Target system", + "description": "System to execute commands on", + "address": { + "ipv4": [ + "__target_ip__:value" + ] + } + } +} +``` + +### Start and end steps + +Every CACAO playbook should start with a `start` step. From there, each step can define which step should be executed after the current step finishes. Depending on whether the current step has executed successfully, the next step is defined by the `on_completion` property. A non-successful step execution may instead trigger the `workflow_exception` step, specified in the playbook properties. Alternatively to `on_completion`, a step can specify `on_success` and `on_failure`, which allow a finer-grain control over the execution flow. + +What constitutes a successful step execution and what is a failure depends on the specific capability executing the step. + +Example of a `start` step: + +```json +"start--d6c44626-c9b6-426b-ad5d-3311bafaf068": { + "on_completion": "action--4b08af84-3741-48ca-8c92-df1557a87379", + "type": "start" +} +``` + +According to the CACAO specification, every branch of steps should end in a (unique) `end` step. This is the only step type may not specify a next step: + +```json +"end--60fc8d0c-3677-4363-8576-9ea9014f8c8e": { + "type": "end" +} +``` + +### If-condition, while-condition, and parallel steps + +An `if-condition` step allows executing different branches depending on a specified condition. The step must specify an `on_true` property, which references the start of a branch of steps that should be executed if the condition evaluates to true. Optionally, the `if-condition` step can define an `on_false` property that defines an alternative branch that is executed if the condition evaluates to false. In each case, the specified branch keeps executing until it encounters an `end` step. + +The `condition` property contains a string that specifies a [STIX Pattern](https://docs.oasis-open.org/cti/stix/v2.0/stix-v2.0-part5-stix-patterning.html). Currently, SOARCA only supports a very small subsection of the STIX Patterning specification. We support string based equality (`'a' = 'a'`) and inequality (`'a' != 'b'`) comparison. Example: + +```json +"if-condition--4b95eaa4-944a-4a9d-88d4-1374a70dbacd": { + "name": "If it is not new years", + "description": "Checks if it is 01-01-2025", + "on_completion": "end--db937fc8-3a42-41cc-b828-ec2db212f425", + "type": "if-condition", + "condition": "__soarca_ssh_result__:value != '01-01-2025'", + "on_true": "action--7fe08053-3685-4d8c-bc0a-40efce75113e" +} +``` + +SOARCA supports variable interpolation, which means that variables can be used inside the `condition` property, as seen in the example above. + +Similarly, CACAO specifies `while-condition` steps, whose `on_true` branch will be repeatedly executed until the condition evaluates to false. + +The `parallel` step allows executing multiple branches (in parallel) specified in the `next_steps` property. At this time, the steps in `next_steps` are executed sequentially. Parallel execution is scheduled for a later release in SOARCA. + +Next, we explain variables in CACAO and SOARCA. + +### Variables + +The CACAO specification allows defining variables on the playbook level, as well as on the step level. Playbook variables are available throughout the playbook. In SOARCA, variables defined on the step level are available in that step, and in any step that executes in a sub-branch of an `if-condition`, `while-condition`, or `parallel` step. + +According to the CACAO spec, variable names should start and end with double underscores (`__`). The CACAO spec allows defining multiple types of variables (strings, ip-addresses, numbers), but at this time SOARCA will interpret every value as a string. The `constant` and `external` properties are ignored. + +```json +"playbook_variables": { + "__target_ip__": { + "type": "ipv4-addr", + "description": "IP address of target system", + "constant": false, + "external": true + } +} +``` + +SOARCA supports the interpolation of variables in different strings. The specific string-based properties that support interpolation depend on the capability. In general, string interpolation is supported in the properties of agents, targets, authentication information, and `command` properties. + +Variable interpolation happens at the last possible moment, which means that step-dependant variables can be used in agent and target definitions. + +Substitution is performed by replacing any occurrence of `[variable_name]:value` with the string `value` of that variable. Undefined variables are not replaced. + +### Action steps + +Within CACAO playbooks, `action` steps can define commands that are executed by an _agent_ against one or more _targets_. The agent and targets are referenced by ID. SOARCA selects the internal capability for handling the step by looking at the `type` and `name` of the agent. After selecting the proper capability, SOARCA will sequentially perform every command in the `commands` property for every target specified in `targets`. If any command fails to execute successfully, further execution is halted and the step is considered to have failed. + +Action steps may return variables. On the successful execution of an action step, any variables returned are added to the globally available playbook variables. If the `out_args` property is specified and non-empty, only the variables listed in `out_args` will be added to the global playbook variables. The `in_args` property from the CACAO spec is ignored. Any variable defined on the playbook level, in parent-steps and within the step itself are available for interpolation. + +In the case an action step ends in a failure, any variables returned from the step are ignored. + +The example below shows how to run an `ssh` command on a single target system: + +```json +"action--4b08af84-3741-48ca-8c92-df1557a87379": { + "name": "Get current time current system", + "step_variables": { + "__soarca_ssh_result__": { + "type": "string", + "description": "Output of the ssh command", + "constant": false, + "external": false + } + }, + "on_completion": "if-condition--4b95eaa4-944a-4a9d-88d4-1374a70dbacd", + "type": "action", + "commands": [ + { + "type": "ssh", + "description": "Retrieve date", + "command": "date -I | tr -d \"\\n\"" + } + ], + "agent": "soarca--664bbe4a-7ad3-462c-baca-53cee8d67594", + "targets": [ + "linux--b49069c2-0b69-4a46-8509-80196c4a9bf8" + ], + "out_args": [ + "__soarca_ssh_result__" + ] +}, +``` + +## Example playbook + +This is de JSON data of the playbook used throughout this page. + +```json +{ + "type": "playbook", + "spec_version": "cacao-2.0", + "id": "playbook--52f8cd0d-179a-48bf-aa90-32401fe6993c", + "name": "Example Playbook", + "description": "Playbook demonstrating SOARCA 1.0 capabilities", + "playbook_types": [ + "mitigation" + ], + "playbook_activities": [ + "step-sequence" + ], + "created_by": "identity--dd22fb7f-af84-4957-84ed-12deb6c42d5d", + "created": "2024-03-07T15:16:19.068Z", + "modified": "2024-03-07T15:16:19.068Z", + "revoked": false, + "derived_from": [ + "playbook--77995581-d375-4905-bd8c-55f820a3e1a3" + ], + "playbook_variables": { + "__target_ip__": { + "type": "ipv4-addr", + "description": "IP address of target system", + "constant": false, + "external": true + }, + "__openc2_actuator_ip__": { + "type": "ipv4-addr", + "description": "IP address of OpenC2 actuator", + "constant": false, + "external": true + } + }, + "workflow_start": "start--d6c44626-c9b6-426b-ad5d-3311bafaf068", + "workflow": { + "start--d6c44626-c9b6-426b-ad5d-3311bafaf068": { + "on_completion": "action--4b08af84-3741-48ca-8c92-df1557a87379", + "type": "start" + }, + "action--4b08af84-3741-48ca-8c92-df1557a87379": { + "name": "Get current time current system", + "step_variables": { + "__soarca_ssh_result__": { + "type": "string", + "description": "Output of the ssh command", + "constant": false, + "external": false + } + }, + "on_completion": "if-condition--4b95eaa4-944a-4a9d-88d4-1374a70dbacd", + "type": "action", + "commands": [ + { + "type": "ssh", + "description": "Retrieve date", + "command": "date -I | tr -d \"\\n\"" + } + ], + "agent": "soarca--664bbe4a-7ad3-462c-baca-53cee8d67594", + "targets": [ + "linux--b49069c2-0b69-4a46-8509-80196c4a9bf8" + ], + "out_args": [ + "__soarca_ssh_result__" + ] + }, + "if-condition--4b95eaa4-944a-4a9d-88d4-1374a70dbacd": { + "name": "If it is not new years", + "description": "Checks if it is 01-01-2025", + "on_completion": "end--db937fc8-3a42-41cc-b828-ec2db212f425", + "type": "if-condition", + "condition": "__soarca_ssh_result__:value != '01-01-2025'", + "on_true": "action--7fe08053-3685-4d8c-bc0a-40efce75113e" + }, + "action--7fe08053-3685-4d8c-bc0a-40efce75113e": { + "name": "Perform an HTTP request", + "description": "Perform a GET request against httpbin.org", + "step_variables": { + "__soarca_http_api_result__": { + "type": "string", + "constant": false, + "external": false + } + }, + "on_completion": "while-condition--d865da4e-4f53-4b29-aaba-b8f5711d50ff", + "type": "action", + "commands": [ + { + "type": "http-api", + "description": "Perform request against httpbin.org", + "command": "GET /get?newyears=false HTTP/1.1" + } + ], + "targets": [ + "http-api--f2ed7db1-54fc-4a3c-ac0c-837dffade754" + ], + "out_args": [ + "__soarca_http_api_result__" + ] + }, + "while-condition--d865da4e-4f53-4b29-aaba-b8f5711d50ff": { + "name": "While the counter is not 5", + "description": "Step showing while condition", + "step_variables": { + "__soarca_ssh_result__": { + "type": "string", + "description": "Incrementing counter", + "value": "0", + "constant": false, + "external": false + } + }, + "on_completion": "action--76fe4c02-6a5d-43ae-8736-433c07ab80b8", + "type": "while-condition", + "condition": "__soarca_ssh_result__:value != '5'", + "on_true": "action--a32cdbb6-403a-47c7-a35b-07430a8de3fd" + }, + "action--a32cdbb6-403a-47c7-a35b-07430a8de3fd": { + "name": "Increment the counter", + "description": "Increment the counter stored in __soarca_ssh_result__", + "step_variables": { + "__soarca_ssh_result__": { + "type": "string", + "constant": false, + "external": false + } + }, + "on_completion": "end--60fc8d0c-3677-4363-8576-9ea9014f8c8e", + "type": "action", + "commands": [ + { + "type": "ssh", + "description": "Increment a string counter using python", + "command": "python -c \"print(__soarca_ssh_result__:value + 1, end='')\"" + } + ], + "targets": [ + "linux--b49069c2-0b69-4a46-8509-80196c4a9bf8" + ], + "out_args": [ + "__soarca_ssh_result__" + ] + }, + "end--60fc8d0c-3677-4363-8576-9ea9014f8c8e": { + "type": "end" + }, + "end--db937fc8-3a42-41cc-b828-ec2db212f425": { + "type": "end" + }, + "action--76fe4c02-6a5d-43ae-8736-433c07ab80b8": { + "name": "Send OpenC2 command", + "description": "Sends a command to an OpenC2 compliant actuator", + "step_variables": { + "__soarca_openc2_http_result__": { + "type": "string", + "constant": false, + "external": false + } + }, + "on_completion": "end--40f92845-e67a-4f13-b72a-23f189bf0cb6", + "type": "action", + "commands": [ + { + "type": "openc2-http", + "command": "POST /openc2-api/ HTTP/1.1", + "content_b64": "ewogICJoZWFkZXJzIjogewogICAgInJlcXVlc3RfaWQiOiAiZDFhYzA0ODktZWQ1MS00MzQ1LTkxNzUtZjMwNzhmMzBhZmU1IiwKICAgICJjcmVhdGVkIjogMTU0NTI1NzcwMDAwMCwKICAgICJmcm9tIjogInNvYXJjYS5ydW5uZXIubmV0IiwKICAgICJ0byI6IFsKICAgICAgImZpcmV3YWxsLmFwaS5jb20iCiAgICBdCiAgfSwKICAiYm9keSI6IHsKICAgICJvcGVuYzIiOiB7CiAgICAgICJyZXF1ZXN0IjogewogICAgICAgICJhY3Rpb24iOiAiZGVueSIsCiAgICAgICAgInRhcmdldCI6IHsKICAgICAgICAgICJmaWxlIjogewogICAgICAgICAgICAiaGFzaGVzIjogewogICAgICAgICAgICAgICJzaGEyNTYiOiAiMjJmZTcyYTM0ZjAwNmVhNjdkMjZiYjcwMDRlMmI2OTQxYjVjMzk1M2Q0M2FlN2VjMjRkNDFiMWE5MjhhNjk3MyIKICAgICAgICAgICAgfQogICAgICAgICAgfQogICAgICAgIH0KICAgICAgfQogICAgfQogIH0KfQ==", + "headers": { + "Content-Type": ["application/openc2+json;version=1.0"] + } + } + ], + "targets": [ + "linux--c50901f4-3802-4b8f-9b19-e1e62cc8fac4" + ], + "out_args": [ + "__soarca_openc2_http_result__" + ] + }, + "end--40f92845-e67a-4f13-b72a-23f189bf0cb6": { + "type": "end" + } + }, + "agent_definitions": { + "soarca--664bbe4a-7ad3-462c-baca-53cee8d67594": { + "type": "soarca", + "name": "soarca-ssh", + "description": "SOARCA SSH capability" + } + }, + "target_definitions": { + "linux--b49069c2-0b69-4a46-8509-80196c4a9bf8": { + "type": "linux", + "name": "Target system", + "description": "System to execute commands on", + "address": { + "ipv4": [ + "__target_ip__:value" + ] + } + }, + "http-api--f2ed7db1-54fc-4a3c-ac0c-837dffade754": { + "type": "http-api", + "name": "HTTPBin", + "description": "The HTTPBin.org testing website", + "address": { + "url": [ + "https://httpbin.org/" + ] + } + }, + "linux--c50901f4-3802-4b8f-9b19-e1e62cc8fac4": { + "type": "http-api", + "name": "OpenC2 Actuator", + "description": "OpenC2 compatiable actuator", + "address": { + "ipv4": [ + "__openc2_actuator_ip__:value" + ] + } + } + } +} +``` \ No newline at end of file diff --git a/docs/content/en/docs/contribution-guidelines/_index.md b/docs/content/en/docs/contribution-guidelines/_index.md index 227f9497..892f063c 100644 --- a/docs/content/en/docs/contribution-guidelines/_index.md +++ b/docs/content/en/docs/contribution-guidelines/_index.md @@ -12,39 +12,54 @@ Thank you for contributing to our project! Your efforts make a difference. ## Contributing to SOARCA -The SOARCA itself lives in https://github.com/google/ddcsy>. - +The SOARCA itself lives on [github](https://github.com/COSSAS/SOARCA). ## How to contribute Before making contributions to the project repositories, please follow these general steps for [GitHub contribution](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project). -### I found a bug or Creating issues +### I found a bug / Creating issues -If there's something you'd like to see in SOARCA (or if you've found something that isn't working the way you'd expect), but you're not sure how to fix it yourself, please create an [issue](https://github.com/). Make sure to adhere to the structure of an issue submission. Fully comprehend the problem at hand and provide comprehensive details in your issue description. +If there's something you'd like to see in SOARCA (or if you've found something that isn't working the way you'd expect), but you're not sure how to fix it yourself, please create an [issue](https://github.com/COSSAS/SOARCA/issues/new/choose). Make sure to adhere to the structure of an issue submission. Fully comprehend the problem at hand and provide comprehensive details in your issue description. {{% alert title="Security issues" color="warning" %}} -For security issues, we kindly request that you refrain from reporting them using the issue tracker. Instead, please contact us directly: `to be added` +For security issues, we kindly request that you refrain from reporting them using the issue tracker. Instead, please contact us directly: [slack](https://cossas.slack.com/archives/C06L65375TN) {{% /alert %}} ### Feature additions or requests -You can submit feature requests either through GitHub issues or the discussion pages. +You can submit feature requests either through [GitHub issues](https://github.com/COSSAS/SOARCA/issues) or the [discussion pages](https://github.com/COSSAS/SOARCA/discussions). ### Code reviews Every submission, including those from project members, must undergo review and approval from at least one core maintainer. GitHub pull requests are utilized for this process. Consult [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more information on using pull requests. +### Branch naming + +The CI is configured to only allow for certain branch naming namely: +- master +- development +- feature/ +- feature/docs/ +- bugfix/ #it should be small! +- release/x.x +- hotfix/ + +### Coding style + +The project has opted to select the [go style guide](https://google.github.io/styleguide/go/) with some exceptions: +- Receiver name are not one letter https://google.github.io/styleguide/go/decisions#receiver-names so use `info` instead of `i` +- Initialisms are CamelCase https://google.github.io/styleguide/go/decisions#receiver-names so use `Xml` instead of `XML` ## Communication channels Feel free to engage with the community for discussions and assistance via one of the following channels: -- [Slack](https://google.com) -- [Github discussions](https://github.com) +- [slack](https://cossas.slack.com/archives/C06L65375TN) +- [GitHub discussions](https://github.com/COSSAS/SOARCA/discussions) ## Contributing to these docs @@ -62,8 +77,8 @@ Would you like to enhance our documentation? Our documentation is built using th If you've just spotted something you'd like to change while using the docs, Docsy has a shortcut for you: -1. Click **Edit this page** in the top right hand corner of the page. -1. If you don't already have an up to date fork of the project repo, you are prompted to get one - click **Fork this repository and propose changes** or **Update your Fork** to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode. +1. Click **Edit this page** in the top right-hand corner of the page. +1. If you don't already have an up-to-date fork of the project repo, you are prompted to get one - click **Fork this repository and propose changes** or **Update your Fork** to get an up-to-date version of the project to edit. The appropriate page in your fork is displayed in edit mode. ## License diff --git a/docs/content/en/docs/core-components/_index.md b/docs/content/en/docs/core-components/_index.md index fefbb61d..4398481b 100644 --- a/docs/content/en/docs/core-components/_index.md +++ b/docs/content/en/docs/core-components/_index.md @@ -10,7 +10,7 @@ SOARCA consists of several key components: 1. **SOARCA Core**: This is the heart of SOARCA, represented in green. 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 part of this repository. +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](/images/core_color.png) +![core](/SOARCA/images/core_color.png) diff --git a/docs/content/en/docs/core-components/api-design.md b/docs/content/en/docs/core-components/api-design.md index 0bb12cfc..8cd659f1 100644 --- a/docs/content/en/docs/core-components/api-design.md +++ b/docs/content/en/docs/core-components/api-design.md @@ -145,10 +145,10 @@ When the caller does not have valid authentication 401/unauthorized will be retu ---- ### /playbook -The playbook endpoinst are used to create playbooks in SOARCA, new playbook can be added, current ones edited and deleted. +The playbook endpoints are used to create playbooks in SOARCA, new playbooks can be added, and current ones edited and deleted. #### GET `/playbook` -Get all playbook id's that are currently stored in SOARCA. +Get all playbook ids that are currently stored in SOARCA. ##### Call payload None @@ -172,7 +172,7 @@ None General error #### GET `/playbook/meta` -Get all playbook id's that are currently stored in SOARCA. +Get all playbook ids that are currently stored in SOARCA. ##### Call payload None @@ -204,7 +204,7 @@ General error #### POST `/playbook` -Create a new playbook that and store it in SOARCA. The format is +Create a new playbook and store it in SOARCA. The format is ##### Payload @@ -285,12 +285,12 @@ None 200/OK if deleted ##### Error -400/BAD REQUEST if resource does not exist +400/BAD REQUEST if the resource does not exist --- #### POST `/trigger/playbook/xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx` -Execute playbook with specific id +Execute playbook with a specific id ##### Call payload None @@ -313,13 +313,13 @@ Will return 200/OK when finished with playbook playbook. --- #### POST `/trigger/playbook` -Execute an adhoc playbook +Execute an ad-hoc playbook ##### Call payload A playbook like [cacao playbook JSON](#cacao-playbook-json) ##### Response -Will return 200/OK when finished with playbook. +Will return 200/OK when finished with the playbook. ```plantuml @startjson @@ -473,7 +473,7 @@ Get all running playbooks ---- #### GET `/status/playbook/xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx (playbook-id)` -Get playbook details which is running which will return cacao playbook JSON +Get playbook details of running a playbook. It will return CACAO playbook JSON ##### Call payload None @@ -490,7 +490,7 @@ Empty payload if no playbooks are running ---- #### GET `/status/playbook/{playbook-id}` -Get coarse of action list for coa awaiting action. +Get course of action list for coa awaiting action. ##### Call payload None @@ -518,7 +518,7 @@ None --- #### GET /status/history -Get all playbook id's and statuses that have been run excluded those that are running or paused. +Get all playbook ids and statuses that have been run excluded those that are running or paused. ##### Call payload None diff --git a/docs/content/en/docs/core-components/database.md b/docs/content/en/docs/core-components/database.md index 993f3c98..2d2277aa 100644 --- a/docs/content/en/docs/core-components/database.md +++ b/docs/content/en/docs/core-components/database.md @@ -7,11 +7,11 @@ description: > Database details of SOARCA --- -SOARCA Database architecture, SOARCA makes use of [MongoDB](https://www.mongodb.com). It is used to store and retrieve playbooks. Later it will also store individual steps. +OARCA Database architecture, SOARCA makes use of [MongoDB](https://www.mongodb.com/) It is used to store and retrieve playbooks. Later it will also store individual steps. ## Mongo -Mongo has different collections for SOARCA we use a database object per collection. So that would be: +SOARCA employs separate collections in Mongo, utilizing a dedicated database object for each of them: * Playbook * Step diff --git a/docs/content/en/docs/core-components/decomposer.md b/docs/content/en/docs/core-components/decomposer.md index 42b41d87..36fb469c 100644 --- a/docs/content/en/docs/core-components/decomposer.md +++ b/docs/content/en/docs/core-components/decomposer.md @@ -40,10 +40,10 @@ IExecutor <- Decomposer ``` ### IExecutor -Interface for interfacing with the Executor this will in turn select and execute the command on the right [module](/docs/core-components/modules) or [fin](/docs/soarca-extentions/). +Interface for interfacing with the Executor this will in turn select and execute the command on the right [module](/docs/core-components/modules) or [fin](/docs/soarca-extensions/). ### Execution details -The struct contains the details of the execution (execution id which is created for every execution) and the playbook id. the combination of these are unique. +The struct contains the details of the execution (execution id which is created for every execution) and the playbook id. The combination of these is unique. ## Decomposition of playbook diff --git a/docs/content/en/docs/core-components/executer.md b/docs/content/en/docs/core-components/executer.md index cf829a65..3b16a8d7 100644 --- a/docs/content/en/docs/core-components/executer.md +++ b/docs/content/en/docs/core-components/executer.md @@ -8,16 +8,15 @@ description: > --- ## Components - -The executer consists of the following components. +The executor consists of the following components. - The capability selector - Native capabilities (command executors) -- MQTT capability to interact with: Fin capabilities (third party 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`: +The capability selector will select the implementation which is capable of executing the incoming command. There are native capabilities based on the CACAO `command-type-ov`: * **Currently implemented** * ssh @@ -35,9 +34,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 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 executor will select a module that is capable of executing the command and pass the details to it. The capability selection is performed based on 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. +The result of the step execution will be returned to the decomposer. A result can be either output variables or error status. ### MQTT executor -> Fin capabilities The Executor will put the command on the MQTT topic that is offered by the module. How a module handles this is described in the link:modules.adoc[module documentation] diff --git a/docs/content/en/docs/core-components/log.md b/docs/content/en/docs/core-components/log.md index 35623404..3022f8b1 100644 --- a/docs/content/en/docs/core-components/log.md +++ b/docs/content/en/docs/core-components/log.md @@ -7,7 +7,7 @@ categories: [architecture] tags: [logging] --- -SOARCA support extensive logging. Logging is based on the [logrus](https://github.com/sirupsen/logrus) framework. +SOARCA supports extensive logging. Logging is based on the [logrus](https://github.com/sirupsen/logrus) framework. ## Format Logging can be done in different formats suitable for your application. The following formats are available: @@ -22,18 +22,18 @@ Logging can be done in different formats suitable for your application. The foll Later: -* syslog (NOT IMPLEMENTED) +* syslog (*NOT YET IMPLEMENTED*) ## Log levels SOARCA supports the following log levels. Also is indicated how they are used. -* PANIC (non fixable error system crash) -* FATAL (non fixable error, restart would fix) -* ERROR (operation went wrong but can be caught by other higher component) -* WARNING (let the user know some operation might not have the expected result but execution can continue on normal path) -* INFO `default` (let the user know that a major event has occurred) -* DEBUG (add some extra detail to normal execution paths) -* TRACE (get some fine grained detail from the logging) +* `PANIC` (non fixable error system crash) +* `FATAL` (non fixable error, restart would fix) +* `ERROR` (operation went wrong but can be caught by other higher component) +* `WARNING` (let the user know some operation might not have the expected result but execution can continue on normal path) +* `INFO` `default` (let the user know that a major event has occurred) +* `DEBUG` (add some extra detail to normal execution paths) +* `TRACE` (get some fine grained detail from the logging) ## Types of logging SOARCA will log different information, these will be combined in the same output. @@ -50,7 +50,6 @@ Will log the status of the execution of an playbook, database updates of playboo To use SOARCA logging you can add the following to your module. ```golang - type YourModule struct { } @@ -60,12 +59,11 @@ var log *logger.Log func init() { log = logger.Logger(component, logger.Info, "", logger.Json) } - ``` ## Changing log level -To change logging for your SOARCA instance you can use use the following environment variables +To change logging for your SOARCA instance you can use the following environment variables |variable |content |description @@ -79,7 +77,6 @@ To change logging for your SOARCA instance you can use use the following environ This can be set as environment variables or loaded through the `.env` ```bash - LOG_GLOBAL_LEVEL: "info" LOG_MODE: "production" LOG_FILE_PATH: "" diff --git a/docs/content/en/docs/core-components/modules.md b/docs/content/en/docs/core-components/modules.md index 4bc696e4..4ef88399 100644 --- a/docs/content/en/docs/core-components/modules.md +++ b/docs/content/en/docs/core-components/modules.md @@ -7,84 +7,149 @@ 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: +The following capability modules are currently 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-`. +The capability will be selected based on the agent in the CACAO playbook step. The agent should be of type `soarca` and have a name corresponding to `soarca-[capability name]`. ### SSH capability -This module is defined in a playbook with the following TargetAgent definition: +This capability executes [SSH Commands](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256500) on the specified targets. + +This capability support [User Authentication](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256508) using the `user-auth` type. Both username/password and username/privatekey authentication are supported. + +#### Success and failure + +The SSH step is considered successful if a proper connection to each target can be initialized, the supplied command executes without error, and returns with zero exit status. + +In every other circumstance the step is considered to have failed. + +#### Variables + +This module does not define specific variables as input, but variable interpolation is supported in the command and target definitions. It has the following output variables: ```json -"agent_definitions": { - "soarca--00010001-1000-1000-a000-000100010001": { - "type": "soarca-ssh" - } - }, +{ + "__soarca_ssh_result__": { + "type": "string", + "value": "" + } +} ``` -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: +#### Example ```json { - "__soarca_ssh_result__": { - Type: "string", - Name: "result", - Value: "" + "workflow": { + "action--7777c6b6-e275-434e-9e0b-d68f72e691c1": { + "type": "action", + "agent": "soarca--00010001-1000-1000-a000-000100010001", + "targets": ["linux--c7e6af1b-9e5a-4055-adeb-26b97e1c4db7"], + "commands": [ + { + "type": "ssh", + "command": "ls -la" + } + ] + } + }, + "agent_definitions": { + "soarca--00010001-1000-1000-a000-000100010001": { + "type": "soarca", + "name": "soarca-ssh" + } + }, + "target_definitions": { + "linux--c7e6af1b-9e5a-4055-adeb-26b97e1c4db7": { + "type": "linux", + "name": "target", + "address": { "ipv4": ["10.0.0.1"] } + } } } ``` -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 -## HTTP-API capability +This capability implements the [HTTP API Command](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256495). -This module is defined in a playbook with the following TargetAgent definition: +Both [HTTP Basic Authentication](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256506) with user_id/password and token based [OAuth2 Authentication](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256507) are supported. -```json -"agent_definitions": { - "soarca--00020001-1000-1000-a000-000100010001": { - "type": "soarca-http-api" - }, - }, -``` +At this time, redirects are not supported. + +#### Success and failure -It supports variable interpolation in the command, port, authentication info, and target definitions. +The command is considered to have successfully completed if a successful HTTP response is returned from each target. An HTTP response is successful if it's response code is in the range 200-299. + +#### Variables + +This capability 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: "" + "type": "string", + "value": "" } } ``` -## OPEN-C2 capabilty - -This module is defined in a playbook with the following TargetAgent definition: +#### Example ```json -"agent_definitions": { - "soarca--00030001-1000-1000-a000-000100010001": { - "type": "soarca-openc2-http" - }, +{ + "workflow": { + "action--8baa7c78-751b-4de9-81d4-775806cee0fb": { + "type": "action", + "agent": "soarca--00020001-1000-1000-a000-000100010001", + "targets": ["http-api--4ebae9c3-9454-4e28-b25b-0f43cd97f9e0"], + "commands": [ + { + "type": "http-api", + "command": "GET /overview HTTP/1.1", + "port": "8080" + } + ] + } }, + "agent_definitions": { + "soarca--00020001-1000-1000-a000-000100010001": { + "type": "soarca", + "name": "soarca-http-api" + } + }, + "target_definitions": { + "http-api--4ebae9c3-9454-4e28-b25b-0f43cd97f9e0": { + "type": "http-api", + "name": "target", + "address": { "dname": ["my.server.com"] } + } + } +} ``` +### OpenC2 capability + +This capability implements the [OpenC2 HTTP Command](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256498), by sending [OpenC2 messages](https://docs.oasis-open.org/openc2/oc2ls/v1.0/cs01/oc2ls-v1.0-cs01.html) using the [HTTPS transport method](https://docs.oasis-open.org/openc2/open-impl-https/v1.0/open-impl-https-v1.0.html). + +It supports the same authentication mechanisms as the HTTP-API capability. + +#### Success and failure + +Any successful HTTP response from an OpenC2 compliant endpoint (with a status code in the range 200-299) is considered a success. Connection failures and HTTP responses outside the 200-299 range are considered a failure. + +#### Variables + It supports variable interpolation in the command, headers, and target definitions. The result of the step is stored in the following output variables: @@ -92,9 +157,43 @@ The result of the step is stored in the following output variables: ```json { "__soarca_openc2_http_result__": { - Type: "string", - Name: "result", - Value: "" + "type": "string", + "value": "" + } +} +``` + +#### Example + +```json +{ + "workflow": { + "action--aa1470d8-57cc-4164-ae07-05745bef24f4": { + "type": "action", + "agent": "soarca--00030001-1000-1000-a000-000100010001", + "targets": ["http-api--5a274b6d-dc65-41f7-987e-9717a7941876"], + "commands": [{ + "type": "openc2-http", + "command": "POST /openc2-api/ HTTP/1.1", + "content_b64": "ewogICJoZWFkZXJzIjogewogICAgInJlcXVlc3RfaWQiOiAiZDFhYzA0ODktZWQ1MS00MzQ1LTkxNzUtZjMwNzhmMzBhZmU1IiwKICAgICJjcmVhdGVkIjogMTU0NTI1NzcwMDAwMCwKICAgICJmcm9tIjogInNvYXJjYS5ydW5uZXIubmV0IiwKICAgICJ0byI6IFsKICAgICAgImZpcmV3YWxsLmFwaS5jb20iCiAgICBdCiAgfSwKICAiYm9keSI6IHsKICAgICJvcGVuYzIiOiB7CiAgICAgICJyZXF1ZXN0IjogewogICAgICAgICJhY3Rpb24iOiAiZGVueSIsCiAgICAgICAgInRhcmdldCI6IHsKICAgICAgICAgICJmaWxlIjogewogICAgICAgICAgICAiaGFzaGVzIjogewogICAgICAgICAgICAgICJzaGEyNTYiOiAiMjJmZTcyYTM0ZjAwNmVhNjdkMjZiYjcwMDRlMmI2OTQxYjVjMzk1M2Q0M2FlN2VjMjRkNDFiMWE5MjhhNjk3MyIKICAgICAgICAgICAgfQogICAgICAgICAgfQogICAgICAgIH0KICAgICAgfQogICAgfQogIH0KfQ==", + "headers": { + "Content-Type": ["application/openc2+json;version=1.0"] + } + }] + } + }, + "agent_definitions": { + "soarca--00030001-1000-1000-a000-000100010001": { + "type": "soarca", + "name": "soarca-openc2-http" + } + }, + "target_definitions": { + "http-api--5a274b6d-dc65-41f7-987e-9717a7941876": { + "type": "http-api", + "name": "openc2-compliant actuator", + "address": { "ipv4": ["187.0.2.12"] } + } } } ``` @@ -102,4 +201,4 @@ The result of the step is stored in the following output variables: --- ## MQTT fin module -This module is used by SOARCA to communicate with fins (capabilities) see [fin documentation](/docs/soarca-extentions/) for more information +This module is used by SOARCA to communicate with fins (capabilities) see [fin documentation](/docs/soarca-extensions/) for more information diff --git a/docs/content/en/docs/core-components/soarca-application-design.md b/docs/content/en/docs/core-components/soarca-application-design.md index d9e44588..4b0a3298 100644 --- a/docs/content/en/docs/core-components/soarca-application-design.md +++ b/docs/content/en/docs/core-components/soarca-application-design.md @@ -8,17 +8,17 @@ description: > --- ## Design decisions and core dependencies -To allow for fast execution and type safe development SOARCA is developed in `go`. The application application can be deployed in `Docker`. Further dependencies are `MQTT` for the module system and `go-gin` for the REST API. +To allow for fast execution and type-safe development SOARCA is developed in `go`. The application application can be deployed in `Docker`. Further dependencies are `MQTT` for the module system and `go-gin` for the REST API. -The overview on this page is aimed to guid you through the SOARCA architecture and components as well as the main flow. +The overview on this page is aimed to guide you through the SOARCA architecture and components as well as the main flow. ## Components Components of SOARCA are displayed in the component diagram. - Green is implemented - Orange has limited functionality -- Red is not started, but will be added in future releases +- Red is not started but will be added in future releases ```plantuml @startuml @@ -156,9 +156,9 @@ IExecuter -> Decomposer ## Main application flow -These sequences will show the simplified overview how the SOARCA components interact. +These sequences will show a simplified overview of how the SOARCA components interact. -The main flow of the application is the following. Execution will start by processing the JSON formatted CACAO playbook if successful the playbook is handed over to the Decomposer. This is where the playbook is decomposed into it's parts and passed step by step to the executor. These operations will block the api until execution is finished. For now no variables are exposed via the API to the caller. +The main flow of the application is the following. Execution will start by processing the JSON formatted CACAO playbook if successful the playbook is handed over to the Decomposer. This is where the playbook is decomposed into its parts and passed step by step to the executor. These operations will block the API until execution is finished. For now, no variables are exposed via the API to the caller. ```plantuml Actor Caller diff --git a/docs/content/en/docs/getting-started/_index.md b/docs/content/en/docs/getting-started/_index.md index 0bd0e59c..6e4da01d 100644 --- a/docs/content/en/docs/getting-started/_index.md +++ b/docs/content/en/docs/getting-started/_index.md @@ -17,7 +17,7 @@ Before you begin, you might need to install the following tools: ## Quick Run -Below, we outline various options to kickstart SOARCA. The latests pre-compiled releases can be found [here](). +Below, we outline various options to kickstart SOARCA. The latest pre-compiled releases can be found [here](). {{< tabpane langEqualsHeader=false >}} {{< tab header="make" lang="sh" >}} @@ -53,12 +53,12 @@ swag init {{< /tabpane >}} {{% /alert %}} -Compiles binary files can be found under `/bin`. +Compiled binary files can be found under `/bin`. ## Configuration -SOARCA reads it's configuration from the environment variables or an `.env` file. An example of an `.env` is given below: +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" >}} diff --git a/docs/content/en/docs/release-notes/_index.md b/docs/content/en/docs/release-notes/_index.md index 5918aef4..ef8a8303 100644 --- a/docs/content/en/docs/release-notes/_index.md +++ b/docs/content/en/docs/release-notes/_index.md @@ -8,7 +8,7 @@ description: ## V1.0 ---- -Finally, the first release of alpha release of SOARCA is here! In the first release we put an emphasis on laying the inital foundation and design of SOARCA to enable proof-of-concept demonstrations. With release +Finally, the first release of the alpha release of SOARCA is here! In the first release, we emphasize laying the initial foundation and design of SOARCA to enable proof-of-concept demonstrations. Included in this release: - Execution of CACAO action steps via: - SSH @@ -16,4 +16,4 @@ Finally, the first release of alpha release of SOARCA is here! In the first rele - OpenC2 - Logging capabilities - Efficient storage for playbooks -- Design fin-protocol: the protocol desription between SOARCA and \ No newline at end of file +- Design fin-protocol: the protocol description between SOARCA and the `TO BE ADDED` \ No newline at end of file diff --git a/docs/content/en/docs/soarca-extentions/_index.md b/docs/content/en/docs/soarca-extensions/_index.md similarity index 58% rename from docs/content/en/docs/soarca-extentions/_index.md rename to docs/content/en/docs/soarca-extensions/_index.md index d75186b1..36b680c9 100644 --- a/docs/content/en/docs/soarca-extentions/_index.md +++ b/docs/content/en/docs/soarca-extensions/_index.md @@ -13,15 +13,15 @@ date: 2023-01-05 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. +SOARCA features a set of [native capabilities](/docs/soarca-extensions/native-capabilities). The HTTP, OpenC2 HTTP, and SSH transport mechanisms are supported by the first release of SOARCA. SOARCA's capabilities can be extended with custom implementations, which is further discussed on this page. ## 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. +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. +MQTT is a lightweight messaging protocol with libraries written in various programming languages. To integrate with SOARCA, you 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). +The underlying protocol for the SOARCA fins can be found [here](/docs/soarca-extensions/fin-protocol). diff --git a/docs/content/en/docs/soarca-extentions/fin-protocol.md b/docs/content/en/docs/soarca-extensions/fin-protocol.md similarity index 96% rename from docs/content/en/docs/soarca-extentions/fin-protocol.md rename to docs/content/en/docs/soarca-extensions/fin-protocol.md index 4e2f73d5..59d92ed3 100644 --- a/docs/content/en/docs/soarca-extentions/fin-protocol.md +++ b/docs/content/en/docs/soarca-extensions/fin-protocol.md @@ -12,9 +12,9 @@ date: 2023-01-05 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. +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 fin UUID. +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 fin UUID. Commands to a specific capability will be communicated of the capability UUID channel. @@ -259,7 +259,7 @@ The message is used to send a command from SOARCA. It has the following payload. ``` ### result -The message is used to send response from the Fin to SOARCA. It has the following payload. +The message is used to send a response from the Fin to SOARCA. It has the following payload. |field |content |type | description | | ----------------- | ------------- | ------ | ----------- | @@ -327,7 +327,7 @@ The message is used to send response from the Fin to SOARCA. It has the followin |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. +The message is used to halt the further execution of the Fin. The following command will be responded to with a nack, unless it is resumed or stopped. ```plantuml @startjson @@ -341,7 +341,7 @@ The message is used to halt the further execution of the Fin. Following command #### 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. +The message is used to resume a paused Fin, the response will be an ack if ok or a nack when the Fin could not be resumed. ```plantuml @startjson @@ -354,7 +354,7 @@ The message is used to resume a paused Fin, the response will be ack if ok or na ``` #### stop -The message is used to shutdown the Fin. this will be responded to by ack, after that there will follow an unregister. +The message is used to shut down the Fin. this will be responded to by ack, after that there will follow an unregister. ```plantuml @startjson diff --git a/docs/content/en/docs/soarca-extentions/native-capabilities.md b/docs/content/en/docs/soarca-extensions/native-capabilities.md similarity index 87% rename from docs/content/en/docs/soarca-extentions/native-capabilities.md rename to docs/content/en/docs/soarca-extensions/native-capabilities.md index 69b3d813..b8ec7f0f 100644 --- a/docs/content/en/docs/soarca-extentions/native-capabilities.md +++ b/docs/content/en/docs/soarca-extensions/native-capabilities.md @@ -8,7 +8,8 @@ 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/). +This page contains a list of capabilities that are natively implemented in SOARCA see details [here](/docs/core-components/modules). For MQTT-message-based capabilities, check [here](/docs/soarca-extensions/). + ## OpenC2 capability diff --git a/docs/content/en/featured-background.jpg b/docs/content/en/featured-background.jpg index addbeb6c..e561327d 100644 Binary files a/docs/content/en/featured-background.jpg and b/docs/content/en/featured-background.jpg differ diff --git a/docs/hugo.toml b/docs/hugo.toml index d97e481f..6780dc74 100644 --- a/docs/hugo.toml +++ b/docs/hugo.toml @@ -27,7 +27,7 @@ category = "categories" taxonomyCloud = ["tags", "categories"] # If used, must have same length as taxonomyCloud -taxonomyCloudTitle = ["Tag Cloud", "Categories"] +taxonomyCloudTitle = ["Tags", "Categories"] # set taxonomyPageHeader = [] to hide taxonomies on the page headers taxonomyPageHeader = ["tags", "categories"] @@ -87,7 +87,7 @@ section = ["HTML", "print", "RSS"] [params] copyright = "The SOARCA Authors" -privacy_policy = "https://policies.google.com/privacy" +privacy_policy = "https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement" # First one is picked as the Twitter card image if not set on page. # images = ["images/project-illustration.png"] @@ -185,11 +185,11 @@ enable = false url = "https://github.com/COSSAS/SOARCA" icon = "fab fa-github" desc = "Development takes place here!" -# [[params.links.developer]] -# name = "Slack" -# url = "https://example.org/slack" -# icon = "fab fa-slack" -# desc = "Chat with other project developers" +[[params.links.developer]] + name = "Slack" + url = "https://cossas.slack.com/archives/C06L65375TN" + icon = "fab fa-slack" + desc = "Chat with other project developers" # [[params.links.developer]] # name = "Developer mailing list" # url = "https://example.org/mail" diff --git a/docs/layouts/shortcodes/blocks/cover.html b/docs/layouts/shortcodes/blocks/cover.html index 9f5d709e..4450f3be 100644 --- a/docs/layouts/shortcodes/blocks/cover.html +++ b/docs/layouts/shortcodes/blocks/cover.html @@ -3,25 +3,32 @@ {{ $promo_image := (.Page.Resources.ByType "image").GetMatch "**background*" -}} {{ $logo_image := (.Page.Resources.ByType "image").GetMatch "**logo*" -}} {{ $col_id := .Get "color" | default "dark" -}} -{{ $image_anchor := .Get "image_anchor" | default "smart" -}} +{{ $image_anchor := .Get "image_anchor" | default "center" -}} {{ $logo_anchor := .Get "logo_anchor" | default "smart" -}} {{/* Height can be one of: auto, min, med, max, full. */ -}} {{ $height := .Get "height" | default "max" -}} {{ with $promo_image -}} {{ $promo_image_big := (.Fill (printf "1920x1080 %s" $image_anchor)) -}} +{{ $promo_image_large := (.Fill (printf "4096x2160 %s" $image_anchor)) -}} {{ $promo_image_small := (.Fill (printf "960x540 %s" $image_anchor)) -}} - + + {{ end -}} diff --git a/docs/netlify.toml b/docs/netlify.toml deleted file mode 100644 index e087db82..00000000 --- a/docs/netlify.toml +++ /dev/null @@ -1,12 +0,0 @@ -# Hugo build configuration for Netlify -# (https://gohugo.io/hosting-and-deployment/hosting-on-netlify/#configure-hugo-version-in-netlify) - -[build] -command = "npm run build:preview" -publish = "public" - -[build.environment] -GO_VERSION = "1.21.4" - -[context.production] -command = "npm run build:production" diff --git a/docs/static/images/eu-funded-logo.png b/docs/static/images/eu-funded-logo.png new file mode 100644 index 00000000..0430c7a0 Binary files /dev/null and b/docs/static/images/eu-funded-logo.png differ diff --git a/docs/static/images/example-playbook.svg b/docs/static/images/example-playbook.svg new file mode 100644 index 00000000..2cb0a35e --- /dev/null +++ b/docs/static/images/example-playbook.svg @@ -0,0 +1,4 @@ + + + +on completionon completionon completionon trueon completionEndon trueon completionwhile-condition StepWhile the counter is not 5on completionif-condition StepIf it is not new yearsaction StepGet current time current systemStartaction StepPerform an HTTP requestaction StepIncrement the counterEndaction StepSend OpenC2 commandEnd \ No newline at end of file