doc: Add full documentation to test_wazuh_db.py #1820

tests/integration/test_wazuh_db/test_wazuh_db.py

@@ -1,7 +1,59 @@
-# Copyright (C) 2015-2021, Wazuh Inc.
-# Created by Wazuh, Inc. <[email protected]>.
-# This program is free software; you can redistribute it and/or modify it under the terms of GPLv2
-
+'''
+copyright: Copyright (C) 2015-2021, Wazuh Inc.
+
+ Created by Wazuh, Inc. <[email protected]>.
+
+ This program is free software; you can redistribute it and/or modify it under the terms of GPLv2
+
+type: integration
+
+brief: Wazuh-db is the daemon in charge of the databases with all the Wazuh persistent information, exposing a socket
+ to receive requests and provide information. The Wazuh core uses list-based databases to store information
+ related to agent keys, and FIM/Rootcheck event data.
+ Wazuh-db confirms that is able to save, update and erase the necessary information into the corresponding
+ databases, using the proper commands and response strings.
+
+tier: 0
+
+modules:
+ - wazuh_db
+
+components:
+ - manager
+
+daemons:
+ - wazuh-db
+
+os_platform:
+ - linux
+
+os_version:
+ - Arch Linux
+ - Amazon Linux 2
+ - Amazon Linux 1
+ - CentOS 8
+ - CentOS 7
+ - CentOS 6
+ - Ubuntu Focal
+ - Ubuntu Bionic
+ - Ubuntu Xenial
+ - Ubuntu Trusty
+ - Debian Buster
+ - Debian Stretch
+ - Debian Jessie
+ - Debian Wheezy
+ - Red Hat 8
+ - Red Hat 7
+ - Red Hat 6
+
+references:
+ - https:/wazuh/wazuh-qa/blob/master/docs/tests/integration/test_wazuh_db/index.md
+ - https:/wazuh/wazuh-qa/blob/master/docs/tests/integration/test_wazuh_db/test_wazuh_db.md
+ - https://documentation.wazuh.com/current/user-manual/reference/daemons/wazuh-db.html
+
+tags:
+ - wazuh_db
+'''
 import os
 import re
 import time
@@ -74,14 +126,18 @@ def clean_registered_agents():
 
 @pytest.fixture(scope='module')
 def wait_range_checksum_avoided(line):
- """Callback function to wait until the manager avoided the checksum calculus by using the last saved one."""
+ '''
+ Callback function to wait until the manager avoided the checksum calculus by using the last saved one.
+ '''
  if 'range checksum avoided' in line:
  return line
  return None
 
 
 def wait_range_checksum_calculated(line):
- """Callback function to wait until the manager calculates the new checksum."""
+ '''
+ Callback function to wait until the manager calculates the new checksum.
+ '''
  if 'range checksum: Time: ' in line:
  return line
  return None
@@ -121,7 +177,9 @@ def prepare_range_checksum_data():
 
 @pytest.fixture(scope="function")
 def pre_insert_agents():
- """Insert agents. Only used for the global queries"""
+ '''
+ Insert agents. Only used for the global queries.
+ '''
  AGENTS_CANT = 14000
  AGENTS_OFFSET = 20
  for id in range(AGENTS_OFFSET, AGENTS_OFFSET + AGENTS_CANT):
@@ -135,7 +193,9 @@ def pre_insert_agents():
 
 @pytest.fixture(scope='function')
 def insert_agents_test():
- """Insert agents. Only used for the agent queries"""
+ '''
+ Insert agents. Only used for the agent queries.
+ '''
  agent_list = [1, 2]
  for agent in agent_list:
  insert_agent(agent)
@@ -156,23 +216,29 @@ def restart_wazuh(request):
 
 
 def execute_wazuh_db_query(command):
- """Function to send a command to the wazuh-db socket.
+ '''
+ Function to send a command to the wazuh-db socket.
+
  Args:
  command(str): Message to send to the socket.
+
  Returns:
  str: A response from the socket
- """
+ '''
  receiver_sockets[0].send(command, size=True)
  return receiver_sockets[0].receive(size=True).decode()
 
 
 def insert_agent(agent_id, agent_name='TestName'):
- """Function that wraps the needed queries to register an agent.
+ '''
+ Function that wraps the needed queries to register an agent.
+
  Args:
