diff --git a/Makefile b/Makefile index 28440294daabb88bd78911f42c8b5e124ab67829..64917a5b4f9288174c4ebaf5c77e82cd5002b8f2 100644 --- a/Makefile +++ b/Makefile @@ -4,6 +4,9 @@ ENV_DIR = $(DEPLOY_DIR)/environments/$(ENVIRONMENT) ANSIBLE_DIR = $(DEPLOY_DIR)/ansible include $(ENV_DIR)/$(ENVIRONMENT).mk +CUSTOM_PROVISIONING_DIR = $(DEPLOY_DIR)/custom-provision +include $(CUSTOM_PROVISIONING_DIR)/custom-provision.mk + ANSIBLE_ARGS = -i $(ENV_DIR)/inventory.txt \ -e ansible_dir=$(ANSIBLE_DIR) \ -e environment_dir=$(ENV_DIR) diff --git a/README.md b/README.md index a92aa791da6153a5b3a4c6d87023eb2b1b69d6c0..a6d9f3c7f6d3118395fd9e25e0d706a14398eaf7 100644 --- a/README.md +++ b/README.md @@ -4,55 +4,70 @@ This project is meant for quickly setting up a demo of evidence collection with Project is deployed using Ansible scripts on top of infrastructure provisioned with Vagrant. -It creates 4 VMs: a Wazuh server (manager), two machines acting as Wazuh agents, the Evidence Collector, and Clouditor. +It creates 5 CentOS virtual machines (if ran in `full-setup` mode): +- Wazuh server (manager), +- 2x machines acting as Wazuh agents, +- Evidence Collector, +- Clouditor. -In addition to Wazuh, ClamAV is also installed on agent machines (for testing purposes). +In addition to Wazuh, ClamAV is also installed on agent machines. + +--- ## Requirements * Vagrant 2.2.14 * Ansible 2.9.16 * (optional / integrations) `npm` / `npx` in order to run the simple HTTP server for the integrations - + +--- + ## Setting up the demo -First, checkout Wazuh's tag `v4.1.5` into the current directory: +1. Checkout Wazuh's tag `v4.1.5` into the current directory: -``` -$ make clone-wazuh -``` -or -``` -$ git clone https://github.com/wazuh/wazuh-ansible.git -$ git checkout tags/v4.1.5 -``` + ``` + $ make clone-wazuh + ``` -Then select your `ENVIRONMENT` in `Makefile`. Set it to `full-setup` or `no-collector`. +2. Select your `ENVIRONMENT` in `Makefile`. Set it to `full-setup` or `no-collector` (for development purposes, when `evidence-collector` runs on local machine). -If the case of `full-setup`, installation of additional Ansible roles is required: -``` -$ ansible-galaxy install --roles-path ansible/ gantsign.golang -``` +3. Create and provision VMs: -1. Provision Wazuh server and Wazuh agents: + ``` + $ make create provision + ``` + +--- + +## Using demo components + +### Alert forwarding + +To test Wazuh's alert forwarding, run HTTP Simple server using `npx`: ``` -$ make create provision +$ PORT=8088 npx http-echo-server ``` -2. Check the running instances: +### Clouditor -Navigate browser to: `https://192.168.33.10:5601`, login with default credentials `admin:changeme`. Navigate to `wazuh` section on the left hand-side. +Clouditor starts automatically when Clouditor VM is provisioned. -You should see 2 agents registered and running with Wazuh. +To see Clouditor's output, `ssh` to its machine and examine the log file: -3. Run HTTP Simple server using `npx` +``` +$ make ssh-clouditor +$ tail /var/log/clouditor.log +``` + +To manually (re)start Clouditor (normally not needed), you can use the following command on the Clouditor VM (inside `/home/vagrant/clouditor`): ``` -$ PORT=8088 npx http-echo-server +$ make run ``` -## Using Evidence Collector +### Evidence Collector To see Evidence Collector's output, `ssh` to its machine and open Docker logs: @@ -61,29 +76,130 @@ $ make ssh-evidence-collector $ docker logs -ft evidence-collector ``` -## Testing with Clouditor +### Wazuh -Clouditor starts automatically when clouditor VM is provisioned. +To check running instances (via Wazuh web interface): -To see Clouditor's output, `ssh` to its machine and examine the log file: +1. Navigate browser to: `https://192.168.33.10:5601`. -``` -$ make ssh-clouditor -$ tail /var/log/clouditor.log -``` +2. Login with default credentials `admin:changeme`. -To manually start clouditor (normally not needed), you can use the following command on the clouditor VM (in `/home/vagrant/`): -``` -$ make run -``` +3. Navigate to `Wazuh` section on the left hand-side. + +You should see 2 agents registered and running with Wazuh. + +--- + +## Vagrant & Ansible environment configuration + +Vagrant boxes (and variables later used by Ansible) are defined inside `/environments/` folder. Each environment contains 3 main files: + +- `inventory.txt`: + + contains environment variables/configs that will be used by Ansible when provisioning. + +- `Makefile`: + + named the same as the environment (for easier referencing in the main `Makefile` in root directory), adds additional commands that are environment specific. + +- `Vagrantfile`: + + contains Vagrant configuration. IPs, hostnames etc. of machines have to match those defined in the corresponding `inventory.txt`. + +> Note: `full-setup` environment contains additional `.env` file containing environment variables required by `evidence-collector`. + +To deploy to some other existing machines (assuming they run same/similar Linux distro etc.), use `custom-provision` functionality. + +--- + +## Provision existing machines + +Ansible playbooks allow for easy installation and set-up of Wazuh (both manager and agents) and Evidence collector. + +As part of the Wazuh agent deploy, machines will also have ClamAV installed. + +Wazuh manager and Evidence collector should be installed on the same, clean machine, while Wazuh agents can be (and should be) installed onto existing machines with other software running. + +> Note: this functionality was developed primarily for CentOS based machines (as it uses YUM package manager). + +> Possible problems: CentOS 7 versions with RHEL 7.9 could have problems starting Docker containers due to `libseccomp-devel` package deprecation. + +1. Generate SSH key-pair on the remote server(s) as well as on your local machine (if you haven't yet done so or want to use separate credentials): + + ``` + $ ssh-keygen -t rsa + ``` + +2. Copy your SSH public key to remote server's `authorized_keys` file: + + ``` + $ ssh-copy-id root@192.168.0.13 + ``` + + > Note: this will copy your default SSH pub-key from `~/.ssh/id_rsa.pub`. + +3. Add machine info to `/custom-provision/custom-inventory.txt` file (see `/environments/.../inventory.txt` file for example). + + Make sure to set correct variables: + + | Variable | Description | + | -------- | -------- | + | `public_ip` | Machine's IP address. | + | `ansible_sudo_pass` | Machine's root password. | + | `ansible_ssh_user` | Username used to SSH (and later used by Ansible). | + | `ansible_ssh_pass` | SSH password (corresponding to `ansible_ssh_user`). | + | `ansible_ssh_private_key_file` | Location of your private key (corresponding to public key set in previous step). | + + Example (user: `root`, password: `admin`, @ `192.168.0.13`): + + ``` + 192.168.0.13 public_ip=192.168.0.13 ansible_sudo_pass=admin ansible_ssh_pass=admin ansible_ssh_user=root ansible_ssh_private_key_file=~/.ssh/id_rsa + ``` + +4. Set `evidence-collector` environment variables in `/custom-provision/.env`. See [Evidence collector's documentation](https://git.code.tecnalia.com/medina/wp3/task_3.2/evidence-collector) for more information. + + If you're installing both Evidence collector as well as Wazuh manager on the same machine (as intended), you have to set only `clouditor_host`, `elastic_host` & `wazuh_host` variables (where `elastic_host` & `wazuh_host` are the same). + + > Note: empty line in `.env` file can cause `Invalid line in environment file` Docker error. This happens only on certain Docker builds - distro dependant. + +5. Set variables in `/ansible/globals/globals.yml`: + + | Variable | Description | + | ---- | ---- | + | `elasticsearch_host_ip` | IP of the machine running Elasticsearch (same as Wazuh manager). | + | `wazuh_manager_ip` | IP of the machine running Wazuh manager. | + +6. Provision: + + ``` + $ make -B custom-provision + ``` + +### Wazuh troubleshooting + +Depending on your machine and network configuration, Wazuh could have problem connecting agents to manager. Check Wazuh's web interface to see if agents work corrrectly. + +If not, check the logs in `/var/ossec/logs/ossec.log` and consult [official troubleshooting manual](https://documentation.wazuh.com/current/user-manual/agent-enrollment/troubleshooting.html). + +Two of the most common problems are [missing open ports](https://documentation.wazuh.com/current/user-manual/agent-enrollment/troubleshooting.html#testing-communication-with-wazuh-manager) and [invalid agent names](https://documentation.wazuh.com/current/user-manual/agent-enrollment/troubleshooting.html#invalid-agent-name-for-enrollment) (if agent machine's hostname matches hostname of any already existing Wazuh machine). + +### Minimum hardware requirements + +| Component | Wazuh manager + <br>Evidence collector machine | Wazuh agent<br>machine | +| ---- | ---- | ---- | +| Memory | 2 GB | 1 GB | +| CPU | 2 | 1 | +| Storage | 10 GB | 10 GB | + +--- ## Potential issues ### ClamAV (re)start failed/timed out -ClamAV restart can time-out due to slow disk read/write speeds (if using HDD) and lack of memory. To resolve this, provide the machine with more RAM. Current implementation has it set to `1024` MB (which should suffice for the majoirty of host machine configurations). If you're using SSD, you can lower it to `512` MB. +ClamAV restart can time-out due to slow disk read/write speeds (if using HDD) and lack of memory. To resolve this, provide the machine with more RAM. Current implementation has it set to `1024 MB` (which should suffice for the majoirty of host machine configurations). If you're using SSD, you can lower it to `512 MB`. -### Vagrant issue: +### Vagrant issue ``` The following SSH command responded with a non-zero exit status. @@ -94,14 +210,15 @@ Stdout from the command: Stderr from the command: umount: /mnt: not mounted. - ``` + Solved: + ``` $ vagrant plugin uninstall vagrant-vbguest ``` -### Ansible failing due to ssh issues. +### Ansible failing due to ssh issues This is important for `manager` and `agents` - VMs need to be running already. diff --git a/ansible/docker/tasks/main.yml b/ansible/docker/tasks/main.yml index 42c7d248f955f73f869acaf790d1d2788eab8b43..46e625dba27f70cfa88a95e216cec71523c96af4 100644 --- a/ansible/docker/tasks/main.yml +++ b/ansible/docker/tasks/main.yml @@ -1,5 +1,19 @@ --- -- name: add Docker CE repository +- name: Remove container tools + yum: + name: + - buildah + - podman + - runc + state: absent + +- name: Install (updated) runc + yum: + name: + - runc + state: present + +- name: Add Docker CE repository yum_repository: name: docker-ce-stable file: docker @@ -9,17 +23,25 @@ gpgcheck: yes gpgkey: https://download.docker.com/linux/centos/gpg -- name: create a docker group +- name: Create a docker group group: name=docker -- name: install Docker CE from repository - yum: name=docker-ce state=installed +- name: Install Docker CE from repository + yum: + name: docker-ce + state: installed -- name: add curent '{{ ansible_user }}' to docker groups - user: name={{ ansible_user }} groups=docker append=yes +- name: Add curent "{{ ansible_user }}" to docker groups + user: + name: "{{ ansible_user }}" + groups: docker + append: yes -- name: enable docker service - service: name=docker enabled=yes state=started +- name: Enable docker service + service: + name: docker + enabled: yes + state: started -- name: reset connection to apply group permissions +- name: Reset connection to apply group permissions meta: reset_connection \ No newline at end of file diff --git a/ansible/provision-agents.yml b/ansible/provision-agents.yml index be2d4da10a60571c5107f98dae462bdc1b9292b2..f19e085f519b23c375eb9872b966c71ed97d550d 100644 --- a/ansible/provision-agents.yml +++ b/ansible/provision-agents.yml @@ -3,8 +3,8 @@ - hosts: wazuh_agents become: yes pre_tasks: - - import_tasks: "{{ ansible_dir }}/globals/vars.yml" - roles: + - import_tasks: "{{ ansible_dir }}/globals/vars.yml" + roles: - ../wazuh-ansible/roles/wazuh/ansible-wazuh-agent - docker vars: diff --git a/ansible/provision-evidence-collector.yml b/ansible/provision-evidence-collector.yml index fa13074a6eae484b0943811654fad3a33047d8f5..5cf26f6605cd32010a675a670db99c7cf9d8e351 100644 --- a/ansible/provision-evidence-collector.yml +++ b/ansible/provision-evidence-collector.yml @@ -15,15 +15,35 @@ - name: Install docker-py pip: name: docker-py + executable: pip3 + vars: + ansible_python_interpreter: /usr/bin/python3.6 + - name: Create 'evidence-collector' directory + file: + path: /home/security-monitoring + state: directory + owner: "{{ ansible_ssh_user }}" + group: "{{ ansible_ssh_user }}" + - name: Copy .env file + copy: + src: "{{ environment_dir }}/.env" + dest: /home/security-monitoring/.env + owner: "{{ ansible_ssh_user }}" + group: "{{ ansible_ssh_user }}" - name: Log in to Docker image registry docker_login: registry: "{{ docker_registry }}" username: "{{ docker_username }}" password: "{{ docker_token }}" + vars: + ansible_python_interpreter: /usr/bin/python3.6 - name: Run Docker container docker_container: name: evidence-collector image: "{{ docker_registry }}/medina/evidence-collector:latest" state: started pull: yes - restart_policy: always \ No newline at end of file + restart_policy: always + env_file: /home/security-monitoring/.env + vars: + ansible_python_interpreter: /usr/bin/python3.6 \ No newline at end of file diff --git a/custom-provision/.env b/custom-provision/.env new file mode 100644 index 0000000000000000000000000000000000000000..548f7679c061d26b5645e183a25372d04c5014bf --- /dev/null +++ b/custom-provision/.env @@ -0,0 +1,14 @@ +demo_mode=false +wazuh_host=192.168.0.12 +wazuh_port=55000 +wazuh_username=wazuh-wui +wazuh_password=wazuh-wui +elastic_host=192.168.0.12 +elastic_port=9200 +elastic_username=admin +elastic_password=changeme +redis_host=localhost +redis_port=6379 +redis_queue=low +clouditor_host=192.168.0.13 +clouditor_port=9090 \ No newline at end of file diff --git a/custom-provision/custom-inventory.txt b/custom-provision/custom-inventory.txt new file mode 100644 index 0000000000000000000000000000000000000000..dc138ca7765b7a9d79a43c27622923ec7f19b59b --- /dev/null +++ b/custom-provision/custom-inventory.txt @@ -0,0 +1,25 @@ +# +# Ansible hosts +# + +[wazuh_managers] +192.168.0.12 public_ip=192.168.0.12 ansible_sudo_pass=admin ansible_ssh_pass=admin ansible_ssh_user=root ansible_ssh_private_key_file=~/.ssh/is_rsa + +[wazuh_agents] +192.168.0.13 public_ip=192.168.0.13 ansible_sudo_pass=admin ansible_ssh_pass=admin ansible_ssh_user=root ansible_ssh_private_key_file=~/.ssh/is_rsa + +[evidence_collector] +192.168.0.12 public_ip=192.168.0.12 ansible_sudo_pass=admin ansible_ssh_pass=admin ansible_ssh_user=root ansible_ssh_private_key_file=~/.ssh/is_rsa + +# +# Ansible hosts' variables +# + +[wazuh_managers:vars] +ansible_ssh_common_args='-o StrictHostKeyChecking=no' + +[wazuh_agents:vars] +ansible_ssh_common_args='-o StrictHostKeyChecking=no' + +[evidence_collector:vars] +ansible_ssh_common_args='-o StrictHostKeyChecking=no' \ No newline at end of file diff --git a/custom-provision/custom-provision.mk b/custom-provision/custom-provision.mk new file mode 100644 index 0000000000000000000000000000000000000000..b7d4987f690a37b61bc9ab70e0e7401e487bfba0 --- /dev/null +++ b/custom-provision/custom-provision.mk @@ -0,0 +1,6 @@ +CUSTOM_ARGS = -i $(CUSTOM_PROVISIONING_DIR)/custom-inventory.txt \ + -e ansible_dir=$(ANSIBLE_DIR) \ + -e environment_dir=$(CUSTOM_PROVISIONING_DIR) + +custom-provision: + @ANSIBLE_HOST_KEY_CHECKING=False ansible-playbook $(CUSTOM_ARGS) $(ANSIBLE_DIR)/provision.yml \ No newline at end of file diff --git a/environments/full-setup/.env b/environments/full-setup/.env new file mode 100644 index 0000000000000000000000000000000000000000..166ba70e9c14e4c94b7d03b18f475911bcf60b2e --- /dev/null +++ b/environments/full-setup/.env @@ -0,0 +1,14 @@ +demo_mode=false +wazuh_host=192.168.33.10 +wazuh_port=55000 +wazuh_username=wazuh-wui +wazuh_password=wazuh-wui +elastic_host=192.168.33.10 +elastic_port=9200 +elastic_username=admin +elastic_password=changeme +redis_host=localhost +redis_port=6379 +redis_queue=low +clouditor_host=192.168.33.14 +clouditor_port=9090 \ No newline at end of file