App white-labeling

[AlexRuiz7]

White-labeling

Supporting our partners in their commercial offerings.

Related Issues

• [ ] https://github.com/wazuh/wazuh-kibana-whitelabeling-customer1/issues/1
• [ ] https://github.com/wazuh/wazuh-kibana-app/issues/3892

Introduction

We want to make it easier for our partners and the general open source community to white-label our application interface to include their branding.

Strategy

We can use multiple strategies to allow our users to dynamically change the aspect of the UI. Most changes will need to be made to the base wazuh-indexer and wazuh-dashboard packages, while the application will need to develop an interface to manage these changes.

Important use cases

• Use case: vendors that don’t want the users to access the customization options

  • Proposed solution: access to the customization section only for authorized roles.

• Use case: possibility to add “Powered by Wazuh” to let users know the product they are using under the hood.

  • Proposed solution: keep the About section of the app unchanged.

• Use case: internationalization. Support for different languages (not officially supported by Wazuh). Users that do want to translate the plugin without the need to modify the source code.

  • Proposed solution: extract the hard-coded texts to resource assets, which can be switched and added without source code changes.

CSS variables

Design our custom opensearch-dashboard theme to use a separate CSS that will define variables that will affect the logos, texts, colors, and fonts of the areas we want to personalize.

Their values can be overridden programmatically by style.setProperty() and the related styles change accordingly, in run-time.

Our application will need a configuration to save and restore these values on page load. CSS variables are supported by all evergreen browsers. We might be able to style the favicon and support different themes too.

Requirements

Requirements

1. Wazuh dashboard - login: Logo, title, and subtitle
2. Wazuh dashboard - plugin: Drop-down icon
3. Wazuh dashboard - plugin - reports: Icon
4. Wazuh dashboard - plugin - reports: Contact info
5. Wazuh dashboard - plugin - reports: Copyright
6. Wazuh dashboard - browser tab: Title

The items above translate to the following tasks:

Prepare the app for white-labeling

• [ ] #4443
• [ ] #4446
• [ ] #4450

Include white-labeling support to the app These issues depend on the issues above.

• [ ] Custom branding-- login page @wazuh/cicd is currently the owner of this section (platform). We need to design a way to customize this from our UI. If we need @wazuh/cicd to make changes, we will open the correspondent issues.
• [ ] #3491 & #4434
• [ ] #4426
• [ ] #4506
• [ ] Custom branding-- page title and favicon Partially possible using variables from the platform. To be studied.

Bug fixes

• [x] #4538

Additional changes (potential requirements)

Global changes

• The plugin name (wazuh) is shown in the platform navigation drawer.
• The plugin name is used to build the URL.
• The index patterns (wazuh-alerts-*, wazuh-monitoring-*, wazuh-statistics-*)
• Programmatic navigation and redirects to /app/wazuh.
• Hard-coded wazuh … in the error messages shown by the App.
• The UI colors (light and dark themes)(background, accent)
• The fonts.

1st iteration

We'll focus on adapting the app to support white-labeling on a first iteration. This means, we'll provide mechanisms to upload and change the logos and text the app use as branding.

The changes related to the platform might stay out of this iteration, as we already use the built-in OpenSearch Dashboard custom branding settings for Wazuh. We need to find a way to enable / disable custom branding easily, resulting in no conflicts with the official branding.

[Desvelao]

Customize the Wazuh dashboard

Built-in customizations

Wazuh dashboard is based on OpenSearch Dashboards, which supports customization through its settings:

• OpenSearch Dashboards custom branding
• OpenSearch Dashboards security plugin settings

Settings

Section	Setting
Browser tab title	opensearchDashboards.branding.applicationTitle
Favicon	opensearchDashboards.branding.faviconUrl
Branding mark	opensearchDashboards.branding.mark.defaultUrl
Branding mark (dark)	opensearchDashboards.branding.mark.darkModeUrl
Branding logo	opensearchDashboards.branding.logo.defaultUrl
Branding logo (dark)	opensearchDashboards.branding.logo.darkModeUrl
Branding loading	opensearchDashboards.branding.loadingLogo.defaultUrl
Branding loading (dark)	opensearchDashboards.branding.loadingLogo.darkModeUrl
Login logo	opensearch_security.basicauth.login.brandimage
Login title	opensearch_security.basicauth.login.title
Login subtitle	opensearch_security.basicauth.login.subtitle