- agent_id(int): Unique identifier of an agent
+ agent_id(int): Unique identifier of an agent.
+
  Raises:
  AssertionError: If the agent couldn't be inserted in the DB
- """
+ '''
  insert_data = json.dumps({'id': agent_id,
  'name': f"{agent_name}{agent_id}",
  'date_add': 1599223378
@@ -193,10 +259,12 @@ def insert_agent(agent_id, agent_name='TestName'):
 
 
 def remove_agent(agent_id):
- """Function that wraps the needed queries to remove an agent.
+ '''
+ Function that wraps the needed queries to remove an agent.
+
  Args:
- agent_id(int): Unique identifier of an agent
- """
+ agent_id(int): Unique identifier of an agent.
+ '''
  data = execute_wazuh_db_query(f"global delete-agent {agent_id}").split(' ', 1)
  assert data[0] == 'ok', f"Unable to remove agent {agent_id} - {data[1]}"
 
@@ -211,11 +279,51 @@ def remove_agent(agent_id):
  )
 def test_wazuh_db_messages_agent(restart_wazuh, clean_registered_agents, configure_sockets_environment,
  connect_to_sockets_module, insert_agents_test, test_case):
- """Check that every input agent message in wazuh-db socket generates the adequate output to wazuh-db socket.
-
- Args:
- test_case(list): List of test_case stages (dicts with input, output and stage keys).
- """
+ '''
+ description: Check that every input agent message in wazuh-db socket generates the adequate output to wazuh-db
+ socket. To do this, query the socket with a command taken from the input list of stages (test_case,
+ input field) and compare the result with the input list of stages (test_case, output field).
+
+ wazuh_min_version: 4.2.0
+
+ parameters:
+ - restart_wazuh:
+ type: fixture
+ brief: Reset the 'ossec.log' file and start a new monitor.
+ - clean_registered_agents:
+ type: fixture
+ brief: Remove all agents of wazuhdb.
+ - configure_sockets_environment:
+ type: fixture
+ brief: Configure environment for sockets and MITM.
+ - connect_to_sockets_module:
+ type: fixture
+ brief: Module scope version of 'connect_to_sockets' fixture.
+ - insert_agents_test:
+ type: fixture
+ brief: Insert agents. Only used for the agent queries.
+ - test_case:
+ type: fixture
+ brief: List of test_case stages (dicts with input, output and stage keys).
+
+ assertions:
+ - Verify that the socket response matches the expected output of the yaml input file.
+
+ input_description:
+ - Test cases are defined in the agent_messages.yaml file. This file contains the command to insert and clear
+ information of registered agents in the database. Also, it contains a case to check messages from not
+ registered agents.
+
+ expected_output:
+ - r'Failed test case stage .*'
+ - r'Error when executing .* in daemon'
+ - 'Unable to add agent'
+ - 'Unable to upgrade agent'
+
+ tags:
+ - wazuh_db
+ - wdb_socket
+ '''
  for index, stage in enumerate(test_case):
  if 'ignore' in stage and stage['ignore'] == 'yes':
  continue
@@ -240,11 +348,40 @@ def test_wazuh_db_messages_agent(restart_wazuh, clean_registered_agents, configu
  for case in module_data]
  )
 def test_wazuh_db_messages_global(connect_to_sockets_module, restart_wazuh, test_case):
- """Check that every input global message in wazuh-db socket generates the adequate output to wazuh-db socket.
-
- Args:
- test_case(list): List of test_case stages (dicts with input, output and stage keys).
- """
+ '''
+ description: Check that every input global message in wazuh-db socket generates the adequate output to wazuh-db
+ socket. To do this, query the socket with a command taken from the input list of stages (test_case,
+ input field) and compare the result with the input list of stages (test_case, output field).
+
+ wazuh_min_version: 4.2.0
+
+ parameters:
+ - restart_wazuh:
+ type: fixture
+ brief: Reset the 'ossec.log' file and start a new monitor.
+ - connect_to_sockets_module:
+ type: fixture
+ brief: Module scope version of 'connect_to_sockets' fixture.
+ - test_case:
+ type: fixture
+ brief: List of test_case stages (dicts with input, output and stage keys).
+
+ assertions:
+ - Verify that the socket response matches the expected output of the yaml input file.
+
+ input_description:
+ - Test cases are defined in the global_messages.yaml file. This file contains cases to insert, upgrade, label,
+ select, get-all-agents, sync-agent-info-get, sync-agent-info-set, belongs table, reset connection status,
+ get-agents-by-connection-status, disconnect-agents, delete and keepalive commands in global database.
+
+ expected_output:
+ - r'Failed test case stage .*'
+ - r'Error when executing * in daemon'
+
+ tags:
+ - wazuh_db
+ - wdb_socket
+ '''
  for index, stage in enumerate(test_case):
  if 'ignore' in stage and stage['ignore'] == 'yes':
  continue
