Merge pull request #2109 from wazuh/1796-migrate-doc-test_fim_basic_u…

…sage

Migrate `test_basic_usage` of `test_fim/test_files` documentation to `qa-docs`

tests/integration/test_fim/test_files/test_basic_usage/test_basic_usage_baseline_generation.py

@@ -1,7 +1,77 @@
-# Copyright (C) 2015-2021, Wazuh Inc.
-# Created by Wazuh, Inc. <info@wazuh.com>.
-# 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. <info@wazuh.com>.
+
+           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 the modifications made on files during
+       the initial scan ('baseline') generate events when the scan is finished.
+       The FIM capability is managed by the 'wazuh-syscheckd' daemon, which checks configured files
+       for changes to the checksums, permissions, and ownership.
+
+tier: 0
+
+modules:
+    - fim
+
+components:
+    - agent
+    - manager
+
+daemons:
+    - wazuh-syscheckd
+
+os_platform:
+    - linux
+    - windows
+
+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
+    - Windows 10
+    - Windows 8
+    - Windows 7
+    - Windows Server 2019
+    - 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
+
+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_basic_usage
+'''
 import os
 from time import time
 
@@ -62,14 +132,39 @@ def extra_configuration_before_yield():
 
 
 def test_wait_until_baseline(get_configuration, configure_environment, restart_syscheckd):
-    """
-    Check if events are appearing after the baseline
-    The message 'File integrity monitoring scan ended' informs about the end of the first scan,
-    which generates the baseline
-
-    It creates a file, checks if the baseline has generated before the file addition event, and then
-    if this event has generated.
-    """
+    '''
+    description: Check if FIM events are appearing after the 'baseline'. The log message
+                 'File integrity monitoring scan ended' informs about the end of the first scan,
+                 which generates the 'baseline'. For this purpose, the test creates a test file
+                 while the initial scan is being performed. When the baseline has been generated
+                 it checks if the FIM addition event has been triggered.
+
+    wazuh_min_version: 4.2.0
+
+    parameters:
+        - 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.
+
+    assertions:
+        - Verify that a FIM addition event was generated during the initial scan.
+
+    input_description: A test case (ossec_conf) is contained in external YAML file (wazuh_conf.yaml)
+                       which includes configuration settings for the 'wazuh-syscheckd' daemon and, it
+                       is combined with the testing directories to be monitored defined in this module.
+
+    expected_output:
+        - r'.*Sending FIM event: (.+)$'
+
+    tags:
+        - realtime
+    '''
     check_apply_test({'ossec_conf'}, get_configuration['tags'])
 
     # Create a file during initial scan to check if the event is logged after the 'scan ended' message

tests/integration/test_fim/test_files/test_basic_usage/test_basic_usage_changes.py

@@ -1,7 +1,82 @@
-# Copyright (C) 2015-2021, Wazuh Inc.
-# Created by Wazuh, Inc. <info@wazuh.com>.
-# 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. <info@wazuh.com>.
+
+           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. In particular, these tests will check if common operations
+       ('add', 'modify', and 'delete') on monitored directories are correctly detected.
+       The FIM capability is managed by the 'wazuh-syscheckd' daemon, which checks configured
+       files for changes to the checksums, permissions, and ownership.
+
+tier: 0
+
+modules:
+    - fim
+
+components:
+    - agent
+    - manager
+
+daemons:
+    - wazuh-syscheckd
+
+os_platform:
+    - linux
+    - windows
+    - macos
+    - solaris
+
+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
+    - Windows 10
+    - Windows 8
+    - Windows 7
+    - Windows Server 2019
+    - Windows Server 2016
+    - Windows Server 2012
+    - Windows Server 2003
+    - Windows XP
+    - macOS Catalina
+    - Solaris 10
+    - Solaris 11
+
+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
+
+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_basic_usage
+'''
 import os
 import sys
 
@@ -68,16 +143,59 @@ def get_configuration(request):
 def test_regular_file_changes(folder, name, encoding, checkers, tags_to_apply,
                               get_configuration, configure_environment,
                               restart_syscheckd, wait_for_fim_start):
-    """
-    Check if syscheckd detects regular file changes (add, modify, delete)
-
-    Parameters
-    ----------
-    folder : str
-        Directory where the files will be created.
-    checkers : dict
-        Syscheck checkers (check_all).
-    """
+    '''
+    description: Check if the 'wazuh-syscheckd' daemon detects regular file changes (add, modify, delete).
+                 For this purpose, the test uses different character encodings in the names of the testing
+                 directories and files and performs operations on them. Finally, it verifies that
+                 the FIM events have been generated properly.
+
+    wazuh_min_version: 4.2.0
+
+    parameters:
+        - folder:
+            type: str
+            brief: Path to the monitored testing directory.
+        - name:
+            type: str
+            brief: Name used for the testing files.
+        - encoding:
+            type: str
+            brief: Character encoding used for the directory and testing files.
+        - checkers:
+            type: dict
+            brief: Syscheck checkers (check_all).
+        - tags_to_apply:
+            type: set
+            brief: Run test if match 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 all FIM events are generated for the operations performed,
+          and these contain all 'check_' fields specified in the configuration.
+
+    input_description: A test case (ossec_conf) is contained in external YAML file (wazuh_conf.yaml)
+                       which includes configuration settings for the 'wazuh-syscheckd' daemon and, it
+                       is combined with the testing directories to be monitored defined in this module.
+
+    expected_output:
+        - r'.*Sending FIM event: (.+)$' (Initial scan when restarting Wazuh)
+        - Multiple FIM events logs of the monitored directories.
+
+    tags:
+        - scheduled
+        - time_travel
+    '''
     check_apply_test(tags_to_apply, get_configuration['tags'])
     mult = 1 if sys.platform == 'win32' else 2