Building the Plugins

This guide explains how to build the Wazuh Dashboard Plugins from source code into distributable packages.

Build Types

There are two primary build workflows:

Plugin-only builds - Build individual plugins as ZIP files for development
System packages - Build complete DEB/RPM packages including the full dashboard distribution

Building Plugins from Source

This workflow builds only the plugins in this repository into distributable ZIP packages.

Prerequisites

Development environment configured (see Setup)
jq installed for reading plugin versions
Compatible Git reference from wazuh-indexer-plugins

Installing Dependencies

If dependencies are not already installed:

# Set GIT_REF to a compatible wazuh-indexer-plugins branch/tag
export GIT_REF=main

# Install dependencies for main plugin (downloads indexer resources)
cd plugins/main
GIT_REF=$GIT_REF yarn
cd ../..

# Install dependencies for other plugins
for plugin in plugins/wazuh-core plugins/wazuh-check-updates; do
  (cd "$plugin" && yarn)
done

The main plugin requires the GIT_REF environment variable during installation to download resources from the wazuh-indexer-plugins repository. Ensure the referenced branch or tag exists and is compatible with your plugin version.

External Resources

The main plugin downloads external resources during the yarn installation:

Indexer resources from wazuh-indexer-plugins repository
API specification files for endpoint generation

The postinstall script automatically executes:

yarn run generate:indexer-resources

Building Individual Plugins

Each plugin must be built with the OpenSearch Dashboards version declared in its package.json.

# Read the OpenSearch Dashboards version from package.json
OPENSEARCH_DASHBOARDS_VERSION=$(jq -r .pluginPlatform.version plugins/main/package.json)

# Build main plugin
cd plugins/main
OPENSEARCH_DASHBOARDS_VERSION=$OPENSEARCH_DASHBOARDS_VERSION yarn build
cd ../..

# Build wazuh-core plugin
cd plugins/wazuh-core
OPENSEARCH_DASHBOARDS_VERSION=$OPENSEARCH_DASHBOARDS_VERSION yarn build
cd ../..

# Build wazuh-check-updates plugin
cd plugins/wazuh-check-updates
OPENSEARCH_DASHBOARDS_VERSION=$OPENSEARCH_DASHBOARDS_VERSION yarn build
cd ../..

Build Artifacts

Build artifacts are written to each plugin’s build/ directory:

plugins/main/build/wazuh-<version>.zip
plugins/wazuh-core/build/wazuhCore-<version>.zip
plugins/wazuh-check-updates/build/wazuhCheckUpdates-<version>.zip

Building Inside Docker

The recommended workflow is to build inside the Docker development environment. This ensures:

Required OpenSearch Dashboards build helpers are available
Build matches the target platform
Consistent build environment across different machines

Start the development environment and execute build commands from within the container:

cd docker/osd-dev
./dev.sh up

Attach to the container:

docker ps
docker exec -it <CONTAINER_ID> bash

From inside the container, run the build commands as described above.

Running from Sources

The recommended method for running plugins during development is using the Docker-based development environments.

Starting the Development Environment

Navigate to the OpenSearch Dashboards development environment:

cd docker/osd-dev
./dev.sh up

The script automatically detects versions from plugins/wazuh-core/package.json and internal plugins from plugins/.

Specify Versions

To use specific OpenSearch and OpenSearch Dashboards versions:

./dev.sh up -os 2.11.0 -osd 2.11.0

Development with Agents

Include Wazuh agents in the environment:

# DEB-based agent
./dev.sh up --server-local my-tag -a deb

# RPM-based agent
./dev.sh up --server-local my-tag -a rpm

# Without agents
./dev.sh up --server-local my-tag -a without

SAML Environment

Enable SAML authentication:

./dev.sh up -saml

External Plugin Repositories

Mount external plugin repositories using the -r flag:

./dev.sh up -os 2.11.0 -osd 2.11.0 \
  -r wazuh-dashboard-reporting=$WZ_REPORTING \
  -r wazuh-security-dashboards-plugin=$WZ_SECURITY

Environment Components

The Docker environment includes:

OpenSearch single-node cluster - Indexer for Wazuh data
Wazuh manager - Real or local build depending on flags
OpenSearch Dashboards dev environment - Bootstrapped with pre-compiled node modules
Wazuh agents (optional) - Deployed based on -a flag
Imposter - Mock server for testing
Elasticsearch-exporter - Metrics adapter for Prometheus

Starting the Development Server

Attach a shell to the development container:

docker ps
docker exec -it <CONTAINER_ID> bash

