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":"#blog-posts","title":"Blog posts","text":"Resources and content
Discover tutorials, best practices and deep dives on OpenBAS features on our Filigran blog.
Read now
Below, you will find external resources which may be useful along your OpenCTI journey.
OpenBAS Ecosystem List of available injectors and collectors to expand platform usage.
Training Courses Training courses for analysts and administrators in the Filigran training center.
Video materials Set of video illustrating the implementation of use cases and platform capabilities.
"},{"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\nYou can manage users in Settings > Security > Users. If you are using Single Sign-On (SSO), user accounts in OpenBAS are automatically created upon login.
To create a user, just click on the + button :
To update a user, click on the ellipsis menu (\u22ee) :
Here, you can modify parameters such as the organization, phone number, password, and even your GPG public key :
To delete a user :
"},{"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":"Tips
If you want to learn more about the concept and features of collectors, you can have more info here.
"},{"location":"deployment/collectors/#installation","title":"Installation","text":""},{"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 openbas.unsecured-certificate OPENBAS_UNSECURED-CERTIFICATE false Turn on to authorize self-signed or unsecure ssl certificate openbas.with-proxy OPENBAS_WITH-PROXY false Turn on to authorize environment with proxy"},{"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\") openbas.rabbitmq.management-insecure OPENBAS_RABBITMQ_MANAGEMENT-INSECURE true Whether or not the calls to the management plugin of rabbitmq can be insecure openbas.rabbitmq.trust.store OPENBAS_RABBITMQ_TRUST_STORE <file:/path/to/client-store.p12> Path to the p12 keystore file to use if ssl is activated and insecure management is deactivated. The keystore must contain the client side certificate and key generated for ssl. openbas.rabbitmq.trust-store-password OPENBAS_RABBITMQ_TRUST-STORE-PASSWORD <trust-store-password> Password of the keystore"},{"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. openbas.s3.use-aws-role OPENBAS_S3_USE-AWS-ROLE false Whether or not we want to get the AWS role using AWS Security Token Service openbas.s3.sts-endpoint OPENBAS_S3_STS-ENDPOINT experimental This parameter is optional. If it stays empty, it will use either the AWS legacy STS endpoint (https://sts.amazonaws.com) or the regional one using AWS_REGION if the environment variable is set (you can learn more about it here). Otherwise, if you want to use your own custom implementation of STS endpoints, you can set it here."},{"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 neutral executor that will be in charge of executing implants as detached processes. Implants will then 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)To know more about other available executors, please refer to the executors documentation
"},{"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 Note : Example with Gmail
Parameter Environment variable Value Description spring.mail.host SPRING_MAIL_HOST smtp.gmail.com Gmail SMTP server hostname spring.mail.port SPRING_MAIL_PORT 587 Gmail SMTP server port (TLS) spring.mail.username SPRING_MAIL_USERNAME username@mail.com Gmail address spring.mail.password SPRING_MAIL_PASSWORD app password Gmail App-specific password spring.mail.properties.mail.smtp.auth SPRING_MAIL_PROPERTIES_MAIL_SMTP_AUTH true Enable SMTP authentication spring.mail.properties.mail.smtp.starttls.enable SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE true Enable SMTP STARTTLS\u26a0\ufe0f Important: If you are using two-factor authentication on your Gmail account, an app-specific password is required. You can find a guide here.
"},{"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 STARTTLSNote : Example with Gmail
Parameter Environment variable Value Description openbas.mail.imap.enabled OPENBAS_MAIL_IMAP_ENABLED true Enable IMAP for Gmail openbas.mail.imap.host OPENBAS_MAIL_IMAP_HOST imap.gmail.com Gmail IMAP server hostname openbas.mail.imap.port OPENBAS_MAIL_IMAP_PORT 993 Gmail IMAP port (SSL) openbas.mail.imap.username OPENBAS_MAIL_IMAP_USERNAME username@mail.com Gmail address openbas.mail.imap.password OPENBAS_MAIL_IMAP_PASSWORD app password Gmail App-specific password openbas.mail.imap.ssl.enable OPENBAS_MAIL_IMAP_SSL_ENABLE true Enable IMAP SSL openbas.mail.imap.ssl.trust OPENBAS_MAIL_IMAP_SSL_TRUST * Trust unverified certificates openbas.mail.imap.auth OPENBAS_MAIL_IMAP_AUTH true Enable IMAP authentication openbas.mail.imap.sent OPENBAS_MAIL_IMAP_SENT [Gmail]/Sent Mail IMAP sent directory to synchronize from\u26a0\ufe0f Important: If you are using two-factor authentication on your Gmail account, an app-specific password is required. You can find a guide here.
"},{"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/executors/","title":"Executors","text":""},{"location":"deployment/executors/#introduction","title":"Introduction","text":"To be able to use the power of the OpenBAS platform on endpoints, you need at least one neutral executor that will be in charge of executing implants as detached processes. Implants will then execute payloads.
"},{"location":"deployment/executors/#openbas-agent","title":"OpenBAS Agent","text":"More informations here
"},{"location":"deployment/executors/#tanium-agent","title":"Tanium Agent","text":"The Tanium agent can be leveraged to execute implants as detached processes that will the execute payloads according to the OpenBAS architecture.
"},{"location":"deployment/executors/#configure-the-tanium-platform","title":"Configure the Tanium Platform","text":"First of all, we are providing 2 Tanium packages to be imported in the Tanium platform.
Tanium package configuration
Because OpenBAS should run implants as detached processed, you must uncheck the box \"Launch this package command in a process group\" in the package configuration:
Once configured and imported, retrieve the package IDs from the URL ui/console/packages/XXXXX/preview.
To use the Tanium executor, just fill the following configuration.
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 Tanium API Key
Please note that the Tanium API key should have the permissions to retrieve endpoint list from the Tanium GraphQL API as well as to launch packages on endpoints.
"},{"location":"deployment/executors/#checks","title":"Checks","text":"Once enabled, you should see Tanium available in your Install agents section
Also, the assets in the selected computer groups should now be available in the endpoints section in OpenBAS:
NB : An Asset can only have one Tanium agent installed thanks to an unicity with hostname and IP parameters. If you try to install again a Tanium agent on a platform, it will overwrite the actual one and you will always see one endpoint on the OpenBAS endpoint page.
Installation done
You are now ready to leverage your Tanium platform to run OpenBAS payloads!
"},{"location":"deployment/executors/#caldera-agent","title":"Caldera Agent","text":"The Caldera agent can be leveraged to execute implants as detached processes that will the execute payloads according to the OpenBAS architecture.
Caldera already installed
If you already have a working Caldera installation, just go directly to OpenBAS configuration section.
"},{"location":"deployment/executors/#deploy-caldera","title":"Deploy Caldera","text":"To deploy Caldera, you can just add Caldera to the OpenBAS stack, we advise you to modify your docker-compose.yml and add a Caldera service:
services:\n caldera:\n image: openbas/caldera-server:5.0.0\n restart: always\n ports:\n - \"8888:8888\"\n environment:\n CALDERA_URL: http://localhost:8888\n volumes:\n - type: bind\n source: caldera.yml\n target: /usr/src/app/conf/local.yml\nAs you can see in the configuration, you will also need a configuration file caldera.yml because Caldera does not support well environment variables for configuration.
Download caldera.yml and put it alongside your docker-compose.yml file. This file must be modified prior launching, only change what is marked as Change this, listed below.
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\nJust update your stack and check Caldera is running:
docker compose up -d\nThen, just change the OpenBAS configuration as follow:
Parameter Environment variable Default value Description executor.caldera.enable EXECUTOR_CALDERA_ENABLEfalse 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 (ex: http://caldera.myopenbas.myorganization.com:8888) executor.caldera.api-key EXECUTOR_CALDERA_API-KEY Caldera API key"},{"location":"deployment/executors/#agents","title":"Agents","text":""},{"location":"deployment/executors/#deploy-agents","title":"Deploy agents","text":"Once enabled, you should see Caldera available in your Install agents section:
OpenBAS has built-in instruction if you want command line examples to deploy the agent on one endpoint.
Caldera AV detection
By default, the Caldera agent \"Sandcat\" is detected and blocked by antivirus. Here, we are using Caldera as a neutral executor that will execute implants that will execute payloads, so you need to add the proper AV exclusions as instructed in the OpenBAS screen.
"},{"location":"deployment/executors/#checks_1","title":"Checks","text":"All assets with a proper Caldera agent installed using the OpenBAS provided command line (then persistent) should now be available in the OpenBAS endpoints list.
NB : An Asset can only have one Caldera agent installed thanks to an unicity with hostname and IP parameters. If you try to install again a Caldera agent on a platform, it will overwrite the actual one and you will always see one endpoint on the OpenBAS endpoint page.
"},{"location":"deployment/injectors/","title":"Injectors","text":"Tips
If you want to learn more about the concept and features of injectors, you can have more info here.
"},{"location":"deployment/injectors/#installation","title":"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 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.
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\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_ENABLED=true\nOPENBAS_MAIL_IMAP_HOST=imap.changeme.com\nOPENBAS_MAIL_IMAP_PORT=993\nOPENBAS_ADMIN_EMAIL=ChangeMe@domain.com # Should be a valid email address\nOPENBAS_ADMIN_PASSWORD=ChangeMe\nOPENBAS_ADMIN_TOKEN=ChangeMe # Should be a valid UUI\nCOLLECTOR_MITRE_ATTACK_ID=3050d2a3-291d-44eb-8038-b4e7dd107436 # No need for change\nCOLLECTOR_ATOMIC_RED_TEAM_ID=0f2a85c1-0a3b-4405-a79c-c65398ee4a76 # No need for change\nIf 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/#openbas-x-caldera-optional-part","title":"OpenBAS X Caldera (Optional part)","text":"You can deploy Caldera alongside OpenBAS to manage agent deployment and execute Caldera scripts.
Use Docker
Deploy OpenBAS using Docker and the default docker-compose.yml provided in the docker.
Setup
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 .env.sample file for .env and enter the required values, or directly update the docker-compose.yml file with the values specific 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@domain.com\nOPENBAS_ADMIN_PASSWORD=ChangeMe\nOPENBAS_ADMIN_TOKEN=ChangeMe # Should be a valid UUID\nCALDERA_URL=http://caldera:8888 # Change me for production deployment to something accessible from your OpenBAS\nCALDERA_PUBLIC_URL=http://localhost:8888 # Change me for production deployment to something accessible from your endpoint(s)\nCALDERA_API-KEY=ChangeMe # Should be the same as api_key in your caldera.yml file\nCOLLECTOR_MITRE_ATTACK_ID=3050d2a3-291d-44eb-8038-b4e7dd107436 # No need for change\nCOLLECTOR_ATOMIC_RED_TEAM_ID=0f2a85c1-0a3b-4405-a79c-c65398ee4a76 # No need for change\nINJECTOR_CALDERA_ENABLE=false\nEXECUTOR_CALDERA_ENABLE=false\nCOLLECTOR_CALDERA_ENABLE=false\nCOLLECTOR_CALDERA_ID=ChangeMe # Should be a valid UUID\nIf your docker-compose deployment does not support .env files, just export all environment variables before launching the platform:
export $(cat .env | grep -v \"#\" | xargs)\nTo connect to Caldera, you need to use one of the users defined in your caldera.yml file (either 'red' or 'blue'). OpenBAS will use the red user.
You have to install all the needed dependencies for the main application if you would like to play breach and attack simulation scenarios. The example below is 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 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.
Kubernetes Helm Charts
OpenBAS Helm Charts for Kubernetes with a global configuration file. More information how to deploy here on basic installation and examples.
GitHub Repository
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":"reference/apis/filters/","title":"Filter knowledge","text":"In OpenBAS, you can filter data to focus on or display information with specific attributes.
"},{"location":"reference/apis/filters/#filters-usages","title":"Filters usages","text":""},{"location":"reference/apis/filters/#dynamic-filters","title":"Dynamic filters","text":"Dynamic filters allow you to filter the UI view based on the attributes present in the data, such as the list of scenarios or simulations.
These filters are not stored in the database. However, they remain persistent on the frontend of the platform. Your web browser saves the filters you set in different areas of the platform in local storage, allowing you to retrieve them when you return to the same view. This way, you can continue working from where you left off.
Additionally, the filters applied in a view are saved as URL parameters, enabling you to save and share links to these filtered views.
"},{"location":"reference/apis/filters/#create-a-filter","title":"Create a filter","text":"To create a filter, add every key you need using the 'Add filter' select box. It will give you the possible attributes on which you can filter in the current view.
A grey box appears and allows to select:
You can add as many filters as you need.
The boolean modes (and/or) are global (between every attribute filters) and can be switched with a single click, changing the logic of your filtering.
"},{"location":"reference/apis/filters/#filters-format","title":"Filters format","text":"The OpenBAS platform uses a filter format called FilterGroup. The FilterGroup model enables to do complex filters imbrication with different boolean operators, which extends greatly the filtering capabilities in every part of the platform.
The format can be described as below:
{\n \"filterGroup\": {\n \"mode\": \"and\",\n // or \"or\"\n \"filters\": [\n {\n \"key\": \"name\",\n \"mode\": \"or\",\n // or \"and\"\n \"values\": [\n \"value1\",\n \"value2\"\n ],\n \"operator\": \"contains\"\n // or \"not_contains\", \"eq\", \"not_eq\", \"starts_with\", \"not_starts_with\",\n // \"empty\", \"not_empty\"\n }\n ]\n }\n}\nIn a given filter group, the mode (and or or) represents the boolean operation between the different filters and filterGroups arrays. The filters and filterGroups arrays are composed of objects of type Filter and FilterGroup.
The Filter has 4 properties:
key, representing the kind of data we want to target (example: tags to filter on tags or name to filter on the data's name),values, representing the values we want to compare to,operator representing the operation we want to apply between the key and the values,mode (and or or) to apply between the values if there are several ones.The available operators are:
Value Meaning contains contains not_contains not contains eq equal not_eq different empty empty / no value not_empty non-empty / any valueIn addition, there are operators:
starts_with / not_starts_with, available for searching in short string fields (name, value, title, etc.),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/assets/#security-platforms","title":"Security platforms","text":"Some integrations in OpenBAS are connected to your security platforms, such as Microsoft Sentinel, Microsoft Defender, etc., and can be viewed on this screen.
OpenBAS strives to support as many integrations as possible with the most popular tools on the market. However, if your security platform integration is not yet available, you can create it manually here.
"},{"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 configuration, the command lines (if relevant) and the execution logs of the atomic testing and its expectations.
You can also see the raw execution logs of the Injector responsible for the test execution.
"},{"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":"Collectors list
You are looking for the available collectors? The list is in the OpenBAS Ecosystem.
"},{"location":"usage/collectors/#introduction","title":"Introduction","text":"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 important 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":"usage/collectors/#detection-prevention-with-edr","title":"Detection & Prevention with EDR","text":"For EDRs, we analyze the tool's logs to identify matches for the hostname and the parent process name associated with the attack. If the attack is initiated by the OpenBAS agent, the parent process name will follow this format: openbas-implant-INJECT_ID.exe.
"},{"location":"usage/collectors/#detection-prevention-with-siem","title":"Detection & Prevention with SIEM","text":"For SIEMs, we rely on the upstream-deployed EDR, whose logs are collected by the SIEM. If the EDR confirms an expectation of type detection or prevention, we trace this information back in the SIEM to validate it as well.
This means that within the workflow, the EDR collector must first validate the expectation before the SIEM collector can perform its task.
"},{"location":"usage/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":"usage/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":"usage/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":"usage/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":"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/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 target reads articles: Automatically validated when the article of a Media pressure inject has been read by targets.There are two modes for validating an expectation :
All targets (per group) must validate the expectation : in this case, the result depends on every group member's performance. If one target fails, the entire team fails. The score is calculated as the average of all targets' scores.
At least one target (per group) must validate the expectation : here, the success of the group depends on at least one target succeeding. If one target succeeds, the group is considered successful. The score is an average of all successful targets' 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.
"},{"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/expectations/#customize-expectations","title":"Customize expectations","text":""},{"location":"usage/expectations/#default-score","title":"Default score","text":"Expectations have a default score at creation. Depending on the expectation's type, there is a default score value set in the system.
Expectations results must be validated within a time limit. Depending on the expectation's type, there is a default expiration time set in the system. You have two ways to modify that expiration time:
A default expiration time is set for technical and human expectations. Users can override them for each type of expectations.
When creating an expectation, users can set an expiration time. The system's default times are set on the form and users decide to override it.
"},{"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 scenarios based on real threat. OpenBAS is result-oriented with many dashboards helping you to evaluate you security posture given a defined context.
Here are some examples of use cases:
The Home screen provides every OpenBAS platform visitor with a snapshot of the platform activity as well as an overview of your global security posture. You can find more information in this section.
"},{"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 establishing such a template, you will be able to schedule it as a one shot simulation, or as a recurring one.
Optionally, you can enhance 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. From 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.
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 list
You are looking for the available injectors? The list is in the OpenBAS Ecosystem.
"},{"location":"usage/injectors/#introduction","title":"Introduction","text":"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":"usage/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.
Some of them :
Those injectors are used to push information to human assets (aka players) such as emails, SMS, phone calls, instant messaging etc.
Some of them :
Those injectors are used to inject real or fake information into case management, ticketing and incident response systems.
"},{"location":"usage/injectors/#others","title":"\ud83d\udc89 Others","text":"All other system OpenBAS can inject, as part of breach and attack simulation campaigns.
Some of them :
Tips
If you want to learn more about the concept and features of agents, you can have more info here.
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/#inject-tests","title":"Inject tests","text":"You can test direct contact injects in simulations and scenarios.
"},{"location":"usage/injects/#unit-test","title":"Unit test","text":"You can test injects one at a time.
In the injects list of your simulation/scenario, open the contextual menu of an email or sms inject. Click on \"Test\". A confirmation dialog appears, you can confirm the test or cancel it.
After launching the test, an alert appears at the top of the page. You can click on the \"dedicated page\" link. You are redirected to the tests list, a drawer with the execution details of the test opens.
Warning
The option is disabled if your inject doesn't have any teams.
"},{"location":"usage/injects/#bulk-test","title":"Bulk test","text":"You can test injects in bulk.
Select the injects you want to test then click on the bug icon. A confirmation dialog appears, you can cancel or confirm the launch of the test.
As mentioned in the dialog, only sms and emails injects will be tested. The emails/sms are sent to the current user.
After the launch of the test, you are redirected to the tests list page.
"},{"location":"usage/injects/#tests-list","title":"Tests list","text":"A \"Tests\" tab is available in simulations and scenarios. The list of all the tests done on the injects of the simulation/scenario are displayed. Clicking on one of the lines opens the drawer with the execution details of the tests.
Note
Only the latest test is displayed for each inject.
"},{"location":"usage/injects/#replay-tests","title":"Replay tests","text":"Each test in the list has a menu allowing users to delete or replay the test.
After confirming the replay of the test, the details are updated.
The user can also replay all the tests in the list. An icon similar to the one in the injects toolbar is available at the top of the list. After clicking on it, the user confirms the tests launch and the details are updated.
"},{"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/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/openbas-agent/","title":"OpenBAS Agent","text":""},{"location":"usage/openbas-agent/#introduction","title":"Introduction","text":"The OpenBAS Agent is an application whose main role is to enroll an Asset on the OpenBAS platform, to retrieve jobs or scripts to be executed and to transmit this information to Implants (subject to come) for execution on the host Asset.
The Agent will not perform direct actions on the Asset to remain neutral for antivirus and ensure the full run of the simulation.
The OpenBAS Agent is compatible with different OS (Windows, Linux, macOS) and is developed in Rust.
"},{"location":"usage/openbas-agent/#installation","title":"Installation","text":"Depending on the OS, several installations are at your disposal, you can find them on OpenBAS by clicking the blue icon on the right top corner :
Linux
systemctl enable openbas-agentsystemctl start openbas-agent & systemctl stop openbas-agentMacOS
launchctl list | grep openbas.agentlaunchctl bootstrap system ~/Library/LaunchDaemons/openbas-agent.plist & launchctl bootout system ~/Library/LaunchDaemons/openbas-agent.plistWindows
Get-Service -Name \"OBASAgentService\"Start-Service -Name \"OBASAgentService\" & Stop-Service -Name \"OBASAgentService\"The following flow diagram represents the Agent installation flow :
"},{"location":"usage/openbas-agent/#network-traffic","title":"Network Traffic","text":"The installation creates two firewall rules.
Inbound rule
Outbound rule
"},{"location":"usage/openbas-agent/#features","title":"Features","text":"The main features of the OpenBAS Agent are:
The Agent is installed on the Asset using an agent-installer.exe file and runs as a service. It communicates with the deployed OpenBAS instance in order to enroll the Asset. In some cases like unsecured certificates or environment with proxy, the agent can't communicate with OpenBAS. In order to fix those issues, look at \"Network and security\" chapter from configuration to add the required attributes.
NB : An Asset can only have one OpenBAS agent installed thanks to a machine id calculated according to the operating system and its parameters. If you try to install again an OpenBAS agent on a platform, it will overwrite the actual one and you will always see one endpoint on the OpenBAS endpoint page.
Auto upgrade the Agent (on start-up and registration)
Retrieval of jobs to be executed
The Agent retrieves jobs to be executed from the OpenBAS instance every 30 seconds. For the moment, jobs are Implant to spawn and launch on the Asset, waiting to execute payloads of your Simulation's Injects. Each job execution logs is kept in a dedicated directory in order to have a trace of what happened (pid, executable).
The Agent deletes Implants that have been running for a predefined time and cleans the execution directories.
The Agent pings the OpenBAS instance every 2 minutes to notify it of its healthy status.
The Agent ensures that the processes it has executed are correctly finished or deleted if necessary. The maximum time in minutes that a process associated with an execution directory can remain active is 20 minutes.
The Agent removes execution directories to avoid excessive disk space. The maximum time in minutes that an execution directory can be kept before being deleted is 2 days.
"},{"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/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/scenario_import/","title":"Importing Injects into a Scenario","text":"Recreating a timeline of injects that were already defined in a spreadsheet can be a frustrating task. To help users save time, we added the possibility to import injects as defined in an xls file into a scenario. This is done via a two-steps process : creating a mapper and importing the xls file using the mapper.
"},{"location":"usage/scenario_import/#how-to-create-a-mapper","title":"How to create a mapper ?","text":"First of all, to import injects into a scenario, you need to create a mapper. To do that, using an admin account, navigate to the Settings > Data ingestion page. You will then be able to see a list of all the mappers but also to create new ones by clicking on the \"+\" button on the bottom right of the screen.
"},{"location":"usage/scenario_import/#setting-up-the-mapper-to-tell-each-injects-apart","title":"Setting up the mapper to tell each injects apart","text":"When creating a new mapper, you will quickly be asked to choose an inject type column. This column is the one that will allow the mapper to figure out which injects to create (Sending a mail, sending an sms, ...). Once this column has been chosen, you can add a representation for an inject type.
The first thing to define in this representation is the matching type in the xls. This is the value that will define which inject to create when scanning the column defined in \"inject type column\". For instance, if you want to create an inject that sends individual emails when in the column there is the word \"mail\", then you will need to set the value as \"mail\". You can also make use of regular expressions in this field. Please keep in mind though that this value is case sensitive.
Once that is done, you can select the inject type among a list of injects that are compatible with the xls import. When that selection is done, you will be able to set a column for each of the attribute that can be completed using the import. If you wish to set a default value you can do so by clicking the gear on the right side of the field.
"},{"location":"usage/scenario_import/#properly-setting-the-trigger-time-of-the-inject","title":"Properly setting the trigger time of the inject","text":"It should also be noted that the \"Trigger Time\" field has a second parameter that can be set using the gear button. It can be used to set a custom format for specific dates and or time to be interpreted. The complete format rules are available here but here is a very quick overview :
Symbol Meaning Presentation Examples y year-of-era year 2004; 04 M/L month-of-year number/text 7; 07; Jul; July; J d day-of-month number 10 a am-pm-of-day text PM h clock-hour-of-am-pm (1-12) number 12 H hour-of-day (0-23) number 0 m minute-of-hour number 30 s second-of-minute number 55 ' escape for text delimiter '' single quote literal ' [ optional section start ] optional section endPlease, do note that if you wish to use exact time of the day (e.g. 9:30) in your trigger time, you will need to set a launch date on your scenario before importing the timeline of injects from the xls file.
You can also decide to use relative dates for each injects. For instance, you can say that your first inject happens at T and that subsequent injects happens at T+x. If so, you can set relative dates using the following values :
Symbol Meaning D Day J Day H Hour T Hour M MinutesThis means that if you want your inject to start 2 days, 3 hours and 45 minutes after the start of your scenario, you can set the trigger time to D+2 H+3 M+45. When using relative dates, you do not need to define a pattern for the trigger time field.
Once you have set all fields you wish to set, you can click on the create button if you wish to create your mapper but you can also click on the test button to check that it works as intended.
"},{"location":"usage/scenario_import/#testing-the-mapper","title":"Testing the mapper","text":"If you click on the test button, you'll then be asked to choose a file. Once that is done, you will have to select the sheet to test out of the spreadsheet and the timezone. You will then be able to click on Test to have the result field filled as well as a list of the messages generated during the import (those are not saved, and are just there to help figure out what happened during the import itself).
"},{"location":"usage/scenario_import/#how-to-import-injects-into-a-scenario-using-a-mapper","title":"How to import injects into a scenario using a mapper ?","text":"Once your mapper has been created, navigate to your scenario and then to the injects tab. There, you will be able to click on an import button on the top right. A modal will be opening, inviting you to select an .xls/.xlsx file. Once it has been selected, you can click on next. You will then be asked to choose the sheet to import out of the spreadsheet and to select the mapper to use. You will also be able to select the timezone to use for the import. Once everything is set, click on the launch import button and your injects will be imported into the current scenario ! Please do not that if all the dates in the xls file are absolute time of the day (e.g. 9:30, 12:45, ...), it is required for the scenario to have a launch date set.
"},{"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/simulation_reports/","title":"Generating and Sharing Simulation Reports in PDF Format","text":"You can generate and share a simulation report in PDF format. The following steps guide you through viewing, creating, and editing simulation reports, as well as generating PDF of these reports.
"},{"location":"usage/simulation_reports/#viewing-the-list-of-simulation-reports","title":"Viewing the List of Simulation Reports","text":"When you navigate into the Report Simulation Details page: * You can add a global observation related to the overall simulation. * You can add specific comments to each inject within the report.
All observations and comments are independent and unique to each report.
"},{"location":"usage/simulation_reports/#editing-a-generated-report","title":"Editing a Generated Report","text":"Even after a report has been generated, it is still possible to update: * The report name. * The modules to be displayed in the report.
"},{"location":"usage/simulation_reports/#generating-a-pdf-of-the-report","title":"Generating a PDF of the Report","text":"Once you are on the report page: Click on the \"PDF\" button on the top of the simulation report details page to generate a PDF format.
"},{"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/components/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.
Challenges are integral to handling CTF (Capture The Flag) activities on the OpenBAS platform. You can define your challenge and the flags that need to be found to complete it.
"},{"location":"usage/components/challenges/#create-a-challenge","title":"Create a Challenge","text":"To create a new challenge, follow these steps:
Once completed, your new challenge will appear in the challenge list.
"},{"location":"usage/components/challenges/#use-a-challenge","title":"Use a Challenge","text":"Challenges can be utilized in Scenarios and Simulations. When creating an inject of type \"Publish challenges,\" you need to select a challenge to be sent to your players.
"},{"location":"usage/components/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/components/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/components/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/components/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/components/lessons/","title":"Lessons","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.
Lessons in OpenBAS enable you to create customizable surveys for your simulations. These surveys can be composed of various categories and questions within those categories. This feature helps in conducting the often overlooked part of a Breach and Attack Simulation involving real people, by automating the process and complementing your simulation results with qualitative feedback.
"},{"location":"usage/components/lessons/#create-a-lesson-template","title":"Create a Lesson template","text":"To create a new lesson template, follow these steps:
Once completed, your new lesson will appear in the lesson learned list.
"},{"location":"usage/components/lessons/#create-a-category","title":"Create a Category","text":"To create a new category, follow these steps:
To create a new question, follow these steps:
Lesson templates can be utilized in the Lesson Learned tab of a Simulation. Here\u2019s how to use them:
By integrating lesson templates into your simulations, you can gather valuable insights and improve the effectiveness of your Breach and Attack Simulations.
"},{"location":"usage/components/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/components/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/components/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/components/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.
In OpenBAS, you can create custom payloads based on different types to create new injects.
Payloads enhance the platform, allowing you to further customize your scenarios.
"},{"location":"usage/components/payloads/#create-a-payload","title":"Create a Payload","text":"To create a new payload, follow these steps:
Once completed, your new payload will appear in the payload list.
"},{"location":"usage/components/payloads/#common-payload-properties","title":"Common Payload properties","text":"Property Description Name Payload name Platforms Compatible platforms (ex. Windows, Linux, MacOS) Description Payload description Prerequisites Prerequisites required to execute the command Cleanup executor Executor for cleaning commands Cleanup command Cleanup command to remove or reset changes made Attack patterns Command-related attack patterns Tags Tags Arguments Arguments for the cleanup, prerequisites and potential command line"},{"location":"usage/components/payloads/#prerequisites-in-depth","title":"Prerequisites in depth","text":"Property Description Command executor Executor for prerequisite Check command Verifies if specific condition are met Get command Run command if check command failed"},{"location":"usage/components/payloads/#additional-payload-properties-by-type","title":"Additional Payload properties by type","text":""},{"location":"usage/components/payloads/#command-line","title":"Command Line","text":"This payload type executes commands directly on the command line interface (CLI) of the target system (e.g., Windows Command Prompt, PowerShell, Linux Shell).
Command Line payloads are used for remote command execution to simulate common attacker actions like privilege escalation or data exfiltration.
Property Description Command executor Executor for command to execute Command Command to execute"},{"location":"usage/components/payloads/#executable","title":"Executable","text":"An Executable payload involves delivering a binary file (such as .exe on Windows or ELF on Linux) that the system runs as an independent process.
Executables can perform a variety of functions, from establishing a backdoor to running complex scripts (mimic malware).
Property Description Architecture Compatible architecture (ex. x86_64, arm64) Executable file File to execute"},{"location":"usage/components/payloads/#file-drop","title":"File Drop","text":"File Drop payloads are designed to deliver files (e.g., scripts, documents, binaries) to the target system without immediately executing them.
The goal is typically to simulate scenarios where attackers place files in specific locations for later use, either manually or by another process.
Property Description File to drop File to drop"},{"location":"usage/components/payloads/#dns-resolution","title":"DNS Resolution","text":"DNS resolution payloads attempts to resolve hostnames to associated IP address(es).
The goal of DNS resolution is to test if specific hostnames resolve to IP addresses correctly, helping assess network accessibility, detect issues, and simulate potential attacker behavior.
Property Description Hostnames Hostname list to resolve"},{"location":"usage/components/payloads/#payload-execution-workflow","title":"Payload execution workflow","text":""},{"location":"usage/components/payloads/#use-a-payload","title":"Use a Payload","text":"After creation, a new inject type will automatically appear in the inject types list if the implant you're using supports it (the OpenBAS Implant does).
"},{"location":"usage/components/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/components/variables/","title":"Variables","text":""},{"location":"usage/components/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 :
The list of available variables is found in the definition of the inject :
"},{"location":"usage/components/variables/#custom-variables","title":"Custom Variables","text":"
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/components/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 injects within an exercise. Here is a non-exhaustive list of concerned injects : - Email sending - Sms sending
In case of a list like articles, which is a list of articles with properties such as id, name, and uri, or ${teams}, you could write:
<#list articles as article> - ${article.name} </#list> <#list teams as team> ${team} </#list>
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 Home screen provides visitors of the OpenBAS platform with an overview of the platform's live activity and a snapshot of your global security posture. Below is a breakdown of the various widgets available on this page.
"},{"location":"usage/evaluate/overview/#metric-cards","title":"Metric cards","text":"This section displays the count of different components within the platform, shown in two metrics:
Note
From here, the data is based on simulations created and launched within the last 180 days.
"},{"location":"usage/evaluate/overview/#performance-overview","title":"Performance overview","text":"This section highlights the results of your simulation inject expectations, categorized in three types: prevention, detection, and human response.
"},{"location":"usage/evaluate/overview/#simulations","title":"Simulations","text":"This bar chart represents simulations grouped by week, based on their start date.
"},{"location":"usage/evaluate/overview/#top-simulation-categories","title":"Top simulation categories","text":"This polar chart aggregates all simulations by category, giving you a visual breakdown of the top categories.
"},{"location":"usage/evaluate/overview/#top-attack-patterns","title":"Top attack patterns","text":"This horizontal bar chart displays the top attack patterns identified in your simulations, based on the number of injects associated with each attack pattern.
"},{"location":"usage/evaluate/overview/#last-simulations","title":"Last simulations","text":"Here, we display the six most recent simulations, sorted in descending order by their start date.
"},{"location":"usage/evaluate/overview/#mitre-attck-coverage","title":"MITRE ATT&CK Coverage","text":"This section presents the MITRE ATT&CK matrix, based on the results of your simulation inject expectations. It provides an overview of which tactics and techniques have been covered in your simulations.
"},{"location":"usage/scenario/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.
This integration works across multiple entities:
When you click on the simulate button, you\u2019ll have two options:
It\u2019s essential to understand that a scenario creation for these entities relies on matching TTPs between OpenCTI and OpenBAS. You\u2019ll need to ensure that the TTPs in both platforms are aligned. For instance, if your report contains the TTP T1059.001, a scenario can be created with an inject, provided OpenBAS also includes T1059.001.
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 do for any other scenarios. 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.
"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"OpenBAS Documentation Space","text":"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":"#blog-posts","title":"Blog posts","text":"Resources and content
Discover tutorials, best practices and deep dives on OpenBAS features on our Filigran blog.
Read now
Below, you will find external resources which may be useful along your OpenCTI journey.
OpenBAS Ecosystem List of available injectors and collectors to expand platform usage.
Training Courses Training courses for analysts and administrators in the Filigran training center.
Video materials Set of video illustrating the implementation of use cases and platform capabilities.
"},{"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\nYou can manage users in Settings > Security > Users. If you are using Single Sign-On (SSO), user accounts in OpenBAS are automatically created upon login.
To create a user, just click on the + button :
To update a user, click on the ellipsis menu (\u22ee) :
Here, you can modify parameters such as the organization, phone number, password, and even your GPG public key :
To delete a user :
"},{"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":"Tips
If you want to learn more about the concept and features of collectors, you can have more info here.
"},{"location":"deployment/collectors/#installation","title":"Installation","text":""},{"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 openbas.unsecured-certificate OPENBAS_UNSECURED-CERTIFICATE false Turn on to authorize self-signed or unsecure ssl certificate openbas.with-proxy OPENBAS_WITH-PROXY false Turn on to authorize environment with proxy"},{"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\") openbas.rabbitmq.management-insecure OPENBAS_RABBITMQ_MANAGEMENT-INSECURE true Whether or not the calls to the management plugin of rabbitmq can be insecure openbas.rabbitmq.trust.store OPENBAS_RABBITMQ_TRUST_STORE <file:/path/to/client-store.p12> Path to the p12 keystore file to use if ssl is activated and insecure management is deactivated. The keystore must contain the client side certificate and key generated for ssl. openbas.rabbitmq.trust-store-password OPENBAS_RABBITMQ_TRUST-STORE-PASSWORD <trust-store-password> Password of the keystore"},{"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. openbas.s3.use-aws-role OPENBAS_S3_USE-AWS-ROLE false Whether or not we want to get the AWS role using AWS Security Token Service openbas.s3.sts-endpoint OPENBAS_S3_STS-ENDPOINT experimental This parameter is optional. If it stays empty, it will use either the AWS legacy STS endpoint (https://sts.amazonaws.com) or the regional one using AWS_REGION if the environment variable is set (you can learn more about it here). Otherwise, if you want to use your own custom implementation of STS endpoints, you can set it here."},{"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 neutral executor that will be in charge of executing implants as detached processes. Implants will then 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)To know more about other available executors, please refer to the executors documentation
"},{"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 Note : Example with Gmail
Parameter Environment variable Value Description spring.mail.host SPRING_MAIL_HOST smtp.gmail.com Gmail SMTP server hostname spring.mail.port SPRING_MAIL_PORT 587 Gmail SMTP server port (TLS) spring.mail.username SPRING_MAIL_USERNAME username@mail.com Gmail address spring.mail.password SPRING_MAIL_PASSWORD app password Gmail App-specific password spring.mail.properties.mail.smtp.auth SPRING_MAIL_PROPERTIES_MAIL_SMTP_AUTH true Enable SMTP authentication spring.mail.properties.mail.smtp.starttls.enable SPRING_MAIL_PROPERTIES_MAIL_SMTP_STARTTLS_ENABLE true Enable SMTP STARTTLS\u26a0\ufe0f Important: If you are using two-factor authentication on your Gmail account, an app-specific password is required. You can find a guide here.
"},{"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 STARTTLSNote : Example with Gmail
Parameter Environment variable Value Description openbas.mail.imap.enabled OPENBAS_MAIL_IMAP_ENABLED true Enable IMAP for Gmail openbas.mail.imap.host OPENBAS_MAIL_IMAP_HOST imap.gmail.com Gmail IMAP server hostname openbas.mail.imap.port OPENBAS_MAIL_IMAP_PORT 993 Gmail IMAP port (SSL) openbas.mail.imap.username OPENBAS_MAIL_IMAP_USERNAME username@mail.com Gmail address openbas.mail.imap.password OPENBAS_MAIL_IMAP_PASSWORD app password Gmail App-specific password openbas.mail.imap.ssl.enable OPENBAS_MAIL_IMAP_SSL_ENABLE true Enable IMAP SSL openbas.mail.imap.ssl.trust OPENBAS_MAIL_IMAP_SSL_TRUST * Trust unverified certificates openbas.mail.imap.auth OPENBAS_MAIL_IMAP_AUTH true Enable IMAP authentication openbas.mail.imap.sent OPENBAS_MAIL_IMAP_SENT [Gmail]/Sent Mail IMAP sent directory to synchronize from\u26a0\ufe0f Important: If you are using two-factor authentication on your Gmail account, an app-specific password is required. You can find a guide here.
"},{"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/executors/","title":"Executors","text":""},{"location":"deployment/executors/#introduction","title":"Introduction","text":"To be able to use the power of the OpenBAS platform on endpoints, you need at least one neutral executor that will be in charge of executing implants as detached processes. Implants will then execute payloads.
"},{"location":"deployment/executors/#openbas-agent","title":"OpenBAS Agent","text":"More informations here
"},{"location":"deployment/executors/#tanium-agent","title":"Tanium Agent","text":"The Tanium agent can be leveraged to execute implants as detached processes that will the execute payloads according to the OpenBAS architecture.
"},{"location":"deployment/executors/#configure-the-tanium-platform","title":"Configure the Tanium Platform","text":"First of all, we are providing 2 Tanium packages to be imported in the Tanium platform.
Tanium package configuration
Because OpenBAS should run implants as detached processed, you must uncheck the box \"Launch this package command in a process group\" in the package configuration:
Once configured and imported, retrieve the package IDs from the URL ui/console/packages/XXXXX/preview.
To use the Tanium executor, just fill the following configuration.
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 Tanium API Key
Please note that the Tanium API key should have the permissions to retrieve endpoint list from the Tanium GraphQL API as well as to launch packages on endpoints.
"},{"location":"deployment/executors/#checks","title":"Checks","text":"Once enabled, you should see Tanium available in your Install agents section
Also, the assets in the selected computer groups should now be available in the endpoints section in OpenBAS:
NB : An Asset can only have one Tanium agent installed thanks to an unicity with hostname and IP parameters. If you try to install again a Tanium agent on a platform, it will overwrite the actual one and you will always see one endpoint on the OpenBAS endpoint page.
Installation done
You are now ready to leverage your Tanium platform to run OpenBAS payloads!
"},{"location":"deployment/executors/#caldera-agent","title":"Caldera Agent","text":"The Caldera agent can be leveraged to execute implants as detached processes that will the execute payloads according to the OpenBAS architecture.
Caldera already installed
If you already have a working Caldera installation, just go directly to OpenBAS configuration section.
"},{"location":"deployment/executors/#deploy-caldera","title":"Deploy Caldera","text":"To deploy Caldera, you can just add Caldera to the OpenBAS stack, we advise you to modify your docker-compose.yml and add a Caldera service:
services:\n caldera:\n image: openbas/caldera-server:5.0.0\n restart: always\n ports:\n - \"8888:8888\"\n environment:\n CALDERA_URL: http://localhost:8888\n volumes:\n - type: bind\n source: caldera.yml\n target: /usr/src/app/conf/local.yml\nAs you can see in the configuration, you will also need a configuration file caldera.yml because Caldera does not support well environment variables for configuration.
Download caldera.yml and put it alongside your docker-compose.yml file. This file must be modified prior launching, only change what is marked as Change this, listed below.
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\nJust update your stack and check Caldera is running:
docker compose up -d\nThen, just change the OpenBAS configuration as follow:
Parameter Environment variable Default value Description executor.caldera.enable EXECUTOR_CALDERA_ENABLEfalse 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 (ex: http://caldera.myopenbas.myorganization.com:8888) executor.caldera.api-key EXECUTOR_CALDERA_API-KEY Caldera API key"},{"location":"deployment/executors/#agents","title":"Agents","text":""},{"location":"deployment/executors/#deploy-agents","title":"Deploy agents","text":"Once enabled, you should see Caldera available in your Install agents section:
OpenBAS has built-in instruction if you want command line examples to deploy the agent on one endpoint.
Caldera AV detection
By default, the Caldera agent \"Sandcat\" is detected and blocked by antivirus. Here, we are using Caldera as a neutral executor that will execute implants that will execute payloads, so you need to add the proper AV exclusions as instructed in the OpenBAS screen.
"},{"location":"deployment/executors/#checks_1","title":"Checks","text":"All assets with a proper Caldera agent installed using the OpenBAS provided command line (then persistent) should now be available in the OpenBAS endpoints list.
NB : An Asset can only have one Caldera agent installed thanks to an unicity with hostname and IP parameters. If you try to install again a Caldera agent on a platform, it will overwrite the actual one and you will always see one endpoint on the OpenBAS endpoint page.
"},{"location":"deployment/injectors/","title":"Injectors","text":"Tips
If you want to learn more about the concept and features of injectors, you can have more info here.
"},{"location":"deployment/injectors/#installation","title":"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 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.
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\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_ENABLED=true\nOPENBAS_MAIL_IMAP_HOST=imap.changeme.com\nOPENBAS_MAIL_IMAP_PORT=993\nOPENBAS_ADMIN_EMAIL=ChangeMe@domain.com # Should be a valid email address\nOPENBAS_ADMIN_PASSWORD=ChangeMe\nOPENBAS_ADMIN_TOKEN=ChangeMe # Should be a valid UUI\nCOLLECTOR_MITRE_ATTACK_ID=3050d2a3-291d-44eb-8038-b4e7dd107436 # No need for change\nCOLLECTOR_ATOMIC_RED_TEAM_ID=0f2a85c1-0a3b-4405-a79c-c65398ee4a76 # No need for change\nIf 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/#openbas-x-caldera-optional-part","title":"OpenBAS X Caldera (Optional part)","text":"You can deploy Caldera alongside OpenBAS to manage agent deployment and execute Caldera scripts.
Use Docker
Deploy OpenBAS using Docker and the default docker-compose.yml provided in the docker.
Setup
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 .env.sample file for .env and enter the required values, or directly update the docker-compose.yml file with the values specific 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@domain.com\nOPENBAS_ADMIN_PASSWORD=ChangeMe\nOPENBAS_ADMIN_TOKEN=ChangeMe # Should be a valid UUID\nCALDERA_URL=http://caldera:8888 # Change me for production deployment to something accessible from your OpenBAS\nCALDERA_PUBLIC_URL=http://localhost:8888 # Change me for production deployment to something accessible from your endpoint(s)\nCALDERA_API-KEY=ChangeMe # Should be the same as api_key in your caldera.yml file\nCOLLECTOR_MITRE_ATTACK_ID=3050d2a3-291d-44eb-8038-b4e7dd107436 # No need for change\nCOLLECTOR_ATOMIC_RED_TEAM_ID=0f2a85c1-0a3b-4405-a79c-c65398ee4a76 # No need for change\nINJECTOR_CALDERA_ENABLE=false\nEXECUTOR_CALDERA_ENABLE=false\nCOLLECTOR_CALDERA_ENABLE=false\nCOLLECTOR_CALDERA_ID=ChangeMe # Should be a valid UUID\nIf your docker-compose deployment does not support .env files, just export all environment variables before launching the platform:
export $(cat .env | grep -v \"#\" | xargs)\nTo connect to Caldera, you need to use one of the users defined in your caldera.yml file (either 'red' or 'blue'). OpenBAS will use the red user.
You have to install all the needed dependencies for the main application if you would like to play breach and attack simulation scenarios. The example below is 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 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.
Kubernetes Helm Charts
OpenBAS Helm Charts for Kubernetes with a global configuration file. More information how to deploy here on basic installation and examples.
GitHub Repository
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":"reference/apis/filters/","title":"Filter knowledge","text":"In OpenBAS, you can filter data to focus on or display information with specific attributes.
"},{"location":"reference/apis/filters/#filters-usages","title":"Filters usages","text":""},{"location":"reference/apis/filters/#dynamic-filters","title":"Dynamic filters","text":"Dynamic filters allow you to filter the UI view based on the attributes present in the data, such as the list of scenarios or simulations.
These filters are not stored in the database. However, they remain persistent on the frontend of the platform. Your web browser saves the filters you set in different areas of the platform in local storage, allowing you to retrieve them when you return to the same view. This way, you can continue working from where you left off.
Additionally, the filters applied in a view are saved as URL parameters, enabling you to save and share links to these filtered views.
"},{"location":"reference/apis/filters/#create-a-filter","title":"Create a filter","text":"To create a filter, add every key you need using the 'Add filter' select box. It will give you the possible attributes on which you can filter in the current view.
A grey box appears and allows to select:
You can add as many filters as you need.
The boolean modes (and/or) are global (between every attribute filters) and can be switched with a single click, changing the logic of your filtering.
"},{"location":"reference/apis/filters/#filters-format","title":"Filters format","text":"The OpenBAS platform uses a filter format called FilterGroup. The FilterGroup model enables to do complex filters imbrication with different boolean operators, which extends greatly the filtering capabilities in every part of the platform.
The format can be described as below:
{\n \"filterGroup\": {\n \"mode\": \"and\",\n // or \"or\"\n \"filters\": [\n {\n \"key\": \"name\",\n \"mode\": \"or\",\n // or \"and\"\n \"values\": [\n \"value1\",\n \"value2\"\n ],\n \"operator\": \"contains\"\n // or \"not_contains\", \"eq\", \"not_eq\", \"starts_with\", \"not_starts_with\",\n // \"empty\", \"not_empty\"\n }\n ]\n }\n}\nIn a given filter group, the mode (and or or) represents the boolean operation between the different filters and filterGroups arrays. The filters and filterGroups arrays are composed of objects of type Filter and FilterGroup.
The Filter has 4 properties:
key, representing the kind of data we want to target (example: tags to filter on tags or name to filter on the data's name),values, representing the values we want to compare to,operator representing the operation we want to apply between the key and the values,mode (and or or) to apply between the values if there are several ones.The available operators are:
Value Meaning contains contains not_contains not contains eq equal not_eq different empty empty / no value not_empty non-empty / any valueIn addition, there are operators:
starts_with / not_starts_with, available for searching in short string fields (name, value, title, etc.),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/assets/#security-platforms","title":"Security platforms","text":"Some integrations in OpenBAS are connected to your security platforms, such as Microsoft Sentinel, Microsoft Defender, etc., and can be viewed on this screen.
OpenBAS strives to support as many integrations as possible with the most popular tools on the market. However, if your security platform integration is not yet available, you can create it manually here.
"},{"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 configuration, the command lines (if relevant) and the execution logs of the atomic testing and its expectations.
You can also see the raw execution logs of the Injector responsible for the test execution.
"},{"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":"Collectors list
You are looking for the available collectors? The list is in the OpenBAS Ecosystem.
"},{"location":"usage/collectors/#introduction","title":"Introduction","text":"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 important 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":"usage/collectors/#detection-prevention-with-edr","title":"Detection & Prevention with EDR","text":"For EDRs, we analyze the tool's logs to identify matches for the hostname and the parent process name associated with the attack. If the attack is initiated by the OpenBAS agent, the parent process name will follow this format: openbas-implant-INJECT_ID.exe.
"},{"location":"usage/collectors/#detection-prevention-with-siem","title":"Detection & Prevention with SIEM","text":"For SIEMs, we rely on the upstream-deployed EDR, whose logs are collected by the SIEM. If the EDR confirms an expectation of type detection or prevention, we trace this information back in the SIEM to validate it as well.
This means that within the workflow, the EDR collector must first validate the expectation before the SIEM collector can perform its task.
"},{"location":"usage/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":"usage/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":"usage/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":"usage/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":"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/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 target reads articles: Automatically validated when the article of a Media pressure inject has been read by targets.There are two modes for validating an expectation :
All targets (per group) must validate the expectation : in this case, the result depends on every group member's performance. If one target fails, the entire team fails. The score is calculated as the average of all targets' scores.
At least one target (per group) must validate the expectation : here, the success of the group depends on at least one target succeeding. If one target succeeds, the group is considered successful. The score is an average of all successful targets' 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.
"},{"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/expectations/#customize-expectations","title":"Customize expectations","text":""},{"location":"usage/expectations/#default-score","title":"Default score","text":"Expectations have a default score at creation. Depending on the expectation's type, there is a default score value set in the system.
Expectations results must be validated within a time limit. Depending on the expectation's type, there is a default expiration time set in the system. You have two ways to modify that expiration time:
A default expiration time is set for technical and human expectations. Users can override them for each type of expectations.
When creating an expectation, users can set an expiration time. The system's default times are set on the form and users decide to override it.
"},{"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 scenarios based on real threat. OpenBAS is result-oriented with many dashboards helping you to evaluate you security posture given a defined context.
Here are some examples of use cases:
The Home screen provides every OpenBAS platform visitor with a snapshot of the platform activity as well as an overview of your global security posture. You can find more information in this section.
"},{"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 establishing such a template, you will be able to schedule it as a one shot simulation, or as a recurring one.
Optionally, you can enhance 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. From 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.
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 list
You are looking for the available injectors? The list is in the OpenBAS Ecosystem.
"},{"location":"usage/injectors/#introduction","title":"Introduction","text":"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":"usage/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.
Some of them :
Those injectors are used to push information to human assets (aka players) such as emails, SMS, phone calls, instant messaging etc.
Some of them :
Those injectors are used to inject real or fake information into case management, ticketing and incident response systems.
"},{"location":"usage/injectors/#others","title":"\ud83d\udc89 Others","text":"All other system OpenBAS can inject, as part of breach and attack simulation campaigns.
Some of them :
Tips
If you want to learn more about the concept and features of agents, you can have more info here.
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/#inject-tests","title":"Inject tests","text":"You can test direct contact injects in simulations and scenarios.
"},{"location":"usage/injects/#unit-test","title":"Unit test","text":"You can test injects one at a time.
In the injects list of your simulation/scenario, open the contextual menu of an email or sms inject. Click on \"Test\". A confirmation dialog appears, you can confirm the test or cancel it.
After launching the test, an alert appears at the top of the page. You can click on the \"dedicated page\" link. You are redirected to the tests list, a drawer with the execution details of the test opens.
Warning
The option is disabled if your inject doesn't have any teams.
"},{"location":"usage/injects/#bulk-test","title":"Bulk test","text":"You can test injects in bulk.
Select the injects you want to test then click on the bug icon. A confirmation dialog appears, you can cancel or confirm the launch of the test.
As mentioned in the dialog, only sms and emails injects will be tested. The emails/sms are sent to the current user.
After the launch of the test, you are redirected to the tests list page.
"},{"location":"usage/injects/#tests-list","title":"Tests list","text":"A \"Tests\" tab is available in simulations and scenarios. The list of all the tests done on the injects of the simulation/scenario are displayed. Clicking on one of the lines opens the drawer with the execution details of the tests.
Note
Only the latest test is displayed for each inject.
"},{"location":"usage/injects/#replay-tests","title":"Replay tests","text":"Each test in the list has a menu allowing users to delete or replay the test.
After confirming the replay of the test, the details are updated.
The user can also replay all the tests in the list. An icon similar to the one in the injects toolbar is available at the top of the list. After clicking on it, the user confirms the tests launch and the details are updated.
"},{"location":"usage/injects/#conditional-execution-of-injects","title":"Conditional execution of injects","text":"You can add conditions to an inject, ensuring it is triggered at a specific time only if the specified conditions are met. These conditions typically relate to whether an expectation is fulfilled or not, but they can also pertain to the success or failure of an execution. There are several methods to achieve this.
"},{"location":"usage/injects/#using-the-update-form","title":"Using the update form","text":"You can set conditions when updating an inject. In the inject update form, there is a tab \"Logical Chains\" for that.
As you can see, you can assign a Parent and multiple Children. A Parent indicates that the current inject will only execute if the conditions set on the Parent are met at the time of execution. Similarly, a Child will execute at the specified time only if the conditions set on the current inject are satisfied.
The conditions you can set include the expectations for the inject and whether its execution was successful or not. You can select the desired expectation and Success/Fail status by clicking on them.
You can also toggle whether all conditions must be met or just one by clicking on the small OR/AND cards. Note that these settings are interconnected, so you cannot assign different values to them
"},{"location":"usage/injects/#using-the-timeline","title":"Using the timeline","text":"You also have the possibility to quickly create conditions between injects. To do that, you can go to the timeline view of injects and place your cursor on the small point on the left and right of each injects. You can then drag and drop a link from a point to another.
The links created in this way will default to an expectation of \"Execution is Success\" and must be updated using the injects' update form. Additionally, you can reposition links between injects or remove them entirely by dragging them to an empty space.
"},{"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). They are always triggered at a specific point in time but it is possible to execute them only if one or multiple conditions are met.
"},{"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. Expectations can also be used as conditions for the execution of other injects.
"},{"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/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/openbas-agent/","title":"OpenBAS Agent","text":""},{"location":"usage/openbas-agent/#introduction","title":"Introduction","text":"The OpenBAS Agent is an application whose main role is to enroll an Asset on the OpenBAS platform, to retrieve jobs or scripts to be executed and to transmit this information to Implants (subject to come) for execution on the host Asset.
The Agent will not perform direct actions on the Asset to remain neutral for antivirus and ensure the full run of the simulation.
The OpenBAS Agent is compatible with different OS (Windows, Linux, macOS) and is developed in Rust.
"},{"location":"usage/openbas-agent/#installation","title":"Installation","text":"Depending on the OS, several installations are at your disposal, you can find them on OpenBAS by clicking the blue icon on the right top corner :
Linux
systemctl enable openbas-agentsystemctl start openbas-agent & systemctl stop openbas-agentMacOS
launchctl list | grep openbas.agentlaunchctl bootstrap system ~/Library/LaunchDaemons/openbas-agent.plist & launchctl bootout system ~/Library/LaunchDaemons/openbas-agent.plistWindows
Get-Service -Name \"OBASAgentService\"Start-Service -Name \"OBASAgentService\" & Stop-Service -Name \"OBASAgentService\"The following flow diagram represents the Agent installation flow :
"},{"location":"usage/openbas-agent/#network-traffic","title":"Network Traffic","text":"The installation creates two firewall rules.
Inbound rule
Outbound rule
"},{"location":"usage/openbas-agent/#features","title":"Features","text":"The main features of the OpenBAS Agent are:
The Agent is installed on the Asset using an agent-installer.exe file and runs as a service. It communicates with the deployed OpenBAS instance in order to enroll the Asset. In some cases like unsecured certificates or environment with proxy, the agent can't communicate with OpenBAS. In order to fix those issues, look at \"Network and security\" chapter from configuration to add the required attributes.
NB : An Asset can only have one OpenBAS agent installed thanks to a machine id calculated according to the operating system and its parameters. If you try to install again an OpenBAS agent on a platform, it will overwrite the actual one and you will always see one endpoint on the OpenBAS endpoint page.
Auto upgrade the Agent (on start-up and registration)
Retrieval of jobs to be executed
The Agent retrieves jobs to be executed from the OpenBAS instance every 30 seconds. For the moment, jobs are Implant to spawn and launch on the Asset, waiting to execute payloads of your Simulation's Injects. Each job execution logs is kept in a dedicated directory in order to have a trace of what happened (pid, executable).
The Agent deletes Implants that have been running for a predefined time and cleans the execution directories.
The Agent pings the OpenBAS instance every 2 minutes to notify it of its healthy status.
The Agent ensures that the processes it has executed are correctly finished or deleted if necessary. The maximum time in minutes that a process associated with an execution directory can remain active is 20 minutes.
The Agent removes execution directories to avoid excessive disk space. The maximum time in minutes that an execution directory can be kept before being deleted is 2 days.
"},{"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/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/scenario_import/","title":"Importing Injects into a Scenario","text":"Recreating a timeline of injects that were already defined in a spreadsheet can be a frustrating task. To help users save time, we added the possibility to import injects as defined in an xls file into a scenario. This is done via a two-steps process : creating a mapper and importing the xls file using the mapper.
"},{"location":"usage/scenario_import/#how-to-create-a-mapper","title":"How to create a mapper ?","text":"First of all, to import injects into a scenario, you need to create a mapper. To do that, using an admin account, navigate to the Settings > Data ingestion page. You will then be able to see a list of all the mappers but also to create new ones by clicking on the \"+\" button on the bottom right of the screen.
"},{"location":"usage/scenario_import/#setting-up-the-mapper-to-tell-each-injects-apart","title":"Setting up the mapper to tell each injects apart","text":"When creating a new mapper, you will quickly be asked to choose an inject type column. This column is the one that will allow the mapper to figure out which injects to create (Sending a mail, sending an sms, ...). Once this column has been chosen, you can add a representation for an inject type.
The first thing to define in this representation is the matching type in the xls. This is the value that will define which inject to create when scanning the column defined in \"inject type column\". For instance, if you want to create an inject that sends individual emails when in the column there is the word \"mail\", then you will need to set the value as \"mail\". You can also make use of regular expressions in this field. Please keep in mind though that this value is case sensitive.
Once that is done, you can select the inject type among a list of injects that are compatible with the xls import. When that selection is done, you will be able to set a column for each of the attribute that can be completed using the import. If you wish to set a default value you can do so by clicking the gear on the right side of the field.
"},{"location":"usage/scenario_import/#properly-setting-the-trigger-time-of-the-inject","title":"Properly setting the trigger time of the inject","text":"It should also be noted that the \"Trigger Time\" field has a second parameter that can be set using the gear button. It can be used to set a custom format for specific dates and or time to be interpreted. The complete format rules are available here but here is a very quick overview :
Symbol Meaning Presentation Examples y year-of-era year 2004; 04 M/L month-of-year number/text 7; 07; Jul; July; J d day-of-month number 10 a am-pm-of-day text PM h clock-hour-of-am-pm (1-12) number 12 H hour-of-day (0-23) number 0 m minute-of-hour number 30 s second-of-minute number 55 ' escape for text delimiter '' single quote literal ' [ optional section start ] optional section endPlease, do note that if you wish to use exact time of the day (e.g. 9:30) in your trigger time, you will need to set a launch date on your scenario before importing the timeline of injects from the xls file.
You can also decide to use relative dates for each injects. For instance, you can say that your first inject happens at T and that subsequent injects happens at T+x. If so, you can set relative dates using the following values :
Symbol Meaning D Day J Day H Hour T Hour M MinutesThis means that if you want your inject to start 2 days, 3 hours and 45 minutes after the start of your scenario, you can set the trigger time to D+2 H+3 M+45. When using relative dates, you do not need to define a pattern for the trigger time field.
Once you have set all fields you wish to set, you can click on the create button if you wish to create your mapper but you can also click on the test button to check that it works as intended.
"},{"location":"usage/scenario_import/#testing-the-mapper","title":"Testing the mapper","text":"If you click on the test button, you'll then be asked to choose a file. Once that is done, you will have to select the sheet to test out of the spreadsheet and the timezone. You will then be able to click on Test to have the result field filled as well as a list of the messages generated during the import (those are not saved, and are just there to help figure out what happened during the import itself).
"},{"location":"usage/scenario_import/#how-to-import-injects-into-a-scenario-using-a-mapper","title":"How to import injects into a scenario using a mapper ?","text":"Once your mapper has been created, navigate to your scenario and then to the injects tab. There, you will be able to click on an import button on the top right. A modal will be opening, inviting you to select an .xls/.xlsx file. Once it has been selected, you can click on next. You will then be asked to choose the sheet to import out of the spreadsheet and to select the mapper to use. You will also be able to select the timezone to use for the import. Once everything is set, click on the launch import button and your injects will be imported into the current scenario ! Please do not that if all the dates in the xls file are absolute time of the day (e.g. 9:30, 12:45, ...), it is required for the scenario to have a launch date set.
"},{"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/simulation_reports/","title":"Generating and Sharing Simulation Reports in PDF Format","text":"You can generate and share a simulation report in PDF format. The following steps guide you through viewing, creating, and editing simulation reports, as well as generating PDF of these reports.
"},{"location":"usage/simulation_reports/#viewing-the-list-of-simulation-reports","title":"Viewing the List of Simulation Reports","text":"When you navigate into the Report Simulation Details page: * You can add a global observation related to the overall simulation. * You can add specific comments to each inject within the report.
All observations and comments are independent and unique to each report.
"},{"location":"usage/simulation_reports/#editing-a-generated-report","title":"Editing a Generated Report","text":"Even after a report has been generated, it is still possible to update: * The report name. * The modules to be displayed in the report.
"},{"location":"usage/simulation_reports/#generating-a-pdf-of-the-report","title":"Generating a PDF of the Report","text":"Once you are on the report page: Click on the \"PDF\" button on the top of the simulation report details page to generate a PDF format.
"},{"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/components/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.
Challenges are integral to handling CTF (Capture The Flag) activities on the OpenBAS platform. You can define your challenge and the flags that need to be found to complete it.
"},{"location":"usage/components/challenges/#create-a-challenge","title":"Create a Challenge","text":"To create a new challenge, follow these steps:
Once completed, your new challenge will appear in the challenge list.
"},{"location":"usage/components/challenges/#use-a-challenge","title":"Use a Challenge","text":"Challenges can be utilized in Scenarios and Simulations. When creating an inject of type \"Publish challenges,\" you need to select a challenge to be sent to your players.
"},{"location":"usage/components/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/components/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/components/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/components/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/components/lessons/","title":"Lessons","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.
Lessons in OpenBAS enable you to create customizable surveys for your simulations. These surveys can be composed of various categories and questions within those categories. This feature helps in conducting the often overlooked part of a Breach and Attack Simulation involving real people, by automating the process and complementing your simulation results with qualitative feedback.
"},{"location":"usage/components/lessons/#create-a-lesson-template","title":"Create a Lesson template","text":"To create a new lesson template, follow these steps:
Once completed, your new lesson will appear in the lesson learned list.
"},{"location":"usage/components/lessons/#create-a-category","title":"Create a Category","text":"To create a new category, follow these steps:
To create a new question, follow these steps:
Lesson templates can be utilized in the Lesson Learned tab of a Simulation. Here\u2019s how to use them:
By integrating lesson templates into your simulations, you can gather valuable insights and improve the effectiveness of your Breach and Attack Simulations.
"},{"location":"usage/components/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/components/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/components/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/components/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.
In OpenBAS, you can create custom payloads based on different types to create new injects.
Payloads enhance the platform, allowing you to further customize your scenarios.
"},{"location":"usage/components/payloads/#create-a-payload","title":"Create a Payload","text":"To create a new payload, follow these steps:
Once completed, your new payload will appear in the payload list.
"},{"location":"usage/components/payloads/#common-payload-properties","title":"Common Payload properties","text":"Property Description Name Payload name Platforms Compatible platforms (ex. Windows, Linux, MacOS) Description Payload description Prerequisites Prerequisites required to execute the command Cleanup executor Executor for cleaning commands Cleanup command Cleanup command to remove or reset changes made Attack patterns Command-related attack patterns Tags Tags Arguments Arguments for the cleanup, prerequisites and potential command line"},{"location":"usage/components/payloads/#prerequisites-in-depth","title":"Prerequisites in depth","text":"Property Description Command executor Executor for prerequisite Check command Verifies if specific condition are met Get command Run command if check command failed"},{"location":"usage/components/payloads/#additional-payload-properties-by-type","title":"Additional Payload properties by type","text":""},{"location":"usage/components/payloads/#command-line","title":"Command Line","text":"This payload type executes commands directly on the command line interface (CLI) of the target system (e.g., Windows Command Prompt, PowerShell, Linux Shell).
Command Line payloads are used for remote command execution to simulate common attacker actions like privilege escalation or data exfiltration.
Property Description Command executor Executor for command to execute Command Command to execute"},{"location":"usage/components/payloads/#executable","title":"Executable","text":"An Executable payload involves delivering a binary file (such as .exe on Windows or ELF on Linux) that the system runs as an independent process.
Executables can perform a variety of functions, from establishing a backdoor to running complex scripts (mimic malware).
Property Description Architecture Compatible architecture (ex. x86_64, arm64) Executable file File to execute"},{"location":"usage/components/payloads/#file-drop","title":"File Drop","text":"File Drop payloads are designed to deliver files (e.g., scripts, documents, binaries) to the target system without immediately executing them.
The goal is typically to simulate scenarios where attackers place files in specific locations for later use, either manually or by another process.
Property Description File to drop File to drop"},{"location":"usage/components/payloads/#dns-resolution","title":"DNS Resolution","text":"DNS resolution payloads attempts to resolve hostnames to associated IP address(es).
The goal of DNS resolution is to test if specific hostnames resolve to IP addresses correctly, helping assess network accessibility, detect issues, and simulate potential attacker behavior.
Property Description Hostnames Hostname list to resolve"},{"location":"usage/components/payloads/#payload-execution-workflow","title":"Payload execution workflow","text":""},{"location":"usage/components/payloads/#use-a-payload","title":"Use a Payload","text":"After creation, a new inject type will automatically appear in the inject types list if the implant you're using supports it (the OpenBAS Implant does).
"},{"location":"usage/components/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/components/variables/","title":"Variables","text":""},{"location":"usage/components/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 :
The list of available variables is found in the definition of the inject :
"},{"location":"usage/components/variables/#custom-variables","title":"Custom Variables","text":"
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/components/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 injects within an exercise. Here is a non-exhaustive list of concerned injects : - Email sending - Sms sending
In case of a list like articles, which is a list of articles with properties such as id, name, and uri, or ${teams}, you could write:
<#list articles as article> - ${article.name} </#list> <#list teams as team> ${team} </#list>
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 Home screen provides visitors of the OpenBAS platform with an overview of the platform's live activity and a snapshot of your global security posture. Below is a breakdown of the various widgets available on this page.
"},{"location":"usage/evaluate/overview/#metric-cards","title":"Metric cards","text":"This section displays the count of different components within the platform, shown in two metrics:
Note
From here, the data is based on simulations created and launched within the last 180 days.
"},{"location":"usage/evaluate/overview/#performance-overview","title":"Performance overview","text":"This section highlights the results of your simulation inject expectations, categorized in three types: prevention, detection, and human response.
"},{"location":"usage/evaluate/overview/#simulations","title":"Simulations","text":"This bar chart represents simulations grouped by week, based on their start date.
"},{"location":"usage/evaluate/overview/#top-simulation-categories","title":"Top simulation categories","text":"This polar chart aggregates all simulations by category, giving you a visual breakdown of the top categories.
"},{"location":"usage/evaluate/overview/#top-attack-patterns","title":"Top attack patterns","text":"This horizontal bar chart displays the top attack patterns identified in your simulations, based on the number of injects associated with each attack pattern.
"},{"location":"usage/evaluate/overview/#last-simulations","title":"Last simulations","text":"Here, we display the six most recent simulations, sorted in descending order by their start date.
"},{"location":"usage/evaluate/overview/#mitre-attck-coverage","title":"MITRE ATT&CK Coverage","text":"This section presents the MITRE ATT&CK matrix, based on the results of your simulation inject expectations. It provides an overview of which tactics and techniques have been covered in your simulations.
"},{"location":"usage/scenario/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.
This integration works across multiple entities:
When you click on the simulate button, you\u2019ll have two options:
It\u2019s essential to understand that a scenario creation for these entities relies on matching TTPs between OpenCTI and OpenBAS. You\u2019ll need to ensure that the TTPs in both platforms are aligned. For instance, if your report contains the TTP T1059.001, a scenario can be created with an inject, provided OpenBAS also includes T1059.001.
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 do for any other scenarios. 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.
"}]} \ No newline at end of file diff --git a/1.9.X/sitemap.xml b/1.9.X/sitemap.xml index 02c6ebc..2e0cf63 100644 --- a/1.9.X/sitemap.xml +++ b/1.9.X/sitemap.xml @@ -2,238 +2,238 @@
After confirming the replay of the test, the details are updated.
The user can also replay all the tests in the list. An icon similar to the one in the injects toolbar is available at the top of the list. After clicking on it, the user confirms the tests launch and the details are updated.
+You can add conditions to an inject, ensuring it is triggered at a specific time only if the specified conditions are met. These conditions typically relate to whether an expectation is fulfilled or not, but they can also pertain to the success or failure of an execution. There are several methods to achieve this.
+You can set conditions when updating an inject. In the inject update form, there is a tab "Logical Chains" for that.
+
As you can see, you can assign a Parent and multiple Children. A Parent indicates that the current inject will only execute if the conditions set on the Parent are met at the time of execution. Similarly, a Child will execute at the specified time only if the conditions set on the current inject are satisfied.
+The conditions you can set include the expectations for the inject and whether its execution was successful or not. You can select the desired expectation and Success/Fail status by clicking on them.
+
You can also toggle whether all conditions must be met or just one by clicking on the small OR/AND cards. Note that these settings are interconnected, so you cannot assign different values to them
+You also have the possibility to quickly create conditions between injects. To do that, you can go to the timeline view of injects and place your cursor on the small point on the left and right of each injects. You can then drag and drop a link from a point to another.
+
The links created in this way will default to an expectation of "Execution is Success" and must be updated using the injects' update form. Additionally, you can reposition links between injects or remove them entirely by dragging them to an empty space.
@@ -3176,7 +3255,7 @@