Merge pull request #2175 from wazuh/1796-migrate-doc-logc-macos

Migrate `test_macos` of `test_logcollector` documentation to `qa-docs`

deps/wazuh_testing/wazuh_testing/qa_docs/schema.yaml

@@ -105,6 +105,7 @@ predefined_values:
  - Ubuntu Xenial
  - Ubuntu Focal
  - macOS Server
+ - macOS Sierra
  - macOS Catalina
  - Windows XP
  - Windows 7
@@ -254,6 +255,7 @@ predefined_values:
  - key_polling
  - limits
  - logcollector
+ - logcollector_macos
  - logcollector_age
  - logcollector_cmd_exec
  - logcollector_configuration

tests/integration/test_logcollector/test_macos/test_macos_file_status_basic.py

@@ -1,7 +1,45 @@
-# 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: The 'wazuh-logcollector' daemon monitors configured files and commands for new log messages.
+ Specifically, these tests will check if the logcollector generates the 'file_status.json'
+ file used by the 'only future events' option when using ULS (unified logging system) events in
+ macOS systems. Log data collection is the real-time process of making sense out of the records
+ generated by servers or devices. This component can receive logs through text files or Windows
+ event logs. It can also directly receive logs via remote syslog which is useful
+ for firewalls and other such devices.
+
+tier: 0
+
+modules:
+ - logcollector
+
+components:
+ - agent
+
+daemons:
+ - wazuh-logcollector
+
+os_platform:
+ - macos
+
+os_version:
+ - macOS Catalina
+
+references:
+ - https://documentation.wazuh.com/current/user-manual/capabilities/log-data-collection/index.html
+ - https://documentation.wazuh.com/current/user-manual/reference/ossec-conf/localfile.html
+ - https://developer.apple.com/documentation/os/logging
+
+tags:
+ - logcollector_macos
+'''
 import pytest
 import wazuh_testing.logcollector as logcollector
 import sys
@@ -54,19 +92,63 @@ def get_configuration(request):
  return request.param
 
 
-def test_macos_file_status_basic(restart_logcollector_required_daemons_package, truncate_log_file, delete_file_status_json,
- configure_local_internal_options_module,
- get_configuration, configure_environment,
- file_monitoring, daemons_handler):
- """Checks if logcollector stores correctly "macos"-formatted localfile data.
-
- This test uses logger tool and a custom log to generate an ULS event. When logcollector receives a valid log, then
- the file_status.json is updated.
-
- Raises:
- TimeoutError: If the callbacks, that checks the expected logs, are not satisfied in the expected time.
- FileNotFoundError: If the file_status.json is not available in the expected time.
- """
+def test_macos_file_status_basic(restart_logcollector_required_daemons_package, truncate_log_file,
+ delete_file_status_json, configure_local_internal_options_module,
+ get_configuration, configure_environment, file_monitoring, daemons_handler):
+ '''
+ description: Check if the 'wazuh-logcollector' builds and updates the 'file_status.json' file from ULS events.
+ For this purpose, the test will configure a 'localfile' section using the macOS settings.
+ Once the logcollector is started, it will wait until the macOS ULS module is ready, and then,
+ the test will generate 'unified logging system' (ULS) events by using a logger tool. After this,
+ it will check if the 'file_status.json' file has been created and if the 'macos' key is inside it.
+ Finally, the test will verify that the 'file_status.json' file has valid content.
+
+ wazuh_min_version: 4.2.0
+
+ parameters:
+ - restart_logcollector_required_daemons_package:
+ type: fixture
+ brief: Restart the 'wazuh-agentd', 'wazuh-logcollector', and 'wazuh-modulesd' daemons.
+ - truncate_log_file:
+ type: fixture
+ brief: Clear the 'ossec.log' file.
+ - delete_file_status_json:
+ type: fixture
+ brief: Delete the 'file_status.json' file from logcollector.
+ - configure_local_internal_options_module:
+ type: fixture
+ brief: Set internal configuration for testing.
+ - get_configuration:
+ type: fixture
+ brief: Get configurations from the module.
+ - configure_environment:
+ type: fixture
+ brief: Configure a custom environment for testing.
+ - file_monitoring:
+ type: fixture
+ brief: Handle the monitoring of a specified file.
+ - daemons_handler:
+ type: fixture
+ brief: Handler of Wazuh daemons.
+
+ assertions:
+ - Verify that the logcollector detects the macOS ULS events.
+ - Verify that the logcollector generates the 'file_status.json' file with valid content.
+
+ input_description: A configuration template (test_macos_file_status_basic) is contained in an external YAML
+ file (wazuh_macos_file_status_basic.yaml). That template is combined with two test cases
+ defined in the module. Those include configuration settings
+ for the 'wazuh-logcollector' daemon.
+
+ expected_output:
+ - r'Monitoring macOS logs with.*'
+ - r'Monitoring macOS logs with.*log stream'
+ - r'Logger testing message - file status' (testing macOS ULS message)
+ - r'"macos"'
+
+ tags:
+ - logs
+ '''
  log_monitor.start(timeout=LOG_COLLECTOR_GLOBAL_TIMEOUT,
  callback=logcollector.callback_monitoring_macos_logs,
  error_message=logcollector.GENERIC_CALLBACK_ERROR_TARGET_SOCKET)
@@ -109,4 +191,4 @@ def test_macos_file_status_basic(restart_logcollector_required_daemons_package,
  assert file_status_json['macos']['settings'], "Error finding 'settings' key inside 'macos'"
 
  assert file_status_json['macos']['settings'] \
- == logcollector.compose_macos_log_command(conf_type, conf_level, conf_predicate)
+ == logcollector.compose_macos_log_command(conf_type, conf_level, conf_predicate)

tests/integration/test_logcollector/test_macos/test_macos_file_status_predicate.py

@@ -1,7 +1,43 @@
-# 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: The 'wazuh-logcollector' daemon monitors configured files and commands for new log messages.
+ Specifically, these tests will verify that the logcollector does not add to the 'file_status.json'
+ file event-related data when the predicate used in the 'query' tag is invalid. Log data collection
+ is the real-time process of making sense out of the records generated by servers or devices.
+ This component can receive logs through text files or Windows event logs. It can also directly
+ receive logs via remote syslog which is useful for firewalls and other such devices.
+
+tier: 0
+
+modules:
+ - logcollector
+
+components:
+ - agent
+
+daemons:
+ - wazuh-logcollector
+
+os_platform:
+ - macos
+
+os_version:
+ - macOS Catalina
+
+references:
+ - https://documentation.wazuh.com/current/user-manual/capabilities/log-data-collection/index.html
+ - https://documentation.wazuh.com/current/user-manual/reference/ossec-conf/localfile.html#query
+
+tags:
+ - logcollector_macos
+'''
 import pytest
 import sys
 import time