From inside the container:

yarn start --no-base-path

The dashboard becomes available at:

URL: https://0.0.0.0:5601/
Default credentials: admin:admin
SAML credentials: wazuh:wazuh

Hot Reloading

The development server supports hot module reloading. Changes to plugin code are automatically detected and reloaded without restarting the server.

Package Scripts

The main plugin package.json includes several useful scripts:

Linting

yarn lint              # Lint all code
yarn lint:public       # Lint public (client) code
yarn lint:server       # Lint server code
yarn lint:common       # Lint common code
yarn lint:fix          # Auto-fix linting issues

Formatting

yarn format            # Format code with Prettier

Testing

yarn test:jest         # Run Jest unit tests
yarn test:server       # Run server tests
yarn test:browser      # Run browser tests

See Testing for detailed testing information.

Building

yarn build             # Build plugin (requires OPENSEARCH_DASHBOARDS_VERSION)

API Data Generation

yarn generate:api-data # Generate API endpoint data from spec

This script downloads the Wazuh API specification and generates:

common/api-info/endpoints.json - API endpoint definitions
common/api-info/security-actions.json - Security action definitions

Building System Packages

To build complete DEB or RPM system packages, see the detailed guide in the source repository at docs/dev/build-packages.md. This process:

Builds the base Wazuh Dashboard
Builds all plugin dependencies
Packages everything into distributable system packages

Key steps:

Clone and build wazuh-dashboard
Clone and build wazuh-security-dashboards-plugin
Clone and build wazuh-dashboard-plugins
Clone and build wazuh-dashboard-reporting
Clone and build wazuh-dashboard-security-analytics
Create ZIP packages
Run build-packages.sh script

Refer to ~/workspace/source/docs/dev/build-packages.md for the complete workflow.

Troubleshooting

Missing Dependencies

If build fails with missing dependencies:

cd plugins/<plugin-name>
yarn install

OpenSearch Dashboards Version Mismatch

Ensure the OPENSEARCH_DASHBOARDS_VERSION environment variable matches the version in package.json:

jq -r .pluginPlatform.version plugins/main/package.json

Indexer Resources Download Failure

If the main plugin fails to download indexer resources, verify:

GIT_REF environment variable is set
The referenced branch/tag exists in wazuh-indexer-plugins
Network connectivity to GitHub

Docker Build Issues

If building inside Docker fails:

Ensure sufficient resources allocated to Docker Desktop
Check Docker daemon is running
Verify networks exist: docker network ls

Next Steps

Run tests on the built plugins
Contribute improvements
Review source repository documentation

Get Started

Core Concepts

Security Modules

Compliance

Cloud Integrations

Agent Management

Configuration

Development

Build Types

Building Plugins from Source

Prerequisites

Installing Dependencies

External Resources

Building Individual Plugins

Build Artifacts

Building Inside Docker

Running from Sources

Starting the Development Environment

Specify Versions

Development with Agents

SAML Environment

External Plugin Repositories

Environment Components

Starting the Development Server

Hot Reloading

Package Scripts

Linting

Formatting

Testing

Building

API Data Generation

Building System Packages

Troubleshooting

Missing Dependencies

OpenSearch Dashboards Version Mismatch

Indexer Resources Download Failure

Docker Build Issues

Next Steps

​Build Types

​Building Plugins from Source

​Prerequisites

​Installing Dependencies

​External Resources

​Building Individual Plugins

​Build Artifacts

​Building Inside Docker

​Running from Sources

​Starting the Development Environment

​Specify Versions

​Development with Agents

​SAML Environment

​External Plugin Repositories

​Environment Components

​Starting the Development Server

​Hot Reloading

​Package Scripts

​Linting

​Formatting

​Testing

​Building

​API Data Generation

​Building System Packages

​Troubleshooting

​Missing Dependencies

​OpenSearch Dashboards Version Mismatch

​Indexer Resources Download Failure

​Docker Build Issues

​Next Steps

Build Types

Building Plugins from Source

Prerequisites

Installing Dependencies

External Resources

Building Individual Plugins

Build Artifacts

Building Inside Docker

Running from Sources

Starting the Development Environment

Specify Versions

Development with Agents

SAML Environment

External Plugin Repositories

Environment Components

Starting the Development Server

Hot Reloading

Package Scripts

Linting

Formatting

Testing

Building

API Data Generation

Building System Packages

Troubleshooting

Missing Dependencies

OpenSearch Dashboards Version Mismatch

Indexer Resources Download Failure

Docker Build Issues

Next Steps