Migrate test_registry_restrict and test_registry_tags of test_fim/test_registry, and test_fim/test_synchronization documentation to qa-docs

docs/DocGenerator/config.yaml

@@ -83,6 +83,9 @@ Ignore paths:
  - "../../tests/integration/test_fim/test_registry/test_registry_multiple_registries/data"
  - "../../tests/integration/test_fim/test_registry/test_registry_recursion_level/data"
  - "../../tests/integration/test_fim/test_registry/test_registry_report_changes/data"
+ - "../../tests/integration/test_fim/test_registry/test_registry_restrict/data"
+ - "../../tests/integration/test_fim/test_registry/test_registry_tags/data"
+ - "../../tests/integration/test_fim/test_synchronization/data"
 
 Output fields:
  Module:

tests/integration/test_fim/test_registry/test_registry_restrict/test_registry_restrict.py

@@ -1,6 +1,58 @@
-# 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: File Integrity Monitoring (FIM) system watches selected files and triggering alerts when
+ these files are modified. Specifically, these tests will verify that FIM generates events
+ only for registry entry operations in monitored keys that do not match the 'restrict_key'
+ or the 'restrict_value' attributes.
+ The FIM capability is managed by the 'wazuh-syscheckd' daemon, which checks configured
+ files for changes to the checksums, permissions, and ownership.
+
+tier: 1
+
+modules:
+ - fim
+
+components:
+ - agent
+
+daemons:
+ - wazuh-syscheckd
+
+os_platform:
+ - windows
+
+os_version:
+ - Windows 10
+ - Windows 8
+ - Windows 7
+ - Windows Server 2016
+ - Windows Server 2012
+ - Windows Server 2003
+ - Windows XP
+
+references:
+ - https://documentation.wazuh.com/current/user-manual/capabilities/file-integrity/index.html
+ - https://documentation.wazuh.com/current/user-manual/reference/ossec-conf/syscheck.html#windows-registry
+
+pytest_args:
+ - fim_mode:
+ realtime: Enable real-time monitoring on Linux (using the 'inotify' system calls) and Windows systems.
+ whodata: Implies real-time monitoring but adding the 'who-data' information.
+ - tier:
+ 0: Only level 0 tests are performed, they check basic functionalities and are quick to perform.
+ 1: Only level 1 tests are performed, they check functionalities of medium complexity.
+ 2: Only level 2 tests are performed, they check advanced functionalities and are slow to perform.
+
+tags:
+ - fim_registry_restrict
+'''
 import os
 
 import pytest
@@ -62,24 +114,66 @@ def get_configuration(request):
 def test_restrict_value(key, subkey, arch, value_name, triggers_event, tags_to_apply,
  get_configuration, configure_environment, restart_syscheckd,
  wait_for_fim_start):
- """
- Check the only registry values detected are those matching the restrict regex
-
- Parameters
- ----------
- key : str
- Root key (HKEY_*)
- subkey : str
- path of the registry.
- arch : str
- Architecture of the registry.
- value_name : str
- Name of the value that will be created
- triggers_event : bool
- True if an event must be generated, False otherwise.
- tags_to_apply : set
- Run test if match with a configuration identifier, skip otherwise.
- """
+ '''
+ description: Check if the 'wazuh-syscheckd' daemon detects or ignores events in monitored registry entries
+ depending on the value set in the 'restrict_value' attribute. This attribute limit checks to
+ values that match the entered string or regex and its name. For this purpose, the test will
+ monitor a key, create testing values inside it, and make operations on that values. Finally,
+ the test will verify that FIM 'added' and 'modified' events are generated only for the testing
+ values that are not restricted.
+
+ wazuh_min_version: 4.2.0
+
+ parameters:
+ - key:
+ type: str
+ brief: Path of the registry root key (HKEY_* constants).
+ - subkey:
+ type: str
+ brief: The registry key being monitored by syscheck.
+ - arch:
+ type: str
+ brief: Architecture of the registry.
+ - value_name:
+ type: str
+ brief: Name of the testing value that will be created.
+ - triggers_event:
+ type: bool
+ brief: True if an event must be generated, False otherwise.
+ - tags_to_apply:
+ type: set
+ brief: Run test if matches with a configuration identifier, skip otherwise.
+ - get_configuration:
+ type: fixture
+ brief: Get configurations from the module.
+ - configure_environment:
+ type: fixture
+ brief: Configure a custom environment for testing.
+ - restart_syscheckd:
+ type: fixture
+ brief: Clear the 'ossec.log' file and start a new monitor.
+ - wait_for_fim_start:
+ type: fixture
+ brief: Wait for realtime start, whodata start, or end of initial FIM scan.
+
+ assertions:
+ - Verify that FIM events are only generated for operations in monitored values
+ that do not match the 'restrict_value' attribute.
+ - Verify that FIM 'ignoring' events are generated for monitored values that are restricted.
+
+ input_description: A test case (value_restrict) is contained in external YAML file
+ (wazuh_restrict_conf.yaml) which includes configuration settings
+ for the 'wazuh-syscheckd' daemon. That is combined with the testing
+ registry keys to be monitored defined in this module.
+
+ expected_output:
+ - r'.*Sending FIM event: (.+)$' ('added', 'modified' events)
+ - r'.*Ignoring entry .* due to restriction .*'
+
+ tags:
+ - scheduled
+ - time_travel
+ '''
  check_apply_test(tags_to_apply, get_configuration['tags'])
  # This shouldn't create an alert because the key is already created
  key_h = create_registry(registry_parser[key], subkey, arch)
@@ -146,24 +240,66 @@ def test_restrict_value(key, subkey, arch, value_name, triggers_event, tags_to_a
 def test_restrict_key(key, subkey, test_subkey, arch, triggers_event, tags_to_apply,
  get_configuration, configure_environment, restart_syscheckd,
  wait_for_fim_start):
- """
- Check the only registry keys detected are those matching the restrict regex
-
- Parameters
- ----------
- key : str
- Root key (HKEY_*)
- subkey : str
- Path of the registry.
- test_subkey : str
- Name of the key that will be used for the test
- arch : str
- Architecture of the registry.
- triggers_event : bool
- True if an event must be generated, False otherwise.
- tags_to_apply : set
- Run test if match with a configuration identifier, skip otherwise.
- """
+ '''
+ description: Check if the 'wazuh-syscheckd' daemon detects or ignores events in monitored registry entries
+ depending on the value set in the 'restrict_key' attribute. This attribute limit checks to
+ keys that match the entered string or regex and its name. For this purpose, the test will
+ monitor a key, create testing subkeys inside it, and make operations on those subkeys. Finally,
+ the test will verify that FIM 'added' and 'deleted' events are generated only for the testing
+ subkeys that are not restricted.
+
+ wazuh_min_version: 4.2.0
+
+ parameters:
+ - key:
+ type: str
+ brief: Path of the registry root key (HKEY_* constants).
+ - subkey:
+ type: str
+ brief: The registry key being monitored by syscheck.
+ - test_subkey:
+ type: str
+ brief: Name of the key that will be used for the test
+ - arch:
+ type: str
+ brief: Architecture of the registry.
+ - triggers_event:
+ type: bool
+ brief: True if an event must be generated, False otherwise.
+ - tags_to_apply:
+ type: set
+ brief: Run test if matches with a configuration identifier, skip otherwise.
+ - get_configuration:
+ type: fixture
+ brief: Get configurations from the module.
+ - configure_environment:
+ type: fixture
+ brief: Configure a custom environment for testing.
+ - restart_syscheckd:
+ type: fixture
+ brief: Clear the 'ossec.log' file and start a new monitor.
+ - wait_for_fim_start:
+ type: fixture
+ brief: Wait for realtime start, whodata start, or end of initial FIM scan.
+
+ assertions:
+ - Verify that FIM events are only generated for operations in monitored keys
+ that do not match the 'restrict_key' attribute.
+ - Verify that FIM 'ignoring' events are generated for monitored keys that are restricted.
+
+ input_description: A test case (key_restrict) is contained in external YAML file
+ (wazuh_restrict_conf.yaml) which includes configuration settings
+ for the 'wazuh-syscheckd' daemon. That is combined with the testing
+ registry keys to be monitored defined in this module.
+
+ expected_output:
+ - r'.*Sending FIM event: (.+)$' ('added', 'deleted' events)
+ - r'.*Ignoring entry .* due to restriction .*'
+
+ tags:
+ - scheduled
+ - time_travel
+ '''
  check_apply_test(tags_to_apply, get_configuration['tags'])
  test_key = os.path.join(subkey, test_subkey)
  create_registry(registry_parser[key], test_key, arch)

tests/integration/test_fim/test_registry/test_registry_tags/test_registry_tags.py

@@ -1,6 +1,57 @@
-# 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: File Integrity Monitoring (FIM) system watches selected files and triggering alerts when
+ these files are modified. Specifically, these tests will check if FIM events include
+ all tags set in the 'tags' attribute.
+ The FIM capability is managed by the 'wazuh-syscheckd' daemon, which checks configured
+ files for changes to the checksums, permissions, and ownership.
+
+tier: 1
+
+modules:
+ - fim
+
+components:
+ - agent
+
+daemons:
+ - wazuh-syscheckd
+
+os_platform:
+ - windows
+
+os_version:
+ - Windows 10
+ - Windows 8
+ - Windows 7
+ - Windows Server 2016
+ - Windows Server 2012
+ - Windows Server 2003
+ - Windows XP
+
+references:
+ - https://documentation.wazuh.com/current/user-manual/capabilities/file-integrity/index.html
+ - https://documentation.wazuh.com/current/user-manual/reference/ossec-conf/syscheck.html#windows-registry
+
+pytest_args:
+ - fim_mode:
+ realtime: Enable real-time monitoring on Linux (using the 'inotify' system calls) and Windows systems.
+ whodata: Implies real-time monitoring but adding the 'who-data' information.
+ - tier:
+ 0: Only level 0 tests are performed, they check basic functionalities and are quick to perform.
+ 1: Only level 1 tests are performed, they check functionalities of medium complexity.
+ 2: Only level 2 tests are performed, they check advanced functionalities and are slow to perform.
+
+tags:
+ - fim_registry_tags
+'''
 import os
 
 import pytest
