OpenBAS installation demystified: your ultimate guide

OpenBAS (Open Breach and Attack Simulation), is a powerful platform designed to evaluate and enhance an organization’s Security Posture by simulating real-world cyberattacks. Built on a modular architecture, OpenBAS seamlessly integrates various components and dependencies, providing flexibility and scalability.

OpenBAS is part of the eXtended Threat Management (XTM) suite and can leverage its built-in integration with OpenCTI to use qualified Cyber Threat Intelligence (CTI) and enhance your Adversarial Exposure Validation program. This integration allows organizations to leverage threat intelligence in their attack simulations, making security testing more dynamic and aligned with real-world threats.

This article is intended for individuals looking to install OpenBAS. A minimum level of technical knowledge is recommended:

• Docker: for quick deployment using containerization.
• Java/Spring: for manual installation and a deeper understanding of OpenBAS’s internal components.

This article is based on the OpenBAS 1.12.2 release. The versions of dependencies and the environment variables/application properties may vary depending on the version you intend to deploy.

OpenBAS Technical Architecture

The OpenBAS platform is structured around the following key components:

Core Platform

The heart of OpenBAS, featuring business logic, a Java/Spring-based API, and a React-based user interface. It also includes built-in injectors and integrations with third-party agents.

OpenBAS Agent & Implant

Developed in Rust, these components execute technical injectors on targeted assets:

• Agent: Registers an asset on the OpenBAS platform and retrieves jobs to be executed. The Agent will not perform direct attack to remain neutral for antivirus and ensure attack scenario continuity.
• Implant: Executes jobs received from the Agent. The implant performs direct attacks and may be detected and terminated by antivirus software.

Injectors

External modules that extend the platform’s capabilities by adding different types of injects to customize attack scenarios, simulations, and atomic testings. These injectors can function independently or interact with third-party services.

You can create your own injector by cloning an existing one. Filigran team maintains a python library to allow you accelerate your developments.

Collectors

Python modules that pull data from various external services for two purposes:

• Integrate with security systems like SIEM, EDR, and XDR to verify if a technical inject was detected or prevented, thus offering critical insights into an organization’s security posture.
• Collect any data that may help to schedule breach and attack simulations such as list of assets, groups, identities, payloads, etc.

Dependencies

OpenBAS relies on several external components:

• PostgreSQL (17): Serves as the primary database for storing core platform data.
• RabbitMQ (4): Manages messaging between Python injectors and OpenBAS, enabling asynchronous communication.
• MinIO (>= RELEASE.2024): Handles object storage, including image management.
• Elasticsearch (8.x): Supports indexing and retrieval of platform data, and can be used alongside Kibana for enhanced observability.

Deployment & Configuration Guide

Deploying OpenBAS with Docker

Prerequisites

Before installing OpenBAS, ensure that Docker Compose is installed on your system. Here’s how to install it:

For Linux

1. Set up Docker’s repository based on the official documentation:

Example on Ubuntu 24.04

 sudo apt-get update
 sudo apt-get install docker-compose-plugin

2. Verify the installation:

docker compose version

For Windows & macOS

1. Download Docker Desktop from the official website.
2. Follow the installation instructions provided on the website.

Installing OpenBAS

1. Clone the OpenBAS Docker repository:

mkdir -p obas && cd obas
git clone https://github.com/OpenBAS-Platform/docker.git
cd docker

2. Configure the environment:

By default, the docker-compose.yml file utilizes environment variables specified in the .env.sample file. You can make a copy of.env.sample to .env and populate the necessary values to reflect your configuration.

OpenBAS provides official Docker images available here: OpenBAS Docker Hub.

One of the key strengths of this platform is its modular architecture, allowing you to deploy multiple Docker images to best fit your specific needs and use cases. Whether you’re setting up a lightweight development environment or a full-fledged production system, the flexibility of Docker ensures seamless adaptability.

In-depth exploration of the Docker Compose file

We will go through the docker-compose.yml and .env file together to understand its structure, allowing you to modify the variables according to your needs.

⚠️ Important: The .env file provided is an example configuration. For security reasons, be sure to update your credentials before deploying to prevent unauthorized access.

1. Dependencies

