Skip to content

Update wazuh.rst to better explain how to use TLS #1105

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: stackhpc/2023.1
Choose a base branch
from
Open

Update wazuh.rst to better explain how to use TLS #1105

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
028f639
Update wazuh.rst to better explain how to use TLS
MaxBed4d Jun 21, 2024
3f8b9c6
Update wazuh.rst
MaxBed4d Jul 22, 2024
a444a45
Update wazuh.rst to read better
MaxBed4d Nov 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 42 additions & 11 deletions doc/source/configuration/wazuh.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ The short version
``etc/kayobe/inventory/group_vars/wazuh-manager/wazuh-manager``, in
particular the defaults assume that the ``provision_oc_net`` network will be
used.
#. Ensure to export vault password: ``export KAYOBE_VAULT_PASSWORD={ansible_vault_password}``
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
#. Ensure to export vault password: ``export KAYOBE_VAULT_PASSWORD={ansible_vault_password}``
#. Export the Ansible vault password e.g. : ``export KAYOBE_VAULT_PASSWORD=$(cat path/to/vault/password/file)``

#. Generate secrets: ``kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/wazuh-secrets.yml``
#. Encrypt the secrets: ``ansible-vault encrypt --vault-password-file ~/vault.password $KAYOBE_CONFIG_PATH/environments/ci-multinode/wazuh-secrets.yml``
#. Deploy the Wazuh manager: ``kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/wazuh-manager.yml``
#. Deploy the Wazuh agents: ``kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/wazuh-agent.yml``

Expand Down Expand Up @@ -241,16 +241,17 @@ Wazuh secrets playbook is located in ``etc/kayobe/ansible/wazuh-secrets.yml``.
Running this playbook will generate and put pertinent security items into secrets
vault file which will be placed in ``$KAYOBE_CONFIG_PATH/wazuh-secrets.yml``.
If using environments it ends up in ``$KAYOBE_CONFIG_PATH/environments/<env_name>/wazuh-secrets.yml``
Remember to encrypt!
The secrets will be encrypted after templating and so requires that ``KAYOBE_VAULT_PASSWORD`` is set and exported before running the playbook!
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The secrets will be encrypted after templating and so requires that ``KAYOBE_VAULT_PASSWORD`` is set and exported before running the playbook!
The secrets will be encrypted after templating. Ensure that ``KAYOBE_VAULT_PASSWORD`` is set and exported before running the playbook!


Wazuh secrets template is located in ``etc/kayobe/ansible/templates/wazuh-secrets.yml.j2``.
It will be used by wazuh secrets playbook to generate wazuh secrets vault file.
It will be used by wazuh secrets playbook to generate wazuh secrets vault file, which will then be encrypted.


.. code-block:: console

kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/wazuh-secrets.yml
ansible-vault encrypt --vault-password-file ~/vault.pass $KAYOBE_CONFIG_PATH/wazuh-secrets.yml

To view ``wazuh-secrets.yml`` simply ``ansible-vault view --vault-password-file ~/vault.pass $KAYOBE_CONFIG_PATH/wazuh-secrets.yml``
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To view ``wazuh-secrets.yml`` simply ``ansible-vault view --vault-password-file ~/vault.pass $KAYOBE_CONFIG_PATH/wazuh-secrets.yml``
To view ``wazuh-secrets.yml``:
..code-block:: console
ansible-vault view --vault-password-file path/to/vault/password/file $KAYOBE_CONFIG_PATH/wazuh-secrets.yml


