diff --git a/source/data/deployment.yml b/source/data/deployment.yml index 209d2fd..874c82c 100644 --- a/source/data/deployment.yml +++ b/source/data/deployment.yml @@ -16,3 +16,12 @@ ironic_automated_cleaning: true # Whether Kayobe manages physical network devices. kayobe_manages_physical_network: true + +# Whether the deployment includes Wazuh. +wazuh: true + +# Whether the Wazuh deployment is managed via StackHPC. +wazuh_managed: true + +# Whether the Wazuh deployment is handled via Ansible. +wazuh_ansible: true diff --git a/source/include/wazuh_ansible.rst b/source/include/wazuh_ansible.rst new file mode 100644 index 0000000..a71abcc --- /dev/null +++ b/source/include/wazuh_ansible.rst @@ -0,0 +1,94 @@ +One method for deploying and maintaining Wazuh is the `official +Ansible playbooks `_. These +can be integrated into |kayobe_config| as a custom playbook. + +Configuring Wazuh Manager +------------------------- + +Wazuh Manager is configured by editing the ``wazuh-manager.yml`` +groups vars file found at +``etc/kayobe/inventory/group_vars/wazuh-manager/``. This file +controls various aspects of Wazuh Manager configuration. +Most notably: + +*domain_name*: + The domain used by Search Guard CE when generating certificates. + +*wazuh_manager_ip*: + The IP address that the Wazuh Manager shall reside on for communicating with the agents. + +*wazuh_manager_connection*: + Used to define port and protocol for the manager to be listening on. + +*wazuh_manager_authd*: + Connection settings for the daemon responsible for registering new agents. + +Running ``kayobe playbook run +$KAYOBE_CONFIG_PATH/ansible/wazuh-manager.yml`` will deploy these +changes. + +Secrets +------- + +Wazuh requires that secrets or passwords are set for itself and the services with which it communiticates. +The playbook ``etc/kayobe/ansible/wazuh-secrets.yml`` automates the creation of these secrets, which should then be encrypted with Ansible Vault. + +To update the secrets you can execute the following two commands + +.. code-block:: shell + :substitutions: + + kayobe# kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/wazuh-secrets.yml \ + -e wazuh_user_pass=$(uuidgen) \ + -e wazuh_admin_pass=$(uuidgen) + kayobe# ansible-vault encrypt --vault-password-file |vault_password_file_path| \ + $KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh-manager/wazuh-secrets.yml + +Once generated, run ``kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/wazuh-manager.yml`` which copies the secrets into place. + +.. note:: Use ``ansible-vault`` to view the secrets: + + ``ansible-vault view --vault-password-file ~/vault.password $KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh-manager/wazuh-secrets.yml`` + +Adding a New Agent +------------------ +The Wazuh Agent is deployed to all hosts in the ``wazuh-agent`` +inventory group, comprising the ``seed`` group (containing |seed_name|) +plus the ``overcloud`` group (containing all hosts in the +OpenStack control plane). + +.. code-block:: ini + + [wazuh-agent:children] + seed + overcloud + +The following playbook deploys the Wazuh Agent to all hosts in the +``wazuh-agent`` group: + +.. code-block:: shell + + kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/wazuh-agent.yml + +The hosts running Wazuh Agent should automatically be registered +and visible within the Wazuh Manager dashboard. + +.. note:: It is good practice to use a `Kayobe deploy hook + `_ + to automate deployment and configuration of the Wazuh Agent + following a run of ``kayobe overcloud host configure``. + +Accessing Wazuh Manager +----------------------- + +To access the Wazuh Manager dashboard, navigate to the ip address +of |wazuh_manager_name| (|wazuh_manager_url|). + +You can login to the dashboard with the username ``admin``. The +password for ``admin`` is defined in the secret +``opendistro_admin_password`` which can be found within +``etc/kayobe/inventory/group_vars/wazuh-manager/wazuh-secrets.yml``. + +.. note:: Use ``ansible-vault`` to view Wazuh secrets: + + ``ansible-vault view --vault-password-file ~/vault.password $KAYOBE_CONFIG_PATH/inventory/group_vars/wazuh-manager/wazuh-secrets.yml`` diff --git a/source/index.rst b/source/index.rst index 05cdd86..b05a42b 100644 --- a/source/index.rst +++ b/source/index.rst @@ -24,6 +24,7 @@ Contents ceph_storage managing_users_and_projects operations_and_monitoring + wazuh customising_deployment gpus_in_openstack baremetal_management diff --git a/source/vars.rst b/source/vars.rst index b95f4ce..61f5239 100644 --- a/source/vars.rst +++ b/source/vars.rst @@ -48,3 +48,6 @@ .. |tempest_recipes| replace:: https://github.com/acme-openstack/tempest-recipes.git .. |tls_setup| replace:: TLS is implemented using a wildcard certificate available for ``*.acme.example``. .. |vault_password_file_path| replace:: ~/vault-password +.. |wazuh_manager_url| replace:: https://172.168.0.10:5601 +.. |wazuh_manager_ip| replace:: 172.168.0.10:5601 +.. |wazuh_manager_name| replace:: wazuh-manager01 diff --git a/source/wazuh.rst b/source/wazuh.rst new file mode 100644 index 0000000..316b97b --- /dev/null +++ b/source/wazuh.rst @@ -0,0 +1,28 @@ +.. include:: vars.rst + +======================= +Wazuh Security Platform +======================= + +.. ifconfig:: deployment['wazuh'] + + The |project_name| deployment uses `Wazuh `_ as security monitoring platform. Among other things, Wazuh monitors for: + +* Security-related system events. +* Known vulnerabilities (CVEs) in versions of installed software. +* Misconfigurations in system security. + +.. ifconfig:: deployment['wazuh_managed'] + + The Wazuh deployment is managed by StackHPC Ltd. + +.. ifconfig:: not deployment['wazuh_managed'] + + The Wazuh deployment is not managed by StackHPC Ltd. + +.. ifconfig:: deployment ['wazuh_ansible'] + + Wazuh deployment via Ansible + ============================ + + .. include:: include/wazuh_ansible.rst