PostgreSQL

  pgsql:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: openbas
    volumes:
      - pgsqldata:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: [ "CMD", "pg_isready", "-U", "${POSTGRES_USER}", "-d", "openbas" ]
      interval: 10s
      timeout: 5s
      retries: 5

docker-compose.yml

# PostgreSQL Configuration
POSTGRES_USER=postgres
POSTGRES_PASSWORD=admin

.env

MinIO

  minio:
    image: minio/minio:RELEASE.2024-05-28T17-19-04Z
    volumes:
      - s3data:/data
    ports:
      - "9000:9000"
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    command: server /data
    restart: always
    healthcheck:
      test: [ "CMD", "curl", "-f", "http://localhost:9000/minio/health/live" ]
      interval: 10s
      timeout: 5s
      retries: 5

docker-compose.yml

# MinIO Configuration
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin

.env

RabbitMQ

  rabbitmq:
    image: rabbitmq:3.13-management
    environment:
      - RABBITMQ_DEFAULT_USER=${RABBITMQ_DEFAULT_USER}
      - RABBITMQ_DEFAULT_PASS=${RABBITMQ_DEFAULT_PASS}
      - RABBITMQ_NODENAME=rabbit01@localhost
    volumes:
      - amqpdata:/var/lib/rabbitmq
    restart: always
    healthcheck:
      test: [ "CMD", "rabbitmq-diagnostics", "-q", "ping" ]
      interval: 10s
      timeout: 5s
      retries: 5

docker-compose.yml

# RabbitMQ Configuration
RABBITMQ_DEFAULT_USER=rabbitadmin
RABBITMQ_DEFAULT_PASS=rabbitadmin

.env

Elasticsearch

  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.17.4
    volumes:
      - esdata:/usr/share/elasticsearch/data
    environment:
      # Comment-out the line below for a cluster of multiple nodes
      - discovery.type=single-node
      # Uncomment the line below below for a cluster of multiple nodes
      # - cluster.name=docker-cluster
      - xpack.ml.enabled=false
      - xpack.security.enabled=false
      - thread_pool.search.queue_size=5000
      - logger.org.elasticsearch.discovery="ERROR"
      - "ES_JAVA_OPTS=-Xms${ELASTIC_MEMORY_SIZE} -Xmx${ELASTIC_MEMORY_SIZE}"
    restart: always
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 65536
        hard: 65536
    healthcheck:
      test: curl -s http://elasticsearch:9200 >/dev/null || exit 1
      interval: 30s
      timeout: 10s
      retries: 50

docker-compose.yml

# ElasticSearch Configuration
ELASTIC_MEMORY_SIZE=4G

.env