Configure Wazuh Dashboard's Server Host
---------------------------------------
Expand Down Expand Up @@ -303,9 +304,10 @@ does not exist, it will generate the following certificates in ``{{ kayobe_env_c
* root-ca.key root-ca.pem


It is also possible to use externally generated certificates for
wazuh-dashboard. Customise the ``dashboard_node_name`` variable so that you can
use a separate certificate and key for this service e.g:
It is also possible to use externally generated certificates for
wazuh-dashboard and wazuh-indexer. Customise the ``dashboard_node_name``
or ``indexer_node_name`` variable, respectively, so that you can use a
separate certificate and key for this service e.g:

.. code-block:: yaml
:caption: $KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh-manager/wazuh-manager
Expand All @@ -317,16 +319,45 @@ You will need to create two files matching the following pattern:
- ``{{ dashboard_node_name }}-key.pem`` for the private key
- ``{{ dashboard_node_name }}.pem`` for the certificate

Drop these files into ``$KAYOBE_CONFIG_PATH/environments/<environment>/wazuh/wazuh-certificates/`` if
using the kayobe environments feature, or ``$KAYOBE_CONFIG_PATH/wazuh/wazuh-certificates/`` if not.
The key for the external certificate should be in PKCS#8 format (in its header it may have BEGIN
In order to use externally generated certificates, you must first deploy Wazuh Ansible as normal in order to generate the base certificates.
This is because Wazuh will require to deploy with some sort of certificates, as well as, not every Wazuh service needing a custom external certificate;
for example the ``root`` and ``admin`` certificates. Therefore the ``<...>/wazuh/wazuh-certificates`` directory must be created and populated by ``wazuh-cert-tool.sh``, which it won't do if the ``<...>/wazuh/wazuh-certificates`` directory already exists.
Comment on lines +322 to +324
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While the existing text is correct, the "why" section makes it much more confusing.

Suggested change
In order to use externally generated certificates, you must first deploy Wazuh Ansible as normal in order to generate the base certificates.
This is because Wazuh will require to deploy with some sort of certificates, as well as, not every Wazuh service needing a custom external certificate;
for example the ``root`` and ``admin`` certificates. Therefore the ``<...>/wazuh/wazuh-certificates`` directory must be created and populated by ``wazuh-cert-tool.sh``, which it won't do if the ``<...>/wazuh/wazuh-certificates`` directory already exists.
To use externally generated certificates, you must first deploy Wazuh Ansible as normal to generate the base certificates. The custom certificates can then be added to this bundle.


Once the Wazuh generated certificates have been made, the desired custom external certificates need to be added in.
To do so, must ``SSH`` into the ``infra VM`` which Wazuh services have been deployed to and, with ``sudo`` privileges,
remove any of the 'base' certificates from ``/etc/wazuh-{dashboard | indexer}/certs/`` which are being replaced with custom ones.
After this, return to the ``seed`` VM and drop the custom new ``pem`` certificates into ``$KAYOBE_CONFIG_PATH/environments/<environment>/wazuh/wazuh-certificates/`` if using a kayobe environment, or ``$KAYOBE_CONFIG_PATH/wazuh/wazuh-certificates/`` if not.
Finally, rerun the Wazuh Ansible playbook and now the custom certificates should be copied over to their respective directories in the ``infra VM``.
Comment on lines +326 to +330
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some changes here to wording, just to make it a bit clearer and more generic (e.g. not all wazuh-managers are infra VMs)

Suggested change
Once the Wazuh generated certificates have been made, the desired custom external certificates need to be added in.
To do so, must ``SSH`` into the ``infra VM`` which Wazuh services have been deployed to and, with ``sudo`` privileges,
remove any of the 'base' certificates from ``/etc/wazuh-{dashboard | indexer}/certs/`` which are being replaced with custom ones.
After this, return to the ``seed`` VM and drop the custom new ``pem`` certificates into ``$KAYOBE_CONFIG_PATH/environments/<environment>/wazuh/wazuh-certificates/`` if using a kayobe environment, or ``$KAYOBE_CONFIG_PATH/wazuh/wazuh-certificates/`` if not.
Finally, rerun the Wazuh Ansible playbook and now the custom certificates should be copied over to their respective directories in the ``infra VM``.
Once the Wazuh generated certificates have been made, the custom external certificates need to be added in. To do so, ssh into the Wazuh Manager and remove any of the 'base' certificates from ``/etc/wazuh-{dashboard | indexer}/certs/`` which are being replaced with custom ones.
Return to the ``seed`` and drop the custom ``pem`` certificates into ``$KAYOBE_CONFIG_PATH/environments/<environment>/wazuh/wazuh-certificates/`` if using a kayobe environment, or ``$KAYOBE_CONFIG_PATH/wazuh/wazuh-certificates/`` if not.
Finally, rerun the Wazuh Ansible playbook to deploy the custom certificates.


Following this, the ``sudo systemctl status`` for the three Wazuh services should be checked to make sure they are up and running with no errors. Additionally, testing ``sudo filebeat test output`` and trying to ``curl`` the service's IP will also signify if the certificates are working correctly.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Following this, the ``sudo systemctl status`` for the three Wazuh services should be checked to make sure they are up and running with no errors. Additionally, testing ``sudo filebeat test output`` and trying to ``curl`` the service's IP will also signify if the certificates are working correctly.
Ensure the systemd units for the three Wazuh services are healthy. Additionally, testing ``sudo filebeat test output`` and trying to ``curl`` the service's IP will also signify if the certificates are working correctly.


It should also be noted that the key for the external certificate should be in PKCS#8 format (in its header it may have BEGIN
PRIVATE KEY instead of BEGIN RSA PRIVATE KEY or BEGIN OPENSSH PRIVATE KEY).

Example OpenSSL rune to convert to PKCS#8:

``openssl pkcs8 -topk8 -nocrypt -in wazuh.key -out wazuh.key.pkcs8``

TODO: document how to use a local certificate. Do we need to override all certificates?
.. note::

If you find that your Wazuh playbook isn't generating some of the non custom 'base' certificates,
such as the ``indexer`` or ``dashboard`` certificates, it is likely that those services aren't being
templated correctly into the ``wazuh-cert-tool.sh`` which then creates the certificates.
Therefore it is likely that a variable in ``$KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh-manager/wazuh-manager``
is not matching the corresponding variable used to template ``wazuh-cert-tool.sh``.

Below is the template for generating ``wazuh-cert-tool.sh``; make sure all the ``"{{ variables }}"`` have been defined:

.. code-block:: bash

instances:
wazuh:
name: "{{ inventory_hostname }}"
ip: "{{ wazuh_manager_ip }}"
role: indexer

Where ``role`` defines the service which ``wazuh-cert-tool.sh`` will create a certificate for.
This should be defined in ``$KAYOBE_CONFIG_PATH/environments/<environment>/inventory/group_vars/wazuh-manager/wazuh-manager.yml``.
Comment on lines +341 to +360
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can't work out what this is saying


Custom SCA Policies (optional)
------------------------------
Expand Down