Filigran
-Filigran is providing an Enterprise Edition of the platform, whether on-premise or in the SaaS.
-OpenBAS Enterprise Edition is based on the open core concept. This means that the source code of OCTI EE remains open source and included in the main GitHub repository of the platform but is published under a specific license. As specified in the GitHub license file:
-The source files in this repository have a header indicating which license they are under. If no such header is provided, this means that the file belongs to the Community Edition under the Apache License, Version 2.0.
-Enterprise edition is easy to activate. You need to go the platform settings and click on the Activate button.
-
Then you will need to agree to the Filigran EULA.
-
As a reminder:
-Be able to use AI for content generation including emails, media pressure articles etc.
-More features will be available in OpenBAS in the future. Features like:
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-The Policies configuration page, located under Settings > Security > Policies, is designed to manage and customize various security-related settings. -This page currently includes the configuration of login messages, with plans to expand its capabilities in the future.
-Login Messages
-Administrators can create and manage messages that are displayed to users upon login. This feature is useful for providing important information or updates directly to users when they access the platform.
- There are three types of messages:
- * Platform Login Message: Displayed above the login form to communicate vital information or announcements.
- * Platform Consent Message: Displayed to users during the login process. It appears as a notification that blocks access to the login form until users actively give their consent by checking an approval box. This ensures that users acknowledge and agree to certain terms or conditions before proceeding with logging in.
- * Platform Consent Confirm Text: A message accompanying the consent box, providing clarity on the consent confirmation process.
These messages can be customized to fit the organization's specific needs and requirements, ensuring that critical information is communicated effectively to users.
-
-
-
-
-
To access the Policies configuration page, navigate to:
-Settings / Security / Policies
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Welcome to the authentication documentation for OpenBAS. This documentation provides details on setting up and utilizing the authentication system, which supports multiple authentication methods to cater to different user needs and security requirements.
-OpenBAS use this strategy as the default, but it's not the one we recommend for security reasons.
-OPENBAS.AUTH-LOCAL-ENABLE: Set this to true to enable username/password authentication.Production deployment
-Please use the LDAP/Auth0/OpenID/SAML strategy for production deployment.
-This method allows to use the OpenID Connect Protocol to handle the authentication.
-OPENBAS.AUTH-OPENID-ENABLE: Set this to true to enable OAuth (OpenID) authentication.Example for Auth0:
-SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_{registrationId}_ISSUER-URI=https://auth.auth0.io
-SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT-NAME=Login with auth0
-SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT-ID=
-SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT-SECRET=
-SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_REDIRECT-URI=${openbas.base-url}/login/oauth2/code/{registrationId}
-SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_SCOPE=openid,profile,email
-Example for GitHub (or others pre-handled oauth2 providers):
-SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT_NAME=Login with Github
-SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT_ID=
-SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT_SECRET=
-Tips
-{registrationId} is an arbitrary identifier you choose.
-This strategy can be used to authenticate your user with your company SAML.
-OPENBAS.AUTH-SAML2-ENABLE: Set this to true to enable SAML2 authentication. Example for Microsoft : -
SPRING_SECURITY_SAML2_RELYINGPARTY_REGISTRATION_{registrationId}_ENTITY-ID=
-SPRING_SECURITY_SAML2_RELYINGPARTY_REGISTRATION_{registrationId}_ASSERTINGPARTY_METADATA-URI=
-OPENBAS_PROVIDER_{registrationId}_FIRSTNAME_ATTRIBUTE_KEY=
-OPENBAS_PROVIDER_{registrationId}_LASTNAME_ATTRIBUTE_KEY=
-Tips
-{registrationId} is an arbitrary identifier you choose. - metadata-uri is the uri of the xml file given by your identity provider
-Url for the config of your sso provider -
-To grant administrative roles, you can utilize OAuth and SAML2 integration. If you opt for this approach, you'll need to include the following variables:
-OPENBAS_PROVIDER_{registrationId}_ROLES_PATH=http://schemas.microsoft.com/ws/2008/06/identity/claims/role
-OPENBAS_PROVIDER_{registrationId}_ROLES_ADMIN=
-However, if you intend to manage administrative roles within the OpenBAS platform itself, there's no need to provide these variables.
-Under construction
-We are doing our best to complete this page. -If you want to participae, dont hesitate to join the Filigran Community on Slack -or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Collectors list
-You are looking for the available collectors? The list is in the OpenBAS Ecosystem.
-Collectors are one of the cornerstones of the OpenBAS platform, they are responsible for pulling data from various external services for two purposes:
-Those collectors are the most import ones as they are used to evaluate the security posture (response to injects) from various detection and response systems and fulfill expectations for detection and prevention.
-Those collectors are used to collect threat intelligence data such as kill chains, scenarios, TTPs, payloads, etc.
-Those collectors are pulling alternative information about your endpoints and assets to complete the overview about your current posture in terms of vulnerabilities and compliance.
-Those collectors are pulling all information related to identities, including human assets, to be used in scenario or to complete the view overview about your current posture.
-All other system OpenBAS can pull from, to add more meaningful and relevant information to the view of your security posture.
-Some collectors such as Microsoft Sentinel are directly embedded into the application. To configure them, just add the proper configuration parameters in your platform configuration.
-All external collectors have to be able to access the OpenBAS API. To allow this connection, they have 2 mandatory configuration parameters, the OPENBAS_URL and the OPENBAS_TOKEN. In addition to these 2 parameters, collectors have other mandatory parameters that need to be set in order to get them work.
Collector tokens
-You can use your administrator token or create another administrator service account to put in your collectors. It is not necessary to have one dedicated user for each collector.
-Here is an example of a collector docker-compose.yml file:
-
- OPENBAS_URL=http://localhost
-- OPENBAS_TOKEN=ChangeMe
-- COLLECTOR_ID=ChangeMe # Valid UUIDv4
-- "COLLECTOR_NAME=MITRE ATT&CK"
-- COLLECTOR_LOG_LEVEL=error
-Here is an example in a collector config.yml file:
openbas:
- url: 'http://localhost:3001'
- token: 'ChangeMe'
-
-collector:
- id: 'ChangeMe'
- name: 'MITRE ATT&CK'
- log_level: 'info'
-You can either directly run the Docker image of collectors or add them to your current docker-compose.yml file.
For instance, to enable the MITRE ATT&CK collector, you can add a new service to your docker-compose.yml file:
collector-mitre-attack:
- image: openbas/collector-mitre-attack:1.0.0
- environment:
- - OPENBAS_URL=http://localhost
- - OPENBAS_TOKEN=ChangeMe
- - COLLECTOR_ID=ChangeMe
- - "COLLECTOR_NAME=MITRE ATT&CK"
- - COLLECTOR_LOG_LEVEL=error
- restart: always
-To launch standalone collector, you can use the docker-compose.yml file of the collector itself. Just download the latest release and start the collector:
$ wget https://github.com/OpenBAS-Platform/collectors/archive/{RELEASE_VERSION}.zip
-$ unzip {RELEASE_VERSION}.zip
-$ cd collectors-{RELEASE_VERSION}/mitre-attack/
-Change the configuration in the docker-compose.yml according to the parameters of the platform and of the targeted service. Then launch the collector:
If you want to manually launch collector, you just have to install Python 3 and pip3 for dependencies:
- -Download the release of the collectors:
-$ wget <https://github.com/OpenBAS-Platform/collectors/archive/{RELEASE_VERSION}.zip>
-$ unzip {RELEASE_VERSION}.zip
-$ cd collectors-{RELEASE_VERSION}/mitre-attack/src/
-Install dependencies and initialize the configuration:
- -Change the config.yml content according to the parameters of the platform and of the targeted service and launch the collector:
The collector status can be displayed in the dedicated section of the platform available in Integration > collectors. You will be able to see the statistics of the RabbitMQ queue of the collector:
-
Problem
-If you encounter problems deploying OpenBAS or collectors, you can consult the troubleshooting page page.
-The purpose of this section is to learn how to configure OpenBAS to have it tailored for your production and development needs. It is possible to check all default parameters implemented in the platform in the application.properties file.
Here are the configuration keys, for both containers (environment variables) and manual deployment.
-Parameters equivalence
-The equivalent of a config variable in environment variables is the usage of an underscore (_) for a level of config.
For example: -
-will become: -
-| Parameter | -Environment variable | -Default value | -Description | -
|---|---|---|---|
| server.address | -SERVER_ADDRESS | -0.0.0.0 | -Listen address of the application | -
| server.port | -SERVER_PORT | -8080 | -Listen port of the application | -
| openbas.base-url | -OPENBAS_BASE-URL | -http://localhost:8080 | -Base URL of the application, will be used in some email links | -
| server.servlet.session.timeout | -SERVER_SERVLET_SESSION_TIMEOUT | -60m | -Default duration of session (60 minutes) | -
| openbas.cookie-secure | -OPENBAS_COOKIE-SECURE | -false |
-Turn on if the access is done in HTTPS | -
| openbas.cookie-duration | -OPENBAS_COOKIE-DURATION | -P1D | -Cookie duration (default 1 day) | -
| openbas.admin.email | -OPENBAS_ADMIN_EMAIL | -admin@openbas.io | -Default login email of the admin user | -
| openbas.admin.password | -OPENBAS_ADMIN_PASSWORD | -ChangeMe | -Default password of the admin user | -
| openbas.admin.token | -OPENBAS_ADMIN_TOKEN | -ChangeMe | -Default token (must be a valid UUIDv4) | -
| Parameter | -Environment variable | -Default value | -Description | -
|---|---|---|---|
| server.ssl.enabled | -SERVER_SSL_ENABLED | -false |
-Turn on to enable SSL on the local server | -
| server.ssl.key-store-type | -SERVER_SSL_KEY-STORE-TYPE | -PKCS12 | -Type of SSL keystore | -
| server.ssl.key-store | -SERVER_SSL_KEY-STORE | -classpath:localhost.p12 | -SSL keystore path | -
| server.ssl.key-store-password | -SERVER_SSL_KEY-STORE-PASSWORD | -admin | -SSL keystore password | -
| server.ssl.key-alias | -SERVER_SSL_KEY-ALIAS | -localhost | -SSL key alias | -
| Parameter | -Environment variable | -Default value | -Description | -
|---|---|---|---|
| logging.level.root | -LOGGING_LEVEL_ROOT | -fatal | -Root log level | -
| logging.level.io.openbas | -LOGGING_LEVEL_IO_OPENBAS | -warn | -OpenBAS log level | -
| logging.file.name | -LOGGING_FILE_NAME | -./logs/openbas.log | -Log file path (in addition to console output) | -
| logging.logback.rollingpolicy.max-file-size | -LOGGING_LOGBACK_ROLLINGPOLICY_MAX-FILE-SIZE | -10MB | -Rolling max file size | -
| logging.logback.rollingpolicy.max-history | -LOGGING_LOGBACK_ROLLINGPOLICY_MAX-HISTORY | -7 | -Rolling max days | -
| Parameter | -Environment variable | -Default value | -Description | -
|---|---|---|---|
| openbas.xtm.opencti.enable | -OPENBAS_XTM_OPENCTI_ENABLE | -false | -Enable integration with OpenCTI | -
| openbas.xtm.opencti.url | -OPENBAS_XTM_OPENCTI_URL | -- | OpenCTI URL | -
| openbas.xtm.opencti.token | -OPENBAS_XTM_OPENCTI_TOKEN | -- | OpenCTI token | -
| openbas.xtm.opencti.disable-display | -OPENBAS_XTM_OPENCTI_DISABLE-DISPLAY | -false |
-Disable OpenCTI in the UI | -
| Parameter | -Environment variable | -Default value | -Description | -
|---|---|---|---|
| spring.datasource.url | -SPRING_DATASOURCE_URL | -jdbc:postgresql://... | -URL of the database (ex jdbc:postgresql://postgresql.mydomain.com:5432/openbas) | -
| spring.datasource.username | -SPRING_DATASOURCE_USERNAME | -- | Login for the database | -
| spring.datasource.password | -SPRING_DATASOURCE_PASSWORD | -password | -Password for the database | -
| Parameter | -Environment variable | -Default value | -Description | -
|---|---|---|---|
| openbas.rabbitmq.prefix | -OPENBAS_RABBITMQ_PREFIX | -openbas | -Prefix for the queue names | -
| openbas.rabbitmq.hostname | -OPENBAS_RABBITMQ_HOSTNAME | -localhost | -Hostname of the RabbitMQ server | -
| openbas.rabbitmq.vhost | -OPENBAS_RABBITMQ_VHOST | -/ | -Vhost of the RabbitMQ server | -
| openbas.rabbitmq.port | -OPENBAS_RABBITMQ_PORT | -5672 | -Port of the RabbitMQ Server | -
| openbas.rabbitmq.management-port | -OPENBAS_RABBITMQ_MANAGEMENT-PORT | -15672 | -Management port of the RabbitMQ Server | -
| openbas.rabbitmq.ssl | -OPENBAS_RABBITMQ_SSL | -false |
-Use SSL | -
| openbas.rabbitmq.user | -OPENBAS_RABBITMQ_USER | -guest | -RabbitMQ user | -
| openbas.rabbitmq.pass | -OPENBAS_RABBITMQ_PASS | -guest | -RabbitMQ password | -
| openbas.rabbitmq.queue-type | -OPENBAS_RABBITMQ_QUEUE-TYPE | -classic | -RabbitMQ Queue Type ("classic" or "quorum") | -
| Parameter | -Environment variable | -Default value | -Description | -
|---|---|---|---|
| minio.endpoint | -MINIO_ENDPOINT | -localhost | -Hostname of the S3 Service. Example if you use AWS Bucket S3: s3.us-east-1.amazonaws.com (if minio:bucket_region value is us-east-1). This parameter value can be omitted if you use Minio as an S3 Bucket Service. |
-
| minio.port | -MINIO_PORT | -9000 | -Port of the S3 Service. For AWS Bucket S3 over HTTPS, this value can be changed (usually 443). | -
| minio.secure | -MINIO_SECURE | -false |
-Indicates whether the S3 Service has TLS enabled. For AWS Bucket S3 over HTTPS, this value could be true. |
-
| minio.access-key | -MINIO_ACCESS-KEY | -key | -Access key for the S3 Service. | -
| minio.access-secret | -MINIO_ACCESS-SECRET | -secret | -Secret key for the S3 Service. | -
| minio.bucket | -MINIO_BUCKET | -openbas | -S3 bucket name. Useful to change if you use AWS. | -
| minio.bucket-region | -MINIO_BUCKET-REGION | -us-east-1 | -Region of the S3 bucket if you are using AWS. This parameter value can be omitted if you use Minio as an S3 Bucket Service. | -
To be able to use the power of the OpenBAS platform on endpoints, you need at least one executor that will be in charge of spawing temporary processes (endpoint injectors) which will execute payloads.
-The OpenBAS agent is enabled by default and cannot be disabled. It is available for:
-x86_64 / arm64)x86_64 / arm64)x86_64 / arm64)Tanium Packages
-To use the Tanium executor, please install the OpenBAS packages on the Tanium platform and fill their IDs in the configuration below.
-| Parameter | -Environment variable | -Default value | -Description | -
|---|---|---|---|
| executor.tanium.enable | -EXECUTOR_TANIUM_ENABLE | -false |
-Enable the Tanium executor | -
| executor.tanium.url | -EXECUTOR_TANIUM_URL | -- | Tanium URL | -
| executor.tanium.api-key | -EXECUTOR_TANIUM_API-KEY | -- | Tanium API key | -
| executor.tanium.computer-group-id | -EXECUTOR_TANIUM_COMPUTER_GROUP_ID | -- | Tanium Computer Group to be used in simulations | -
| executor.tanium.windows-package-id | -EXECUTOR_TANIUM_WINDOWS_PACKAGE_ID | -- | ID of the OpenBAS Tanium Windows package | -
| executor.tanium.unix-package-id | -EXECUTOR_TANIUM_UNIX_PACKAGE_ID | -- | ID of the OpenBAS Tanium Unix package | -
| Parameter | -Environment variable | -Default value | -Description | -
|---|---|---|---|
| executor.caldera.enable | -EXECUTOR_CALDERA_ENABLE | -false |
-Enable the Caldera executor | -
| executor.caldera.url | -EXECUTOR_CALDERA_URL | -- | Caldera URL | -
| executor.caldera.public-url | -EXECUTOR_CALDERA_PUBLIC-URL | -- | Caldera URL accessible from endpoints | -
| executor.caldera.api-key | -EXECUTOR_CALDERA_API-KEY | -- | Caldera API key | -
For the associated mailbox, for the moment the platform only relies on IMAP / SMTP protocols, we are actively developing integrations with APIs such as O365 and Google Apps.
-| Parameter | -Environment variable | -Default value | -Description | -
|---|---|---|---|
| spring.mail.host | -SPRING_MAIL_HOST | -smtp.mail.com | -SMTP Server hostname | -
| spring.mail.port | -SPRING_MAIL_PORT | -465 | -SMTP Server port | -
| spring.mail.username | -SPRING_MAIL_USERNAME | -username@mail.com | -SMTP Server username | -
| spring.mail.password | -SPRING_MAIL_PASSWORD | -password | -SMTP Server password | -
| Parameter | -Environment variable | -Default value | -Description | -
|---|---|---|---|
| spring.mail.properties.mail.smtp.ssl.enable | -SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_ENABLE | -true |
-Turn on SMTP SSL mode | -
| spring.mail.properties.mail.smtp.ssl.trust | -SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_TRUST | -* | -Trust unverified certificates | -
| spring.mail.properties.mail.smtp.auth | -SPRING_MAIL_PROPERTIES_MAIL_SMTP_AUTH | -true |
-Turn on SMTP authentication | -
| spring.mail.properties.mail.smtp.starttls.enable | -SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE | -false |
-Turn on SMTP STARTTLS | -
| Parameter | -Environment variable | -Default value | -Description | -
|---|---|---|---|
| openbas.mail.imap.enabled | -OPENBAS_MAIL_IMAP_ENABLED | -false | -Turn on to enable IMAP mail synchronization. Injector email must be well configured | -
| openbas.mail.imap.host | -OPENBAS_MAIL_IMAP_HOST | -imap.mail.com | -IMAP Server hostname | -
| openbas.mail.imap.port | -OPENBAS_MAIL_IMAP_PORT | -993 | -IMAP Server port | -
| openbas.mail.imap.username | -OPENBAS_MAIL_IMAP_USERNAME | -username@mail.com | -IMAP Server username | -
| openbas.mail.imap.password | -OPENBAS_MAIL_IMAP_PASSWORD | -password | -IMAP Server password | -
| openbas.mail.imap.inbox | -OPENBAS_MAIL_IMAP_INBOX | -INBOX | -IMAP inbox directory to synchronize from | -
| openbas.mail.imap.sent | -OPENBAS_MAIL_IMAP_SENT | -Sent | -IMAP sent directory to synchronize from | -
| Parameter | -Environment variable | -Default value | -Description | -
|---|---|---|---|
| openbas.mail.imap.ssl.enable | -OPENBAS_MAIL_IMAP_SSL_ENABLE | -true | -Turn on IMAP SSL mode | -
| openbas.mail.imap.ssl.trust | -OPENBAS_MAIL_IMAP_SSL_TRUST | -* | -Trust unverified certificates | -
| openbas.mail.imap.auth | -OPENBAS_MAIL_IMAP_AUTH | -true | -Turn on IMAP authentication | -
| openbas.mail.imap.starttls.enable | -OPENBAS_MAIL_IMAP_STARTTLS_ENABLE | -true | -Turn on IMAP STARTTLS | -
AI deployment and cloud services
-There are several possibilities for Enterprise Edition customers to use OpenBAS AI endpoints:
-| Parameter | -Environment variable | -Default value | -Description | -
|---|---|---|---|
| ai.enabled | -AI_ENABLED | -true | -Enable AI capabilities | -
| ai.type | -AI_TYPE | -mistralai | -AI type (mistralai or openai) |
-
| ai.endpoint | -AI_ENDPOINT | -- | Endpoint URL (empty means default cloud service) | -
| ai.token | -AI_TOKEN | -- | Token for endpoint credentials | -
| ai.model | -AI_MODEL | -- | Model to be used for text generation (depending on type) | -
| ai.model_images | -AI_MODEL_IMAGES | -- | Model to be used for image generation (depending on type) | -
Injectors list
-You are looking for the available injectors? The list is in the OpenBAS Ecosystem.
-Injectors are one of the cornerstones of the OpenBAS platform, they are responsible for pushing simulation actions to third party systems. According to their functionality and use case, they are categorized in the following classes.
-
Those injectors are special as they required an executor (neutral agent) to be launched on endpoints. When they register to the platform, they inform available executors on how to spawn them on the 3 currently supported platforms: Windows, Linux and MacOS.
-Those injectors are used to push information to human assets (aka players) such as emails, SMS, phone calls, instant messaging etc.
-Those injectors are used to inject real or fake information into case management, ticketing and incident response systems.
-All other system OpenBAS can inject, as part of breach and attack simulation campaigns.
-Some injectors such as email, SMS, media pressure, etc. are directly embedded into the application. To configure them, just add the proper configuration parameters in your platform configuration.
-All external injectors have to be able to access the OpenBAS API. To allow this connection, they have 2 mandatory configuration parameters, the OPENBAS_URL and the OPENBAS_TOKEN. In addition to these 2 parameters, injectors have other mandatory parameters that need to be set in order to get them work.
Injector tokens
-You can use your administrator token or create another administrator service account to put in your injectors. It is not necessary to have one dedicated user for each injector.
-Here is an example of a injector docker-compose.yml file:
-
- OPENBAS_URL=http://localhost
-- OPENBAS_TOKEN=ChangeMe
-- INJECTOR_ID=ChangeMe # Valid UUIDv4
-- "INJECTOR_NAME=HTTP query"
-- INJECTOR_LOG_LEVEL=error
-Here is an example in a injector config.yml file:
openbas:
- url: 'http://localhost:3001'
- token: 'ChangeMe'
-
-injector:
- id: 'ChangeMe'
- name: 'HTTP query'
- log_level: 'info'
-Be aware that all injectors are reaching RabbitMQ based the RabbitMQ configuration provided by the OpenBAS platform. The injector must be able to reach RabbitMQ on the specified hostname and port. If you have a specific Docker network configuration, please be sure to adapt your docker-compose.yml file in such way that the injector container gets attached to the OpenBAS Network, e.g.:
You can either directly run the Docker image of injectors or add them to your current docker-compose.yml file.
For instance, to enable the HTTP query injector, you can add a new service to your docker-compose.yml file:
injector-http-query:
- image: openbas/injector-http-query:latest
- environment:
- - OPENBAS_URL=http://localhost
- - OPENBAS_TOKEN=ChangeMe
- - INJECTOR_ID=ChangeMe
- - "INJECTOR_NAME=HTTP query"
- - INJECTOR_LOG_LEVEL=error
- restart: always
-To launch standalone injector, you can use the docker-compose.yml file of the injector itself. Just download the latest release and start the injector:
$ wget https://github.com/OpenBAS-Platform/injectors/archive/{RELEASE_VERSION}.zip
-$ unzip {RELEASE_VERSION}.zip
-$ cd injectors-{RELEASE_VERSION}/http-query/
-Change the configuration in the docker-compose.yml according to the parameters of the platform and of the targeted service. Then launch the injector:
If you want to manually launch injector, you just have to install Python 3 and pip3 for dependencies:
- -Download the release of the injectors:
-$ wget <https://github.com/OpenBAS-Platform/injectors/archive/{RELEASE_VERSION}.zip>
-$ unzip {RELEASE_VERSION}.zip
-$ cd injectors-{RELEASE_VERSION}/http-query/src/
-Install dependencies and initialize the configuration:
- -Change the config.yml content according to the parameters of the platform and of the targeted service and launch the injector:
The injector status can be displayed in the dedicated section of the platform available in Integration > injectors. You will be able to see the statistics of the RabbitMQ queue of the injector:
-
Problem
-If you encounter problems deploying OpenBAS or injectors, you can consult the troubleshooting page page.
-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.yml provided
-in the docker.
Manual installation
-Deploy dependencies and launch the platform manually using the packages -released in the GitHub releases.
- -OpenBAS can be deployed using the docker-compose command.
-Linux
- -Windows and MacOS
-Just download the appropriate Docker for Desktop version for your operating system.
-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
-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.
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
-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:
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:
After changing your .env file run docker-compose in detached (-d) mode:
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.
-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:
- -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
-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:
- -Installation done
-You can now go to http://localhost:8080 and log in with the credentials configured in your application.properties file.
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=/openbasBy 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;
- }
-OpenBAS platform is based on a JAVA runtime. The application needs at least 4GB of RAM to work properly.
-PostgreSQL is the main database of OpenBAS. You can find more information in the official PostgresQL documentation.
-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.
- - - - - - - - - - - - - - - - - - - - - - - - -Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Before starting the installation, let's discover how OpenBAS is working, which dependencies are needed and what are the minimal requirements to deploy it in production.
-The OpenBAS platform relies on several external databases and services in order to work.
-
The platform is the central part of the OpenBAS platform, allowing users to configure scenarios, simulations, atomic testings and all other components used in the context of breach and attack simulations and security validations.
-Executors are embedded into the platform but you should configure at least one. It is the system that will be used to execute local injectors on endpoints. Currently we support Caldera (default) and Tanium but multiple will be added in the near future including a home-made XTM agent (by Filigran).
-Required executor
-Executors are responsible of executing endpoint payload injectors. To use them, you have to have at least one executor / neutral agent enabled. Injectors that require executors are marked in red in the OpenBAS Ecosystem.
-
Injects are used to interact with third-party applications or services (including execution on the endpoints through executors) in the context of a simulation or an atomic testing. A few injectors are built-in but most of them are standalone Python processes.
-List of injectors
-You can find all currently available injectors in the OpenBAS Ecosystem.
-Collectors are used to connect to all security systems such as SIEMs, XDRs, EDRs, firewalls, mail gateways etc. to check if an inject (execution, emails, etc.) has been detected or prevented and fill the security posture.
-List of collectors
-You can find all currently available collectors in the OpenBAS Ecosystem.
-| Component | -Version | -CPU | -RAM | -Disk type | -Disk space | -
|---|---|---|---|---|---|
| PostgreSQL | -≥ 16.0 | -2 cores | -≥ 8GB | -SSD | -≥ 16GB | -
| RabbitMQ | ->= 3.11 | -1 core | -≥ 512MB | -Standard | -≥ 2GB | -
| S3 / MinIO | -≥ RELEASE.2023-02 | -1 core | -≥ 128MB | -SSD | -≥ 16GB | -
| Component | -CPU | -RAM | -Disk type | -Disk space | -
|---|---|---|---|---|
| OpenBAS Core | -2 cores | -≥ 8GB | -None (stateless) | -- | -
| Injector(s) | -1 core | -≥ 128MB | -None (stateless) | -- | -
| Collector(s) | -1 core | -≥ 128MB | -None (stateless) | -- | -
Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Depending on your installation mode, upgrade path may change.
-Migrations
-The platform is taking care of all necessary underlying migrations in the databases if any, you can upgrade OpenBAS from any version to the latest one, including skipping multiple major releases.
-Before applying this procedure, please update your docker-compose.yml file with the new version number of container images.
For each of services, you have to run the following command:
- -When upgrading the platform, you have to replace all files and restart the platform, the database migrations will be done automatically:
- - - - - - - - - - - - - - - - - - - - - - - - - -Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Welcome to the OpenBAS Documentation space. Here you will be able to find all documents, meeting notes and presentations about the platform.
-Release notes
-Please, be sure to also take a look at the OpenBAS releases notes, they may contain important information about releases and deployments.
-OpenBAS is an open source platform allowing organizations to plan, schedule and conduct crisis exercises as well as adversary and breach simulations. OpenBAS is an ISO 22398 compliant product and has been designed as a modern web application including a RESTFul API and an UX oriented frontend.
-Deployment & Setup
-Learn how to deploy and configure the platform as well as -launch connectors to get the first data in OpenBAS.
- -User Guide
-Understand how to use the platform, create exercises and campaigns, use -media pressure simulation and integrate with other tools.
- -Administration
-Know how to administrate OpenBAS, create users and groups using RBAC / -segregation, customize the overall experience.
- -Need more help?
-We are doing our best to keep this documentation complete, accurate and up to date.
-If you still have questions or you find something which is not sufficiently explained, join the Filigran Community on Slack.
-All tutorials are published directly on the Medium blog, this section provides a comprehensive list of the most important ones.
-How we are disrupting tactical and strategical crisis management exercises with OpenBAS 3
- Oct 10, 2022
It’s been a while since we’ve talked about OpenBAS and yet… In the trying times we live in, both in cyberspace and in real life, crisis preparedness has become...
- -Plan, execute and conduct your crisis management exercises
- Jan 25, 2021
More than 3 years ago, we decided to build the OpenBAS application which allows organizations to facilitate the planning of crisis management...
- -Below, you will find external resources which may be useful along your OpenBAS journey.
- Training Courses
-Training courses for analysts and administrators in the Filigran training center.
Welcome to the OpenBAS Documentation space. Here you will be able to find all documents, meeting notes and presentations about the platform.
Release notes
Please, be sure to also take a look at the OpenBAS releases notes, they may contain important information about releases and deployments.
"},{"location":"#introduction","title":"Introduction","text":"OpenBAS is an open source platform allowing organizations to plan, schedule and conduct crisis exercises as well as adversary and breach simulations. OpenBAS is an ISO 22398 compliant product and has been designed as a modern web application including a RESTFul API and an UX oriented frontend.
"},{"location":"#getting-started","title":"Getting started","text":"Deployment & Setup
Learn how to deploy and configure the platform as well as launch connectors to get the first data in OpenBAS.
Deploy now
User Guide
Understand how to use the platform, create exercises and campaigns, use media pressure simulation and integrate with other tools.
Explore
Administration
Know how to administrate OpenBAS, create users and groups using RBAC / segregation, customize the overall experience.
Customize
Need more help?
We are doing our best to keep this documentation complete, accurate and up to date.
If you still have questions or you find something which is not sufficiently explained, join the Filigran Community on Slack.
"},{"location":"#latest-blog-posts","title":"Latest blog posts","text":"All tutorials are published directly on the Medium blog, this section provides a comprehensive list of the most important ones.
How we are disrupting tactical and strategical crisis management exercises with OpenBAS 3 Oct 10, 2022
It\u2019s been a while since we\u2019ve talked about OpenBAS and yet\u2026 In the trying times we live in, both in cyberspace and in real life, crisis preparedness has become...
Read
Plan, execute and conduct your crisis management exercises Jan 25, 2021
More than 3 years ago, we decided to build the OpenBAS application which allows organizations to facilitate the planning of crisis management...
Read
Below, you will find external resources which may be useful along your OpenBAS journey.
Training Courses Training courses for analysts and administrators in the Filigran training center.
"},{"location":"administration/enterprise/","title":"Enterprise edition","text":"Filigran
Filigran is providing an Enterprise Edition of the platform, whether on-premise or in the SaaS.
"},{"location":"administration/enterprise/#what-is-openbas-ee","title":"What is OpenBAS EE?","text":"OpenBAS Enterprise Edition is based on the open core concept. This means that the source code of OCTI EE remains open source and included in the main GitHub repository of the platform but is published under a specific license. As specified in the GitHub license file:
The source files in this repository have a header indicating which license they are under. If no such header is provided, this means that the file belongs to the Community Edition under the Apache License, Version 2.0.
"},{"location":"administration/enterprise/#ee-activation","title":"EE Activation","text":"Enterprise edition is easy to activate. You need to go the platform settings and click on the Activate button.
Then you will need to agree to the Filigran EULA.
As a reminder:
Be able to use AI for content generation including emails, media pressure articles etc.
"},{"location":"administration/enterprise/#more-to-come","title":"More to come","text":"More features will be available in OpenBAS in the future. Features like:
Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"administration/parameters/","title":"Parameters","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"administration/policies/","title":"Policies","text":""},{"location":"administration/policies/#overview","title":"Overview","text":"The Policies configuration page, located under Settings > Security > Policies, is designed to manage and customize various security-related settings. This page currently includes the configuration of login messages, with plans to expand its capabilities in the future.
"},{"location":"administration/policies/#current-features","title":"Current Features","text":"Login Messages Administrators can create and manage messages that are displayed to users upon login. This feature is useful for providing important information or updates directly to users when they access the platform. There are three types of messages: * Platform Login Message: Displayed above the login form to communicate vital information or announcements. * Platform Consent Message: Displayed to users during the login process. It appears as a notification that blocks access to the login form until users actively give their consent by checking an approval box. This ensures that users acknowledge and agree to certain terms or conditions before proceeding with logging in. * Platform Consent Confirm Text: A message accompanying the consent box, providing clarity on the consent confirmation process.
These messages can be customized to fit the organization's specific needs and requirements, ensuring that critical information is communicated effectively to users.
"},{"location":"administration/policies/#accessing-the-policies-configuration-page","title":"Accessing the Policies Configuration Page","text":"
To access the Policies configuration page, navigate to:
Settings / Security / Policies\nUnder construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"deployment/authentication/","title":"Authentication","text":""},{"location":"deployment/authentication/#introduction","title":"Introduction","text":"Welcome to the authentication documentation for OpenBAS. This documentation provides details on setting up and utilizing the authentication system, which supports multiple authentication methods to cater to different user needs and security requirements.
"},{"location":"deployment/authentication/#supported-authentication-methods","title":"Supported authentication methods","text":""},{"location":"deployment/authentication/#local-users","title":"Local users","text":"OpenBAS use this strategy as the default, but it's not the one we recommend for security reasons.
OPENBAS.AUTH-LOCAL-ENABLE: Set this to true to enable username/password authentication.Production deployment
Please use the LDAP/Auth0/OpenID/SAML strategy for production deployment.
"},{"location":"deployment/authentication/#openid","title":"OpenID","text":"This method allows to use the OpenID Connect Protocol to handle the authentication.
OPENBAS.AUTH-OPENID-ENABLE: Set this to true to enable OAuth (OpenID) authentication.Example for Auth0:
SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_{registrationId}_ISSUER-URI=https://auth.auth0.io\nSPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT-NAME=Login with auth0\nSPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT-ID=\nSPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT-SECRET=\nSPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_REDIRECT-URI=${openbas.base-url}/login/oauth2/code/{registrationId}\nSPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_SCOPE=openid,profile,email\nExample for GitHub (or others pre-handled oauth2 providers):
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT_NAME=Login with Github\nSPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT_ID=\nSPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT_SECRET=\nTips
{registrationId} is an arbitrary identifier you choose.
"},{"location":"deployment/authentication/#saml2","title":"SAML2","text":"This strategy can be used to authenticate your user with your company SAML.
OPENBAS.AUTH-SAML2-ENABLE: Set this to true to enable SAML2 authentication. Example for Microsoft :
SPRING_SECURITY_SAML2_RELYINGPARTY_REGISTRATION_{registrationId}_ENTITY-ID=\nSPRING_SECURITY_SAML2_RELYINGPARTY_REGISTRATION_{registrationId}_ASSERTINGPARTY_METADATA-URI=\nOPENBAS_PROVIDER_{registrationId}_FIRSTNAME_ATTRIBUTE_KEY=\nOPENBAS_PROVIDER_{registrationId}_LASTNAME_ATTRIBUTE_KEY=\nTips
{registrationId} is an arbitrary identifier you choose. metadata-uri is the uri of the xml file given by your identity provider
"},{"location":"deployment/authentication/#single-sign-on-url","title":"Single Sign On URL","text":""},{"location":"deployment/authentication/#saml2_1","title":"SAML2","text":"Url for the config of your sso provider
${openbas.base-url}/login/saml2/sso/{registrationId}\nTo grant administrative roles, you can utilize OAuth and SAML2 integration. If you opt for this approach, you'll need to include the following variables:
OPENBAS_PROVIDER_{registrationId}_ROLES_PATH=http://schemas.microsoft.com/ws/2008/06/identity/claims/role\nOPENBAS_PROVIDER_{registrationId}_ROLES_ADMIN=\nHowever, if you intend to manage administrative roles within the OpenBAS platform itself, there's no need to provide these variables.
"},{"location":"deployment/authentication/#error-handling","title":"Error Handling","text":"Under construction
We are doing our best to complete this page. If you want to participae, dont hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"deployment/clustering/","title":"Clustering","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"deployment/collectors/","title":"Collectors","text":""},{"location":"deployment/collectors/#introduction","title":"Introduction","text":"Collectors list
You are looking for the available collectors? The list is in the OpenBAS Ecosystem.
Collectors are one of the cornerstones of the OpenBAS platform, they are responsible for pulling data from various external services for two purposes:
Those collectors are the most import ones as they are used to evaluate the security posture (response to injects) from various detection and response systems and fulfill expectations for detection and prevention.
"},{"location":"deployment/collectors/#threat-intelligence","title":"\ud83e\uddec Threat Intelligence","text":"Those collectors are used to collect threat intelligence data such as kill chains, scenarios, TTPs, payloads, etc.
"},{"location":"deployment/collectors/#endpoint-management","title":"\ud83d\udcfa Endpoint management","text":"Those collectors are pulling alternative information about your endpoints and assets to complete the overview about your current posture in terms of vulnerabilities and compliance.
"},{"location":"deployment/collectors/#identities","title":"\ud83c\udfad Identities","text":"Those collectors are pulling all information related to identities, including human assets, to be used in scenario or to complete the view overview about your current posture.
"},{"location":"deployment/collectors/#others","title":"\ud83d\udd2d Others","text":"All other system OpenBAS can pull from, to add more meaningful and relevant information to the view of your security posture.
"},{"location":"deployment/collectors/#collectors-installation","title":"Collectors installation","text":""},{"location":"deployment/collectors/#built-in-collectors","title":"Built-in collectors","text":"Some collectors such as Microsoft Sentinel are directly embedded into the application. To configure them, just add the proper configuration parameters in your platform configuration.
"},{"location":"deployment/collectors/#external-python-collectors","title":"External (Python) collectors","text":""},{"location":"deployment/collectors/#configuration","title":"Configuration","text":"All external collectors have to be able to access the OpenBAS API. To allow this connection, they have 2 mandatory configuration parameters, the OPENBAS_URL and the OPENBAS_TOKEN. In addition to these 2 parameters, collectors have other mandatory parameters that need to be set in order to get them work.
Collector tokens
You can use your administrator token or create another administrator service account to put in your collectors. It is not necessary to have one dedicated user for each collector.
Here is an example of a collector docker-compose.yml file:
- OPENBAS_URL=http://localhost\n- OPENBAS_TOKEN=ChangeMe\n- COLLECTOR_ID=ChangeMe # Valid UUIDv4\n- \"COLLECTOR_NAME=MITRE ATT&CK\"\n- COLLECTOR_LOG_LEVEL=error\nHere is an example in a collector config.yml file:
openbas:\n url: 'http://localhost:3001'\n token: 'ChangeMe'\n\ncollector:\n id: 'ChangeMe'\n name: 'MITRE ATT&CK'\n log_level: 'info'\nYou can either directly run the Docker image of collectors or add them to your current docker-compose.yml file.
For instance, to enable the MITRE ATT&CK collector, you can add a new service to your docker-compose.yml file:
collector-mitre-attack:\n image: openbas/collector-mitre-attack:1.0.0\n environment:\n - OPENBAS_URL=http://localhost\n - OPENBAS_TOKEN=ChangeMe\n - COLLECTOR_ID=ChangeMe\n - \"COLLECTOR_NAME=MITRE ATT&CK\"\n - COLLECTOR_LOG_LEVEL=error\n restart: always\nTo launch standalone collector, you can use the docker-compose.yml file of the collector itself. Just download the latest release and start the collector:
$ wget https://github.com/OpenBAS-Platform/collectors/archive/{RELEASE_VERSION}.zip\n$ unzip {RELEASE_VERSION}.zip\n$ cd collectors-{RELEASE_VERSION}/mitre-attack/\nChange the configuration in the docker-compose.yml according to the parameters of the platform and of the targeted service. Then launch the collector:
$ docker-compose up\nIf you want to manually launch collector, you just have to install Python 3 and pip3 for dependencies:
$ apt install python3 python3-pip\nDownload the release of the collectors:
$ wget <https://github.com/OpenBAS-Platform/collectors/archive/{RELEASE_VERSION}.zip>\n$ unzip {RELEASE_VERSION}.zip\n$ cd collectors-{RELEASE_VERSION}/mitre-attack/src/\nInstall dependencies and initialize the configuration:
$ pip3 install -r requirements.txt\n$ cp config.yml.sample config.yml\nChange the config.yml content according to the parameters of the platform and of the targeted service and launch the collector:
$ python3 openbas_mitre.py\nThe collector status can be displayed in the dedicated section of the platform available in Integration > collectors. You will be able to see the statistics of the RabbitMQ queue of the collector:
Problem
If you encounter problems deploying OpenBAS or collectors, you can consult the troubleshooting page page.
"},{"location":"deployment/configuration/","title":"Configuration","text":"The purpose of this section is to learn how to configure OpenBAS to have it tailored for your production and development needs. It is possible to check all default parameters implemented in the platform in the application.properties file.
Here are the configuration keys, for both containers (environment variables) and manual deployment.
Parameters equivalence
The equivalent of a config variable in environment variables is the usage of an underscore (_) for a level of config.
For example:
spring.servlet.multipart.max-file-size=5GB\nwill become:
SPRING_SERVLET_MULTIPART_MAX-FILE-SIZE=5GB\nfalse Turn on if the access is done in HTTPS openbas.cookie-duration OPENBAS_COOKIE-DURATION P1D Cookie duration (default 1 day) openbas.admin.email OPENBAS_ADMIN_EMAIL admin@openbas.io Default login email of the admin user openbas.admin.password OPENBAS_ADMIN_PASSWORD ChangeMe Default password of the admin user openbas.admin.token OPENBAS_ADMIN_TOKEN ChangeMe Default token (must be a valid UUIDv4)"},{"location":"deployment/configuration/#network-and-security","title":"Network and security","text":"Parameter Environment variable Default value Description server.ssl.enabled SERVER_SSL_ENABLED false Turn on to enable SSL on the local server server.ssl.key-store-type SERVER_SSL_KEY-STORE-TYPE PKCS12 Type of SSL keystore server.ssl.key-store SERVER_SSL_KEY-STORE classpath:localhost.p12 SSL keystore path server.ssl.key-store-password SERVER_SSL_KEY-STORE-PASSWORD admin SSL keystore password server.ssl.key-alias SERVER_SSL_KEY-ALIAS localhost SSL key alias"},{"location":"deployment/configuration/#logging","title":"Logging","text":"Parameter Environment variable Default value Description logging.level.root LOGGING_LEVEL_ROOT fatal Root log level logging.level.io.openbas LOGGING_LEVEL_IO_OPENBAS warn OpenBAS log level logging.file.name LOGGING_FILE_NAME ./logs/openbas.log Log file path (in addition to console output) logging.logback.rollingpolicy.max-file-size LOGGING_LOGBACK_ROLLINGPOLICY_MAX-FILE-SIZE 10MB Rolling max file size logging.logback.rollingpolicy.max-history LOGGING_LOGBACK_ROLLINGPOLICY_MAX-HISTORY 7 Rolling max days"},{"location":"deployment/configuration/#dependencies","title":"Dependencies","text":""},{"location":"deployment/configuration/#xtm-suite","title":"XTM Suite","text":"Parameter Environment variable Default value Description openbas.xtm.opencti.enable OPENBAS_XTM_OPENCTI_ENABLE false Enable integration with OpenCTI openbas.xtm.opencti.url OPENBAS_XTM_OPENCTI_URL OpenCTI URL openbas.xtm.opencti.token OPENBAS_XTM_OPENCTI_TOKEN OpenCTI token openbas.xtm.opencti.disable-display OPENBAS_XTM_OPENCTI_DISABLE-DISPLAY false Disable OpenCTI in the UI"},{"location":"deployment/configuration/#postgresql","title":"PostgreSQL","text":"Parameter Environment variable Default value Description spring.datasource.url SPRING_DATASOURCE_URL jdbc:postgresql://... URL of the database (ex jdbc:postgresql://postgresql.mydomain.com:5432/openbas) spring.datasource.username SPRING_DATASOURCE_USERNAME Login for the database spring.datasource.password SPRING_DATASOURCE_PASSWORD password Password for the database"},{"location":"deployment/configuration/#rabbitmq","title":"RabbitMQ","text":"Parameter Environment variable Default value Description openbas.rabbitmq.prefix OPENBAS_RABBITMQ_PREFIX openbas Prefix for the queue names openbas.rabbitmq.hostname OPENBAS_RABBITMQ_HOSTNAME localhost Hostname of the RabbitMQ server openbas.rabbitmq.vhost OPENBAS_RABBITMQ_VHOST / Vhost of the RabbitMQ server openbas.rabbitmq.port OPENBAS_RABBITMQ_PORT 5672 Port of the RabbitMQ Server openbas.rabbitmq.management-port OPENBAS_RABBITMQ_MANAGEMENT-PORT 15672 Management port of the RabbitMQ Server openbas.rabbitmq.ssl OPENBAS_RABBITMQ_SSL false Use SSL openbas.rabbitmq.user OPENBAS_RABBITMQ_USER guest RabbitMQ user openbas.rabbitmq.pass OPENBAS_RABBITMQ_PASS guest RabbitMQ password openbas.rabbitmq.queue-type OPENBAS_RABBITMQ_QUEUE-TYPE classic RabbitMQ Queue Type (\"classic\" or \"quorum\")"},{"location":"deployment/configuration/#s3-bucket","title":"S3 bucket","text":"Parameter Environment variable Default value Description minio.endpoint MINIO_ENDPOINT localhost Hostname of the S3 Service. Example if you use AWS Bucket S3: s3.us-east-1.amazonaws.com (if minio:bucket_region value is us-east-1). This parameter value can be omitted if you use Minio as an S3 Bucket Service. minio.port MINIO_PORT 9000 Port of the S3 Service. For AWS Bucket S3 over HTTPS, this value can be changed (usually 443). minio.secure MINIO_SECURE false Indicates whether the S3 Service has TLS enabled. For AWS Bucket S3 over HTTPS, this value could be true. minio.access-key MINIO_ACCESS-KEY key Access key for the S3 Service. minio.access-secret MINIO_ACCESS-SECRET secret Secret key for the S3 Service. minio.bucket MINIO_BUCKET openbas S3 bucket name. Useful to change if you use AWS. minio.bucket-region MINIO_BUCKET-REGION us-east-1 Region of the S3 bucket if you are using AWS. This parameter value can be omitted if you use Minio as an S3 Bucket Service."},{"location":"deployment/configuration/#agents-executors","title":"Agents (executors)","text":"To be able to use the power of the OpenBAS platform on endpoints, you need at least one executor that will be in charge of spawing temporary processes (endpoint injectors) which will execute payloads.
"},{"location":"deployment/configuration/#openbas-agent","title":"OpenBAS Agent","text":"The OpenBAS agent is enabled by default and cannot be disabled. It is available for:
x86_64 / arm64)x86_64 / arm64)x86_64 / arm64)Tanium Packages
To use the Tanium executor, please install the OpenBAS packages on the Tanium platform and fill their IDs in the configuration below.
Parameter Environment variable Default value Description executor.tanium.enable EXECUTOR_TANIUM_ENABLEfalse Enable the Tanium executor executor.tanium.url EXECUTOR_TANIUM_URL Tanium URL executor.tanium.api-key EXECUTOR_TANIUM_API-KEY Tanium API key executor.tanium.computer-group-id EXECUTOR_TANIUM_COMPUTER_GROUP_ID Tanium Computer Group to be used in simulations executor.tanium.windows-package-id EXECUTOR_TANIUM_WINDOWS_PACKAGE_ID ID of the OpenBAS Tanium Windows package executor.tanium.unix-package-id EXECUTOR_TANIUM_UNIX_PACKAGE_ID ID of the OpenBAS Tanium Unix package"},{"location":"deployment/configuration/#caldera","title":"Caldera","text":"Parameter Environment variable Default value Description executor.caldera.enable EXECUTOR_CALDERA_ENABLE false Enable the Caldera executor executor.caldera.url EXECUTOR_CALDERA_URL Caldera URL executor.caldera.public-url EXECUTOR_CALDERA_PUBLIC-URL Caldera URL accessible from endpoints executor.caldera.api-key EXECUTOR_CALDERA_API-KEY Caldera API key"},{"location":"deployment/configuration/#mail-services","title":"Mail services","text":"For the associated mailbox, for the moment the platform only relies on IMAP / SMTP protocols, we are actively developing integrations with APIs such as O365 and Google Apps.
"},{"location":"deployment/configuration/#smtp","title":"SMTP","text":"Parameter Environment variable Default value Description spring.mail.host SPRING_MAIL_HOST smtp.mail.com SMTP Server hostname spring.mail.port SPRING_MAIL_PORT 465 SMTP Server port spring.mail.username SPRING_MAIL_USERNAME username@mail.com SMTP Server username spring.mail.password SPRING_MAIL_PASSWORD password SMTP Server password Parameter Environment variable Default value Description spring.mail.properties.mail.smtp.ssl.enable SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_ENABLEtrue Turn on SMTP SSL mode spring.mail.properties.mail.smtp.ssl.trust SPRING_MAIL_PROPERTIES_MAIL_SMTP_SSL_TRUST * Trust unverified certificates spring.mail.properties.mail.smtp.auth SPRING_MAIL_PROPERTIES_MAIL_SMTP_AUTH true Turn on SMTP authentication spring.mail.properties.mail.smtp.starttls.enable SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE false Turn on SMTP STARTTLS"},{"location":"deployment/configuration/#imap","title":"IMAP","text":"Parameter Environment variable Default value Description openbas.mail.imap.enabled OPENBAS_MAIL_IMAP_ENABLED false Turn on to enable IMAP mail synchronization. Injector email must be well configured openbas.mail.imap.host OPENBAS_MAIL_IMAP_HOST imap.mail.com IMAP Server hostname openbas.mail.imap.port OPENBAS_MAIL_IMAP_PORT 993 IMAP Server port openbas.mail.imap.username OPENBAS_MAIL_IMAP_USERNAME username@mail.com IMAP Server username openbas.mail.imap.password OPENBAS_MAIL_IMAP_PASSWORD password IMAP Server password openbas.mail.imap.inbox OPENBAS_MAIL_IMAP_INBOX INBOX IMAP inbox directory to synchronize from openbas.mail.imap.sent OPENBAS_MAIL_IMAP_SENT Sent IMAP sent directory to synchronize from Parameter Environment variable Default value Description openbas.mail.imap.ssl.enable OPENBAS_MAIL_IMAP_SSL_ENABLE true Turn on IMAP SSL mode openbas.mail.imap.ssl.trust OPENBAS_MAIL_IMAP_SSL_TRUST * Trust unverified certificates openbas.mail.imap.auth OPENBAS_MAIL_IMAP_AUTH true Turn on IMAP authentication openbas.mail.imap.starttls.enable OPENBAS_MAIL_IMAP_STARTTLS_ENABLE true Turn on IMAP STARTTLS"},{"location":"deployment/configuration/#ai-service","title":"AI Service","text":"AI deployment and cloud services
There are several possibilities for Enterprise Edition customers to use OpenBAS AI endpoints:
mistralai or openai) ai.endpoint AI_ENDPOINT Endpoint URL (empty means default cloud service) ai.token AI_TOKEN Token for endpoint credentials ai.model AI_MODEL Model to be used for text generation (depending on type) ai.model_images AI_MODEL_IMAGES Model to be used for image generation (depending on type)"},{"location":"deployment/injectors/","title":"Injectors","text":""},{"location":"deployment/injectors/#introduction","title":"Introduction","text":"Injectors list
You are looking for the available injectors? The list is in the OpenBAS Ecosystem.
Injectors are one of the cornerstones of the OpenBAS platform, they are responsible for pushing simulation actions to third party systems. According to their functionality and use case, they are categorized in the following classes.
"},{"location":"deployment/injectors/#endpoint-payloads-execution","title":"\ud83d\udce1 Endpoint payloads execution","text":"Those injectors are special as they required an executor (neutral agent) to be launched on endpoints. When they register to the platform, they inform available executors on how to spawn them on the 3 currently supported platforms: Windows, Linux and MacOS.
"},{"location":"deployment/injectors/#communication-social-medias","title":"\ud83c\udf10 Communication & social medias","text":"Those injectors are used to push information to human assets (aka players) such as emails, SMS, phone calls, instant messaging etc.
"},{"location":"deployment/injectors/#incident-response-case-management","title":"\ud83e\uddef Incident Response & Case Management","text":"Those injectors are used to inject real or fake information into case management, ticketing and incident response systems.
"},{"location":"deployment/injectors/#others","title":"\ud83d\udc89 Others","text":"All other system OpenBAS can inject, as part of breach and attack simulation campaigns.
"},{"location":"deployment/injectors/#injectors-installation","title":"Injectors installation","text":""},{"location":"deployment/injectors/#built-in-injectors","title":"Built-in injectors","text":"Some injectors such as email, SMS, media pressure, etc. are directly embedded into the application. To configure them, just add the proper configuration parameters in your platform configuration.
"},{"location":"deployment/injectors/#external-python-injectors","title":"External (Python) injectors","text":""},{"location":"deployment/injectors/#configuration","title":"Configuration","text":"All external injectors have to be able to access the OpenBAS API. To allow this connection, they have 2 mandatory configuration parameters, the OPENBAS_URL and the OPENBAS_TOKEN. In addition to these 2 parameters, injectors have other mandatory parameters that need to be set in order to get them work.
Injector tokens
You can use your administrator token or create another administrator service account to put in your injectors. It is not necessary to have one dedicated user for each injector.
Here is an example of a injector docker-compose.yml file:
- OPENBAS_URL=http://localhost\n- OPENBAS_TOKEN=ChangeMe\n- INJECTOR_ID=ChangeMe # Valid UUIDv4\n- \"INJECTOR_NAME=HTTP query\"\n- INJECTOR_LOG_LEVEL=error\nHere is an example in a injector config.yml file:
openbas:\n url: 'http://localhost:3001'\n token: 'ChangeMe'\n\ninjector:\n id: 'ChangeMe'\n name: 'HTTP query'\n log_level: 'info'\nBe aware that all injectors are reaching RabbitMQ based the RabbitMQ configuration provided by the OpenBAS platform. The injector must be able to reach RabbitMQ on the specified hostname and port. If you have a specific Docker network configuration, please be sure to adapt your docker-compose.yml file in such way that the injector container gets attached to the OpenBAS Network, e.g.:
networks:\n default:\n external: true\n name: openbas-docker_default\nYou can either directly run the Docker image of injectors or add them to your current docker-compose.yml file.
For instance, to enable the HTTP query injector, you can add a new service to your docker-compose.yml file:
injector-http-query:\n image: openbas/injector-http-query:latest\n environment:\n - OPENBAS_URL=http://localhost\n - OPENBAS_TOKEN=ChangeMe\n - INJECTOR_ID=ChangeMe\n - \"INJECTOR_NAME=HTTP query\"\n - INJECTOR_LOG_LEVEL=error\n restart: always\nTo launch standalone injector, you can use the docker-compose.yml file of the injector itself. Just download the latest release and start the injector:
$ wget https://github.com/OpenBAS-Platform/injectors/archive/{RELEASE_VERSION}.zip\n$ unzip {RELEASE_VERSION}.zip\n$ cd injectors-{RELEASE_VERSION}/http-query/\nChange the configuration in the docker-compose.yml according to the parameters of the platform and of the targeted service. Then launch the injector:
$ docker-compose up\nIf you want to manually launch injector, you just have to install Python 3 and pip3 for dependencies:
$ apt install python3 python3-pip\nDownload the release of the injectors:
$ wget <https://github.com/OpenBAS-Platform/injectors/archive/{RELEASE_VERSION}.zip>\n$ unzip {RELEASE_VERSION}.zip\n$ cd injectors-{RELEASE_VERSION}/http-query/src/\nInstall dependencies and initialize the configuration:
$ pip3 install -r requirements.txt\n$ cp config.yml.sample config.yml\nChange the config.yml content according to the parameters of the platform and of the targeted service and launch the injector:
$ python3 openbas_http.py\nThe injector status can be displayed in the dedicated section of the platform available in Integration > injectors. You will be able to see the statistics of the RabbitMQ queue of the injector:
Problem
If you encounter problems deploying OpenBAS or injectors, you can consult the troubleshooting page page.
"},{"location":"deployment/installation/","title":"Installation","text":"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.yml provided in the docker.
Setup
Manual installation
Deploy dependencies and launch the platform manually using the packages released in the GitHub releases.
Explore
OpenBAS can be deployed using the docker-compose command.
"},{"location":"deployment/installation/#pre-requisites","title":"Pre-requisites","text":"Linux
sudo apt install docker-compose\nWindows and MacOS
Just download the appropriate Docker for Desktop version for your operating system.
"},{"location":"deployment/installation/#clone-the-repository","title":"Clone the repository","text":"Docker helpers are available in the Docker GitHub repository.
mkdir -p /path/to/your/app && cd /path/to/your/app\ngit clone https://github.com/OpenBAS-Platform/docker.git\ncd docker\nBefore 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.
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:\n red:\n red: ChangeMe # Change this\n blue:\n blue: ChangeMe # Change this\napi_key_red: ChangeMe # Change this\napi_key_blue: ChangeMe # Change this\napi_key: ChangeMe # Change this\ncrypt_salt: ChangeMe # Change this\nencryption_key: ChangeMe # Change this\napp.contact.http: http://caldera.myopenbas.myorganization.com:8888 # Change this\napp.contact.tunnel.ssh.user_password: ChangeMe # Change this\nConfiguration 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\nPOSTGRES_PASSWORD=ChangeMe\nKEYSTORE_PASSWORD=ChangeMe\nMINIO_ROOT_USER=ChangeMeAccess\nMINIO_ROOT_PASSWORD=ChangeMeKey\nRABBITMQ_DEFAULT_USER=ChangeMe\nRABBITMQ_DEFAULT_PASS=ChangeMe\nSPRING_MAIL_HOST=smtp.changeme.com\nSPRING_MAIL_PORT=465\nSPRING_MAIL_USERNAME=ChangeMe@domain.com\nSPRING_MAIL_PASSWORD=ChangeMe\nOPENBAS_MAIL_IMAP_HOST=imap.changeme.com\nOPENBAS_MAIL_IMAP_PORT=993\nOPENBAS_ADMIN_EMAIL=ChangeMe\nOPENBAS_ADMIN_PASSWORD=ChangeMe\nOPENBAS_ADMIN_TOKEN=ChangeMe\nCALDERA_PUBLIC_URL=http://localhost:8888 # Change me for production deployment to something accessible from your endpoint(s)\nCALDERA_API_KEY=ChangeMe\nCOLLECTOR_MITRE_ATTACK_ID=3050d2a3-291d-44eb-8038-b4e7dd107436 # No need for change\nCaldera 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:
export $(cat .env | grep -v \"#\" | xargs)\nThe 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:
volumes:\n esdata: # ElasticSearch data\n s3data: # S3 bucket data\n amqpdata: # RabbitMQ data\nAfter changing your .env file run docker-compose in detached (-d) mode:
sudo systemctl start docker.service\n# Run docker-compose in detached \ndocker-compose up -d\nIn 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.
# If your virtual machine is not a part of a Swarm cluster, please use:\ndocker swarm init\nPut your environment variables in /etc/environment:
# If you already exported your variables to .env from above:\nsudo cat .env >> /etc/environment\nsudo bash -c 'cat .env >> /etc/environment\u2019\nsudo docker stack deploy --compose-file docker-compose.yml openbas\nInstallation done
You can now go to http://localhost:8080 and log in with the credentials filled in your configuration.
"},{"location":"deployment/installation/#manual-installation","title":"Manual installation","text":""},{"location":"deployment/installation/#prepare-the-installation","title":"Prepare the installation","text":""},{"location":"deployment/installation/#installation-of-dependencies","title":"Installation of dependencies","text":"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:
sudo apt install openjdk-22-jre \nFirst, you have to download and extract the latest release file.
mkdir /path/to/your/app && cd /path/to/your/app\nwget <https://github.com/OpenBAS-Platform/openbas/releases/download/{RELEASE_VERSION}/openbas-release-{RELEASE_VERSION}.tar.gz>\ntar xvfz openbas-release-{RELEASE_VERSION}.tar.gz\nThe main application has just one environment configuration file to change.
cd openbas\nChange the application.properties file according to your configuration of PostgreSQL, RabbitMQ, Minio and Caldera admin account and to your platform.
"},{"location":"deployment/installation/#start-the-application","title":"Start the application","text":"Start the Application:
java -jar openbas-api.jar\nInstallation done
You can now go to http://localhost:8080 and log in with the credentials configured in your application.properties file.
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=/openbasBy default OpenBAS use websockets so don't forget to configure your proxy for this usage, an example with Nginx:
location / {\n proxy_cache off;\n proxy_buffering off;\n proxy_http_version 1.1;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection \"upgrade\";\n proxy_set_header Host $host;\n chunked_transfer_encoding off;\n proxy_pass http://YOUR_UPSTREAM_BACKEND;\n }\nOpenBAS platform is based on a JAVA runtime. The application needs at least 4GB of RAM to work properly.
"},{"location":"deployment/installation/#postgresql","title":"PostgreSQL","text":"PostgreSQL is the main database of OpenBAS. You can find more information in the official PostgresQL documentation.
"},{"location":"deployment/installation/#minio","title":"MinIO","text":"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.
"},{"location":"deployment/integrations/","title":"Integrations","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"deployment/overview/","title":"Overview","text":"Before starting the installation, let's discover how OpenBAS is working, which dependencies are needed and what are the minimal requirements to deploy it in production.
"},{"location":"deployment/overview/#architecture","title":"Architecture","text":"The OpenBAS platform relies on several external databases and services in order to work.
"},{"location":"deployment/overview/#platform","title":"Platform","text":"The platform is the central part of the OpenBAS platform, allowing users to configure scenarios, simulations, atomic testings and all other components used in the context of breach and attack simulations and security validations.
"},{"location":"deployment/overview/#neutral-agents-executors","title":"Neutral agents / executors","text":"Executors are embedded into the platform but you should configure at least one. It is the system that will be used to execute local injectors on endpoints. Currently we support Caldera (default) and Tanium but multiple will be added in the near future including a home-made XTM agent (by Filigran).
Required executor
Executors are responsible of executing endpoint payload injectors. To use them, you have to have at least one executor / neutral agent enabled. Injectors that require executors are marked in red in the OpenBAS Ecosystem.
"},{"location":"deployment/overview/#injectors","title":"Injectors","text":"Injects are used to interact with third-party applications or services (including execution on the endpoints through executors) in the context of a simulation or an atomic testing. A few injectors are built-in but most of them are standalone Python processes.
List of injectors
You can find all currently available injectors in the OpenBAS Ecosystem.
"},{"location":"deployment/overview/#collectors","title":"Collectors","text":"Collectors are used to connect to all security systems such as SIEMs, XDRs, EDRs, firewalls, mail gateways etc. to check if an inject (execution, emails, etc.) has been detected or prevented and fill the security posture.
List of collectors
You can find all currently available collectors in the OpenBAS Ecosystem.
"},{"location":"deployment/overview/#infrastructure-requirements","title":"Infrastructure requirements","text":""},{"location":"deployment/overview/#dependencies","title":"Dependencies","text":"Component Version CPU RAM Disk type Disk space PostgreSQL \u2265 16.0 2 cores \u2265 8GB SSD \u2265 16GB RabbitMQ >= 3.11 1 core \u2265 512MB Standard \u2265 2GB S3 / MinIO \u2265 RELEASE.2023-02 1 core \u2265 128MB SSD \u2265 16GB"},{"location":"deployment/overview/#platform_1","title":"Platform","text":"Component CPU RAM Disk type Disk space OpenBAS Core 2 cores \u2265 8GB None (stateless) - Injector(s) 1 core \u2265 128MB None (stateless) - Collector(s) 1 core \u2265 128MB None (stateless) -"},{"location":"deployment/resources/","title":"Resources","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"deployment/troubleshooting/","title":"Troubleshooting","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"deployment/upgrade/","title":"Upgrade","text":"Depending on your installation mode, upgrade path may change.
Migrations
The platform is taking care of all necessary underlying migrations in the databases if any, you can upgrade OpenBAS from any version to the latest one, including skipping multiple major releases.
"},{"location":"deployment/upgrade/#using-docker","title":"Using Docker","text":"Before applying this procedure, please update your docker-compose.yml file with the new version number of container images.
$ sudo docker-compose stop\n$ sudo docker-compose pull\n$ sudo docker-compose up -d\nFor each of services, you have to run the following command:
$ sudo docker service update --force service_name\nWhen upgrading the platform, you have to replace all files and restart the platform, the database migrations will be done automatically:
$ java -jar openbas-api.jar\nUnder construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"development/environment_ubuntu/","title":"Prerequisites Ubuntu","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"development/environment_windows/","title":"Prerequisites Windows","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"development/injectors/","title":"Injector development","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"development/platform/","title":"Platform development","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"usage/assets/","title":"Assets","text":"The Assets section provides users with a centralized hub for managing and organizing the entities targeted for testing and simulation.
When you click on \u201cAssets\u201d in the left-hand banner, you see all the \u201cAssets\u201d pages. When accessing the Assets section, users are directed by default to the Endpoints page, where they can start managing their assets.
From the Assets section, users can access the following pages:
Endpoints: Individual entities, representing any object or terminal that can be connected to a network.Asset groups: Group of asset allowing you to organize endpoints into logical groups based on various filters applied by the user.Endpoints encompass devices and systems that connect to a network, serving as the foundation for interaction with OpenBAS.
The list of endpoints continues to grow with the changing landscape of networked technologies and the increasing interconnectivity of digital ecosystems. Below is a non-exhaustive list of terminal categories:
When accessing the Endpoints pages, you see the list of all endpoints imported in your platform. Here, users can create and manage details specific to each endpoint.
Assets can be imported with the help of specific Collectors, like Microsoft Entra.
"},{"location":"usage/assets/#asset-groups","title":"Asset groups","text":"Asset groups serve as a mechanism for organizing and grouping related Endpoints. These groups are constructed based on filters that define the criteria for inclusion, allowing administrators to segment and categorize Endpoints based on common characteristics or attributes.
When creating a new asset group, administrators have the flexibility to specify the filters that will delineate the group's membership. Currently, the platform offers a range of filters such as platform type, hostname, and IP addresses. We plan to extend the possibilities by including additional filters in future updates.
"},{"location":"usage/atomic/","title":"Atomic testing","text":"Under construction
We are doing our best to complete this page. If you want to participae, dont hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
When clicking on Atomic testing in the left menu, you access to the list of all atomic testings ever launched in the platform.
Atomic testing is a great way to simulate a singular attack technique you are particulary interested in, and test immediately your capability to prevent and detect it.
You can search for a specific one by name.
The presented list allows you to easily see global scores of all your recent atomic testings.
"},{"location":"usage/atomic/#create-an-atomic-testing","title":"Create an Atomic testing","text":"An atomic testing is essentially the simulation of a single inject, against a selection of targets (Players, Teams, Assets, Assets Group) with assorted expectations.
By clicking on the + button at the bottom right of the screen, you enter the atomic testing creation workflow.
On the left of the creation screen is the list of all available Inject you can play for atomic testing. Logos on the left of each line indicates which Injector is associated with each inject.
Depending on your integrations, this list can be long. You can filter the list by compatible platforms or by Mitre Att&ck tactics.By clicking on the \"Att&CK\" logo near the search bar, you can also filter by selecting a precise Mitre Att&ck techniques.
When selecting an inject on the left, the form on the right populates itself with a by-default title and propose you to define when the inject should be played after the launch of the atomic testing. You can keep it to 0.
By clicking on Inject content, you can define now or later the targeted assets or players, needed configurations, and the assorted expectations.
The \"available variables\" button helps you to use already defined variables into compatible fields.
"},{"location":"usage/atomic/#atomic-testing-screens","title":"Atomic testing screens","text":"Details of an Atomic testing is composed of three parts: - a header allowing to launch the test, see its state and update/delete it. - an Overview screen to eaily see the results of the test. - an execution details screen to see expectations of the test and investigate on execution logs
"},{"location":"usage/atomic/#overview","title":"Overview","text":"The first screen displayed when you click on a specific Atomic testing from the list is a breakdown of your security posture against this test.
As for Simulation and Scenario, Results are broken down into: - Prevention: the ability of your security posture to prevent the inject - Detection: the ability of your security posture to detect the inject - Human response: the ability of your security teams to react as intented facing the inject
Big metrics on top of the screen sum up the expectations' result of all targets.
The list of targets on the left allows you to easily see the result per Target, and for example investigate further why a specific Asset have failed the test.
For a selected target, you can on the right the timeline of the test against the target and the assorted results. The result logs are also displayed.
"},{"location":"usage/atomic/#execution-details","title":"Execution details","text":"On this screen, you can retrieve details about the atomic testing and its expectations.
You can also see the raw execution logs of the Injector responsible for the test execution.
"},{"location":"usage/challenges/","title":"Challenges","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"usage/channels/","title":"Channels","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
In OpenBAS, Channels represent communication medias with a particular look. There are used to present web articles or other media contents to Players in a specific way.
It helps give shape to your Scenario context and events.
"},{"location":"usage/channels/#create-a-channel","title":"Create a Channel","text":"First step is to click on the + button at the bottom right and give your new Channel a type (Newspaper, Microblogging, TV Channel), a name and a subtitle.
Once done, click on the Channel in the list to access its overview. Here you can define how media content associated to this Chennel will be displayed to Players.
You can define primary and secondary colors, choose logos and define how the header is presented.
On the right, a mock up of the overview is displayed to give you the look and fill of it.
"},{"location":"usage/channels/#use-a-channel","title":"Use a Channel","text":"A Channel will then be used in Scenario and in Simulation definition. When you create an Article, you have to choose the Channel that will give it an adequate shape.
See Media pressure page to know how to create and add Articles to your Scenarios.
"},{"location":"usage/collector-caldera/","title":"Caldera collector","text":"The integration between an OpenBAS instance and a Caldera instance allows you to enrich assets data.
"},{"location":"usage/collector-caldera/#configuration-variables","title":"Configuration variables","text":"Below are the properties you'll need to set for OpenBAS:
Property application.properties Docker environment variable Mandatory Description Enable Caldera collector collector.caldera.enableCOLLECTOR.CALDERA.ENABLE Yes Enable the Caldera collector. Collector ID collector.caldera.id COLLECTOR.CALDERA.ID Yes The ID of the collector. Caldera URL collector.caldera.url COLLECTOR.CALDERA.URL Yes The URL of the Caldera instance. Caldera API Key collector.caldera.api-key COLLECTOR.CALDERA.API-KEY Yes The API Key for the rest API of the Caldera instance. Caldera polling interval collector.caldera.interval COLLECTOR.CALDERA.INTERVAL No The time interval in seconds where the collect is triggered. Default is 60 seconds."},{"location":"usage/collector-caldera/#behavior","title":"Behavior","text":"Each interval, a job retrieves the deployed agents on Caldera and populates the OpenBAS database by creating Assets.
Deduplication is done thanks to the caldera paw property :
paw, a new asset is createdpaw and the source of creation is only Caldera, this asset is updatedThere is no automatic deletion of OpenBAS assets if Caldera agents no longer exist.
"},{"location":"usage/collector-caldera/#mapping","title":"Mapping","text":"Agent Property Asset Property paw externalId paw name host_ip_addrs ips platform platform last_seen lastSeen"},{"location":"usage/collectors/","title":"Collectors","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"usage/components/","title":"Components","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"usage/documents/","title":"Documents","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"usage/expectations/","title":"Expectations","text":"Expectations define what is expected from an Asset (endpoint) or a Players when facing an Inject in terms of security posture. Each expectation has a score representing how well it has been met by the target.
"},{"location":"usage/expectations/#expectation-types","title":"Expectation types","text":"Expectations can be categorized as either Manual or Automatic, depending on how they are validated.
"},{"location":"usage/expectations/#manual-expectations","title":"Manual expectations","text":"Manual expectations require manual validation by the animation team, with the validation process and scoring managed manually. They are simple, customizable expectations to be manually validated.
"},{"location":"usage/expectations/#automatic-expectations","title":"Automatic expectations","text":"Automatic expectations are validated automatically under specific conditions. Currently available automatic expectations include:
Automatic - Prevention: Triggered when inject is processed: automatically validated by security integration with compatible Collectors if the inject's action generates a prevention alert, such as quarantine.Automatic - Detection: Triggered when inject is processed: automatically validated by security integration with compatible Collectors if the inject's action generates a detection alert, such as an incident.Automatic - Triggered when team reads articles: Automatically validated when the article of a Media pressure inject has been read by targets.For injects targeting asset groups, some expectations can be validated in two modes:
Special case: Publish Challenges inject
The \"Publish Challenges\" inject doesn't require an expectation, as results are computed directly from Challenges' scores.
"},{"location":"usage/expectations/#expectation-manipulation","title":"Expectation manipulation","text":""},{"location":"usage/expectations/#add-an-expectation-to-an-inject","title":"Add an expectation to an inject","text":"To add expectations to an inject, navigate to the inject's content and click on \"Add expectations\". From there, select the type of expectation you want to add and set a score for it.
You can add multiple expectations to a single inject.
"},{"location":"usage/expectations/#validate-a-manual-expectation","title":"Validate a manual expectation","text":"If you have configured manual expectations in your scenario, you will have the opportunity to handle manual validations during each simulation. During a Simulation, navigate to the Animation tab, under the Validation screen. Here, you'll find a list of expectations that require manual validation.
"},{"location":"usage/exports/","title":"Exports","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"usage/getting-started/","title":"Getting started","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
This guide aims to give you a full overview of the OpenBAS features and workflows. The platform can be used in various contexts to handle Breach and Attack simulations at technical or strategical levels. OpenBAS has been designed as a part of the Filigran XTM suite and can be integrated with OpenCTI to generate meaningful attack scenario based on real threat. OpenBAS is result-oriented with many dashboard helping you to evaluate you securoty posture given a defined context.
Here are some examples of use cases: - Designing attack scenario based on real threat - Evaluate your security posture against technical simulations on endpoints - Enhance team skills by evaluating them during simulations along with your security systems - Organize Capture The Flag with multiple challenges - Conduct atomic testing
"},{"location":"usage/getting-started/#home-screen","title":"Home screen","text":"The Home screen gives any visitor on the OpenBAS platform an outlook on the live of the platform as well as an overview of your global security posture.
"},{"location":"usage/getting-started/#your-first-breach-and-attack-simulation","title":"Your first Breach and Attack Simulation","text":""},{"location":"usage/getting-started/#importing-players-and-assets-to-play-with","title":"Importing players and assets to play with","text":"First, you need to import Players and Assets that will participate to the simulation and be targeted by technical or strategical events. To do so, you need to ...
"},{"location":"usage/getting-started/#integrate-with-simulation-agent-to-simulate-technical-events","title":"Integrate with Simulation Agent to simulate technical events","text":"If you want to simulate attack at a technical level, you will need to install a Simulation Agent that will play technical events on your imported assets. To do so, you can go to the dedicated panel from the top right button and follow installation instructions. By default, Caldera is part of the OpenBAS stack.
The Caldera agent will allow you to play various technical events, based on the Mitre ATT&CK matrix.
"},{"location":"usage/getting-started/#building-your-scenario","title":"Building your Scenario","text":"Once integrations is done, you are ready to create your first Scenario!
Scenarios act as template for your Breach and Attack simulations. After establihing such a template, you will be able to schedule it as a one shot simulation, or as a recurring one.
Optionnaly, you can buff up your scenario by adding Documents, Media pressures, or even CTF Challenges to your injects.
"},{"location":"usage/getting-started/#play-the-simulation","title":"Play the simulation","text":"You can now schedule your Simulation by hitting the blue \"Simulate now\" button. Choose your moment and hit start.
On time, a Simulation based on your Scenario template is generated. it is listed in your Scenario overview and in the Simulations menu. Fron there, you can follow the course of the Simulation and interact with it, for example to validate manual expectations.
During the course of the simulation, results are updated and can be consulted in the Simulation overview.
"},{"location":"usage/getting-started/#evaluate-your-security-posture","title":"Evaluate your security posture","text":"Results in OpenBAS are based on expectations' results that are linked to injects played during Simulations. It is then important to manually validate expectations that need it.
Results are broken down by \"Prevention\", \"Detection\" and \"Human response\" metrics. - Prevention displays your ability to prevent the scenario's technical events to be completed - Detection displays your ability to detect the scenario's technical events - HUman response displays how well players and teams react as expected facing the scenario's events.
"},{"location":"usage/inject-caldera/","title":"Caldera injects","text":"The Caldera framework, developed by MITRE, is a powerful framework designed to simulate cyberattacks. It enables security teams to conduct realistic and controlled simulations of adversary behavior, reducing the amount of time and resources needed for routine cybersecurity testing.
"},{"location":"usage/inject-caldera/#injects","title":"Injects","text":"In OpenBAS, the Caldera framework has been fully integrated, offering users access to a comprehensive library of injects for conducting simulation exercises. With this integration, users can leverage the extensive capabilities of Caldera within OpenBAS.
Caldera offers 1600+ abilities, covering the full range of ATT&CK tactics and techniques. These capabilities equip security teams with an extensive toolkit to simulate various threats and assess defense mechanisms effectively.
"},{"location":"usage/inject-caldera/#behavior","title":"Behavior","text":"Injects within the Caldera framework can be played on both individual Endpoints and Asset groups. Prior to playing injects, Caldera agents need to be installed on the target machines to enable interaction with the platform.
Once the agents are deployed, simulations with Caldera injects can be executed. The platform will contact the agent to start the ability. Subsequently, the agents will report the results to OpenBAS. Below is the workflow illustrating the behavior of injects.
"},{"location":"usage/inject-caldera/#configuration-variables","title":"Configuration variables","text":"Below are the properties you'll need to set for OpenBAS:
Property application.properties Docker environment variable Mandatory Description Enable Caldera collector injector.caldera.enableINJECTOR_CALDERA_ENABLE Yes Enable the Caldera injector. Injector ID injector.caldera.id INJECTOR_CALDERA_ID Yes The ID of the injector. Collector IDs injector.caldera.collector-ids INJECTOR_CALDERA_COLLECTOR_IDS Yes The collector IDs compatible with the injection process. Caldera URL injector.caldera.url INJECTOR_CALDERA_URL Yes The URL of the Caldera instance. Caldera API Key injector.caldera.api-key INJECTOR_CALDERA_API-KEY Yes The API Key for the rest API of the Caldera instance."},{"location":"usage/injectors/","title":"Injectors","text":"Injectors serve as the backbone of the platform, enabling essential integration and functionalities for conducting simulations and exercises effectively. These components empower administrators to orchestrate a diverse range of activities and responses during simulation scenarios. Some of them are built-in in the platform, and others are external integrations.
Built-in injectors are seamlessly integrated into the platform, while external injectors require the deployment of additional systems alongside the platform to enable their functionality. Together, these injectors provide a comprehensive toolkit for administrators to design and execute simulations tailored to their specific objectives and requirements.
"},{"location":"usage/injectors/#injectors-list","title":"Injectors list","text":"A multitude of injectors are available, each offering distinct capabilities and functionalities to enhance the simulation experience. Here is an overview of the existing injectors:
For certain injectors, deploying an agent on the target machine is necessary to facilitate integration with OpenBAS. These agents are software programs that connect back to OpenBAS at certain intervals to get instructions.
To access the agents and installation instructions, navigate to the dedicated page located in the top right-hand corner (button with the screen logo).
Detailed guidance on installing the agents, along with downloadable packages, is provided on this page. Agents are available for various operating systems, including Windows, Linux, and MacOS, ensuring compatibility across different environments.
As of now, only the Caldera injector requires the installation of an agent. This agent enables full integration with the MITRE Caldera framework, unlocking advanced simulation capabilities and enhancing the overall effectiveness of simulation exercises. Full details of the Caldera agent are available in the MITRE documentation.
"},{"location":"usage/injects/","title":"Injects","text":"Injects are fundamental elements of simulations within OpenBAS, each representing a discrete action to be executed during a Scenario. Managed and facilitated by various injectors, each inject type serves a distinct purpose, contributing to the comprehensive evaluation of defenses.
"},{"location":"usage/injects/#create-an-inject","title":"Create an inject","text":"Whether intended for Atomic testing or for a Simulation, the process for creating injects remains consistent within OpenBAS.
"},{"location":"usage/injects/#for-atomic-testing","title":"For Atomic testing","text":"To create an inject for atomic testing, navigate to the \"Atomic testing\" section located in the left-hand banner. Click on the \"+\" icon in the bottom right corner to initiate the inject creation process.
"},{"location":"usage/injects/#for-scenarios-and-simulations","title":"For Scenarios and Simulations","text":"For injects intended for use within simulations, access the desired Scenario or Simulation and navigate to the \"Injects\" tab. Click on the \"+\" icon in the bottom right corner of the screen to open the inject creation panel.
Note that an inject defined in a Scenario will be used in all the scenario's subsequent simulations. An Inject defined at the simulation level will not be replicated into the Scenario itself, thus it will not be replicated in future scenario's simulations.
"},{"location":"usage/injects/#inject-creation-process","title":"Inject creation process","text":"Once the inject creation panel is open, you can proceed to configure the inject according to your requirements. Key steps in the creation process include:
"},{"location":"usage/injects/#1-choose-the-type-of-inject","title":"1. Choose the type of inject","text":"You first need to select an inject in the list of available ones (on the left of the creation screen). Logos on the left of each line indicates which Injector is associated with each inject. Depending on your integrations, this list can be long.
To facilitate the selection into this possibly very long list, you can search injects by name and filter the list by selecting a precise MITRE ATT&CK techniques for instance.
"},{"location":"usage/injects/#2-set-inject-parameters","title":"2. Set inject parameters","text":"When selecting an inject on the left, the form on the right populates itself with a by-default title and propose you to define:
By clicking on \"Inject content\", you can define now or later:
The \"available variables\" button helps you to use already defined variables into compatible fields.
By following these steps and providing the necessary information, you can create injects tailored to your specific testing or simulation objectives.
"},{"location":"usage/injects/#inject-types","title":"Inject types","text":"There are different types of injector in OpenBAS.
"},{"location":"usage/injects/#manual-action-reminders","title":"Manual action reminders","text":"Manual action reminders are injects designed to prompt animation team to perform specific actions manually. It allows to place in the timeline a stimulus to be produced manually, outside the platform (e.g. simulated a call from a journalist on the switchboard telephone). These reminders ensure that critical tasks are completed as part of the simulation, enhancing the accuracy and realism of the exercise.
The inject associated with this type is referred to as Manual.
Injects for direct contact allow sending emails or SMS messages to players. These injects assess the organization's response to communication-based threats, such as phishing attempts, social engineering attacks, or emergency notifications. They can also assess crisis management, including responses to internal information requests or management pressure.
Here's the list of injects linked to this category:
Send a SMS: enables sending SMS messages.Send individual mails: enables sending emails to individuals separately.Send multi-recipients mail: enables sending emails to a group of people (each recipient can see the other recipients).Injects simulating public communications involve the publication of articles, social media posts, or other fake announcements. These injects replicate scenarios where public disclosure of information or events affects an organization's reputation or operational continuity.
The inject associated with this type is referred to as Publish channel pressure.
Challenge injects are set to test participants' skills and response capabilities by publishing challenges. These injects present scenarios or tasks that require active participation and problem-solving, allowing administrators to evaluate players.
The inject associated with this type is referred to as Publish challenges.
HTTP request injects are used to forge HTTP requests to a third party services in order to perform actions outside the platform (e.g. API call to an EDR). These injects enable the platform to communicate with external services, gather information, or trigger specific actions via HTTP protocols.
HTTP requests GET, POST, and PUT, can be sent. The corresponding injects are named HTTP Request - \\<request type>.
Injects executed on remote systems are facilitated by Injectors like Caldera or Airbus CyberRange. These actions simulate real-world attack techniques, allowing administrators to gauge the effectiveness of their security posture in response to various technical actions attackers may take.
There are over 1,700 such injects covering all the TTPs in the MITRE ATT&CK matrix.
"},{"location":"usage/injects_and_expectations/","title":"Injects and Expectations","text":"Evaluating security posture in OpenBAS is to confront events (aka Injects) with Expectations.
"},{"location":"usage/injects_and_expectations/#injects","title":"Injects","text":"Threats are the results of actions by threat actors, and a combination of intent, capability and opportunity. In OpenBAS, simulating threats and their attack capabilities involves executing injects targeting players and assets.
Injects can be technical, emulating action attackers might take on an endpoint, and non-technical, representing interactions with players or impactful contextual events during a crisis (such as media inquiries by phone following a data breach).
"},{"location":"usage/injects_and_expectations/#expectations","title":"Expectations","text":"Each Inject is associated with Expectations. Expectations outline the anticipated outcomes from security systems and teams in response to attacker actions or contextual events.
Expectations can be about:
The collection and concatenation of expectations' results, broken down per type, allows to assess the security posture against a threat context. This provides insights to identify areas for improvement.
"},{"location":"usage/injects_builtin/","title":"Injects built-in","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"usage/media_pressure/","title":"Media pressure","text":"Under construction
We are doing our best to complete this page. If you want to participae, dont hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
Media pressure are Articles or web contents you create to give more shape to your Scenario, or to simulate contextual pressure on your Teams and Players.
For example, you can create an Article about the data leakage your organization is said to be affected by during the Scenario, and simulate its publishing by a large coverage media outlet with a \"Publish channel pressure\" inject.
"},{"location":"usage/media_pressure/#create-an-article","title":"Create an Article","text":"To create an Article, go to the definition page of your Scenario or your Simulation and click on the + button near \"media pressure\". If you did not create Article yet, you can also click on the more visible \"Create an Article\" button.
An media pressure Article is defined by: - Channel: the Channel template that will shape the article during the display to the Players. A Channel must have been defined in the platform. - Title - Author - Content: the content of your article. You can enrich the text and have a preview of the formatted result. You can also go fullscreen. - To simulate social network engagement, you can define number of comments, Shares and Likes of the Articles. - Documents: you can attach file to the Article. It can be useful if you want to simulate the publication of a large report you don't want to craft inside OpenBAS, like a pdf security report for example.
Once created, Articles appears as cards in the definition screen of the Scenario or Simulation they have been created into. Note that if an article is not yet used in the Scenario or Simulation (probably because it does not have been used in a \"Publish channel pressure\" inject), it is mentioned into the Article's card.
"},{"location":"usage/media_pressure/#use-an-article-in-scenario-and-simulation","title":"Use an Article in Scenario and Simulation","text":"To use an Article in a Scenario or Simulation, it must have been created in the context of the Scenario, the Simulation's parent Scenario or the Simulation itself.
When you select an Inject, if it is compatible with media pressures, you can add a media pressure article to it.
"},{"location":"usage/mitigations/","title":"Mitigations","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"usage/opencti_scenario/","title":"Scenario generation from OpenCTI","text":"Creating a scenario can be a complex task, especially when aiming to build one that is meaningful and relevant to the specific threats facing your organization. To streamline this process and ensure that scenarios are closely aligned with your threat landscape, you can leverage the integration between OpenCTI and OpenBAS.
When generating a scenario from OpenCTI, a scenario is created and can be accessed from the scenarios screen. The scenario name will include a reference to OpenCTI, indicating its origin. This scenario will automatically contain relevant sequences of injects based on the threat context identified in OpenCTI.
However, it's important to review and potentially customize the scenario to ensure it meets your organization's specific requirements. Additionally, you'll need to select appropriate targets for the injects within the scenario.
Once you've finalized the scenario, you can schedule your simulation as you would for any other scenario. The overall results of the simulation will also be available directly within OpenCTI, providing insights into the threat context upon which the scenario is based.
"},{"location":"usage/overview/","title":"Overview","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"usage/payloads/","title":"Payloads","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"usage/personas/","title":"Personas","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"usage/playing/","title":"Playing","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"usage/reports/","title":"Reports","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"usage/scenario/","title":"Scenario","text":"When clicking on Scenarios in the left menu, you access to the list of all Scenarios defined in the platform. Scenarios act as templates that translate threat contexts into meaningful events to simulate.
Scenarios can be grouped by defining categories, main focus, severity and tags. It is then possible to filter the Scenarios list based on these attributes. Quick filters are available by default at the top of the screen to filter Scenario on most used categories.
It is also possible to search Scenarios by their names using the search bar.
"},{"location":"usage/scenario/#create-a-scenario","title":"Create a scenario","text":"To create a scenario, hit the + button on the bottom right of the screen and define general metadata that make sense for you.
Once done, the scenario is accessible in the list. Click on it to see its details and define them.
"},{"location":"usage/scenario/#scenario-overview","title":"Scenario overview","text":"The overview provides comprehensive information for evaluating your security posture against the threat context over time. It displays the scenario's context along with the results of the simulations played from it. Additionally, the list of these simulations is shown, allowing easy access to their specific details and results.
If the scenario has never been simulated, the results' widget contains an example of how results will be displayed, and the list of simulations is replaced with an invitation to generate one.
"},{"location":"usage/scenario/#defining-a-scenario","title":"Defining a Scenario","text":"To define the scenario, navigate to the \"Definition\" and \"Injects\" tabs.
In the \"Definition\" tab, you can add various elements to construct events:
Once you have added all the elements you need, you can go to the \"Injects\" tab to begin to create the chain of events that will shape your scenario.
By clicking on the + button at the bottom right of the screen, you enter the inject creation workflow.
"},{"location":"usage/scenario/#launching-a-simulation-of-the-scenario","title":"Launching a simulation of the scenario","text":"Once you've finished defining your scenario, it's time to simulate it and evaluate your security posture!
To do so, click the \"Simulate now\" button. You can choose to simulate this scenario as a one-time evaluation, scheduling it for a specific date and time. Additionally, you can set it to simulate recurrently to assess your posture over time. The results of each simulation will populate your scenario overview.
A visual indication, located to the right of the scenario's title, provides a quick way to know if the scenario is currently being simulated.
"},{"location":"usage/scenario/#export-your-scenario","title":"Export your scenario","text":"You can export your carefully crafted scenario as a JSON file by clicking the three-dots button at the top right of the scenario screen. This allows you to share it with others, or store it outside the platform.
"},{"location":"usage/scenarios_and_simulations/","title":"Scenarios and Simulations","text":"In OpenBAS, the core concept to simulate attacks is based on the duo Scenario & Simulation.
"},{"location":"usage/scenarios_and_simulations/#scenarios","title":"Scenarios","text":"Scenario enable to translate a threat context, such as an attack or even a threat actor, into a meaningful sequence of events (referred to as injects), which can be technical or non-technical. This chronology of events can be enriched with associated documents or media articles to simulate the environment surrounding them.
Within Scenarios, you also specify who participates, whether actual people (referred to as Players) or endpoints (referred to as Assets). They will be the targets of the events representing the threat.
In order to translate real threats into Scenarios, it is possible to create them from OpenCTI data, such as Reports.
"},{"location":"usage/scenarios_and_simulations/#simulations","title":"Simulations","text":"If a Scenario translates threat context into meaningful events, a Simulation serves as a means to evaluate your security posture against this threat context.
By simulating a scenario with recurrence, you can evaluate your security posture over time in response to a threat context. Since simulations are always linked to their parent scenario, even if it evolves, you can: - assess your risk against evolving threats, - evaluate the effectiveness of your security governance in addressing your most relevant threats.
"},{"location":"usage/simulation/","title":"Simulation","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
When clicking on Simulations in the left menu, you access to the list of all Simulations ever launched in the platform. You can filter by tag (for example to only display simulation related to a specific threat actor) and sort them (chronologically, by status, etc.).
From this screen, you can easily see last global scores and access ongoing Simulations at platform level.
"},{"location":"usage/simulation/#creating-a-simulation","title":"Creating a Simulation","text":"The best practice to create a Simulation is to do it from a Scenario in order to evaluate your security posture over time against a specific threat context.
But you can create directly a Simulation if you want, by hitting the + button on the bottom right of the screen. You will have similar definition options as in Scenario creation.
"},{"location":"usage/simulation/#simulation-overview","title":"Simulation overview","text":"The Overview regroups everything you need to know to follow your Simulation by its Results. Results are broken down into 3 main metrics:
The top of the Simulation screen give you the ability to Start, stop and Reset the Simulation, delay the launch time.
"},{"location":"usage/simulation/#overriding-the-scenario-definition","title":"Overriding the Scenario definition","text":"In a Simulation, you can see and modify all elements defining it: Teams and Players, Variables, Media pressure, Challenges, Injects. Modifying the Simulation definition allows you to customize it to adapt a singular play to some temporary changes. For example, change an email address into Variables to be used in email-related injects, change a playing team, etc.
"},{"location":"usage/simulation/#animating-a-simulation","title":"Animating a Simulation","text":"The Animation screen of a Simulation is the place to follow the Simulation execution, especially if you are conducting simulation at strategical level (heavily relying on interactions with Teams and Players, manual validations of expectations) for training your organization on all aspects of a cyber crisis.
The Timeline screen is the overview of the Animation tab, to see ongoing injects.
The Mails screen is a way to manage email interaction with Players into the OpenBAS platform.
The Validation screen is the place to manually validate expectations of the Simulation to consolidate Results.
The Simulation logs is an interface for the animation team to collaborate during the Simulation.
"},{"location":"usage/simulation/#lessons-learned","title":"Lessons learned","text":"In the Lesson Learned tab of a Simulation, you can manage the collection and concatenation of customizable surveys. It helps you in conducting the most underestimated part of a Breach and Attack simulation involving real people, by automating it and complete your Simulation's Results with qualitative feedback.
"},{"location":"usage/skills/","title":"Skills","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"usage/systems/","title":"Systems","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"usage/targets/","title":"Targets","text":"When you are using an Inject, whether for Atomic testing, Scenario or Simulation, it's necessary to define the recipients, known as \"targets\", which could include Players, Teams, Assets (endpoints) or/and Asset groups it will be sent to. They are called \"targets\" of the inject.
Note that certain injects can't target assets, while others can't target players. For instance, the \"Send individual mails\" inject can only target players and teams, not assets.
Target selection is performed during inject creation or update.
"},{"location":"usage/targets/#selecting-players-and-teams","title":"Selecting Players and Teams","text":"Directly targeting a player isn't yet possible. Instead, you must target a team. In scenarios or simulations, the team must be included in the scenario or simulation to be selectable. However, when creating atomic testing, all teams in the platform are selectable.
Note that visibility of teams and players is limited by the organization's segregation.
When selecting a team as the target, all players within that team will be targeted by the inject. Each player will have to complete expectations.
"},{"location":"usage/targets/#selecting-assets-endpoints-and-asset-groups","title":"Selecting Assets (endpoints) and Asset groups","text":"You can target assets (endpoints) directly or asset groups. In the dedicated dialog, only assets compatible with the inject are listed by default.
When selecting an asset group to target, all assets (endpoints) within the group will be targeted by the inject. Each one will have to complete expectations.
"},{"location":"usage/teams_and_players_and_organizations/","title":"Players, Teams and Organizations","text":"Breach and Attack Simulation involves testing your security posture, and people are an essential part of it!
Players, teams, and organizations are where you organize the human aspect of your security posture within OpenBAS (in the \"People\" section). These entities are the targets for injects during your simulations and atomic testings.
"},{"location":"usage/teams_and_players_and_organizations/#players","title":"Players","text":"Players are the users that may take part into your scenarios, to be tested against attack or contextual events (i.e. injects).
Players can be created manually with the + button at the bottom right, but we encourage you to activate an integration allowing to import them from your IT environment, like with Microsoft Entra integration.
Players are defined by:
This list of players can be exported by clicking on the export button, at the top right of the players screen.
"},{"location":"usage/teams_and_players_and_organizations/#teams","title":"Teams","text":"Teams group players into units that can be targeted by injects during simulations or atomic testing. They serve as a way to represent different security teams (e.g., CSIRT, SOC, VOC) and other relevant teams that might be involved into your scenario (e.g., legal department, communication department).
Teams are defined by:
From the teams list, you can manage players by clicking on the three-dots inline button on the right and selecting \"Manage players.\" From there, you can view, update, or delete all the team's players and see their communication channels' state.
"},{"location":"usage/teams_and_players_and_organizations/#organizations","title":"Organizations","text":"Organization provides a straightforward method to segregate players and teams within the platform. A player associated with an organization, even with the required rights to animate and planned scenarios and simulations, will never see players and teams from other organizations.
This feature can be particularly useful if you are using OpenBAS to plan and execute simulations for various companies or subsidiaries.
"},{"location":"usage/testing/","title":"Testing","text":"Under construction
We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
"},{"location":"usage/variables/","title":"Variables","text":""},{"location":"usage/variables/#built-in-variables","title":"Built-In Variables","text":"Within certain injects, users can leverage a set of predefined built-in variables to dynamically customize content. These variables are designed to streamline the process of personalizing messages. Examples of built-in variables include but not limited to :
In addition to the built-in variables, users can define their own variables within an exercise.
To define custom variables :
In this section, users can create, update or delete custom variables.
"},{"location":"usage/variables/#limitation","title":"Limitation","text":"To create custom variables, consider the following limitation:
_ are authorized for the key valueThese variables can be used to enhance personalization of certain stimuli within an exercise. Here is a non-exhaustive list of concerned stimuli : - Email sending - Sms sending
"}]} \ No newline at end of file diff --git a/1.1.0/sitemap.xml b/1.1.0/sitemap.xml deleted file mode 100755 index 46295ad..0000000 --- a/1.1.0/sitemap.xml +++ /dev/null @@ -1,278 +0,0 @@ - -The Assets section provides users with a centralized hub for managing and organizing the entities targeted for testing and simulation.
-When you click on “Assets” in the left-hand banner, you see all the “Assets” pages. When accessing the Assets section, users are directed by default to the Endpoints page, where they can start managing their assets.
-From the Assets section, users can access the following pages:
Endpoints: Individual entities, representing any object or terminal that can be connected to a network.Asset groups: Group of asset allowing you to organize endpoints into logical groups based on various filters applied by the user.Endpoints encompass devices and systems that connect to a network, serving as the foundation for interaction with OpenBAS.
-The list of endpoints continues to grow with the changing landscape of networked technologies and the increasing interconnectivity of digital ecosystems. Below is a non-exhaustive list of terminal categories:
-When accessing the Endpoints pages, you see the list of all endpoints imported in your platform. Here, users can create and manage details specific to each endpoint.
-Assets can be imported with the help of specific Collectors, like Microsoft Entra.
-
Asset groups serve as a mechanism for organizing and grouping related Endpoints. These groups are constructed based on filters that define the criteria for inclusion, allowing administrators to segment and categorize Endpoints based on common characteristics or attributes.
-When creating a new asset group, administrators have the flexibility to specify the filters that will delineate the group's membership. Currently, the platform offers a range of filters such as platform type, hostname, and IP addresses. We plan to extend the possibilities by including additional filters in future updates.
-
Under construction
-We are doing our best to complete this page. -If you want to participae, dont hesitate to join the Filigran Community on Slack -or submit your pull request on the Github doc repository.
-When clicking on Atomic testing in the left menu, you access to the list of all atomic testings ever launched in the platform.
-Atomic testing is a great way to simulate a singular attack technique you are particulary interested in, and test immediately your capability to prevent and detect it.
-You can search for a specific one by name.
-The presented list allows you to easily see global scores of all your recent atomic testings.
-
An atomic testing is essentially the simulation of a single inject, against a selection of targets (Players, Teams, Assets, Assets Group) with assorted expectations.
-By clicking on the + button at the bottom right of the screen, you enter the atomic testing creation workflow.
-On the left of the creation screen is the list of all available Inject you can play for atomic testing. Logos on the left of each line indicates which Injector is associated with each inject.
-Depending on your integrations, this list can be long. You can filter the list by compatible platforms or by Mitre Att&ck tactics.By clicking on the "Att&CK" logo near the search bar, you can also filter by selecting a precise Mitre Att&ck techniques.
-When selecting an inject on the left, the form on the right populates itself with a by-default title and propose you to define when the inject should be played after the launch of the atomic testing. You can keep it to 0.
-By clicking on Inject content, you can define now or later the targeted assets or players, needed configurations, and the assorted expectations.
-The "available variables" button helps you to use already defined variables into compatible fields.
-Details of an Atomic testing is composed of three parts: -- a header allowing to launch the test, see its state and update/delete it. -- an Overview screen to eaily see the results of the test. -- an execution details screen to see expectations of the test and investigate on execution logs
-The first screen displayed when you click on a specific Atomic testing from the list is a breakdown of your security posture against this test.
-As for Simulation and Scenario, Results are broken down into: -- Prevention: the ability of your security posture to prevent the inject -- Detection: the ability of your security posture to detect the inject -- Human response: the ability of your security teams to react as intented facing the inject
-Big metrics on top of the screen sum up the expectations' result of all targets.
-The list of targets on the left allows you to easily see the result per Target, and for example investigate further why a specific Asset have failed the test.
-For a selected target, you can on the right the timeline of the test against the target and the assorted results. The result logs are also displayed.
-
On this screen, you can retrieve details about the atomic testing and its expectations.
-You can also see the raw execution logs of the Injector responsible for the test execution.
-
Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-In OpenBAS, Channels represent communication medias with a particular look. There are used to present web articles or other media contents to Players in a specific way.
-It helps give shape to your Scenario context and events.
-First step is to click on the + button at the bottom right and give your new Channel a type (Newspaper, Microblogging, TV Channel), a name and a subtitle.
-Once done, click on the Channel in the list to access its overview. Here you can define how media content associated to this Chennel will be displayed to Players.
-You can define primary and secondary colors, choose logos and define how the header is presented.
-On the right, a mock up of the overview is displayed to give you the look and fill of it.
-
A Channel will then be used in Scenario and in Simulation definition. When you create an Article, you have to choose the Channel that will give it an adequate shape.
-See Media pressure page to know how to create and add Articles to your Scenarios.
-
The integration between an OpenBAS instance and a Caldera instance allows you to enrich assets data.
-Below are the properties you'll need to set for OpenBAS:
-| Property | -application.properties | -Docker environment variable | -Mandatory | -Description | -
|---|---|---|---|---|
| Enable Caldera collector | -collector.caldera.enable | -COLLECTOR.CALDERA.ENABLE |
-Yes | -Enable the Caldera collector. | -
| Collector ID | -collector.caldera.id | -COLLECTOR.CALDERA.ID |
-Yes | -The ID of the collector. | -
| Caldera URL | -collector.caldera.url | -COLLECTOR.CALDERA.URL |
-Yes | -The URL of the Caldera instance. | -
| Caldera API Key | -collector.caldera.api-key | -COLLECTOR.CALDERA.API-KEY |
-Yes | -The API Key for the rest API of the Caldera instance. | -
| Caldera polling interval | -collector.caldera.interval | -COLLECTOR.CALDERA.INTERVAL |
-No | -The time interval in seconds where the collect is triggered. Default is 60 seconds. | -
Each interval, a job retrieves the deployed agents on Caldera and populates the OpenBAS database by creating Assets.
-Deduplication is done thanks to the caldera paw property :
paw, a new asset is createdpaw and the source of creation is only Caldera, this asset is updatedThere is no automatic deletion of OpenBAS assets if Caldera agents no longer exist.
-| Agent Property | -Asset Property | -
|---|---|
| paw | -externalId | -
| paw | -name | -
| host_ip_addrs | -ips | -
| platform | -platform | -
| last_seen | -lastSeen | -
Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Expectations define what is expected from an Asset (endpoint) or a Players when facing an Inject in terms of security posture. Each expectation has a score representing how well it has been met by the target.
-Expectations can be categorized as either Manual or Automatic, depending on how they are validated.
-Manual expectations require manual validation by the animation team, with the validation process and scoring managed manually. They are simple, customizable expectations to be manually validated.
-Automatic expectations are validated automatically under specific conditions. Currently available automatic expectations include:
-Automatic - Prevention: Triggered when inject is processed: automatically validated by security integration with compatible Collectors if the inject's action generates a prevention alert, such as quarantine.Automatic - Detection: Triggered when inject is processed: automatically validated by security integration with compatible Collectors if the inject's action generates a detection alert, such as an incident.Automatic - Triggered when team reads articles: Automatically validated when the article of a Media pressure inject has been read by targets.For injects targeting asset groups, some expectations can be validated in two modes:
-Special case: Publish Challenges inject
-The "Publish Challenges" inject doesn't require an expectation, as results are computed directly from Challenges' scores.
-To add expectations to an inject, navigate to the inject's content and click on "Add expectations". From there, select the type of expectation you want to add and set a score for it.
-You can add multiple expectations to a single inject.
- - -If you have configured manual expectations in your scenario, you will have the opportunity to handle manual validations during each simulation. During a Simulation, navigate to the Animation tab, under the Validation screen. Here, you'll find a list of expectations that require manual validation.
- - - - - - - - - - - - - - - - - - - - - - - - - -Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-This guide aims to give you a full overview of the OpenBAS features and workflows. The platform can be used in various contexts to handle Breach and Attack simulations at technical or strategical levels. OpenBAS has been designed as a part of the Filigran XTM suite and can be integrated with OpenCTI to generate meaningful attack scenario based on real threat. OpenBAS is result-oriented with many dashboard helping you to evaluate you securoty posture given a defined context.
-Here are some examples of use cases: -- Designing attack scenario based on real threat -- Evaluate your security posture against technical simulations on endpoints -- Enhance team skills by evaluating them during simulations along with your security systems -- Organize Capture The Flag with multiple challenges -- Conduct atomic testing
-The Home screen gives any visitor on the OpenBAS platform an outlook on the live of the platform as well as an overview of your global security posture.
-First, you need to import Players and Assets that will participate to the simulation and be targeted by technical or strategical events. To do so, you need to ...
-If you want to simulate attack at a technical level, you will need to install a Simulation Agent that will play technical events on your imported assets. To do so, you can go to the dedicated panel from the top right button and follow installation instructions. By default, Caldera is part of the OpenBAS stack.
-
The Caldera agent will allow you to play various technical events, based on the Mitre ATT&CK matrix.
-Once integrations is done, you are ready to create your first Scenario!
-Scenarios act as template for your Breach and Attack simulations. After establihing such a template, you will be able to schedule it as a one shot simulation, or as a recurring one.
-Optionnaly, you can buff up your scenario by adding Documents, Media pressures, or even CTF Challenges to your injects.
-You can now schedule your Simulation by hitting the blue "Simulate now" button. Choose your moment and hit start.
-On time, a Simulation based on your Scenario template is generated. it is listed in your Scenario overview and in the Simulations menu. Fron there, you can follow the course of the Simulation and interact with it, for example to validate manual expectations.
-During the course of the simulation, results are updated and can be consulted in the Simulation overview.
-Results in OpenBAS are based on expectations' results that are linked to injects played during Simulations. It is then important to manually validate expectations that need it.
-Results are broken down by "Prevention", "Detection" and "Human response" metrics. -- Prevention displays your ability to prevent the scenario's technical events to be completed -- Detection displays your ability to detect the scenario's technical events -- HUman response displays how well players and teams react as expected facing the scenario's events.
- - - - - - - - - - - - - - - - - - - - - - - - -The Caldera framework, developed by MITRE, is a powerful framework designed to simulate cyberattacks. It enables security teams to conduct realistic and controlled simulations of adversary behavior, reducing the amount of time and resources needed for routine cybersecurity testing.
-In OpenBAS, the Caldera framework has been fully integrated, offering users access to a comprehensive library of injects for conducting simulation exercises. With this integration, users can leverage the extensive capabilities of Caldera within OpenBAS.
-Caldera offers 1600+ abilities, covering the full range of ATT&CK tactics and techniques. These capabilities equip security teams with an extensive toolkit to simulate various threats and assess defense mechanisms effectively.
- - -Injects within the Caldera framework can be played on both individual Endpoints and Asset groups. Prior to playing injects, Caldera agents need to be installed on the target machines to enable interaction with the platform.
-Once the agents are deployed, simulations with Caldera injects can be executed. The platform will contact the agent to start the ability. Subsequently, the agents will report the results to OpenBAS. Below is the workflow illustrating the behavior of injects.
-
Below are the properties you'll need to set for OpenBAS:
-| Property | -application.properties | -Docker environment variable | -Mandatory | -Description | -
|---|---|---|---|---|
| Enable Caldera collector | -injector.caldera.enable | -INJECTOR_CALDERA_ENABLE |
-Yes | -Enable the Caldera injector. | -
| Injector ID | -injector.caldera.id | -INJECTOR_CALDERA_ID |
-Yes | -The ID of the injector. | -
| Collector IDs | -injector.caldera.collector-ids | -INJECTOR_CALDERA_COLLECTOR_IDS |
-Yes | -The collector IDs compatible with the injection process. | -
| Caldera URL | -injector.caldera.url | -INJECTOR_CALDERA_URL |
-Yes | -The URL of the Caldera instance. | -
| Caldera API Key | -injector.caldera.api-key | -INJECTOR_CALDERA_API-KEY |
-Yes | -The API Key for the rest API of the Caldera instance. | -
Injectors serve as the backbone of the platform, enabling essential integration and functionalities for conducting simulations and exercises effectively. These components empower administrators to orchestrate a diverse range of activities and responses during simulation scenarios. Some of them are built-in in the platform, and others are external integrations.
-Built-in injectors are seamlessly integrated into the platform, while external injectors require the deployment of additional systems alongside the platform to enable their functionality. Together, these injectors provide a comprehensive toolkit for administrators to design and execute simulations tailored to their specific objectives and requirements.
-A multitude of injectors are available, each offering distinct capabilities and functionalities to enhance the simulation experience. Here is an overview of the existing injectors:
-
For certain injectors, deploying an agent on the target machine is necessary to facilitate integration with OpenBAS. These agents are software programs that connect back to OpenBAS at certain intervals to get instructions.
-To access the agents and installation instructions, navigate to the dedicated page located in the top right-hand corner (button with the screen logo).
-Detailed guidance on installing the agents, along with downloadable packages, is provided on this page. Agents are available for various operating systems, including Windows, Linux, and MacOS, ensuring compatibility across different environments.
-As of now, only the Caldera injector requires the installation of an agent. This agent enables full integration with the MITRE Caldera framework, unlocking advanced simulation capabilities and enhancing the overall effectiveness of simulation exercises. Full details of the Caldera agent are available in the MITRE documentation.
-
Injects are fundamental elements of simulations within OpenBAS, each representing a discrete action to be executed during a Scenario. Managed and facilitated by various injectors, each inject type serves a distinct purpose, contributing to the comprehensive evaluation of defenses.
-
Whether intended for Atomic testing or for a Simulation, the process for creating injects remains consistent within OpenBAS.
-
To create an inject for atomic testing, navigate to the "Atomic testing" section located in the left-hand banner. Click on the "+" icon in the bottom right corner to initiate the inject creation process.
-For injects intended for use within simulations, access the desired Scenario or Simulation and navigate to the "Injects" tab. Click on the "+" icon in the bottom right corner of the screen to open the inject creation panel.
-Note that an inject defined in a Scenario will be used in all the scenario's subsequent simulations. An Inject defined at the simulation level will not be replicated into the Scenario itself, thus it will not be replicated in future scenario's simulations.
- -Once the inject creation panel is open, you can proceed to configure the inject according to your requirements. Key steps in the creation process include:
-You first need to select an inject in the list of available ones (on the left of the creation screen). Logos on the left of each line indicates which Injector is associated with each inject. Depending on your integrations, this list can be long.
-To facilitate the selection into this possibly very long list, you can search injects by name and filter the list by selecting a precise MITRE ATT&CK techniques for instance.
-When selecting an inject on the left, the form on the right populates itself with a by-default title and propose you to define:
-By clicking on "Inject content", you can define now or later:
-The "available variables" button helps you to use already defined variables into compatible fields.
-
By following these steps and providing the necessary information, you can create injects tailored to your specific testing or simulation objectives.
-There are different types of injector in OpenBAS.
- -Manual action reminders are injects designed to prompt animation team to perform specific actions manually. It allows to place in the timeline a stimulus to be produced manually, outside the platform (e.g. simulated a call from a journalist on the switchboard telephone). These reminders ensure that critical tasks are completed as part of the simulation, enhancing the accuracy and realism of the exercise.
-The inject associated with this type is referred to as Manual.
Injects for direct contact allow sending emails or SMS messages to players. These injects assess the organization's response to communication-based threats, such as phishing attempts, social engineering attacks, or emergency notifications. They can also assess crisis management, including responses to internal information requests or management pressure.
-Here's the list of injects linked to this category:
-Send a SMS: enables sending SMS messages.Send individual mails: enables sending emails to individuals separately.Send multi-recipients mail: enables sending emails to a group of people (each recipient can see the other recipients).Injects simulating public communications involve the publication of articles, social media posts, or other fake announcements. These injects replicate scenarios where public disclosure of information or events affects an organization's reputation or operational continuity.
-The inject associated with this type is referred to as Publish channel pressure.
Challenge injects are set to test participants' skills and response capabilities by publishing challenges. These injects present scenarios or tasks that require active participation and problem-solving, allowing administrators to evaluate players.
-The inject associated with this type is referred to as Publish challenges.
HTTP request injects are used to forge HTTP requests to a third party services in order to perform actions outside the platform (e.g. API call to an EDR). These injects enable the platform to communicate with external services, gather information, or trigger specific actions via HTTP protocols.
-HTTP requests GET, POST, and PUT, can be sent. The corresponding injects are named HTTP Request - \<request type>.
Injects executed on remote systems are facilitated by Injectors like Caldera or Airbus CyberRange. These actions simulate real-world attack techniques, allowing administrators to gauge the effectiveness of their security posture in response to various technical actions attackers may take.
-There are over 1,700 such injects covering all the TTPs in the MITRE ATT&CK matrix.
- - - - - - - - - - - - - - - - - - - - - - - - -Evaluating security posture in OpenBAS is to confront events (aka Injects) with Expectations.
-Threats are the results of actions by threat actors, and a combination of intent, capability and opportunity. In OpenBAS, simulating threats and their attack capabilities involves executing injects targeting players and assets.
-Injects can be technical, emulating action attackers might take on an endpoint, and non-technical, representing interactions with players or impactful contextual events during a crisis (such as media inquiries by phone following a data breach).
-
Each Inject is associated with Expectations. Expectations outline the anticipated outcomes from security systems and teams in response to attacker actions or contextual events.
-Expectations can be about:
-The collection and concatenation of expectations' results, broken down per type, allows to assess the security posture against a threat context. This provides insights to identify areas for improvement.
- - - - - - - - - - - - - - - - - - - - - - - - -Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. -If you want to participae, dont hesitate to join the Filigran Community on Slack -or submit your pull request on the Github doc repository.
-Media pressure are Articles or web contents you create to give more shape to your Scenario, or to simulate contextual pressure on your Teams and Players.
-For example, you can create an Article about the data leakage your organization is said to be affected by during the Scenario, and simulate its publishing by a large coverage media outlet with a "Publish channel pressure" inject.
-To create an Article, go to the definition page of your Scenario or your Simulation and click on the + button near "media pressure". If you did not create Article yet, you can also click on the more visible "Create an Article" button.
-An media pressure Article is defined by: -- Channel: the Channel template that will shape the article during the display to the Players. A Channel must have been defined in the platform. -- Title -- Author -- Content: the content of your article. You can enrich the text and have a preview of the formatted result. You can also go fullscreen. -- To simulate social network engagement, you can define number of comments, Shares and Likes of the Articles. -- Documents: you can attach file to the Article. It can be useful if you want to simulate the publication of a large report you don't want to craft inside OpenBAS, like a pdf security report for example.
-Once created, Articles appears as cards in the definition screen of the Scenario or Simulation they have been created into. Note that if an article is not yet used in the Scenario or Simulation (probably because it does not have been used in a "Publish channel pressure" inject), it is mentioned into the Article's card.
- - -To use an Article in a Scenario or Simulation, it must have been created in the context of the Scenario, the Simulation's parent Scenario or the Simulation itself.
-When you select an Inject, if it is compatible with media pressures, you can add a media pressure article to it.
- - - - - - - - - - - - - - - - - - - - - - - - - -Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Creating a scenario can be a complex task, especially when aiming to build one that is meaningful and relevant to the specific threats facing your organization. To streamline this process and ensure that scenarios are closely aligned with your threat landscape, you can leverage the integration between OpenCTI and OpenBAS.
- - -When generating a scenario from OpenCTI, a scenario is created and can be accessed from the scenarios screen. The scenario name will include a reference to OpenCTI, indicating its origin. This scenario will automatically contain relevant sequences of injects based on the threat context identified in OpenCTI.
-However, it's important to review and potentially customize the scenario to ensure it meets your organization's specific requirements. Additionally, you'll need to select appropriate targets for the injects within the scenario.
-Once you've finalized the scenario, you can schedule your simulation as you would for any other scenario. The overall results of the simulation will also be available directly within OpenCTI, providing insights into the threat context upon which the scenario is based.
- - - - - - - - - - - - - - - - - - - - - - - - - -Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-When clicking on Scenarios in the left menu, you access to the list of all Scenarios defined in the platform. Scenarios act as templates that translate threat contexts into meaningful events to simulate.
-Scenarios can be grouped by defining categories, main focus, severity and tags. It is then possible to filter the Scenarios list based on these attributes. Quick filters are available by default at the top of the screen to filter Scenario on most used categories.
-It is also possible to search Scenarios by their names using the search bar.
- - -To create a scenario, hit the + button on the bottom right of the screen and define general metadata that make sense for you.
-Once done, the scenario is accessible in the list. Click on it to see its details and define them.
-The overview provides comprehensive information for evaluating your security posture against the threat context over time. It displays the scenario's context along with the results of the simulations played from it. Additionally, the list of these simulations is shown, allowing easy access to their specific details and results.
-If the scenario has never been simulated, the results' widget contains an example of how results will be displayed, and the list of simulations is replaced with an invitation to generate one.
- - -To define the scenario, navigate to the "Definition" and "Injects" tabs.
-In the "Definition" tab, you can add various elements to construct events:
-Once you have added all the elements you need, you can go to the "Injects" tab to begin to create the chain of events that will shape your scenario.
-By clicking on the + button at the bottom right of the screen, you enter the inject creation workflow.
-Once you've finished defining your scenario, it's time to simulate it and evaluate your security posture!
-To do so, click the "Simulate now" button. You can choose to simulate this scenario as a one-time evaluation, scheduling it for a specific date and time. Additionally, you can set it to simulate recurrently to assess your posture over time. The results of each simulation will populate your scenario overview.
-A visual indication, located to the right of the scenario's title, provides a quick way to know if the scenario is currently being simulated.
-You can export your carefully crafted scenario as a JSON file by clicking the three-dots button at the top right of the scenario screen. This allows you to share it with others, or store it outside the platform.
- - - - - - - - - - - - - - - - - - - - - - - - -In OpenBAS, the core concept to simulate attacks is based on the duo Scenario & Simulation.
-Scenario enable to translate a threat context, such as an attack or even a threat actor, into a meaningful sequence of events (referred to as injects), which can be technical or non-technical. This chronology of events can be enriched with associated documents or media articles to simulate the environment surrounding them.
-Within Scenarios, you also specify who participates, whether actual people (referred to as Players) or endpoints (referred to as Assets). They will be the targets of the events representing the threat.
-In order to translate real threats into Scenarios, it is possible to create them from OpenCTI data, such as Reports.
-If a Scenario translates threat context into meaningful events, a Simulation serves as a means to evaluate your security posture against this threat context.
-By simulating a scenario with recurrence, you can evaluate your security posture over time in response to a threat context. Since simulations are always linked to their parent scenario, even if it evolves, you can: -- assess your risk against evolving threats, -- evaluate the effectiveness of your security governance in addressing your most relevant threats.
- - - - - - - - - - - - - - - - - - - - - - - - - -Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-When clicking on Simulations in the left menu, you access to the list of all Simulations ever launched in the platform. You can filter by tag (for example to only display simulation related to a specific threat actor) and sort them (chronologically, by status, etc.).
-From this screen, you can easily see last global scores and access ongoing Simulations at platform level.
-The best practice to create a Simulation is to do it from a Scenario in order to evaluate your security posture over time against a specific threat context.
-But you can create directly a Simulation if you want, by hitting the + button on the bottom right of the screen. You will have similar definition options as in Scenario creation.
- - -The Overview regroups everything you need to know to follow your Simulation by its Results. Results are broken down into 3 main metrics:
-The top of the Simulation screen give you the ability to Start, stop and Reset the Simulation, delay the launch time.
- - - - -In a Simulation, you can see and modify all elements defining it: Teams and Players, Variables, Media pressure, Challenges, Injects. Modifying the Simulation definition allows you to customize it to adapt a singular play to some temporary changes. For example, change an email address into Variables to be used in email-related injects, change a playing team, etc.
- - -The Animation screen of a Simulation is the place to follow the Simulation execution, especially if you are conducting simulation at strategical level (heavily relying on interactions with Teams and Players, manual validations of expectations) for training your organization on all aspects of a cyber crisis.
-The Timeline screen is the overview of the Animation tab, to see ongoing injects.
-The Mails screen is a way to manage email interaction with Players into the OpenBAS platform.
-The Validation screen is the place to manually validate expectations of the Simulation to consolidate Results.
-The Simulation logs is an interface for the animation team to collaborate during the Simulation.
- - -In the Lesson Learned tab of a Simulation, you can manage the collection and concatenation of customizable surveys. It helps you in conducting the most underestimated part of a Breach and Attack simulation involving real people, by automating it and complete your Simulation's Results with qualitative feedback.
- - - - - - - - - - - - - - - - - - - - - - - - - -Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-When you are using an Inject, whether for Atomic testing, Scenario or Simulation, it's necessary to define the recipients, known as "targets", which could include Players, Teams, Assets (endpoints) or/and Asset groups it will be sent to. They are called "targets" of the inject.
-Note that certain injects can't target assets, while others can't target players. For instance, the "Send individual mails" inject can only target players and teams, not assets.
-Target selection is performed during inject creation or update.
- - -Directly targeting a player isn't yet possible. Instead, you must target a team. In scenarios or simulations, the team must be included in the scenario or simulation to be selectable. However, when creating atomic testing, all teams in the platform are selectable.
-Note that visibility of teams and players is limited by the organization's segregation.
-When selecting a team as the target, all players within that team will be targeted by the inject. Each player will have to complete expectations.
- - -You can target assets (endpoints) directly or asset groups. In the dedicated dialog, only assets compatible with the inject are listed by default.
-When selecting an asset group to target, all assets (endpoints) within the group will be targeted by the inject. Each one will have to complete expectations.
- - - - - - - - - - - - - - - - - - - - - - - - - -Breach and Attack Simulation involves testing your security posture, and people are an essential part of it!
-Players, teams, and organizations are where you organize the human aspect of your security posture within OpenBAS (in the "People" section). These entities are the targets for injects during your simulations and atomic testings.
- -Players are the users that may take part into your scenarios, to be tested against attack or contextual events (i.e. injects).
-Players can be created manually with the + button at the bottom right, but we encourage you to activate an integration allowing to import them from your IT environment, like with Microsoft Entra integration.
-Players are defined by:
-This list of players can be exported by clicking on the export button, at the top right of the players screen.
- - -Teams group players into units that can be targeted by injects during simulations or atomic testing. They serve as a way to represent different security teams (e.g., CSIRT, SOC, VOC) and other relevant teams that might be involved into your scenario (e.g., legal department, communication department).
-Teams are defined by:
-From the teams list, you can manage players by clicking on the three-dots inline button on the right and selecting "Manage players." From there, you can view, update, or delete all the team's players and see their communication channels' state.
- - - -Organization provides a straightforward method to segregate players and teams within the platform. A player associated with an organization, even with the required rights to animate and planned scenarios and simulations, will never see players and teams from other organizations.
-This feature can be particularly useful if you are using OpenBAS to plan and execute simulations for various companies or subsidiaries.
- - - - - - - - - - - - - - - - - - - - - - - - -Under construction
-We are doing our best to complete this page. If you want to participate, don't hesitate to join the Filigran Community on Slack or submit your pull request on the Github doc repository.
-Within certain injects, users can leverage a set of predefined built-in variables to dynamically customize content. -These variables are designed to streamline the process of personalizing messages. -Examples of built-in variables include but not limited to :
-In addition to the built-in variables, users can define their own variables within an exercise.
-To define custom variables :
-In this section, users can create, update or delete custom variables.
-
To create custom variables, consider the following limitation:
-_ are authorized for the key valueThese variables can be used to enhance personalization of certain stimuli within an exercise. -Here is a non-exhaustive list of concerned stimuli : -- Email sending -- Sms sending
-