Legacy
- The master branch has the latest -not yet released- changes. It's not necessarily broken but you have no warranty about it.
- Numbered branches such 4.4 are compatible with Wazuh dashboard and have the last patch version released.
- Numbered branches such 4.4-7.10 are compatible with Kibana (7.10.x) and have the last patch version released.
- Numbered branches such 4.4-7.16 are compatible with Kibana (7.16.x and 7.17.x) and have the last patch version released.
- Numbered branches such
4.4.5are development branches for Wazuh dashboard. They are removed when the related tag is created and the version is released. - Numbered branches such
4.4.5-7.10are development branches for Kibana 7.10.x. They are removed when the related tag is created and the version is released. - Numbered branches such
4.4.5-7.16are development branches for Kibana 7.16.x and 7.17.x. They are removed when the related tag is created and the version is released.
Legacy:
- The stable branch has the latest stable changes. It also has the same code as the latest released package.
- Branches with the suffix
-wzdare for the Wazuh dashboard such as 4.3-1.2-wzd. For 4.3-1.2-wzd, 4.3 is the Wazuh version (4.3.x) and 1.2 is the OpenSearch Dashboards version (1.2.x) that is based on the Wazuh dashboard. - Numbered branches such 3.7-6.5, 3.7-6.4... are usually stable branches but you have no warranty about them. For 3.7-6.5, 3.7 is the Wazuh version (3.7.x) and 6.5 is the Kibana version (6.5.x)
- All our tags such as v3.7.0-6.5.1 are stable if they are used with the right versions (Wazuh, Elastic). Each tag provides the code for all our packages, this means that our tag v3.7.0-6.5.1 has the same code as our package for Wazuh 3.7.0 and Kibana 6.5.1.
- Tags are frozen, so it's possible that an old tag has known bugs that are fixed in newer tags.
systemctl stop kibana
sudo -u kibana NODE_OPTIONS="--max-old-space-size=3072" /usr/share/kibana/bin/kibana-plugin install https://packages.wazuh.com/wazuhapp/wazuhapp-<WAZUH_VERSION>_<ELASTIC_VERSION>.zip
systemctl restart kibanasystemctl stop kibana
sudo -u kibana NODE_OPTIONS="--max-old-space-size=3072" /usr/share/kibana/bin/kibana-plugin install file:///path/app.zip
systemctl restart kibanasystemctl stop kibana
sudo -u kibana /usr/share/kibana/bin/kibana-plugin remove wazuh
systemctl restart kibanasystemctl stop kibana
sudo -u kibana /usr/share/kibana/bin/kibana-plugin remove wazuh
rm -rf /usr/share/kibana/optimize/bundles
# for kibana <= 7.9
chown -R kibana:kibana /usr/share/kibana/optimize
chown -R kibana:kibana /usr/share/kibana/plugins
########
# for kibana >= 7.10
chown -R kibana:kibana /usr/share/kibana/data
########
sudo -u kibana NODE_OPTIONS="--max-old-space-size=3072" /usr/share/kibana/bin/kibana-plugin install https://packages.wazuh.com/wazuhapp/wazuhapp-<WAZUH_VERSION>_<ELASTIC_VERSION>.zip
systemctl restart kibanacd /home/vagrant
wget https://snapshots.elastic.co/downloads/logstash/logstash-<VERSION>-SNAPSHOT.tar.gz
tar -xvf logstash-<VERSION>-SNAPSHOT.tar.gz
rm -f logstash-<VERSION>-SNAPSHOT.tar.gz
mv logstash-<VERSION>-SNAPSHOT logstash
mkdir ./config/conf.d
Copy 01-wazuh.conf to /home/vagrant/logstash/config/conf.d/01-wazuh.conf
Edit /home/vagrant/logstash/config/pipelines.yml as follow:
- pipeline.id: main
path.config: "/home/vagrant/logstash/config/conf.d/*.conf"
Run:
./bin/logstash --path.settings /home/vagrant/logstash/config
cd /home/vagrant
wget https://snapshots.elastic.co/downloads/beats/filebeat/filebeat-<VERSION>-SNAPSHOT-linux-x86_64.tar.gz
tar -xvf filebeat-<VERSION>-SNAPSHOT-linux-x86_64.tar.gz
rm -f filebeat-<VERSION>-SNAPSHOT-linux-x86_64.tar.gz
mv filebeat-<VERSION>-SNAPSHOT-linux-x86_64 filebeat
Edit configuration /home/vagrant/filebeat/filebeat.yml to fit our requirements.
Run:
./filebeat -c /home/vagrant/filebeat/filebeat.yml
Note: Change permissions for /var/ossec/logs/alerts/alerts.json for the user vagrant (the user you are using).
Node.js, Yarn required.
git clone https://github.com/elastic/kibana -b <BRANCH> --single-branch --depth=1
cd kibana
yarn kbn bootstrap
yarn start --oss --no-base-path --server.host="0.0.0.0"
After setting up Kibana, just move to the Kibana directory and launch the proper script.
cd kibana
yarn es snapshot -E path.data=../data/
Next snippet will set wazuh-alerts-3.x-* as the default index pattern for Kibana.
default_index="/tmp/default_index.json"
cat > ${default_index} << EOF
{
"changes": {
"defaultIndex": "wazuh-alerts-3.x-*"
}
}
EOF
curl -POST "http://localhost:5601/api/kibana/settings" -H "Content-Type: application/json" -H "kbn-xsrf: true" -d@${default_index}
rm -f ${default_index}Feel free to change it on your own.
To build the Wazuh plugin for the Kibana 7.10 or higher platform you will need to have installed Kibana dev, please follow this article in case you don't have Kibana dev installed yet.
After you have already mounted Kibana dev (with bootstrap) and the corresponding NodeJs and Yarn version installed follow these steps:
- Move to the Wazuh plguin folder
cd <kibana-path>/kibana/plugins/wazuh - Run the build script
yarn build - Put the Kibana version target i.e.
7.10.2
If the above commands were fine, you should have your package under build/<name>.zip.
Wazuh app 4.1.5 and 4.2.0 are compatible with Kibana 7.11.2, but there is an exception to build this combination of versions.
There is an issue when Wazuh app 4.1.5 or 4.2.0 is built for Kibana 7.11.2 using Kibana dev 7.11.2. There are some incompatibility interfaces, so the Wazuh app stops working after the health check. The workaround is to build the Wazuh app 4.1.5 or 4.2.0 for Kibana 7.11.2 but using Kibana dev 7.10.2. In this way, the app works properly.
If you have Node.js installed but a different version, just use n as version manager:
# npm install -g n
# n 8.14.1
If the command node -v shows you a different version please force to use recently installed version:
# mv /usr/local/bin/node /usr/bin
# mv /usr/local/bin/npm /usr/bin
# mv /usr/local/bin/npx /usr/bin
We need this Node.js package manager in order to make it work properly:
# npm install -g [email protected]
Check your version using yarn -v
$ git clone https://github.com/wazuh/wazuh-dashboard-plugins -b <TAG> --single-branch --depth=1 app
$ cd app
$ yarn
$ yarn build
If the above commands were fine, you should have your package under build/<name>.zip.
Kibana has a method to run e2e tests from its plugins, running a special service of Kibana and Elasticsearch.
This environment uses an Elasticsearch snapshot in the port 9220 and exposes Kibana in the port 5620 of the localhost.
- Chromium
- A branch with folder
./test/functional
In this example, we use a centos 7 server with version 7.2 of Elasticsearch and Kibana for use a Wazuh manager with version 3.9.3.
Install Wazuh manager Install Elastic Stack
For install Google-Chrome in centos we use these commands:
cat > /etc/yum.repos.d/google-chrome.repo << EOF
[google-chrome]
name=google-chrome
baseurl=http://dl.google.com/linux/chrome/rpm/stable/x86_64
enabled=1
gpgcheck=1
gpgkey=https://dl.google.com/linux/linux_signing_key.pub
EOF
yum install -y google-chrome-stableTo run the tests, an instance of Kibana and Elasticsearch is required. We recommend using a non-production server because the tests make changes to the configuration of Kibana.
The first step is to configure the environment to specify the addresses and credentials of Kibana and Elasticsearch:
# Specify the address and credentials of Kibana
export TEST_KIBANA_URL=https://kibana:[email protected]:443
# Specify the address and credentials of Elasticsearch
export TEST_ES_URL=https://elastic:[email protected]:9200The last step is to navigate to the Wazuh application and run the tests.
# Navigate to Wazuh-app path
cd /[path]/[to]/kibana/plugins/wazuh
# Run the tests
yarn test:ui:runner
More info in the Kibana documentation: Delevelopment functional tests
To write the tests we rely on the official documentation of Kibana:
- https://www.elastic.co/guide/en/kibana/7.2/development-functional-tests.html
- https://www.elastic.co/guide/en/kibana/7.2/development-plugin-functional-tests.html
The folder ./test/functional has this structure:
functional/
├── apps
├── es_archives
├── page_objects
├── services
└── config.jsTo explained how to write tests we use an example, this example is the welcome manager view should have 'Ruleset' link.
The first step is to locate if the environment has any test for the `Management' view, in this case, it has no test. As we will add many tests in the future to verify other behaviors in the 'Management' view, we create this structure:
functional/
└──apps
└── management
├── _welcome.js
└── index.jsThe index file is used as an entry point to define the status of the environment before and after to execute the tests.
export default function ({ getService, loadTestFile }) {
const browser = getService('browser');
describe('Overview ', () => {
before(async () => {
await browser.setWindowSize(1200, 800);
});
loadTestFile(require.resolve('./_welcome')); // Load the _welcome tests
});
}In the before function, we set the browser size to 1200x800px and then load them from the _welcome.js file.
The tests in the _welcome.js file may have a function before more to define some special state in the environment. This is possible by the test structure:
-
describe ('message', () => {* code *}: thedescribefunction contains the test set of a use case. Within this function, you can insert the functionsbefore,afterandit -
before (() => {* code *}): contains the instruction to configure the environment required to run the tests. All the code within this function is executed before the tests. -
after (() => {* code *}): same as thebeforefunction but the code is executed after the tests. -
it ('message', () => {* code *}): eachitfunction is a test, it can contain one or moreexpectfunctions. Theexpectfunction is the responsible for comparing the result of the code execution with the expected result.
This is the code of the _welcome.js file:
import expect from '@kbn/expect';
export default function({ getService, getPageObjects }) {
const PageObjects = getPageObjects([ 'common' ]);
const testSubjects = getService('testSubjects');
const find = getService('find');
describe('welcome', () => {
before(async function () {
await PageObjects.common.navigateToApp('wazuh');
await PageObjects.common.waitUntilUrlIncludes('tab=welcome');
await testSubjects.click('wzMenuManagement');
});
it('should have `Ruleset` link', async () => {
const RulesetSelector = '#kibana-body > div > div > div > div.application.ng-scope.tab-manager > div > div.ng-scope.layout-align-start-stretch.layout-column > div > react-component > div > div > div:nth-child(1) > div > div:nth-child(3) > div:nth-child(1) > button'
const RulesetButton = await find.byCssSelector(RulesetSelector);
expect(await RulesetButton.getVisibleText()).to.contain('Ruleset');
});
});
}Finally, add the tests to the testFiles property of the config.js file in the root of the functional folder.
// Some code...
return {
testFiles: [
require.resolve('./apps/wazuh'),
require.resolve('./apps/api'),
require.resolve('./apps/health_check'),
require.resolve('./apps/overview'),
require.resolve('./apps/management'), // The new tests
],
// The rest of the code...At this moment the tests are ready to execute.
cd [/path/to/]kibana/plugins/wazuh
yarn test:ui:server
# When the server is ready
yarn test:ui:runnerStop Logstash:
systemctl stop logstash
Ensure the template is inserted:
curl https://raw.githubusercontent.com/wazuh/wazuh/3.9/extensions/elasticsearch/wazuh-elastic6-template-alerts.json | curl -XPUT 'http://elastic_ip:9200/_template/wazuh' -H 'Content-Type: application/json' -d @-
Check if the template was inserted:
curl elastic:9200/_cat/templates/wazuh
You should see:
wazuh [wazuh-alerts-3.x-*] 0
Assuming the only one affected index is wazuh-alerts-3.x-2019.01.29 (repeat this procedure if you have more affected indices):
- Reindex affected index into a backup index:
curl -X POST "elastic_ip:9200/_reindex" -H 'Content-Type: application/json' -d'
{
"source": {
"index": "wazuh-alerts-3.x-2019.01.29"
},
"dest": {
"index": "wazuh-alerts-3.x-backup"
}
}
'
- Remove affected index:
curl -XDELETE elastic_ip:9200/wazuh-alerts-3.x-2019.01.29
- Reindex backup index into a new index (using same name as before):
curl -X POST "elastic_ip:9200/_reindex" -H 'Content-Type: application/json' -d'
{
"source": {
"index": "wazuh-alerts-3.x-backup"
},
"dest": {
"index": "wazuh-alerts-3.x-2019.01.29"
}
}
'
- Remove backup index:
curl -XDELETE elastic_ip:9200/wazuh-alerts-3.x-backup
systemctl restart logstash
Stop Logstash:
systemctl stop logstash
Ensure the template is inserted:
curl https://raw.githubusercontent.com/wazuh/wazuh/3.9/extensions/elasticsearch/wazuh-elastic6-template-alerts.json | curl -XPUT 'http://elastic_ip:9200/_template/wazuh' -H 'Content-Type: application/json' -d @-
Check if the template was inserted:
curl elastic:9200/_cat/templates/wazuh
You should see:
wazuh [wazuh-alerts-3.x-*] 0
Assuming the only one affected index is wazuh-alerts-3.x-2019.01.29 (repeat this procedure if you have more affected indices):
- Reindex affected index into a backup index:
curl -X POST "elastic_ip:9200/_reindex" -H 'Content-Type: application/json' -d'
{
"source": {
"index": "wazuh-alerts-3.x-2019.01.29"
},
"dest": {
"index": "wazuh-alerts-3.x-backup"
}
}
'
- Remove affected index:
curl -XDELETE elastic_ip:9200/wazuh-alerts-3.x-2019.01.29
- Reindex backup index into a new index (using same name as before):
curl -X POST "elastic_ip:9200/_reindex" -H 'Content-Type: application/json' -d'
{
"source": {
"index": "wazuh-alerts-3.x-backup"
},
"dest": {
"index": "wazuh-alerts-3.x-2019.01.29"
}
}
'
- Remove backup index:
curl -XDELETE elastic_ip:9200/wazuh-alerts-3.x-backup
systemctl restart logstash
The latest versions of the Wazuh plugin can be developed through a development environment based on Docker containers.
First of all, you need a working environment composed at least by the next components:
- 1 x Wazuh manager
- 1 x Wazuh API
- 1 x Filebeat
- 1 x Elasticsearch
Once you have the whole environment working you'll need also the next tools:
- nvm
- git
Clone the repository in one of two ways:
- Clone the entire repository:
git clone https://github.com/elastic/kibana - Clone a single branch of the repository:
git clone --single-branch --depth 1 -b v <KIBANA_VERSION> https://github.com/elastic/kibanawhere<KIBANA_VERSION>is the version you want to install.
The above commands will create a folder called kibana in the current directory.
If you cloned the entire repository, you can move to the branch you want with:
git checkout <branch/tag>
where branch/tag is the branch or tag you want to move to. You can check the branches and tags available in the Kibana repository.
Depending on the version of Kibana in use, replace --git-common-dir with --git-dir:
- For Kibana <v7.9.0:
sed -i -e 's/-git-common-dir/-git-dir/' src/dev/register_git_hook/register_git_hook.js - For Kibana> v7.9.x:
sed -i -e 's/-git-common-dir/-git-dir/' packages/kbn-dev-utils/src/precommit_hook/get_git_dir.ts
The wazuh-registry.json file where the app stores some data about the configured hosts is found within the app files within Kibana. In development mode, any change in the app files causes Kibana to restart. Ignore the wazuh-registry.json located in the plugin/wazuh directory.
To do this, edit src/cli/cluster/cluster_manager.ts looking for:
const pluginInternalDirsIgnore = scanDirs
.map (scanDir => resolve (scanDir, '*'))
.concat (pluginPaths)
.reduces (
(acc, path) =>
acc.concat (
resolve (path, 'test'),
resolve (path, 'build'),
resolve (path, 'target'),
resolve (path, 'scripts'),
resolve (path, 'docs'),
Adding the following line at the end:
resolve ('<KIBANA_DEV_PATH> /plugins/wazuh/server/wazuh-registry.json')
Replacing <KIBANA_DEV_PATH> by the directory where the development Kibana folder is located.
It is necessary to install the version of NodeJS required by Kibana, for this, you can look at:
- package.json
- .nvmrc
To change the version of NodeJS, you can use one of the following methods:
-
Install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash -
Restart or open a new terminal session, you will have the nvm command available.
-
Install the NodeJS version:
nvm install <NODEJS_VERSION>where<NODEJS_VERSION>is the version of NodeJS you want to install.
Example:
nvm install 10.22.1
Install package n globally
sudo npm i -g n
Install the NodeJS version:
n <NODEJS_VERSION>
where <NODEJS_VERSION> is the version of NodeJS you want to install.
Example:
n 10.22.1
Install global version of yarn specified in package.json
sudo npm i -g yarn@<YARN_VERSION>
where <YARN_VERSION> is the version to install
Example:
sudo npm i -g [email protected]
At the root of the Kibana of development:
yarn kbn bootstrap
Clone the wazuh-dashboard-plugins repository as a submodule:
git submodule add -f https://github.com/wazuh/wazuh-dashboard-plugins /plugins/wazuh
Go to the cloned directory, and move to the app branch with:
git checkout <BRANCH/TAG>
In case you want to have the source code of the app outside of where you have Kibana, for example in a VM (virtual machine), you can synchronize the source code of the app with the app files within the directory tree of the Kibana of growth. It needs to be synchronized with the plugins/wazuh directory. For this you can use rsync or text editor plugins like sftp. This is useful if you want to have separate where the development Kibana and your source code are.
git clone https://github.com/wazuh/wazuh-dashboard-plugins -b <BRANCH>
cd wazuh-dashboard-plugins
// Make some changes
rsync -avh ./ user@kibana_ip:/kibana-path/plugins/wazuh --exclude=.git --exclude=node_modules --delete
If you are using private SSH keys, add this to your rsync command:
-e "ssh -i /path/private_key"
If you installed the Kibana dependencies before including the Wazuh plugin code, you can install the plugin dependencies by changing the version to the version specified in the package.json in the node_build field. Install the dependencies of the app with the following command being at the root of the Wazuh plugin
yarn
echo fs.inotify.max_user_watches = 524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
- Set the NodeJS version to the one Kibana requires using nvm or n. Settings preferences when starting the development Kibana:
- CLI
- Kibana.dev.yml configuration file
- Kibana.yml configuration file
- CLI Configurations can be added in the Kibana startup command of the type:
--SETTING.NAME = "VALUE"
- Creating
kibana.dev.ymlandkibana.yml
Create a file in <KIBANA_DEV_PATH>/config/kibana.dev.yml and specify the Kibana configuration settings
If you are using a basic Elascticsearch environment without security you can use the following command to start Kibana dev:
yarn start --oss --no-base-path --server.host = \ "0.0.0.0 \" --elasticsearch.hosts = \ "[http / s]: // <ELASTICSEARCH_HOST>: 9200 \"
where
-
[http/s]: protocol where Elasticsearch http or https is served -
<ELASTICSEARCH_HOST>is the Elasticsearch host address -
--ossfor Elasticsearch without security or with Open Distro for Elasticsearch. If you use X-Pack remove this flag from the command. You can add the development configuration in the file <KIBANA_DEV_PATH>/config/kibana.yml or <KIBANA_DEV_PATH>/config/kibana.dev.yml in the Kibana development directory. The second takes precedence.
Now you have Kibana properly configured, let's start it without the Wazuh app:
yarn start --no-base-path --server.host="0.0.0.0" --elasticsearch.url="http://elastic" --no-watch
Press ctrl + c to exit.
The client-side changes should be reflected without any reload from Kibana (press ctrl + F5 in your browser). The server-side changes will fire a server reload, so it could take a bit more to be reflected.