@@ -264,7 +401,44 @@ def test_wazuh_db_messages_global(connect_to_sockets_module, restart_wazuh, test
 
 def test_wazuh_db_chunks(restart_wazuh, configure_sockets_environment, clean_registered_agents,
  connect_to_sockets_module, pre_insert_agents):
- """Check that commands by chunks work properly when agents amount exceed the response maximum size"""
+ '''
+ description: Check that commands by chunks work properly when the agents' amount exceeds the response maximum size.
+ To do this, send a command to the wazuh-db socket and check the response from the socket.
+
+ wazuh_min_version: 4.2.0
+
+ parameters:
+ - restart_wazuh:
+ type: fixture
+ brief: Reset the 'ossec.log' file and start a new monitor.
+ - configure_sockets_environment:
+ type: fixture
+ brief: Configure environment for sockets and MITM.
+ - clean_registered_agents:
+ type: fixture
+ brief: Remove all agents of wazuhdb.
+ - connect_to_sockets_module:
+ type: fixture
+ brief: Module scope version of 'connect_to_sockets' fixture.
+ - pre_insert_agents:
+ type: fixture
+ brief: Insert agents. Only used for the global queries.
+
+ assertions:
+ - Verify that the socket status response matches with 'due' to fail.
+
+ input_description:
+ - Test cases are defined in the global_messages.yaml file. Status response is expected from global
+ get-all-agents last_id 0 command, global sync-agent-info-get last_id 0 command, global
+ get-agents-by-connection-status 0 active command and global disconnect-agents 0 .* syncreq command.
+
+ expected_output:
+ - r'Failed chunks check on .*'
+
+ tags:
+ - wazuh_db
+ - wdb_socket
+ '''
  def send_chunk_command(command):
  response = execute_wazuh_db_query(command)
  status = response.split(' ', 1)[0]
@@ -284,7 +458,50 @@ def send_chunk_command(command):
 
 def test_wazuh_db_range_checksum(restart_wazuh, configure_sockets_environment, connect_to_sockets_module,
  prepare_range_checksum_data, file_monitoring, request):
- """Check the checksum range during the synchroniation of the DBs"""
+ '''
+ description: Calculates the checksum range during the synchronization of the DBs the first time and avoids the
+ checksum range the next time. To do this, query the database with the command that contains agent
+ checksum information and calculate the checksum range.
+
+ wazuh_min_version: 4.2.0
+
+ parameters:
+ - restart_wazuh:
+ type: fixture
+ brief: Reset the 'ossec.log' file and start a new monitor.
+ - configure_sockets_environment:
+ type: fixture
+ brief: Configure environment for sockets and MITM.
+ - connect_to_sockets_module:
+ type: fixture
+ brief: Module scope version of 'connect_to_sockets' fixture.
+ - prepare_range_checksum_data:
+ type: fixture
+ brief: Execute syscheck command with a specific payload to query the database.
+ - file_monitoring:
+ type: fixture
+ brief: Handle the monitoring of a specified file.
+ - request:
+ type: fixture
+ brief: Provide information of the requesting test function.
+
+ assertions:
+ - Verify that the checksum range can be calculated the first time and the checksum range was avoid the second
+ time.
+
+ input_description:
+ - The input of this test is the agent payload defined in the prepare_range_checksum_data fixture.
+
+ expected_output:
+ - r'range checksum Time: .*'
+ - 'Checksum Range wasn´t calculated the first time'
+ - 'range checksum avoided'
+ - 'Checksum Range wasn´t avoided the second time'
+
+ tags:
+ - wazuh_db
+ - wdb_socket
+ '''
  command = """agent 1 syscheck integrity_check_global {\"begin\":\"/home/test/file1\",\"end\":\"/home/test/file2\",
  \"checksum\":\"2a41be94762b4dc57d98e8262e85f0b90917d6be\",\"id\":1}"""
  log_monitor = request.module.log_monitor