@@ -47,19 +98,52 @@ def get_configuration(request):
 ])
 def test_tags(key, subkey, arch,
  get_configuration, configure_environment, restart_syscheckd, wait_for_fim_start):
- """
- Check the tags functionality by applying some tags an ensuring the events raised for the monitored directory has
- the expected tags.
-
- Parameters
- ----------
- folder : str
- Directory where the file is being created.
- name : str
- Name of the file to be created.
- content : str, bytes
- Content to fill the new file.
- """
+ '''
+ description: Check if the 'wazuh-syscheckd' daemon generates the tags required for each event depending
+ on the values set in the 'tags' attribute. This attribute allows adding tags to alerts for
+ monitored registry entries. For this purpose, the test will monitor a key and make value
+ operations inside it. Finally, it will verify that FIM events generated include in the
+ 'tags' field all tags set in the configuration.
+
+ wazuh_min_version: 4.2.0
+
+ parameters:
+ - key:
+ type: str
+ brief: Path of the registry root key (HKEY_* constants).
+ - subkey:
+ type: str
+ brief: The registry key being monitored by syscheck.
+ - arch:
+ type: str
+ brief: Architecture of the registry.
+ - get_configuration:
+ type: fixture
+ brief: Get configurations from the module.
+ - configure_environment:
+ type: fixture
+ brief: Configure a custom environment for testing.
+ - restart_syscheckd:
+ type: fixture
+ brief: Clear the 'ossec.log' file and start a new monitor.
+ - wait_for_fim_start:
+ type: fixture
+ brief: Wait for realtime start, whodata start, or end of initial FIM scan.
+
+ assertions:
+ - Verify that FIM events include all tags set in the 'tags' attribute.
+
+ input_description: A test case (ossec_conf) is contained in external YAML file (wazuh_registry_tag_conf.yaml)
+ which includes configuration settings for the 'wazuh-syscheckd' daemon. That is combined
+ with the testing registry keys to be monitored defined in this module.
+
+ expected_output:
+ - r'.*Sending FIM event: (.+)$' ('added', 'modified', and 'deleted' events)
+
+ tags:
+ - scheduled
+ - time_travel
+ '''
  defined_tags = get_configuration['metadata']['fim_tags']
 
  def tag_validator(event):