Skip to content

Commit c641a1f

Browse files
jackhodgkissjackhodgkiss
committed
feat: add a more concise admin guide for wazuh
1 parent e5aa7e8 commit c641a1f

File tree

2 files changed

+45
-131
lines changed

2 files changed

+45
-131
lines changed

‎source/include/wazuh_ansible.rst‎

Lines changed: 42 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -1,154 +1,65 @@
1-
One of method for deploying Wazuh is with the use of the official Ansible playbooks, integrated into a Kayobe Config.
1+
One of methods for deploying and maintaining Wazuh is with the use of the official Ansible playbooks, integrated into a Kayobe Config.
22

3-
Hosts & Groups
4-
--------------
5-
To begin the deployment of Wazuh we must first configure our hosts and groups definitions.
6-
7-
Firstly, we can edit the groups under ``etc/kayobe/inventory/groups`` to define the related Wazuh groups.
8-
9-
.. code-block:: ini
10-
11-
[infra-vms:children]
12-
wazuh-master
13-
14-
[wazuh:children]
15-
wazuh-master
16-
wazuh-agent
17-
18-
[wazuh-master]
19-
20-
[wazuh-agent]
21-
22-
[wazuh-agent:children]
23-
24-
Secondly, we can edit the hosts file found ``etc/kayobe/inventory/hosts`` to associate membership between hosts and groups.
25-
26-
.. code-block:: ini
27-
28-
[wazuh-master]
29-
wazuh-master-01
3+
Configuring Wazuh Manager
4+
-------------------------
305

31-
[wazuh-agent]
6+
Wazuh manager can easily be configured by editing the ``wazuh-manager.yml`` groups vars file found at ``etc/kayobe/inventory/group_vars/wazuh-master/``.
7+
This file gives you control over various important aspects of the Wazuh manager.
8+
Most notably;
329

10+
*domain_name*:
11+
the domain used by Search Guard CE when generating certificates.
3312

34-
Provision infra-vm & install roles
35-
----------------------------------
13+
*wazuh_manager_ip*:
14+
the IP address that the wazuh manager shall reside on for communicating with the agents.
3615

37-
With the hosts and groups files created we can begin to provision the infra-vm as well install the Wazuh Ansible role.
16+
*wazuh_manager_connection*:
17+
used to define port and protocol for the manager to be listening on.
3818

39-
To provision the infra-vm we can use the kayobe command ``kayobe infra vm provision``.
40-
Once completed we can then install the Wazuh Ansible role we can be achieved by adding the role definition to the ``etc/kayobe/ansible/requirements.yml``.
19+
*wazuh_manager_authd*:
20+
connection settings for the daemon responsible for registering new agents.
4121

42-
.. code-block:: yaml
22+
Running ``kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/wazuh-manager.yml`` will deploy these changes.
4323

24+
Secrets
25+
-------
4426

45-
roles:
46-
- src: https://github.com/stackhpc/wazuh-ansible.git
47-
version: v4.2.3-opendistro-ubuntu
27+
Wazuh requires that secrets or passwords are set for itself and the services it communiticates with.
28+
The playbook ``etc/kayobe/ansible/wazuh-secrets.yml`` automates the creation of these secrets which can then be encrypted with Ansible Vault.
4829

49-
Once added we can then perform a ``kayobe control host bootstrap`` which shall install this role and any other missing roles.
30+
To update the secrets you can execute the following two commands
5031