Examples

These settings are working in Wazuh dashboard based on OpenSearch Dashboards 1.2.0.

Browser tab title and favicon

Login logo, title and subtitle

Loading logo

Limitations

Any changes made to the platform setting must be agreed with the @wazuh/cicd, as they are in charge of building the default settings for Wazuh Dashboard (packaging). These settings cannot be changed from the UI, but from the configuration file.

We need to discuss this in depth, and open issues to the @wazuh/cicd, so they make the required changes.

[Desvelao]

Customize the Wazuh plugin

Currently, the Wazuh plugin only supports some logo customizations.

Identify the brand references

• :heavy_check_mark: plugin menu logo
• :heavy_check_mark: plugin health check logo
• :heavy_check_mark: plugin category logo (sidebar plugin platform menu)
• :heavy_check_mark: module PDF reports logo (sidebar plugin platform menu)
• Plugin
  • name
  • id ( URL: /app/<plugin_id>, redirections)
• Plugin category
  • name
  • id
• Reports
  • Header. Default: Wazuh contact info
  • Footer. Default: Wazuh copyright
• References to products: API, agents, manager/server, plugin platform
• Index patterns
• Templates
• Colors: UI and reports

Legend :heavy_check_mark: currently supported

Approach

• Add new settings to define new customizations
• Remove some unnecessary brand references replacing them with generic terms.

Enhancements

• Let the user uploads the logo assets. With this change, we should remove the possibility to define the path where the assets are exposed. This is a breaking change. :exclamation:

[Desvelao]

In order to simplify the additions of new settings, we'll work on the settings handling section of the app. This work will be tracked in this new issue: #4443

[Desvelao]

In order to minimize the number of requests required to customize the plugin, the endpoint for such functionality will be modified to support several changes at once, with a single request.

This refactor will be tracked in this new issue: #4450

[AlexRuiz7]

Integration process for the first iteration

• https://github.com/wazuh/wazuh-kibana-app/issues/4443
• https://github.com/wazuh/wazuh-kibana-app/issues/4450
  • Resolved by #4501
• https://github.com/wazuh/wazuh-kibana-app/issues/4446
  • Resolved by:
    • #4503
    • #4785

These pull requests will be reviewed separately, but tested together as a unit into an integration branch. These pull request prepare the app for the white-labeling functionalities. We have named these 2 pull requests the core.

• https://github.com/wazuh/wazuh-kibana-app/issues/4434
  • Resolved by https://github.com/wazuh/wazuh-kibana-app/pull/4504
• https://github.com/wazuh/wazuh-kibana-app/issues/4426
  • Resolved by https://github.com/wazuh/wazuh-kibana-app/pull/4505
• https://github.com/wazuh/wazuh-kibana-app/issues/4506
  • Resolved by https://github.com/wazuh/wazuh-kibana-app/pull/4507

After that, the white-labeling specific pull requests will be reviewed, integrated and tested one by one into the integration branch. On each iteration, only the test cases from the integrated pull request will be executed. A full regression will be executed when everything is integrated, in order to verify that there are no bugs due to the integration.

The QA flow, the pull requests dependencies and their order, have been graphically represented in the diagram below.

[AlexRuiz7]

First iteration is done

We'll open new epics (issues) for the next ones.

[ilyesm]

Hello!

Any feedback regarding the future iterations of white-labeling, regarding hard coded error messages, index patterns, fonts, colours, etc?

Thanks!

[AlexRuiz7]

Hello @ilyesm

We have a 2nd iteration currently in the backlog.

[ilyesm]

Hello @ilyesm

We have a 2nd iteration currently in the backlog.

Thanks, subscribed to that issue. Looking forward.