cossas/soarca

SOARCA - The Open Source CACAO-based Security Orchestrator!

soarca's Issues

Update docs & fix logo locations

Enable github action for CI/CD

Describe the solution you'd like
Add ci/cd to github repo

Fix naming inconsistency for return variables of capabilities

Describe the bug
Variable naming in ssh, http and openc2 is not consistent with that of playbooks
cacao.Variables{"__soarca_ssh_result__": {Name: "result", Value: string(response)}}
cacao.Variables{"__soarca_http_result__": {Name: "result", Value: string(response)}}
cacao.Variables{"__soarca_openc2_http_result__": {Name: "result", Value: string(response)}}

This should be:
cacao.Variables{"__soarca_ssh_result__": {Name: "__soarca_ssh_result__", Value: string(response)}}
cacao.Variables{"__soarca_http_result__": {Name: "__soarca_http_result__", Value: string(response)}}
cacao.Variables{"__soarca_openc2_http_result__": {Name: "__soarca_openc2_http_result__", Value: string(response)}}

Only update documentation from feature/docs/* branch and master

Documentation is updated for all pull request this is not a usable strategy as other pr do not update docs regularly.

The solution is to create feature/docs/ matcher to only allow these to update docs live until we have a development deployment available for documentation.

Docs update + .gitignore

Add deployment of soarca binary and docker images

Add docker deployment and release ci to ci/cd

Make fins executable

Link the fin controller to the executor and decomposer.

Docker image missing ca-certificates

Describe the bug
The docker image is missing ca-certificates, so it can't validate http calls and fail.

To Reproduce provide details logs and steps
run docker container and execute playbook
{"component":"soarca/models/decoder","level":"error","msg":"jsonschema https://raw.githubusercontent.com/opencybersecurityalliance/cacao-roaster/main/lib/cacao-json-schemas/schemas/playbook.json compilation failed: Get "https://raw.githubusercontent.com/opencybersecurityalliance/cacao-roaster/main/lib/cacao-json-schemas/schemas/playbook.json\": tls: failed to verify certificate: x509: certificate signed by unknown authority","time":"2024-03-18T10:45:37Z"}

Expected behavior
Playbook execution

Use-Cases Section not found

Is your feature request related to a problem? Please describe.
I am reading through the doc, specifically the vision and concepts section. The last line in the subsection 'Current state of SOARCA', the link to Use-Cases seems to be missing.

Additional context

Update executor documentation

Is your feature request related to a problem? Please describe.
Update executor documentation to implement all step types

Update docs and deploy to Github pages

Add correct ci configuration to github pages ci and deploy them per branch

Validation with CACAO json schemas cds03

Currently the CACAO schema validation is performed at schemas at models/validators/schema.go, with the CACAO V2 draft 1. The most up to date is the CACAO V2 draft 3, at: "https://raw.githubusercontent.com/cyentific-rni/cacao-json-schemas/cacao-v2.0-csd03/schemas/playbook.json".

This feature request is to change the schema validation from CACAO V2 draft 1, to CACAO V2 draft 3

Update readme in accordance with COSSAS projects

Is your feature request related to a problem? Please describe.
The project readme is not in COSSAS template style this needs to be changed

Interpolate variables into commands and targets

Is your feature request related to a problem? Please describe.
This feature will introduce command interpolations into commands and targets in SOARCA

Implement variable handling and API for cacao variables

Name field is missing from variable in fin protocol

Describe the bug
The variable definition has the field name this is missing in the docs.

Versioning of Stored Playbooks

Versioning of stored playbooks

Currently SOARCA does not support versioning for stored playbooks.

Feature request that has been received from the community:

• https://cossas.github.io/SOARCA/docs/core-components/database/ If you want to support versioning of playbooks, the ID should be the combination of playbook ID, created, and modified timestamps.

This feature will be discussed internally with the team and put on the milestones.

Deploy docs on git tag push

Is your feature request related to a problem? Please describe.
The docs are not deployed on a git push of a tag this issue will fix that

go mody tidy has to be ran in the docs folder

Update http url field in agent target to address url

In CACAO V2 there is no http_url property in the agent/target object. The location for such information is in address[dname] (see section 7.8 in CACAO V2). At the moment our code still uses http_url.

Using http_url through the code and not address[dname] is also inconsistent with the official schemas (at https://github.com/oasis-open/cacao-json-schemas/blob/main/schemas/playbook.json), and fails validation with the official schemas.

The solution to this issue would be to

• change the schema selection to the one officially maintained,
• update all playbooks used for testing,
• change the cacao playbook model for marshalling, and update the internal logic that refers to httpUrl

Http and Fin capability do not implement GetType() string

Describe the bug
The Http and Fin capability do not implement GetType() string function so they cant be used as ICapability

Implement OpenC2 capability (using utils/http wrapper)

Document explicitly how to connect Fins

It is not yet evident from the documentation how and where to implement and connect fins.

The sequence for connecting a fin is roughly:

1. SOARCA is run with enable_fins to true
2. SOARCA interfaces an MQTT broker container to which a Fin process should connect
3. any Fin process connects to the MQTT container, and registers as fin to SOARCA according to protocol (evtl. using our libraries)
4. Playbooks which use the fin need to specify a soarca-fin agent. The "name" property of such fin agent should be consistent with the name of the Fin registered via protocol
5. Now all is set to execute playbooks with SOARCA fins

It would be nice to have this process described explicitly in the documentation

Fix empty authentication info check

Authentication information is an optional property. Currently, no authentication information corresponds to an empty authentication information struct passed to the capability.Execute() function, so it is always passed as either a populated or empty authentication information struct.

Http.utils addAuthTo function checks if authentication information is passed, by checking if it has nil value, or not. If it has nil value, then no auth headers are added, and no further auth info checks are performed.

The bug is in the fact that authentication information will never be "nil", but either a completely empty struct, or a non-completely empty struct. Hence it is always != "nil", and subsequent checks fail.

In this MR, the check is changed to compare the authentication information (passed to Execute for http and OpenC2 capabilities) to an empty struct, instead of to nil value.

Add example playbooks to example folder

Is your feature request related to a problem? Please describe.
Add 3 playbooks to show each capability

• SSH
• HTTP
• OPENC2

Update initialisation mathod

The api will use the same object for every run which does not allow for dynamic loading

Soarca swagger using docs folder

Fix docs according to feedback

Updates on the docs required:

• https://cossas.github.io/SOARCA/docs/core-components/api-design/ - “cacao playbook JSON” & “GET /status/playbook”: presents the CACAO v1.1 (instead of CACAO v2)

• Few URLs are resolving to the main page instead of the dedicated website. (E.g., fin ref for python and go in https://cossas.github.io/SOARCA/docs/soarca-extensions/)

• https://cossas.github.io/SOARCA/docs/core-components/modules/ - SSH capability: states the support for “private key” authentication. (The correct name is “public key” authentication. Nevertheless, CACAO v2 does not have that capability)

Inconsistency between two pages regarding soarca agent type:

• https://cossas.github.io/SOARCA/docs/core-components/executer/ - Native capabilities: “... The convention is that the agent type must equal soarca-, e.g. soarca-ssh or soarca-openc2-http.”
• https://cossas.github.io/SOARCA/docs/core-components/modules/ - Native modules in SOARCA: “... The agent should be of type soarca and have a name corresponding to soarca-[capability name].”

CI does not run on feature/docs

Describe the bug
The CI does not run on feature/docs/*

Improve code and check tests for fmt.println

Add logging in test to the testing framework.

Docs getting started + milestones + about soarca EU text

Is your feature request related to a problem? Please describe.

• Add getting started
• Link to milestones on github
• EU text
• Branch naming
• Remove blog
• update readme lables

Reporting logic and documentation

Design and implement additions to the architecture to integrate reporting of playbook handling and execution.

Reporting functionality should be extendible to allow implementation of integrations to report on third party tools.

Update release ci to also build :latest tag for docker hub

Is your feature request related to a problem? Please describe.
There is no latest build for docker hub this feature will add that

Expand executor interface

Is your feature request related to a problem? Please describe.
Expand executor interface to handle the playbook step types

Command.Headers are a map[string]string, but the spec says map[string][]string, so a list of strings instead

Describe the bug
Command.Headers are a map[string]string, but the spec says map[string][]string, so a list of strings instead

Fin protocol needs to send a final ack when receiving the result structure

Describe the bug
When receiving the result structure SOARCA needs to acknowledge this message.

Add playbook-action step typ to executor

Is your feature request related to a problem? Please describe.
The playbook-action step needs to load a playbook this needs a new executor

Reject branch in ci if not adhering to naming schema

Branches not adhering to the schema: (feature|bugfix|hotfix|development|release|master)/* are rejected in CI/CD

Docker build produces a not executable container

Describe the bug
Docker build produces a not executable container

To Reproduce provide details logs and steps
Run the following docker compose:

version: '3.7' services: soarca: image: cossas/soarca:0.8.99-test-zip3 container_name: soarca_server environment: PORT: 8080 MONGODB_URI: "mongodb://mongodb_container:27017" DATABASE_NAME: "soarca" DB_USERNAME: "root" DB_PASSWORD: "rootpassword" PLAYBOOK_API_LOG_LEVEL: trace DATABASE: "false" ports: - 127.0.0.1:8080:8080

output:
Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: exec: "./soarca": permission denied: unknown

Expected behavior

output:
soarca_server | {"component":"MAIN","level":"info","msg":"Version: 0.8.99-54-gbe76886","time":"2024-03-11T07:32:41Z"}
soarca_server |
soarca_server | _____ ____ _____ _____
soarca_server | / ___|/ __ \ /\ | __ \ / | /\
soarca_server | | ( | | | | / \ | |) | | / \
soarca_server | _ | | | |/ /\ \ | _ /| | / /\ \
soarca_server | ) | |__| / ____ | | \ | | / ____ \
soarca_server | |__/ _// __| _\_____// _
soarca_server |
soarca_server |
soarca_server |
soarca_server | [GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
soarca_server | - using env: export GIN_MODE=release
soarca_server | - using code: gin.SetMode(gin.ReleaseMode)
soarca_server |
soarca_server | {"component":"MAIN","level":"info","msg":"Buildtime: 2024-03-10T11:26:29+0100","time":"2024-03-11T07:32:41Z"}
soarca_server | {"component":"MAIN","level":"warning","msg":"Failed to read env variable, but will continue","time":"2024-03-11T07:32:41Z"}
soarca_server | {"component":"soarca/internal/controller","level":"info","msg":"Testing if this works","time":"2024-03-11T07:32:41Z"}
soarca_server | [GIN-debug] GET /coa/ --> soarca/routes/coa.Helloworld (1 handlers)
soarca_server | [GIN-debug] POST /coa/:coa-id --> soarca/routes/coa.id_tester (1 handlers)
soarca_server | [GIN-debug] PUT /coa/:coa-id --> soarca/routes/coa.id_tester (1 handlers)
soarca_server | [GIN-debug] DELETE /coa/:coa-id --> soarca/routes/coa.id_tester (1 handlers)
soarca_server | [GIN-debug] GET /status/ --> soarca/routes/status.Helloworld (1 handlers)
soarca_server | [GIN-debug] GET /status/playbook/:id --> soarca/routes/status.id_tester (1 handlers)
soarca_server | [GIN-debug] GET /status/coa/:id --> soarca/routes/status.id_tester (1 handlers)
soarca_server | [GIN-debug] GET /status/history --> soarca/routes/status.Helloworld (1 handlers)
soarca_server | [GIN-debug] POST /operator/coa/:coa-id --> soarca/routes/operator.Helloworld (1 handlers)
soarca_server | [GIN-debug] POST /trigger/playbook --> soarca/routes/trigger.(*TriggerApi).Execute-fm (1 handlers)
soarca_server | [GIN-debug] GET /swagger/*any --> github.com/swaggo/gin-swagger.CustomWrapHandler.func1 (1 handlers)
soarca_server | [GIN-debug] [WARNING] You trusted all proxies, this is NOT safe. We recommend you to set a value.
soarca_server | Please check https://pkg.go.dev/github.com/gin-gonic/gin#readme-don-t-trust-all-proxies for details.
soarca_server | [GIN-debug] Listening and serving HTTP on :8080

Environment information
Docker compose see reproduce

Use http wrapper in http capability

Change usage of net/http package in http capability to use SOARCA's utils/http

Add soarca output to documentation homepage

docker-compose.yml ENABLE_FINS error

When using sudo docker-compose up you get an error:

ERROR: The Compose file './docker-compose.yml' is invalid because:
services.soarca.environment.ENABLE_FINS contains true, which is an invalid type, it should be a string, number, or a null

This is because ENABLE_FINS: true is not between "", the setting should be ENABLE_FINS: "true".

If you change this manually it works.

Fin controller

Describe the solution you'd like
Fin controller package to allow for fin registration

Additional context
SOARCA has a extensible architecture realised by so called Fins, these need to be managed.

Prevent .env file to be committed

Describe the bug
.gitignore does not contain a **.env

Pull soarca:latest when running docker compose

Is your feature request related to a problem? Please describe.
Add docker compose file for soarca running

Need to add authentication to MQTT

Update on landing page background

Fin protocol authentication model needs to be map of uuid:autstruct

Describe the bug
A clear and concise description of what the bug is.

To Reproduce provide details logs and steps

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots
If applicable, add screenshots to help explain your problem.

Environment information
For example, docker deployment, native run (platform).

Additional context
Add any other context about the problem here.

External reference model is not according to cacao spec

Describe the bug
The cacao model misses the properties:

• external_id
• reference_id

see https://docs.oasis-open.org/cacao/security-playbooks/v2.0/cs01/security-playbooks-v2.0-cs01.html#_Toc152256542

Add openC2 to initialisation

Is your feature request related to a problem? Please describe.
Add openC2 to initialisation