diff --git a/doc/source/configuration/wazuh.rst b/doc/source/configuration/wazuh.rst index 13c65ac2b..b0d87fc55 100644 --- a/doc/source/configuration/wazuh.rst +++ b/doc/source/configuration/wazuh.rst @@ -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}`` #. 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`` @@ -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//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! 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`` Configure Wazuh Dashboard's Server Host --------------------------------------- @@ -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 @@ -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//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. + +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//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``. + +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. + +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//inventory/group_vars/wazuh-manager/wazuh-manager.yml``. Custom SCA Policies (optional) ------------------------------