51-
Configuring Wazuh Manager
52-
-------------------------
32+
.. code-block:: console
33+
:substitutions:
5334
54-
We are almost ready to deploy Wazuh manager.
55-
However, before we can, we must first download the Wazuh manager playbook which can be done by downloading ``https://raw.githubusercontent.com/stackhpc/kayobe-ops/master/wazuh-manager.yml`` into ``etc/kayobe/ansible/wazuh-manager.yml``.
56-
Once downloaded it is recommended you make any changes your deployment/environment requires.
35+
kayobe# kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/wazuh-secrets.yml -e wazuh_user_pass=$(uuidgen) -e wazuh_admin_pass=$(uuidgen)
36+
kayobe# ansible-vault encrypt --vault-password-file |vault_password_file_path| $KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh-master/wazuh-secrets.yml
5737
58-
Next we must create the group varibles for the `wazuh-master` group.
59-
This can be easily accomplished by first creating a directory ``etc/kayobe/inventory/group_vars/wazuh-master/`` which is where we shall download the next two files to.
38+
Once generated you can run ``kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/wazuh-manager.yml`` which shall copy the secrets into place.
6039

61-
``https://raw.githubusercontent.com/stackhpc/kayobe-ops/master/vars/elasticsearch-custom.yml``
40+
.. note:: If you need to view the secrets it is recommended you use ``ansible-vault view --vault-password-file ~/vault.password``
6241

63-
``https://raw.githubusercontent.com/stackhpc/kayobe-ops/master/vars/wazuh-manager.yml``
42+
Adding a New Agent
43+
------------------
44+
When adding a new host it should be automically picked up by the ``wazuh-agent:children`` group in ``etc/kayobe/inventory/groups`` as it would be included in the ``overcloud`` member.
6445

65-
Feel free to modify any of the varibles within these files.
66-
It is expected that you would want to edit the following varibles:
46+
.. code-block:: ini
6747
68-
* domain_name
48+
[wazuh-agent:children]
49+
seed
50+
overcloud
6951
70-
* wazuh_manager_ip
52+
Running the follow playbook ``kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/wazuh-agent.yml`` will deploy the agent to the new host.
53+
This should automatically be registered and accessible within the Wazuh manager dashboard.
7154

72-
Secrets
73-
-------
55+
The playbook ``wazuh-agent.yml`` can be setup as a hook within kayobe, which will automatically run either pre or post a given kayobe command.
56+
See `here <https://docs.openstack.org/kayobe/wallaby/custom-ansible-playbooks.html#hooks>`_ for more details.
7457

