diff --git a/docs/content/en/docs/_index.md b/docs/content/en/docs/_index.md index 20512b19..64456987 100644 --- a/docs/content/en/docs/_index.md +++ b/docs/content/en/docs/_index.md @@ -39,7 +39,6 @@ SOARCA currently supports the following transport mechanisms: {{% card header="SSH - Native" %}} [![Ssh](/SOARCA/images/logos-external/ssh.svg)](/docs/soarca-extensions/native-capabilities/#ssh-capability) {{% /card %}} - {{% card header="PowerShell WinRM - Native" %}} [![PowerShell](/SOARCA/images/logos-external/powershell.svg)](/docs/soarca-extensions/native-capabilities/#powershell-capability) diff --git a/docs/content/en/docs/concepts/executable-playbooks.md b/docs/content/en/docs/concepts/executable-playbooks.md index 8116430e..b2baa8cb 100644 --- a/docs/content/en/docs/concepts/executable-playbooks.md +++ b/docs/content/en/docs/concepts/executable-playbooks.md @@ -12,7 +12,7 @@ resources: SOARCA is build on top of the [CACAO Security Playbook Version 2.0](https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html) standard. {{% alert title="Warning" color="warning" %}} -SOARCA v1.0 only implements a part of the CACAO v2 spec. Only `start`, `end`, and `action` steps are supported at this time. +SOARCA v1.0 only implements a part of the CACAO v2 spec. Only `start`, `end`, `action`, and `if/else` steps are supported at this time. {{% /alert %}} A CACAO playbook is a structured document that outlines a series of orchestrated actions to address specific security events, incidents, or other security-related activities. These playbooks allow for the automation of security steps. @@ -390,4 +390,4 @@ This is de JSON data of the playbook used throughout this page. } } } -``` \ No newline at end of file +``` diff --git a/docs/content/en/docs/core-components/_index.md b/docs/content/en/docs/core-components/_index.md index 60dcb3c7..55f86bb4 100644 --- a/docs/content/en/docs/core-components/_index.md +++ b/docs/content/en/docs/core-components/_index.md @@ -1,6 +1,6 @@ --- title: Design -weight: 5 +weight: 6 description: > The design of SOARCA @@ -12,7 +12,6 @@ SOARCA consists of several key components: 2. **SOARCA Native Capabilities**: These are the functionalities explicitly defined in the Cacao v2 specification and are integral to the core. They are also represented in green. 3. **Fins**: These are the extension capabilities, also known as Fins. They enhance the functionality and integration of SOARCA and are depicted in orange. These are not (yet) part of this repository, but may be implemented by partners or TNO in the future. - ![core](/SOARCA/images/core_color.png) ## Core component overview diff --git a/docs/content/en/docs/core-components/api-reporter.md b/docs/content/en/docs/core-components/api-reporter.md index 2904e2a0..f8358aef 100644 --- a/docs/content/en/docs/core-components/api-reporter.md +++ b/docs/content/en/docs/core-components/api-reporter.md @@ -9,7 +9,7 @@ weight: 2 # Endpoint description -We will use HTTP status codes +We will use HTTP status codes https://en.wikipedia.org/wiki/List_of_HTTP_status_codes ```plantuml @startuml diff --git a/docs/content/en/docs/getting-started/_index.md b/docs/content/en/docs/getting-started/_index.md index 82a01ada..658d51af 100644 --- a/docs/content/en/docs/getting-started/_index.md +++ b/docs/content/en/docs/getting-started/_index.md @@ -9,7 +9,7 @@ date: 2024-03-18 ## Prerequisites -Before you begin, you might need to install the following tools (Linux Ubuntu 22.04 adapt for your needs): +Before you begin, you might need to install the following tools (Linux Ubuntu 22.04 adapt for your needs): - [golang](https://go.dev/doc/install) - go gin `go get -u github.com/gin-gonic/gin` @@ -34,9 +34,6 @@ cd docker/soarca && sudo docker compose up -d {{< /tab >}} {{< /tabpane >}} - - - {{% alert title="Tip" %}} Output will be similar to: {{< tabpane langEqualsHeader=false >}} @@ -53,17 +50,18 @@ swag init {{< /tabpane >}} {{% /alert %}} -Compiled binary files can be found under `/bin`. +Compiled binary files can be found under `/bin`. ### Playbook execution You can use the following commands to execute the example playbooks via the terminal while SOARCA is running assuming on localhost. Alternatively you can go to `http://localhost:8080/swagger/index.html` and use the trigger/playbook endpoint. - Example playbooks: {{< tabpane langEqualsHeader=false >}} {{< tab header="ssh" lang="sh" >}} + # make sure an ssh server is running on adres 192.168.0.10 + curl -X POST -H "Content-Type: application/json" -d @./example/ssh-playbook.json localhost:8080/trigger/playbook {{< /tab >}} {{< tab header="http" lang="sh" >}} @@ -74,7 +72,6 @@ curl -X POST -H "Content-Type: application/json" -d @./example/openc2-playbook.j {{< /tab >}} {{< /tabpane >}} - ## Configuration SOARCA reads its configuration from the environment variables or a `.env` file. An example of a `.env` is given below: @@ -82,6 +79,8 @@ SOARCA reads its configuration from the environment variables or a `.env` file. {{< tabpane langEqualsHeader=false >}} {{< tab header="`.env`" lang="txt" >}} PORT: 8080 +SOARCA_ALLOWED_ORIGINS: "*" +GIN_MODE: "release" MONGODB_URI: "mongodb://localhost:27017" DATABASE_NAME: "soarca" DB_USERNAME: "root" @@ -98,11 +97,14 @@ LOG_FORMAT: "json" ENABLE_FINS: false MQTT_BROKER: "localhost" MQTT_PORT: 1883 -VALIDATION_SCHEMA_URL: "" + +HTTP_SKIP_CERT_VALIDATION: false {{< /tab >}} {{< /tabpane >}} -### Docker hub + +For more custom and advanced deployment instructions go [here](/docs/installation-configuration/_index.md). +### Docker hub `docker pull cossas/soarca` @@ -114,23 +116,3 @@ make build cp .env.example .env ./build/soarca ``` - -### Configuring SOARCA - -|variable |content |description -|---|---|---| -|PORT |port |Set the exposed port of SOARCA the default is `8080` -|DATABASE |true \| false | Set if you want to run with external database default is `false` -|MONGODB_URI |uri |Set the Mongo DB uri default is `mongodb://localhost:27017` -|DATABASE_NAME |name |Set the Mongo DB database name when using docker default is `soarca` -|DB_USERNAME |user |Set the Mongo DB database user when using docker default is `root` -|DB_PASSWORD |password |Set the Mongo DB database users password when using docker default is `rootpassword`. IT IS RECOMMENDED TO CHANGE THIS IN PRODUCTION! -|MAX_REPORTERS |number |Set the maximum number of downstream reporters default is `5` -|LOG_GLOBAL_LEVEL |[Log levels] |One of the specified log levels. Defaults to `info` -|LOG_MODE |development \| production |If production is chosen the `LOG_GLOBAL_LEVEL` is used for all modules defaults to `production` -|LOG_FILE_PATH |filepath |Path to the logfile you want to use for all logging. Defaults to `""` (empty string) -|LOG_FORMAT |text \| json |The logging can be in plain text format or in JSON format. Defaults to `json` -|MQTT_BROKER | dns name or ip | The broker address for SOARCA to connect to, for communication with fins default is `localhost` -|MQTT_PORT | port | The broker address for SOARCA to connect to, for communication with fins default is `1883` -|ENABLE_FINS| true \| false | Enable fins in SOARCA defaults to `false` -|VALIDATION_SCHEMA_URL|url| Set a custom validation schema to be used to validate playbooks defaul is `""` to use internal. NOTE: changing this heavily impacts performance. diff --git a/docs/content/en/docs/installation-configuration/_index.md b/docs/content/en/docs/installation-configuration/_index.md new file mode 100644 index 00000000..2ccfe091 --- /dev/null +++ b/docs/content/en/docs/installation-configuration/_index.md @@ -0,0 +1,69 @@ + +--- + +description: Everything you need to install and configure SOARCA +title: Advanced Installation and Configuration +categories: [documentation, configuration] +tags: [extension, security] +weight: 4 +--- + +After completing the [Getting Started](/docs/getting-started/_index.md) setup for SOARCA, you may find that certain advanced configurations or customizations are necessary to optimize SOARCA for your specific use cases, for example integrating with The Hive. This section provides in-depth guidance on additional steps you can take to enhance, secure, and integrate SOARCA with your infrastructure, ensuring it meets your unique operational needs. + +### Configuring SOARCA + +| Variable | Content | Description | +|----------------------------|-----------------------------------|-----------------------------------------------------------------------------| +| PORT | `8080` | Set the exposed port of SOARCA. Default is `8080`. | +| ENABLE_TLS | `false` | Enable TLS for secure communication. Default is `false`. | +| CERT_FILE | `"/certs/server.crt"` | Path to the TLS certificate file. Default is `"/certs/server.crt"`. | +| CERT_KEY_FILE | `"/certs/server.key"` | Path to the TLS certificate key file. Default is `"/certs/server.key"`. | +| MAX_EXECUTIONS | `1000` | The number of historical executions saved, including the current one. Default is `1000`. | +| SOARCA_ALLOWED_ORIGINS | `*` | Set allowed origins for cross-origin requests. Default is `*`. | +| GIN_MODE | `release` | Set the GIN mode. Default is `release`. | +| DATABASE | `false` | Set if you want to run with an external database. Default is `false`. | +| MONGODB_URI | `mongodb://localhost:27017` | Set the MongoDB URI. Default is `mongodb://localhost:27017`. | +| DATABASE_NAME | `soarca` | Set the MongoDB database name when using Docker. Default is `soarca`. | +| DB_USERNAME | `root` | Set the MongoDB database user when using Docker. Default is `root`. | +| DB_PASSWORD | `rootpassword` | Set the MongoDB database user password when using Docker. **Change this in production!** Default is `rootpassword`. | +| PLAYBOOK_API_LOG_LEVEL | `trace` | Set the log level for the playbook API. Default is `trace`. | +| MAX_REPORTERS | `5` | Set the maximum number of downstream reporters. Default is `5`. | +| LOG_GLOBAL_LEVEL | `info` | One of the specified log levels. Default is `info`. | +| LOG_MODE | `development` | Set the logging mode. If `production`, `LOG_GLOBAL_LEVEL` is used for all modules. Default is `development`. | +| LOG_FILE_PATH | `""` | Path to the logfile for all logging. Default is `""` (empty string). | +| LOG_FORMAT | `json` | Set the logging format. Either `text` or `json`. Default is `json`. | +| ENABLE_FINS | `false` | Enable FINS in SOARCA. Default is `false`. | +| MQTT_BROKER | `localhost` | The broker address for SOARCA to connect to for communication with FINS. Default is `localhost`. | +| MQTT_PORT | `1883` | The port for the MQTT broker. Default is `1883`. | +| HTTP_SKIP_CERT_VALIDATION | `false` | Set whether to skip certificate validation for HTTP connections. Default is `false`. | +| VALIDATION_SCHEMA_URL | `""` | Set a custom validation schema to validate playbooks. Default is `""` to use the internal schema. **Note:** Changing this can heavily impact performance. | + +----- + +### Integrations + +#### The Hive + +| Variable | Content | Description | +|----------------------|-----------------------------------|---------------------------------------------------------| +| THEHIVE_ACTIVATE | `false` | Enable integration with The Hive. Default is `false`. | +| THEHIVE_API_TOKEN | `your_token` | Set the API token for The Hive integration. | +| THEHIVE_API_BASE_URL | `http://your.thehive.instance/api/v1/` | Set the base URL for The Hive API. Default is `""`. | + +----- + +### Authentication + +{{% alert title="Note" color="primary" %}} +More information on setting up authentication can be found [here](/docs/installation-configuration/authentication.md). +{{% /alert %}} +| Variable | Content | Description | +|------------------------|---------------------------------------------|---------------------------------------------------------------------------------------------| +| AUTH_ENABLED | `false` | Enable authentication. Default is `false`. | +| OIDC_ISSUER | `https://localhost:9443/application/u/test/` | The OIDC issuer URL. | +| OIDC_CLIENT_ID | `SOME_CLIENT_ID` | Set the OIDC client ID. | +| OIDC_CLIENT_SECRET | `SOME_CLIENT_SECRET` | Set the OIDC client secret. | +| OIDC_REDIRECT_URL | `http://localhost:8081/auth/soarca_gui/callback` | Set the OIDC redirect URL. | +| COOKIE_SECRET_KEY | `SOME_COOKIE_SECRET` | Optional: Secret key for cookies. Generate using `openssl rand -base64 32` or `head -c 32 /dev/urandom | base64`. | +| OIDC_SKIP_TLS_VERIFY | `true` | Set whether to skip TLS verification. Default is `true`. | +| AUTH_GROUP | `soarca_admin` | Specify the group users must belong to for authentication against SOARCA. | diff --git a/docs/content/en/docs/installation-configuration/authentication.md b/docs/content/en/docs/installation-configuration/authentication.md new file mode 100644 index 00000000..81dbac00 --- /dev/null +++ b/docs/content/en/docs/installation-configuration/authentication.md @@ -0,0 +1,158 @@ + +--- + +title: Setup RBAC for SOARCA +description: > + Setup OIDC based Role-Based Access Control (RBAC) for SOARCA +categories: [extensions, architecture] +tags: [security] +weight: 2 + +--- +Authentication is disabled by default in SOARCA. This means that when SOARCA is launched with its default configuration and exposed to a network, anyone can interact with it. Since SOARCA requires significant capabilities and access to reconfigure systems, exposing it without authentication poses a security risk. This section outlines how to set up authentication and authorization for SOARCA. + +SOARCA leverages our internally developed [gauth library](https://github.com/COSSAS/gauth) as its underlying authentication framework. This library provides convenient Role-Based Access Control (RBAC) middleware, which manages authentication for various endpoints, such as the Playbook API. Based on OpenID Connect (OIDC), the library supports integration with multiple authentication providers. + +Currently, for the used [gauth library](https://github.com/COSSAS/gauth) the [Authentik](https://goauthentik.io/) authentication provider, an open-source solution that supports a wide range of authentication methods is supported and tested. As such other OIDC-based providers might not be compatible. + +## Supported OIDC-Based Auth Providers + +- [Authentik](https://goauthentik.io/) + +## Enabling RBAC + +Enabling RBAC can be done by setting the `AUTH_ENABLED: true`. + +{{< tabpane langEqualsHeader=false >}} +{{< tab header="`.env`" lang="txt" >}} +AUTH_ENABLED: true +AUTH_GROUP: "soarca_admin" +OIDC_ISSUER: "https://authentikuri:9443/application/u/test/" +OIDC_CLIENT_SECRET: "SOME_CLIENT_SECRET" +OIDC_CLIENT_ID: "SOME_CLIENT_ID" +OIDC_SKIP_TLS_VERIFY: true +{{< /tab >}} +{{< /tabpane >}} + +## Setting up Authentik with SOARCA + +Next, we need to obtain variables such as `OIDC_ISSUER` etc. This section will describe how we can setup [Authentik](https://goauthentik.io/). + +### Spinning up Authentik + +Instruction and docker-compose on how to bundle SOARCA with Authentik will come! + +### Making an authentication provider + +In Authentik first setup a new provider. This can be done under `Applications` -> `Providers` ->`Create`. For the provider type select the `OAuth2/OpenID provider` from the various options. An example configuration is given below: + +{{% alert title="Note" color="primary" %}} +We use an token lifetime of **8 hours**, since the [SOARCA-GUI](https://github.com/COSSAS/SOARCA-GUI) uses this token for client validation. As we do not want the user to login every so minute. It is advised to set this to 8 hours. +{{% /alert %}} + +Next, we need to set in the advanced protocol settings the token expiration lifetime needs to be changed to **8 hours**. + +![core](/SOARCA/images/installation_configuration/authentik_setup/setup-provider.png) + +![core](/SOARCA/images/installation_configuration/authentik_setup/change-lifetime.png) + +Endpoints for the auth provider can also be found here: + +![core](/SOARCA/images/installation_configuration/authentik_setup/endpoints.png) + +### Making an application + +Next, we can create a new application as shown in the picture below. A new application can be added under `Applications` --> `Create` Add the earlier made provider to this application. + +![core](/SOARCA/images/installation_configuration/authentik_setup/setting-application.png) + +### Setting the authentication provider + +Next, under `providers` -> `soarca-auth-provider` -> `edit` we can find the following overview: + +![core](/SOARCA/images/installation_configuration/authentik_setup/view-provider.png) + +Here we can find the: + +- Client ID: `some random stuff` +- Client Secret: `some other random stuff` +- Redirect Url: Optional, should be set when using for the SOARCA-GUI explained [here] + +![core](/SOARCA/images/installation_configuration/authentik_setup/editing-provider.png) + +We only use the Authentik integration for token validation on the SOARCA side. As such, only the `OIDC_CLIENT_ID` is required here. For the SOARCA-GUI, we would need the `OIDC_CLIENT_SECRET`. + +{{% alert title="Warning" color="warning" %}} +It is not advised to run Authentik like this! Please setup TLS certificates in a real environment and set the `OIDC_SKIP_TLS_VERIFY` to `false`. +{{% /alert %}} + +Set these variables in the environment variables settings, for example: +{{< tabpane langEqualsHeader=false >}} +{{< tab header="`.env`" lang="txt" >}} +AUTH_ENABLED: true +AUTH_GROUP: "soarca_admin" +OIDC_ISSUER: "https://authentikuri/application/o/does-providing-for-soarca/" +OIDC_CLIENT_ID: "WxUcBMGZdI7c0e5oYp6mYdEd64acpXSuWKh8zBH5" +OIDC_SKIP_TLS_VERIFY: true +{{< /tab >}} + +{{< tab header="`bash`" lang="bash" >}} +export AUTH_ENABLED=true +export AUTH_GROUP="soarca_admin" +export OIDC_ISSUER="https://authentikuri:9443/application/o/does-providing-for-soarca/" +export OIDC_CLIENT_ID="WxUcBMGZdI7c0e5oYp6mYdEd64acpXSuWKh8zBH5" +export OIDC_SKIP_TLS_VERIFY=true +{{< /tab >}} +{{< /tabpane >}} + +### Adding SOARCA user group and users + +{{% alert title="Note" color="primary" %}} +Again, for the current version of the implementation we only support one group to differentiate between access to the different endpoint. We plan for a later version of SOARCA to have different groups/permissions for a given API endpoint. +{{% /alert %}} + +For the current version of SOARCA and the gauth library the access to the API for a given user is dependent on the required set `AUTH_GROUP`. Users are required to be in the same group as the group that has been set through this variable. Currently, there is not yet control over which group can access a specific API or route grooup. This feature is scheduled for a future version of SOARCA. In the example below, the `AUTH_GROUP: soarca_admin` is set. + +Next, we require to setup a group in Authentik that is called `soarca_admin` as explained earlier. The to be obtained tokens from Authentik needs to have this group information as this will be checked by the middleware. A group can be created under `Directory` -> `Groups` -> `New`. + +Under `users` normal as as service accounts can be created. We advise for machine-to-machine implementation service accounts, and for normal users (used for example for SOARCA-GUI logins) normal accounts. Now we can make an users and add to the `soarca_admin` group. Make use under the application that this group is added to the application provider that we have setup earlier, otherwise the grants of token might fail. + +![core](/SOARCA/images/installation_configuration/authentik_setup/groups.png) + +![core](/SOARCA/images/installation_configuration/authentik_setup/add-user.png) + +![core](/SOARCA/images/installation_configuration/authentik_setup/add-groups.png) + +### Authentication with Bearer + +Now that authentication and authorization is enabled, every request requires to have a set `Authorization: Bearer ` header. + +``` +POST /trigger/playbook/ HTTP/1.1 +Host: localhost:8080 +Content-Type: application/json +Authorization: Bearer +Content-Length: 2345 + +{ + "type": "playbook", + "spec_version": "cacao-2.0", + "id": "playbook--300270f9-0e64-42c8-93cc-0927edbe3ae7", + "name": "Example ssh", + ... +} +``` + +The [gauth library](https://github.com/COSSAS/gauth) will validate this bearer token against the setup Authentik provider and grant the user or application access. Replace the token with a working bearer token. + +{{% alert title="Tip" %}} +For obtaining an access (bearer) token for Authentik, we have provided an example [here](https://github.com/COSSAS/gauth/examples/m2m) +{{% /alert %}} + +An example curl command is provided below: + +{{< tabpane langEqualsHeader=false >}} +{{< tab header="`bash`" lang="bash" >}} +curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer " -d @./example/ssh-playbook.json localhost:8080/trigger/playbook +{{< /tab >}} +{{< /tabpane >}} diff --git a/docs/content/en/docs/release-notes/_index.md b/docs/content/en/docs/release-notes/_index.md index ef8a8303..495766b7 100644 --- a/docs/content/en/docs/release-notes/_index.md +++ b/docs/content/en/docs/release-notes/_index.md @@ -1,19 +1,21 @@ --- title: Release Notes -weight: 6 +weight: 7 description: --- ## V1.0 ----- + +---- 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 - - HTTP API - - OpenC2 + - SSH + - HTTP API + - OpenC2 - Logging capabilities - Efficient storage for playbooks -- Design fin-protocol: the protocol description between SOARCA and the `TO BE ADDED` \ No newline at end of file +- Design fin-protocol: the protocol description between SOARCA and the `TO BE ADDED` + diff --git a/docs/content/en/docs/soarca-extensions/_index.md b/docs/content/en/docs/soarca-extensions/_index.md index 95c632e9..8d5e8080 100644 --- a/docs/content/en/docs/soarca-extensions/_index.md +++ b/docs/content/en/docs/soarca-extensions/_index.md @@ -10,7 +10,7 @@ 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](https://github.com/COSSAS/SOARCA/milestones). +SOARCA V.1.0.X implements currently the following native capalities: **HTTP capability**, **OpenC2 capability**, **SSH capability**, and **PowerShell (WINRM)**. Other core capabilities are part of our milestones which can be found [here](https://github.com/COSSAS/SOARCA/milestones). {{% /alert %}} 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. diff --git a/docs/static/images/installation_configuration/authentik_setup/add-groups.png b/docs/static/images/installation_configuration/authentik_setup/add-groups.png new file mode 100644 index 00000000..7ee7833d Binary files /dev/null and b/docs/static/images/installation_configuration/authentik_setup/add-groups.png differ diff --git a/docs/static/images/installation_configuration/authentik_setup/add-user.png b/docs/static/images/installation_configuration/authentik_setup/add-user.png new file mode 100644 index 00000000..80f6ae09 Binary files /dev/null and b/docs/static/images/installation_configuration/authentik_setup/add-user.png differ diff --git a/docs/static/images/installation_configuration/authentik_setup/change-lifetime.png b/docs/static/images/installation_configuration/authentik_setup/change-lifetime.png new file mode 100644 index 00000000..91fac812 Binary files /dev/null and b/docs/static/images/installation_configuration/authentik_setup/change-lifetime.png differ diff --git a/docs/static/images/installation_configuration/authentik_setup/editing-provider.png b/docs/static/images/installation_configuration/authentik_setup/editing-provider.png new file mode 100644 index 00000000..71e756ef Binary files /dev/null and b/docs/static/images/installation_configuration/authentik_setup/editing-provider.png differ diff --git a/docs/static/images/installation_configuration/authentik_setup/endpoints.png b/docs/static/images/installation_configuration/authentik_setup/endpoints.png new file mode 100644 index 00000000..ae0e81cf Binary files /dev/null and b/docs/static/images/installation_configuration/authentik_setup/endpoints.png differ diff --git a/docs/static/images/installation_configuration/authentik_setup/groups.png b/docs/static/images/installation_configuration/authentik_setup/groups.png new file mode 100644 index 00000000..503fd167 Binary files /dev/null and b/docs/static/images/installation_configuration/authentik_setup/groups.png differ diff --git a/docs/static/images/installation_configuration/authentik_setup/setting-application.png b/docs/static/images/installation_configuration/authentik_setup/setting-application.png new file mode 100644 index 00000000..8a185e06 Binary files /dev/null and b/docs/static/images/installation_configuration/authentik_setup/setting-application.png differ diff --git a/docs/static/images/installation_configuration/authentik_setup/setup-provider.png b/docs/static/images/installation_configuration/authentik_setup/setup-provider.png new file mode 100644 index 00000000..a297800d Binary files /dev/null and b/docs/static/images/installation_configuration/authentik_setup/setup-provider.png differ diff --git a/docs/static/images/installation_configuration/authentik_setup/view-provider.png b/docs/static/images/installation_configuration/authentik_setup/view-provider.png new file mode 100644 index 00000000..f2ab3bff Binary files /dev/null and b/docs/static/images/installation_configuration/authentik_setup/view-provider.png differ diff --git a/docs/static/openapi/swagger.json b/docs/static/openapi/swagger.json index 00e53fcc..ee7eee09 100644 --- a/docs/static/openapi/swagger.json +++ b/docs/static/openapi/swagger.json @@ -1,7 +1,9 @@ { "swagger": "2.0", "info": { - "contact": {} + "title": "SOARCA API", + "contact": {}, + "version": "1.0.0" }, "paths": { "/playbook/": { @@ -23,6 +25,12 @@ "$ref": "#/definitions/cacao.Playbook" } } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.Error" + } } } }, @@ -55,6 +63,12 @@ "schema": { "$ref": "#/definitions/cacao.Playbook" } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.Error" + } } } } @@ -78,6 +92,12 @@ "$ref": "#/definitions/api.PlaybookMeta" } } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.Error" + } } } } @@ -110,6 +130,12 @@ "schema": { "$ref": "#/definitions/cacao.Playbook" } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.Error" + } } } }, @@ -149,6 +175,12 @@ "schema": { "$ref": "#/definitions/cacao.Playbook" } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.Error" + } } } }, @@ -176,6 +208,122 @@ "responses": { "200": { "description": "OK" + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.Error" + } + } + } + } + }, + "/reporter": { + "get": { + "description": "return all stored executions", + "produces": [ + "application/json" + ], + "tags": [ + "reporter" + ], + "summary": "gets all the UUIDs for the executions that can be retireved", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/api.PlaybookExecutionReport" + } + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.Error" + } + } + } + } + }, + "/reporter/{id}": { + "get": { + "description": "return execution information", + "produces": [ + "application/json" + ], + "tags": [ + "reporter" + ], + "summary": "gets information about an ongoing playbook execution", + "parameters": [ + { + "type": "string", + "description": "execution identifier", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/api.PlaybookExecutionReport" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.Error" + } + } + } + } + }, + "/status": { + "get": { + "description": "return SOARCA status", + "produces": [ + "application/json" + ], + "tags": [ + "status" + ], + "summary": "gets the SOARCA status", + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/api.Status" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.Error" + } + } + } + } + }, + "/status/ping": { + "get": { + "description": "return SOARCA status", + "produces": [ + "text/plain" + ], + "tags": [ + "ping pong" + ], + "summary": "ping to see if SOARCA is up returns pong", + "responses": { + "200": { + "description": "OK", + "schema": { + "type": "string" + } } } } @@ -206,13 +354,153 @@ ], "responses": { "200": { - "description": "{\"execution_id\":\"uuid\",\"payload\":\"playbook--uuid\"}" + "description": "OK", + "schema": { + "$ref": "#/definitions/api.Execution" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.Error" + } + } + } + } + }, + "/trigger/playbook/{id}": { + "post": { + "description": "trigger playbook by id", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "trigger" + ], + "summary": "trigger a playbook by id that is stored in SOARCA", + "parameters": [ + { + "type": "string", + "description": "playbook ID", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "playbook", + "name": "data", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/cacao.Variables" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/api.Execution" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/api.Error" + } } } } } }, "definitions": { + "api.Error": { + "type": "object", + "required": [ + "message", + "original-call", + "status" + ], + "properties": { + "downstream-call": { + "type": "string", + "example": "{\"some\" : \"json\"}" + }, + "message": { + "type": "string", + "example": "missing argument in call" + }, + "original-call": { + "type": "string", + "example": "/example/route" + }, + "status": { + "type": "integer", + "example": 400 + } + } + }, + "api.Execution": { + "type": "object", + "required": [ + "execution_id", + "payload" + ], + "properties": { + "execution_id": { + "type": "string", + "example": "2c855cd6-bbce-402f-a143-3d6eec346c08" + }, + "payload": { + "type": "string", + "example": "playbook--0cec398c-db69-4f17-bde4-8ecbcc4a8879" + } + } + }, + "api.PlaybookExecutionReport": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "ended": { + "type": "string" + }, + "execution_id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "playbook_id": { + "type": "string" + }, + "request_interval": { + "type": "integer" + }, + "started": { + "type": "string" + }, + "status": { + "type": "string" + }, + "status_text": { + "type": "string" + }, + "step_results": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/api.StepExecutionReport" + } + }, + "type": { + "type": "string" + } + } + }, "api.PlaybookMeta": { "type": "object", "properties": { @@ -239,6 +527,93 @@ } } }, + "api.Status": { + "type": "object", + "properties": { + "mode": { + "type": "string" + }, + "runtime": { + "type": "string" + }, + "time": { + "type": "string" + }, + "uptime": { + "$ref": "#/definitions/api.Uptime" + }, + "version": { + "type": "string" + } + } + }, + "api.StepExecutionReport": { + "type": "object", + "properties": { + "automated_execution": { + "type": "boolean" + }, + "commands_b64": { + "type": "array", + "items": { + "type": "string" + } + }, + "description": { + "type": "string" + }, + "ended": { + "type": "string" + }, + "executed_by": { + "type": "string" + }, + "execution_id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "started": { + "type": "string" + }, + "status": { + "type": "string" + }, + "status_text": { + "type": "string" + }, + "step_id": { + "type": "string" + }, + "variables": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/cacao.Variable" + } + } + } + }, + "api.Uptime": { + "type": "object", + "properties": { + "milliseconds": { + "type": "integer" + }, + "since": { + "type": "string" + } + } + }, + "cacao.Addresses": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + } + }, "cacao.AgentTarget": { "type": "object", "required": [ @@ -247,13 +622,7 @@ ], "properties": { "address": { - "type": "object", - "additionalProperties": { - "type": "array", - "items": { - "type": "string" - } - } + "$ref": "#/definitions/cacao.Addresses" }, "agent_target_extensions": { "$ref": "#/definitions/cacao.Extensions" @@ -299,6 +668,12 @@ } } }, + "cacao.AgentTargets": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/cacao.AgentTarget" + } + }, "cacao.AuthenticationInformation": { "type": "object", "required": [ @@ -343,6 +718,18 @@ } } }, + "cacao.AuthenticationInformations": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/cacao.AuthenticationInformation" + } + }, + "cacao.Cases": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, "cacao.CivicLocation": { "type": "object", "properties": { @@ -410,13 +797,7 @@ "type": "string" }, "headers": { - "type": "object", - "additionalProperties": { - "type": "array", - "items": { - "type": "string" - } - } + "$ref": "#/definitions/cacao.Headers" }, "playbook_activity": { "type": "string" @@ -535,6 +916,12 @@ } } }, + "cacao.DataMarkings": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/cacao.DataMarking" + } + }, "cacao.ExtensionDefinition": { "type": "object", "required": [ @@ -556,6 +943,9 @@ "$ref": "#/definitions/cacao.ExternalReferences" } }, + "id": { + "type": "string" + }, "name": { "type": "string" }, @@ -570,6 +960,12 @@ } } }, + "cacao.ExtensionDefinitions": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/cacao.ExtensionDefinition" + } + }, "cacao.Extensions": { "type": "object", "additionalProperties": true @@ -600,6 +996,15 @@ } } }, + "cacao.Headers": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + } + }, "cacao.Playbook": { "type": "object", "required": [ @@ -615,118 +1020,187 @@ ], "properties": { "agent_definitions": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/cacao.AgentTarget" - } + "description": "Map of agent definitions used by the workflow steps", + "allOf": [ + { + "$ref": "#/definitions/cacao.AgentTargets" + } + ] }, "authentication_info_definitions": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/cacao.AuthenticationInformation" - } + "description": "Map of authentication information objects", + "allOf": [ + { + "$ref": "#/definitions/cacao.AuthenticationInformations" + } + ] }, "created": { - "type": "string" + "description": "Timestamp of the creation of the playbook", + "type": "string", + "example": "2024-01-01T09:00:00.000Z" }, "created_by": { - "type": "string" + "description": "UUID referring to identity", + "type": "string", + "example": "identity--96abab60-238a-44ff-8962-5806aa60cbce" }, "data_marking_definitions": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/cacao.DataMarking" - } + "description": "Map of datamarking definitions", + "allOf": [ + { + "$ref": "#/definitions/cacao.DataMarkings" + } + ] }, "derived_from": { + "description": "Playbook id that this playbook is derived from", "type": "array", "items": { "type": "string" - } + }, + "example": [ + "[\"playbook--77c4c428-6304-4950-93ff-83c5224cb67a\"]" + ] }, "description": { - "type": "string" + "description": "A descriptive text to indicate what your playbook does", + "type": "string", + "example": "This is an example investigation playbook" }, "extension_definitions": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/cacao.ExtensionDefinition" - } + "description": "Map of extension definitions used by the workflow steps", + "allOf": [ + { + "$ref": "#/definitions/cacao.ExtensionDefinitions" + } + ] }, "external_references": { + "description": "List of external reference objects", "type": "array", "items": { "$ref": "#/definitions/cacao.ExternalReferences" } }, "id": { - "type": "string" + "description": "Used by SOARCA so refer to the object while loading it from the database", + "type": "string", + "example": "playbook--77c4c428-6304-4950-93ff-83c5fd4cb67a" }, "impact": { - "type": "integer" + "description": "A priority number ranging 0 - 100", + "type": "integer", + "example": 100 }, "labels": { + "description": "List of labels to label playbook", "type": "array", "items": { "type": "string" } }, "markings": { + "description": "List of datamarking identifiers", "type": "array", "items": { "type": "string" - } + }, + "example": [ + "[marking-statement--6424867b-0440-4885-bd0b-604d51786d06]" + ] }, "modified": { - "type": "string" + "description": "Timestamp of the last modification of the playbook", + "type": "string", + "example": "2024-01-01T09:00:00.000Z" }, "name": { - "type": "string" + "description": "An indicative name of the playbook", + "type": "string", + "example": "Investigation playbook" }, "playbook_extensions": { - "$ref": "#/definitions/cacao.Extensions" + "description": "Map of extensions used by the playbook", + "allOf": [ + { + "$ref": "#/definitions/cacao.Extensions" + } + ] }, "playbook_types": { + "description": "Should be of the CACAO playbook-type-ov", "type": "array", "items": { "type": "string" - } + }, + "example": [ + "investigation" + ] }, "playbook_variables": { - "$ref": "#/definitions/cacao.Variables" + "description": "Map of variables that are global to the playbook", + "allOf": [ + { + "$ref": "#/definitions/cacao.Variables" + } + ] }, "priority": { - "type": "integer" + "description": "A priority number ranging 0 - 100", + "type": "integer", + "example": 100 }, "severity": { - "type": "integer" + "description": "A priority number ranging 0 - 100", + "type": "integer", + "example": 100 }, "spec_version": { - "type": "string" + "description": "Indicate the specification version cacao-2.0 is the only supported version at this time", + "type": "string", + "example": "cacao-2.0" }, "target_definitions": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/cacao.AgentTarget" - } + "description": "Map of target definitions used by the workflow steps", + "allOf": [ + { + "$ref": "#/definitions/cacao.AgentTargets" + } + ] }, "type": { - "type": "string" + "description": "Must be playbook", + "type": "string", + "example": "playbook" }, "valid_from": { - "type": "string" + "description": "Timestamp from when the playbook is valid", + "type": "string", + "example": "2024-01-01T09:00:00.000Z" }, "valid_until": { - "type": "string" + "description": "Timestamp until when the playbook is valid", + "type": "string", + "example": "2124-01-01T09:00:00.000Z" }, "workflow": { - "$ref": "#/definitions/cacao.Workflow" + "description": "Map of workflow steps keyed by the step id", + "allOf": [ + { + "$ref": "#/definitions/cacao.Workflow" + } + ] }, "workflow_exception": { - "type": "string" + "description": "Step that marks the actions that need to be taken when an exception occurs", + "type": "string", + "example": "end--37bea005-4a36-4a77-bd1f-79a6e4682a13" }, "workflow_start": { - "type": "string" + "description": "Start step of the playbook MUST be of step type START", + "type": "string", + "example": "start--07bea005-4a36-4a77-bd1f-79a6e4682a13" } } }, @@ -743,10 +1217,7 @@ "type": "string" }, "cases": { - "type": "object", - "additionalProperties": { - "type": "string" - } + "$ref": "#/definitions/cacao.Cases" }, "commands": { "type": "array", @@ -847,22 +1318,34 @@ ], "properties": { "constant": { - "type": "boolean" + "description": "Indicate if it's a constant", + "type": "boolean", + "example": false }, "description": { - "type": "string" + "description": "A description of the variable", + "type": "string", + "example": "some string" }, "external": { - "type": "boolean" + "description": "Indicate if it's external", + "type": "boolean", + "example": false }, "name": { - "type": "string" + "description": "The name of the variable in the style __variable_name__", + "type": "string", + "example": "__example_string__" }, "type": { - "type": "string" + "description": "Type of the variable should be OASIS variable-type-ov", + "type": "string", + "example": "string" }, "value": { - "type": "string" + "description": "The value of the that the variable will evaluate to", + "type": "string", + "example": "this is a value" } } }, diff --git a/docs/static/openapi/swagger.yaml b/docs/static/openapi/swagger.yaml index 9c3c952a..1e707e57 100644 --- a/docs/static/openapi/swagger.yaml +++ b/docs/static/openapi/swagger.yaml @@ -1,4 +1,62 @@ definitions: + api.Error: + properties: + downstream-call: + example: '{"some" : "json"}' + type: string + message: + example: missing argument in call + type: string + original-call: + example: /example/route + type: string + status: + example: 400 + type: integer + required: + - message + - original-call + - status + type: object + api.Execution: + properties: + execution_id: + example: 2c855cd6-bbce-402f-a143-3d6eec346c08 + type: string + payload: + example: playbook--0cec398c-db69-4f17-bde4-8ecbcc4a8879 + type: string + required: + - execution_id + - payload + type: object + api.PlaybookExecutionReport: + properties: + description: + type: string + ended: + type: string + execution_id: + type: string + name: + type: string + playbook_id: + type: string + request_interval: + type: integer + started: + type: string + status: + type: string + status_text: + type: string + step_results: + additionalProperties: + $ref: '#/definitions/api.StepExecutionReport' + type: object + type: + type: string + type: object api.PlaybookMeta: properties: description: @@ -16,14 +74,67 @@ definitions: valid_until: type: string type: object - cacao.AgentTarget: + api.Status: properties: - address: + mode: + type: string + runtime: + type: string + time: + type: string + uptime: + $ref: '#/definitions/api.Uptime' + version: + type: string + type: object + api.StepExecutionReport: + properties: + automated_execution: + type: boolean + commands_b64: + items: + type: string + type: array + description: + type: string + ended: + type: string + executed_by: + type: string + execution_id: + type: string + name: + type: string + started: + type: string + status: + type: string + status_text: + type: string + step_id: + type: string + variables: additionalProperties: - items: - type: string - type: array + $ref: '#/definitions/cacao.Variable' type: object + type: object + api.Uptime: + properties: + milliseconds: + type: integer + since: + type: string + type: object + cacao.Addresses: + additionalProperties: + items: + type: string + type: array + type: object + cacao.AgentTarget: + properties: + address: + $ref: '#/definitions/cacao.Addresses' agent_target_extensions: $ref: '#/definitions/cacao.Extensions' authentication_info: @@ -56,6 +167,10 @@ definitions: - name - type type: object + cacao.AgentTargets: + additionalProperties: + $ref: '#/definitions/cacao.AgentTarget' + type: object cacao.AuthenticationInformation: properties: description: @@ -85,6 +200,14 @@ definitions: required: - type type: object + cacao.AuthenticationInformations: + additionalProperties: + $ref: '#/definitions/cacao.AuthenticationInformation' + type: object + cacao.Cases: + additionalProperties: + type: string + type: object cacao.CivicLocation: properties: administrative_area: @@ -127,11 +250,7 @@ definitions: description: type: string headers: - additionalProperties: - items: - type: string - type: array - type: object + $ref: '#/definitions/cacao.Headers' playbook_activity: type: string type: @@ -213,6 +332,10 @@ definitions: - id - type type: object + cacao.DataMarkings: + additionalProperties: + $ref: '#/definitions/cacao.DataMarking' + type: object cacao.ExtensionDefinition: properties: created_by: @@ -223,6 +346,8 @@ definitions: items: $ref: '#/definitions/cacao.ExternalReferences' type: array + id: + type: string name: type: string schema: @@ -237,6 +362,10 @@ definitions: - type - version type: object + cacao.ExtensionDefinitions: + additionalProperties: + $ref: '#/definitions/cacao.ExtensionDefinition' + type: object cacao.Extensions: additionalProperties: true type: object @@ -257,83 +386,139 @@ definitions: required: - name type: object + cacao.Headers: + additionalProperties: + items: + type: string + type: array + type: object cacao.Playbook: properties: agent_definitions: - additionalProperties: - $ref: '#/definitions/cacao.AgentTarget' - type: object + allOf: + - $ref: '#/definitions/cacao.AgentTargets' + description: Map of agent definitions used by the workflow steps authentication_info_definitions: - additionalProperties: - $ref: '#/definitions/cacao.AuthenticationInformation' - type: object + allOf: + - $ref: '#/definitions/cacao.AuthenticationInformations' + description: Map of authentication information objects created: + description: Timestamp of the creation of the playbook + example: "2024-01-01T09:00:00.000Z" type: string created_by: + description: UUID referring to identity + example: identity--96abab60-238a-44ff-8962-5806aa60cbce type: string data_marking_definitions: - additionalProperties: - $ref: '#/definitions/cacao.DataMarking' - type: object + allOf: + - $ref: '#/definitions/cacao.DataMarkings' + description: Map of datamarking definitions derived_from: + description: Playbook id that this playbook is derived from + example: + - '["playbook--77c4c428-6304-4950-93ff-83c5224cb67a"]' items: type: string type: array description: + description: A descriptive text to indicate what your playbook does + example: This is an example investigation playbook type: string extension_definitions: - additionalProperties: - $ref: '#/definitions/cacao.ExtensionDefinition' - type: object + allOf: + - $ref: '#/definitions/cacao.ExtensionDefinitions' + description: Map of extension definitions used by the workflow steps external_references: + description: List of external reference objects items: $ref: '#/definitions/cacao.ExternalReferences' type: array id: + description: Used by SOARCA so refer to the object while loading it from the + database + example: playbook--77c4c428-6304-4950-93ff-83c5fd4cb67a type: string impact: + description: A priority number ranging 0 - 100 + example: 100 type: integer labels: + description: List of labels to label playbook items: type: string type: array markings: + description: List of datamarking identifiers + example: + - '[marking-statement--6424867b-0440-4885-bd0b-604d51786d06]' items: type: string type: array modified: + description: Timestamp of the last modification of the playbook + example: "2024-01-01T09:00:00.000Z" type: string name: + description: An indicative name of the playbook + example: Investigation playbook type: string playbook_extensions: - $ref: '#/definitions/cacao.Extensions' + allOf: + - $ref: '#/definitions/cacao.Extensions' + description: Map of extensions used by the playbook playbook_types: + description: Should be of the CACAO playbook-type-ov + example: + - investigation items: type: string type: array playbook_variables: - $ref: '#/definitions/cacao.Variables' + allOf: + - $ref: '#/definitions/cacao.Variables' + description: Map of variables that are global to the playbook priority: + description: A priority number ranging 0 - 100 + example: 100 type: integer severity: + description: A priority number ranging 0 - 100 + example: 100 type: integer spec_version: + description: Indicate the specification version cacao-2.0 is the only supported + version at this time + example: cacao-2.0 type: string target_definitions: - additionalProperties: - $ref: '#/definitions/cacao.AgentTarget' - type: object + allOf: + - $ref: '#/definitions/cacao.AgentTargets' + description: Map of target definitions used by the workflow steps type: + description: Must be playbook + example: playbook type: string valid_from: + description: Timestamp from when the playbook is valid + example: "2024-01-01T09:00:00.000Z" type: string valid_until: + description: Timestamp until when the playbook is valid + example: "2124-01-01T09:00:00.000Z" type: string workflow: - $ref: '#/definitions/cacao.Workflow' + allOf: + - $ref: '#/definitions/cacao.Workflow' + description: Map of workflow steps keyed by the step id workflow_exception: + description: Step that marks the actions that need to be taken when an exception + occurs + example: end--37bea005-4a36-4a77-bd1f-79a6e4682a13 type: string workflow_start: + description: Start step of the playbook MUST be of step type START + example: start--07bea005-4a36-4a77-bd1f-79a6e4682a13 type: string required: - created @@ -353,9 +538,7 @@ definitions: authentication_info: type: string cases: - additionalProperties: - type: string - type: object + $ref: '#/definitions/cacao.Cases' commands: items: $ref: '#/definitions/cacao.Command' @@ -422,16 +605,28 @@ definitions: cacao.Variable: properties: constant: + description: Indicate if it's a constant + example: false type: boolean description: + description: A description of the variable + example: some string type: string external: + description: Indicate if it's external + example: false type: boolean name: + description: The name of the variable in the style __variable_name__ + example: __example_string__ type: string type: + description: Type of the variable should be OASIS variable-type-ov + example: string type: string value: + description: The value of the that the variable will evaluate to + example: this is a value type: string required: - type @@ -446,6 +641,8 @@ definitions: type: object info: contact: {} + title: SOARCA API + version: 1.0.0 paths: /playbook/: get: @@ -459,6 +656,10 @@ paths: items: $ref: '#/definitions/cacao.Playbook' type: array + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.Error' summary: gets all the UUIDs for the stored playbooks tags: - playbook @@ -480,6 +681,10 @@ paths: description: OK schema: $ref: '#/definitions/cacao.Playbook' + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.Error' summary: submit playbook via the api tags: - playbook @@ -499,6 +704,10 @@ paths: responses: "200": description: OK + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.Error' summary: delete playbook by Id tags: - playbook @@ -519,6 +728,10 @@ paths: description: OK schema: $ref: '#/definitions/cacao.Playbook' + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.Error' summary: get CACAO playbook by its ID tags: - playbook @@ -545,6 +758,10 @@ paths: description: OK schema: $ref: '#/definitions/cacao.Playbook' + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.Error' summary: update playbook tags: - playbook @@ -560,9 +777,85 @@ paths: items: $ref: '#/definitions/api.PlaybookMeta' type: array + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.Error' summary: gets all the meta information for the stored playbooks tags: - playbook + /reporter: + get: + description: return all stored executions + produces: + - application/json + responses: + "200": + description: OK + schema: + items: + $ref: '#/definitions/api.PlaybookExecutionReport' + type: array + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.Error' + summary: gets all the UUIDs for the executions that can be retireved + tags: + - reporter + /reporter/{id}: + get: + description: return execution information + parameters: + - description: execution identifier + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/api.PlaybookExecutionReport' + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.Error' + summary: gets information about an ongoing playbook execution + tags: + - reporter + /status: + get: + description: return SOARCA status + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/api.Status' + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.Error' + summary: gets the SOARCA status + tags: + - status + /status/ping: + get: + description: return SOARCA status + produces: + - text/plain + responses: + "200": + description: OK + schema: + type: string + summary: ping to see if SOARCA is up returns pong + tags: + - ping pong /trigger/playbook: post: consumes: @@ -579,8 +872,45 @@ paths: - application/json responses: "200": - description: '{"execution_id":"uuid","payload":"playbook--uuid"}' + description: OK + schema: + $ref: '#/definitions/api.Execution' + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.Error' summary: trigger a playbook by supplying a cacao playbook payload tags: - trigger + /trigger/playbook/{id}: + post: + consumes: + - application/json + description: trigger playbook by id + parameters: + - description: playbook ID + in: path + name: id + required: true + type: string + - description: playbook + in: body + name: data + required: true + schema: + $ref: '#/definitions/cacao.Variables' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/api.Execution' + "400": + description: Bad Request + schema: + $ref: '#/definitions/api.Error' + summary: trigger a playbook by id that is stored in SOARCA + tags: + - trigger swagger: "2.0"