2. OpenBAS platform

  openbas:
    image: openbas/platform:1.11.5
    environment:
      # OpenBAS General Configuration
      - SERVER_SSL_KEY-STORE-PASSWORD=${KEYSTORE_PASSWORD}
      - OPENBAS_BASE-URL=http://localhost:8080
      - OPENBAS_AUTH-LOCAL-ENABLE=true
      - OPENBAS_ADMIN_EMAIL=${OPENBAS_ADMIN_EMAIL}
      - OPENBAS_ADMIN_PASSWORD=${OPENBAS_ADMIN_PASSWORD}
      - OPENBAS_ADMIN_TOKEN=${OPENBAS_ADMIN_TOKEN}
      # POSTGRES
      - SPRING_DATASOURCE_URL=jdbc:postgresql://pgsql:5432/openbas
      - SPRING_DATASOURCE_USERNAME=${POSTGRES_USER}
      - SPRING_DATASOURCE_PASSWORD=${POSTGRES_PASSWORD}
      # MINIO
      - MINIO_ENDPOINT=minio
      - MINIO_ACCESS-KEY=${MINIO_ROOT_USER}
      - MINIO_ACCESS-SECRET=${MINIO_ROOT_PASSWORD}
      # RABBITMQ
      - OPENBAS_RABBITMQ_HOSTNAME=rabbitmq
      - OPENBAS_RABBITMQ_USER=${RABBITMQ_DEFAULT_USER}
      - OPENBAS_RABBITMQ_PASS=${RABBITMQ_DEFAULT_PASS}
      # ELASTICSEARCH
      - ENGINE_URL=http://elasticsearch:9200
      # SPRING MAIL Configurations
      - SPRING_MAIL_HOST=${SPRING_MAIL_HOST}
      - SPRING_MAIL_PORT=${SPRING_MAIL_PORT}
      - SPRING_MAIL_USERNAME=${SPRING_MAIL_USERNAME}
      - SPRING_MAIL_PASSWORD=${SPRING_MAIL_PASSWORD}
      - SPRING_MAIL_PROPERTIES_MAIL_SMTP_AUTH=${SPRING_MAIL_PROPERTIES_MAIL_SMTP_AUTH}
      - SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_ENABLE=${SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_ENABLE}
      - SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_TRUST=*
      - SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE=${SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE}
      # IMAP Configurations
      - OPENBAS_MAIL_IMAP_ENABLED=${OPENBAS_MAIL_IMAP_ENABLED}
      - OPENBAS_MAIL_IMAP_HOST=${OPENBAS_MAIL_IMAP_HOST}
      - OPENBAS_MAIL_IMAP_PORT=${OPENBAS_MAIL_IMAP_PORT}
      - OPENBAS_MAIL_IMAP_USERNAME=${SPRING_MAIL_USERNAME}
      - OPENBAS_MAIL_IMAP_PASSWORD=${SPRING_MAIL_PASSWORD}
      - OPENBAS_MAIL_IMAP_AUTH=${OPENBAS_MAIL_IMAP_AUTH}
      - OPENBAS_MAIL_IMAP_SSL_ENABLE=${OPENBAS_MAIL_IMAP_SSL_ENABLE}
      - OPENBAS_MAIL_IMAP_SSL_TRUST=*
      - OPENBAS_MAIL_IMAP_STARTTLS_ENABLE=${OPENBAS_MAIL_IMAP_STARTTLS_ENABLE}
    ports:
      - "8080:8080"
    depends_on:
      pgsql:
        condition: service_healthy
      minio:
        condition: service_healthy
      rabbitmq:
        condition: service_healthy
      elasticsearch:
        condition: service_started  
    restart: always

docker-compose.yml

# OpenBAS General Configuration
KEYSTORE_PASSWORD=ChangeMe # Specify your KeyStore to use OpenBAS in SSL
OPENBAS_ADMIN_EMAIL=admin@openbas.io # Email of your admin account (should be a valid format)
OPENBAS_ADMIN_PASSWORD=admin # Password of your admin account
OPENBAS_ADMIN_TOKEN=0d17ce9a-f3a8-4c6d-9721-c98dc3dc023f # Token of your admin account (Should be a valid UUID)

# Spring Mail Configuration
SPRING_MAIL_HOST=ssl0.ovh.net
SPRING_MAIL_PORT=465
SPRING_MAIL_USERNAME=username@openbas.io
SPRING_MAIL_PASSWORD=password
SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_TRUST=*
SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_ENABLE=false
SPRING_MAIL_PROPERTIES_MAIL_SMTP_AUTH=false
SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE=false

# OpenBAS IMAP Configuration (can be disabled)
OPENBAS_MAIL_IMAP_ENABLED=true
OPENBAS_MAIL_IMAP_HOST=ssl0.ovh.net
OPENBAS_MAIL_IMAP_PORT=993
OPENBAS_MAIL_IMAP_AUTH=true
OPENBAS_MAIL_IMAP_SSL_ENABLE=true
OPENBAS_MAIL_IMAP_STARTTLS_ENABLE=true

.env

3. Customize

You can add several modules depending on your usage. You can find what is available here → OpenBAS Ecosystem

  collector-mitre-attack:
    image: openbas/collector-mitre-attack:1.11.5
    environment:
      - OPENBAS_URL=http://openbas:8080
      - OPENBAS_TOKEN=${OPENBAS_ADMIN_TOKEN}
      - COLLECTOR_ID=${COLLECTOR_MITRE_ATTACK_ID} # Valid UUIDv4
      - "COLLECTOR_NAME=MITRE ATT&CK"
      - COLLECTOR_LOG_LEVEL=info
    restart: always

docker-compose.yml

COLLECTOR_MITRE_ATTACK_ID=00000000-0000-0000-0000-000000000000 # Should be a valid UUID

.env

Running OpenBAS

Once configured, launch OpenBAS using Docker Compose:

sudo systemctl start docker.service
sudo docker compose up -d

Accessing OpenBAS

Once installed, you can access OpenBAS via your web browser:

