Installation
All components of OpenBAS are shipped both as Docker images and manual installation packages.
Production deployment
For production deployment, we recommend to deploy all components in containers, including dependencies, using native cloud services or orchestration systems such as Kubernetes.
-
Use Docker
Deploy OpenBAS using Docker and the default
docker-compose.ymlprovided in the docker. -
Manual installation
Deploy dependencies and launch the platform manually using the packages released in the GitHub releases.
Using Docker
Introduction
OpenBAS can be deployed using the docker-compose command.
Pre-requisites
Linux
Windows and MacOS
Just download the appropriate Docker for Desktop version for your operating system.
Clone the repository
Docker helpers are available in the Docker GitHub repository.
mkdir -p /path/to/your/app && cd /path/to/your/app
git clone https://github.com/OpenBAS-Platform/docker.git
cd docker
Configure the environment
Before running the docker-compose command, the caldera.yml and docker-compose.yml file should be configured. By default, the docker-compose.yml file is using environment variables available in the file .env.sample.
You can either rename the file .env.sample in .env and put the expected values or just fill directly the docker-compose.yml with the values corresponding to your environment.
Caldera
Unfortunately, Caldera does not support well environment variables, we have packaged it but the caldera.yml needs to be modified to change default API keys and passwords. Only change what is marked as Change this, listed below:
Caldera application
You will never be asked to go into Caldera directly because OpenBAS manages everything for you, so don't hesitate to put the same UUIDv4 in all parameters here.
users:
red:
red: ChangeMe # Change this
blue:
blue: ChangeMe # Change this
api_key_red: ChangeMe # Change this
api_key_blue: ChangeMe # Change this
api_key: ChangeMe # Change this
crypt_salt: ChangeMe # Change this
encryption_key: ChangeMe # Change this
app.contact.http: http://caldera.myopenbas.myorganization.com:8888 # Change this
app.contact.tunnel.ssh.user_password: ChangeMe # Change this
Docker compose env
Configuration static parameters
The complete list of available static parameters is available in the configuration section.
Whether you are using one method or the other, here are the mandatory parameters to fill:
POSTGRES_USER=ChangeMe
POSTGRES_PASSWORD=ChangeMe
KEYSTORE_PASSWORD=ChangeMe
MINIO_ROOT_USER=ChangeMeAccess
MINIO_ROOT_PASSWORD=ChangeMeKey
RABBITMQ_DEFAULT_USER=ChangeMe
RABBITMQ_DEFAULT_PASS=ChangeMe
SPRING_MAIL_HOST=smtp.changeme.com
SPRING_MAIL_PORT=465
SPRING_MAIL_USERNAME=ChangeMe@domain.com
SPRING_MAIL_PASSWORD=ChangeMe
OPENBAS_MAIL_IMAP_HOST=imap.changeme.com
OPENBAS_MAIL_IMAP_PORT=993
OPENBAS_ADMIN_EMAIL=ChangeMe
OPENBAS_ADMIN_PASSWORD=ChangeMe
OPENBAS_ADMIN_TOKEN=ChangeMe
CALDERA_PUBLIC_URL=http://localhost:8888 # Change me for production deployment to something accessible from your endpoint(s)
CALDERA_API_KEY=ChangeMe
COLLECTOR_MITRE_ATTACK_ID=3050d2a3-291d-44eb-8038-b4e7dd107436 # No need for change
Caldera public URL
For production deployment, the Caldera public URL needs to be accessible from the machines where you would like to play breach and attack simulations scenarios.
If your docker-compose deployment does not support .env files, just export all environment variables before launching the platform:
Persist data
The default for OpenBAS data is to be persistent.
In the docker-compose.yml, you will find at the end the list of necessary persistent volumes for the dependencies:
Run OpenBAS
Using single node Docker
After changing your .env file run docker-compose in detached (-d) mode:
Using Docker swarm
In order to have the best experience with Docker, we recommend using the Docker stack feature. In this mode you will have the capacity to easily scale your deployment.
Put your environment variables in /etc/environment:
# If you already exported your variables to .env from above:
sudo cat .env >> /etc/environment
sudo bash -c 'cat .env >> /etc/environment’
sudo docker stack deploy --compose-file docker-compose.yml openbas
Installation done
You can now go to http://localhost:8080 and log in with the credentials filled in your configuration.
Manual installation
Prepare the installation
Installation of dependencies
You have to install all the needed dependencies for the main application including Caldera if you would like to play breach and attack simulation scenarios. The example below if for Ubuntu:
Download the application files
First, you have to download and extract the latest release file.
mkdir /path/to/your/app && cd /path/to/your/app
wget <https://github.com/OpenBAS-Platform/openbas/releases/download/{RELEASE_VERSION}/openbas-release-{RELEASE_VERSION}.tar.gz>
tar xvfz openbas-release-{RELEASE_VERSION}.tar.gz
Install the main platform
Configure the application
The main application has just one environment configuration file to change.
Change the application.properties file according to your configuration of PostgreSQL, RabbitMQ, Minio and Caldera admin account and to your platform.
Start the application
Start the Application:
Installation done
You can now go to http://localhost:8080 and log in with the credentials configured in your application.properties file.
Deploy behind a reverse proxy
If you want to use OpenBAS behind a reverse proxy with a context path, like https://domain.com/openbas, please change the base_path static parameter.
APP__BASE_PATH=/openbas
By default OpenBAS use websockets so don't forget to configure your proxy for this usage, an example with Nginx:
location / {
proxy_cache off;
proxy_buffering off;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
chunked_transfer_encoding off;
proxy_pass http://YOUR_UPSTREAM_BACKEND;
}
Additional memory information
OpenBAS platform is based on a JAVA runtime. The application needs at least 4GB of RAM to work properly.
PostgreSQL
PostgreSQL is the main database of OpenBAS. You can find more information in the official PostgresQL documentation.
MinIO
MinIO is a small process and does not require a high amount of memory. More information are available for Linux here on the Kernel tuning guide.