Getting Started

Getting SOARCA quickly setup

Prerequisites

Before you begin, you might need to install the following tools (Linux Ubuntu 22.04 adapt for your needs):

golang
go gin go get -u github.com/gin-gonic/gin
swaggo go install github.com/swaggo/swag/cmd/swag@latest
cyclonedx-gomod go install github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@latest
make sudo apt install build-essential
docker & docker compose

Quick Run

Below, we outline various options to kickstart SOARCA. The latest pre-compiled releases can be found here.

make build && ./build/soarca

wget https://github.com/COSSAS/SOARCA/releases/download/SOARCA_1.0.0/SOARCA_1.0.0_linux_amd64.tar.gz  && tar -xvf SOARCA* && ./SOARCA

cd docker/soarca && sudo docker compose up -d

Tip

Output will be similar to:

swag init
2024/02/09 12:53:04 Generate swagger docs....
2024/02/09 12:53:04 Generate general API Info, search dir:./
2024/02/09 12:53:06 Generating cacao.Playbook
2024/02/09 12:53:06 Generating cacao.ExternalReferences
2024/02/09 12:53:06 Generating cacao.Workflow
2024/02/09 12:53:06 Generating cacao.Step
.....

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:

# 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

curl -X POST -H "Content-Type: application/json" -d @./example/http-playbook.json localhost:8080/trigger/playbook

curl -X POST -H "Content-Type: application/json" -d @./example/openc2-playbook.json localhost:8080/trigger/playbook

Configuration

SOARCA reads its configuration from the environment variables or a .env file. An example of a .env is given below:

PORT: 8080
MONGODB_URI: "mongodb://localhost:27017"
DATABASE_NAME: "soarca"
DB_USERNAME: "root"
DB_PASSWORD: "rootpassword"
PLAYBOOK_API_LOG_LEVEL: trace
DATABASE: "false"
MAX_REPORTERS: "5"

LOG_GLOBAL_LEVEL: "info"
LOG_MODE: "development"
LOG_FILE_PATH: ""
LOG_FORMAT: "json"

ENABLE_FINS: false
MQTT_BROKER: "localhost"
MQTT_PORT: 1883
VALIDATION_SCHEMA_URL: ""

Docker hub

docker pull cossas/soarca

Building from Source

git clone https://github.com/COSSAS/SOARCA.git
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.