http://localhost:8080

Login using the admin credentials defined in your .env file.

Deploying OpenBAS manually

Dependencies

Before deploying OpenBAS, ensure the following dependencies are installed:

• PostgreSQL: PostgreSQL Documentation
• RabbitMQ: RabbitMQ Documentation
• MinIO: MinIO Official Site
• ElasticSearch: ElasticSearch Official Site
• Java: Java Documentation

You can use the docker-compose.yml file available in the openbas-dev directory.

Installing OpenBAS Manually

1. Download and extract the latest release:

⚠️ Example with release 1.12.2, please change the release version based on your needs.

mkdir /path/to/your/app && cd /path/to/your/app
wget https://github.com/OpenBAS-Platform/openbas/releases/download/1.12.0/openbas-release-1.12.2.tar.gz
tar xvfz openbas-release-1.12.2.tar.gz

2. Configure the application:

Modify the application.properties file (found at the root of the extracted release archive) to meet your requirements.

For a complete list of configurable parameters, visit: OpenBAS Configuration Guide.

In-depth exploration of the application.properties file

We will go through the application.properties file together to understand its structure, allowing you to modify the variables according to your needs.

1. Dependencies

PostgreSQL

# PostgreSQL Configuration
spring.datasource.url=jdbc:postgresql://localhost:5432/openbas
spring.datasource.username=openbas
spring.datasource.password=openbas

MinIO

# MinIO Configuration
minio.port=10000
minio.access-key=minioadmin
minio.access-secret=minioadmin

RabbitMQ

# RabbitMQ Configuration
openbas.rabbitmq.user=guest
openbas.rabbitmq.pass=guest

ElasticSearch

### ENGINE Configuration
engine.index-prefix=openbas
engine.index-suffix=-000001
engine.url=http://localhost:9200

2. OpenBAS platform

# OpenBAS General Configuration
openbas.base-url=http://localhost:3001
openbas.admin.email=admin@openbas.io # Email of your admin account (should be a valid format)
openbas.admin.password=admin # Password of your admin account
openbas.admin.token=0d17ce9a-f3a8-4c6d-9721-c98dc3dc023f # Token of your admin account (Should be a valid UUID)

# Spring Mail Configuration
spring.mail.host=ssl0.ovh.net
spring.mail.username=username@openbas.io
spring.mail.password=password

# OpenBAS IMAP Configuration (can be disabled)
openbas.mail.imap.enabled=true
openbas.mail.imap.host=ssl0.ovh.net
openbas.mail.imap.username=username@openbas.io
openbas.mail.imap.password=password

Running OpenBAS

Ensure all dependencies are running and healthy before executing the following command:

java -jar openbas-api.jar --spring.config.location=file:/path/to/application.properties

Accessing OpenBAS

Once installed, you can access OpenBAS via your web browser:

http://localhost:8080

Login using the admin credentials defined in your application.properties file.

Deploy OpenBAS Agent

This section contains useful information for conducting technical attacks through assets. If you’re using OpenBAS for tabletop scenarios or simulations, you can skip this.

If you are using OpenBAS to conduct attack simulations on technical assets, you need to deploy an agent on the targeted asset.

OpenBAS offers integration with several existing agents, including CrowdStrike, Tanium, and Caldera. However, we also provide our own in-house agent, and we will walk through the deployment process for it.

For other agents, you can find more details in the official documentation.

Depending on the OS, several installations are at your disposal, you can find them on OpenBAS by clicking the blue icon on the right top corner :

After choosing your OS, just follow the instructions provided by the OpenBAS platform:

1. Copy the snippet
2. Add antivirus exclusions

Once the agent is deployed, you will retrieve your registered endpoints in the dedicated list and used it in your technical injects.

Conclusion

OpenBAS enables organizations to proactively assess their cybersecurity resilience through sophisticated breach and attack simulations. Its modular architecture, diverse integration capabilities, and ease of deployment make it a solution for security professionals aiming to strengthen their defense strategies.

Whether you opt for Docker-based deployment or a manual setup, OpenBAS provides the flexibility to adapt to your unique security needs.

Ready to get started? Explore the full documentation at OpenBAS Docs.

Curious to learn more about OpenBAS’s core functionalities and how they can bolster your Continuous Threat Exposure Management (CTEM) program? Check out this in-depth article!