75-
We must ensure that Wazuh has access to a set secrets for all of the services it interacts with.
76-
To automate this process we can use an Ansible playbook and template.
77-
78-
First create a playbook called ``etc/kayobe/ansible/wazuh-secrets.yml`` and add the following contents to it.
79-
80-
.. code-block:: yaml
81-
82-
---
83-
- hosts: localhost
84-
gather_facts: false
85-
vars:
86-
wazuh_secrets_path: "{{ kayobe_env_config_path }}/inventory/group_vars/wazuh/wazuh-secrets.yml"
87-
tasks:
88-
- name: install passlib[bcrypt]
89-
pip:
90-
name: passlib[bcrypt]
91-
virtualenv: "{{ ansible_playbook_python | dirname | dirname }}"
92-
93-
- name: Include existing secrets if they exist
94-
include_vars: "{{ wazuh_secrets_path }}"
95-
ignore_errors: true
96-
97-
- name: Ensure secrets directory exists
98-
file:
99-
path: "{{ wazuh_secrets_path | dirname }}"
100-
state: directory
101-
102-
- name: Template new secrets
103-
template:
104-
src: wazuh-secrets.yml.j2
105-
dest: "{{ wazuh_secrets_path }}"
106-
107-
Then proceed to create a template in ``etc/kayobe/templates/wazuh-secrets.yml.j2`` with the following contents.
108-
109-
.. code-block:: jinja
110-
111-
---
112-
{% set wazuh_admin_pass = secrets_wazuh.wazuh_admin_pass | default(lookup('password', '/dev/null'), true) -%}
113-
{%- set wazuh_user_pass = secrets_wazuh.wazuh_user_pass | default(lookup('password', '/dev/null'), true) -%}
114-
115-
# Secrets used by Wazuh managers and agents
116-
# Store these securely and use lookups here
117-
secrets_wazuh:
118-
# Wazuh agent authd pass
119-
authd_pass: "{{ secrets_wazuh.authd_pass | default(lookup('password', '/dev/null'), true) }}"
120-
# Strengthen default wazuh api user pass
121-
wazuh_api_users:
122-
- username: "wazuh"
123-
password: "{{ secrets_wazuh.wazuh_api_users[0].password | default(lookup('password', '/dev/null length=30' ), true) }}"
124-
# Elasticsearch 'admin' user pass
125-
opendistro_admin_password: "{{ secrets_wazuh.opendistro_admin_password | default(lookup('password', '/dev/null'), true) }}"
126-
# Elasticsearch 'kibanaserver' user pass
127-
opendistro_kibana_password: "{{ secrets_wazuh.opendistro_kibana_password | default(lookup('password', '/dev/null'), true) }}"
128-
# Wazuh/Kibana 'wazuh_admin' custom user pass
129-
wazuh_admin_pass: "{{ wazuh_admin_pass }}"
130-
# Wazuh/Kibana 'wazuh_admin' custom user pass has
131-
# bcrypt ($2y) hash
132-
wazuh_admin_hash: "{{ secrets_wazuh.wazuh_admin_hash | default(wazuh_admin_pass | password_hash('bcrypt'), true) }}"
133-
# Wazuh/Kibana 'wazuh_user' custom user pass
134-
# bcrypt ($2y) hash
135-
wazuh_user_pass: "{{ wazuh_user_pass }}"
136-
wazuh_user_hash: "{{ secrets_wazuh.wazuh_user_hash | default(wazuh_user_pass | password_hash('bcrypt'), true) }}"
137-
138-
And finally, run the following commands to generate and encrypt the secrets.
139-
140-
.. code-block:: bash
141-
142-
kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/wazuh-secrets.yml -e wazuh_user_pass=$(uuidgen) -e wazuh_admin_pass=$(uuidgen)
143-
ansible-vault encrypt --vault-password-file ~/vault.pass $KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh-master/wazuh-secrets.yml
144-
145-
.. note:: you must have a vault password store outside the source control directory in a file called `vault.pass`
146-
147-
Deploying Wazuh Manager
58+
Accessing Wazuh Manager
14859
-----------------------
14960

150-
It is now time to deploy Wazuh manager.
151-
This can be achieved with one simple command. ``kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/wazuh-manager.yml``
61+
To access the Wazuh manager dashboard, navigate to the ip address of the |wazuh_master_name| (|wazuh_master_url|).
62+
63+
You can login to the dashboard with the username ``admin`` and the password for ``opendistro_admin_password`` which can be found within ``etc/kayobe/inventory/group_vars/wazuh-master/wazuh-secrets.yml``.
15264

153-
Once the playbook is finished running you should be able to access the Wazuh manager from the ``wazuh-master-01`` ip address at ``5601`` over ``https``.
154-
You can login to the dashboard with the username ``admin`` and the password for ``opendistro_admin_password`` which can be found within ``etc/kayobe/inventory/group_vars/wazuh-master/wazuh-secrets.yml``.
65+
.. note:: If you need to view the secrets it is recommended you use ``ansible-vault view --vault-password-file ~/vault.password``

‎source/vars.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,3 +48,6 @@
4848
.. |tempest_recipes| replace:: https://github.com/acme-openstack/tempest-recipes.git
4949
.. |tls_setup| replace:: TLS is implemented using a wildcard certificate available for ``*.acme.example``.
5050
.. |vault_password_file_path| replace:: ~/vault-password
51+
.. |wazuh_master_url| replace:: https://|wazuh_master_ip|
52+
.. |wazuh_master_ip| replace:: 172.168.0.10:5601
53+
.. |wazuh_master_name| replace:: wazuh-master01

0 commit comments

Comments
 (0)