Add file regex monitoring tool

[jmv74211]

Related issue
#9

This PR adds a new tool called FileRegexMonitor to monitor files and check if the new content matches the criteria defined in a callback.

In addition, several tests have been added to check the expected behavior.

Tool design

The FileRegexMonitor tool is designed to monitor files to see if new lines added to trigger a specific callback. This is useful to see if expected logs are generated on specific files.

This tool will consist of the following parameters:

• only_new_events: It will allow defining whether the monitoring is performed from the last line of the file or from the beginning.
• callback: It will be a function that will be activated when the event matches the desired pattern.
• accumulations: It will allow defining how many occurrences of the expected pattern it will be necessary to find.
• timeout: It will allow defining the maximum search time. In case of exceeding it, an exception will be generated.

The operation will be very simple, since we will only have to create the object of the class to start directly the monitoring. For example:

FileRegexMonitor(monitored_file, callback, timeout ...)

From here the monitoring will start. If the callback is not triggered with the expected result, an exception will be generated:

wazuh_qa_framework.generic_modules.exceptions.exceptions.TimeoutError: Events from file.log did not match with the callback

[Rebits]

Has been proposed preliminary SRS. Using that for development acceptance we should conclude that some requirements are not fulfilled:

Functional requirements

• 2.3. Sequence Detection The class should be able to check if a list of events was produced in a specified order.
• 2.5. Group Extraction The class should be able to extract the groups that match the regex pattern within the file. The class should return a list of groups that match the regex pattern.

Nonfunctional requirements

3.2 Reliability The library should be reliable and provide accurate results for regex pattern matching, sequence detection, and group extraction. Also, it should be error resistant, handling the case of unexpected inputs on the file.

• Class does not handle correctly unexpected format input. Consider the following example

  >>> with open('my_non_utf8_file.txt', 'w', encoding='iso-8859-1') as f:
    # Write some non-ASCII characters to the file
    f.write("This file contains non-UTF-8 encoded characters: éçñ")
  FileRegexMonitor('my_non_utf8_file.txt', custom_callback, only_new_events=False, timeout=100)
  Traceback (most recent call last):
  File "/usr/lib/python3.10/codecs.py", line 322, in decode
  (result, consumed) = self._buffer_decode(data, self.errors, final)
  UnicodeDecodeError: 'utf-8' codec can't decode byte 0xe9 in position 49: invalid continuation byte

• Only future events could be unstable in case of using only_new_events. Multiple calls of FileRegexMonitor could lead to an event loss. This behavior could be useful for some specific cases, but it should not be the default.

[jmv74211]

According to the proposals made by Victor here, the following changes have been implemented:

• A new tool called FileRegexChecker has been added, which is going to provide us with the functionality to check if the logs appear in a specific order, thus complementing the possible uses of the FileRegexMonitor tool (fulfilling proposed point 2.3).

• Now it is possible to obtain the results obtained from the callback in case extracted values are returned. It will be possible to obtain this value by accessing a variable of the FileRegexMonitor object (fulfilling proposed point 2.5).

• Detection of the encoding of the file to be monitored by the FileRegexMonitor tool has been added. It will now be possible to monitor multiple different formats (complying with proposed point 3.2).

All these new features have been tested with unit tests that are attached in this PR.