@@ -51,15 +87,61 @@ def test_macos_file_status_predicate(restart_logcollector_required_daemons_packa
  configure_local_internal_options_module,
  get_configuration, configure_environment,
  file_monitoring, daemons_handler):
- """Checks that logcollector does not store 'macos'-formatted localfile data since its predicate is erroneous.
-
- The agent uses a dummy localfile (/Library/Ossec/logs/active-responses.log) which triggers the creation of
- file_status.json file.
-
- Raises:
- TimeoutError: If the callbacks, that checks the expected logs, are not satisfied in the expected time.
- FileNotFoundError: If the file_status.json is not available in the expected time.
- """
+ '''
+ description: Check if the 'wazuh-logcollector' does not update the 'file_status.json' file from logging
+ events when using an invalid predicate in the 'query' tag of the 'localfile' section.
+ The agent uses a dummy localfile (/Library/Ossec/logs/active-responses.log) which triggers
+ the creation of the 'file_status.json' file.
+ For this purpose, the test will configure a 'localfile' section using the macOS settings
+ but using an invalid predicate. Once the logcollector is started, it will verify that
+ event errors are generated, indicating that an invalid setting has been detected. After
+ this, the test will check if the 'file_status.json' file has been created, and finally,
+ it will verify that the 'macos' key is not inside it since the predicate used is invalid.
+
+ wazuh_min_version: 4.2.0
+
+ parameters:
+ - restart_logcollector_required_daemons_package:
+ type: fixture
+ brief: Restart the 'wazuh-agentd', 'wazuh-logcollector', and 'wazuh-modulesd' daemons.
+ - truncate_log_file:
+ type: fixture
+ brief: Clear the 'ossec.log' file.
+ - delete_file_status_json:
+ type: fixture
+ brief: Delete the 'file_status.json' file from logcollector.
+ - configure_local_internal_options_module:
+ type: fixture
+ brief: Set internal configuration for testing.
+ - get_configuration:
+ type: fixture
+ brief: Get configurations from the module.
+ - configure_environment:
+ type: fixture
+ brief: Configure a custom environment for testing.
+ - file_monitoring:
+ type: fixture
+ brief: Handle the monitoring of a specified file.
+ - daemons_handler:
+ type: fixture
+ brief: Handler of Wazuh daemons.
+
+ assertions:
+ - Verify that the logcollector generates error events when it detects an invalid predicate.
+ - Verify that the logcollector generates the 'file_status.json' file without the 'macos' key.
+
+ input_description: A configuration template (test_macos_file_status_predicate) is contained in an external
+ YAML file (wazuh_macos_file_status_predicate.yaml). That template is combined with
+ two test cases defined in the module. Those include configuration settings
+ for the 'wazuh-logcollector' daemon.
+
+ expected_output:
+ - r'Execution error .*'
+ - r"macOS 'log stream' process exited"
+
+ tags:
+ - logs
+ '''
  time.sleep(2)
  log_monitor.start(timeout=LOG_COLLECTOR_GLOBAL_TIMEOUT,
  callback=callback_log_bad_predicate(),