Building the Plugins

Build Wazuh Dashboard Plugins from source for development or distribution

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

Build Types

There are two primary build workflows:

1. Plugin-only builds - Build individual plugins as ZIP files for development
2. 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:

1. Builds the base Wazuh Dashboard
2. Builds all plugin dependencies
3. Packages everything into distributable system packages

Key steps:

1. Clone and build wazuh-dashboard
2. Clone and build wazuh-security-dashboards-plugin
3. Clone and build wazuh-dashboard-plugins
4. Clone and build wazuh-dashboard-reporting
5. Clone and build wazuh-dashboard-security-analytics
6. Create ZIP packages
7. 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:

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

Docker Build Issues

If building inside Docker fails:

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

Next Steps

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