doc: Add documentation to new vuln detector methods #2462

deps/wazuh_testing/wazuh_testing/db_interface/__init__.py

@@ -21,7 +21,7 @@ def query_wdb(command):
  command (str): wazuh-db command alias. For example `global get-agent-info 000`.
 
  Returns:
- list: Query response data
+ list: Query response data.
  """
  sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
  sock.connect(WAZUH_DB_SOCKET_PATH)
@@ -49,10 +49,14 @@ def query_wdb(command):
 
 
 def load_sqlite_db(db_path):
- """Load a sqlite database
+ """Load a sqlite database.
 
  Args:
  db_path (str): Path where is located the DB.
+
+ Returns:
+ Connection: connection to the database.
+ Cursor: cursor to the database.
  """
  conn = sqlite3.connect(db_path)
  cursor = conn.cursor()
@@ -81,10 +85,10 @@ def get_sqlite_query_result(db_path, query):
 
  Args:
  db_path (str): Path where is located the DB.
- query (str): SQL query. e.g(SELECT * ..)
+ query (str): SQL query. e.g(SELECT * ..).
 
  Returns:
- result (List[list]): Each row is the query result row and each column is the query field value
+ result (List[list]): Each row is the query result row and each column is the query field value.
  """
  try:
  db, cursor = load_sqlite_db(db_path)

deps/wazuh_testing/wazuh_testing/db_interface/agent_db.py

@@ -9,7 +9,7 @@ def clean_table(agent_id, table):
 
  Args:
  agent_id (str): Agent ID.
- table (str): table from the agent DB.
+ table (str): Table from the agent DB.
  """
  query_string = f"agent {agent_id} sql DELETE FROM {table}"
  query_wdb(query_string)
@@ -19,8 +19,8 @@ def update_last_full_scan(last_scan=0, agent_id='000'):
  """Update the last scan of an agent.
 
  Args:
- last_scan (int): Last scan ID. This is compute by casting to int the result of time()
- agent_id (str): Agent ID
+ last_scan (int): Last scan ID. This is compute by casting to int the result of time().
+ agent_id (str): Agent ID.
  """
  query_string = f"agent {agent_id} sql UPDATE vuln_metadata SET LAST_FULL_SCAN={last_scan}"
  query_wdb(query_string)
@@ -33,9 +33,9 @@ def insert_hotfix(agent_id='000', scan_id=int(time()), scan_time=datetime.dateti
  Args:
  agent_id (str): Agent ID.
  scan_id (int): Last scan ID.
- scan_time (str): Scan date ("%Y/%m/%d %H:%M:%S")
+ scan_time (str): Scan date ("%Y/%m/%d %H:%M:%S").
  hotfix (str): ID of the hotfix value.
- checksum (str): Hotfix checksum
+ checksum (str): Hotfix checksum.
  """
  query_string = f"agent {agent_id} sql INSERT INTO sys_hotfixes (scan_id, scan_time, hotfix, checksum) VALUES " \
  f"({scan_id}, '{scan_time}', '{hotfix}', '{checksum}')"
@@ -49,21 +49,21 @@ def insert_os_info(agent_id='000', scan_id=int(time()), scan_time=datetime.datet
  """Insert the OS information in the agent database.
 
  Args:
- agent_id (str): id of the agent
- scan_id (int): id of the last scan
- scan_time (str): date of the scan with this format "%Y/%m/%d %H:%M:%S"
- hostname (str): name of the host
- architecture (str): architecture of the host
- os_name (str): complete name of the OS
- os_version (str): version of the OS
- os_major (str): major version of the OS
- os_minor (str): minor version of the OS
- os_build (str): build id of the OS
- version (str): version of the OS
- os_release (str): release of the OS
- os_patch (str): current patch of the OS
- release (str): release of the OS
- checksum (str): checksum of the OS
+ agent_id (str): Agent ID.
+ scan_id (int): Id of the last scan.
+ scan_time (str): Date of the scan with this format "%Y/%m/%d %H:%M:%S".
+ hostname (str): Name of the host.
+ architecture (str): Architecture of the host.
+ os_name (str): Complete name of the OS.
+ os_version (str): Version of the OS.
+ os_major (str): Major version of the OS.
+ os_minor (str): Minor version of the OS.
+ os_build (str): Build id of the OS.
+ version (str): Version of the OS.
+ os_release (str): Release of the OS.
+ os_patch (str): Current patch of the OS.
+ release (str): Release of the OS.
+ checksum (str): Checksum of the OS.
  """
  query_string = f"agent {agent_id} sql INSERT OR REPLACE INTO sys_osinfo (scan_id, scan_time, hostname, " \
  'architecture, os_name, os_version, os_major, os_minor, os_patch, os_build, release, version, ' \
@@ -80,13 +80,13 @@ def insert_package(agent_id='000', scan_id=int(time()), format='rpm', name=vd.DE
  install_time=datetime.datetime.now().strftime("%Y/%m/%d %H:%M:%S"),
  scan_time=datetime.datetime.now().strftime("%Y/%m/%d %H:%M:%S"), checksum='dummychecksum',
  item_id='dummyitemid'):
- """Insert a package in the agent DB
+ """Insert a package in the agent DB.
 
  Args:
  agent_id (str): Agent ID.
  scan_id (int): Last scan ID.
- format (str): Package format (deb, rpm, ...)
- name (str): Package name
+ format (str): Package format (deb, rpm, ...).
+ name (str): Package name.
  priority (str): Released package priority.
  section (str): Package section.
  size (int): Package size.
@@ -96,10 +96,10 @@ def insert_package(agent_id='000', scan_id=int(time()), format='rpm', name=vd.DE
  multiarch (str): Define if a package may be installed in different architectures.
  description (str): Package description.
  source (str): Package source.
- location (str): Package location
+ location (str): Package location.
  triaged (int): Times that the package has been installed.
- install_time (str): Installation timestamp
- scan_time (str): Scan timestamp
+ install_time (str): Installation timestamp.
+ scan_time (str): Scan timestamp.
  checksum (str): Package checksum.
  item_id (str): Package ID.
  """
@@ -121,7 +121,17 @@ def insert_package(agent_id='000', scan_id=int(time()), format='rpm', name=vd.DE
 
 def update_sync_info(agent_id='000', component='syscollector-packages', last_attempt=1, last_completion=1,
  n_attempts=0, n_completions=0, last_agent_checksum=''):
- """Update the sync_info table of the specified agent for the selected component."""
+ """Update the sync_info table of the specified agent for the selected component.
+
+ Args:
+ agent_id (str): Agent ID.
+ component (str): Name of the component package.
+ last_attempt (int): Last attempt of query
+ last_completion (int): Last completion package
+ n_attempts (int): Number of attempt.
+ n_completions (int): Number of completion packets.
+ last_agent_checksum (str): Checksum of the last agent registered.
+ """
  query_wdb(f"agent {agent_id} sql UPDATE sync_info SET last_attempt = {last_attempt},"
  f"last_completion = {last_completion}, n_attempts = {n_attempts}, n_completions = {n_completions},"
  f"last_agent_checksum = '{last_agent_checksum}' where component = '{component}'")
@@ -147,8 +157,8 @@ def delete_package(package, agent_id='000'):
  Used to simulate uninstall of the package given.
 
  Args:
- package (str): Package name
- agent_id (str): agent ID.
+ package (str): Package name.
+ agent_id (str): Agent ID.
  """
  delete_query_string = f'agent {agent_id} sql DELETE FROM sys_programs WHERE name="{package}"'
  query_wdb(delete_query_string)
@@ -177,7 +187,7 @@ def modify_agent_scan_timestamp(agent_id='000', timestamp=0, full_scan=True):
 
 
 def delete_os_info_data(agent_id='000'):
- """Delete the sys_osinfo data from a specific agent
+ """Delete the sys_osinfo data from a specific agent.
 
  Args:
  agent_id (str): Agent ID.

deps/wazuh_testing/wazuh_testing/db_interface/cve_db.py

@@ -26,7 +26,7 @@ def insert_vulnerability(cveid=vd.DEFAULT_VULNERABILITY_ID, target='RHEL7', targ
  """Insert a vulnerability in CVE database.
 
  Args:
- cveid (str): Vulnerability ID
+ cveid (str): Vulnerability ID.
  target (str): OS target.
  target_minor (str): OS target minor version.
  package (str): Package name.
@@ -36,15 +36,15 @@ def insert_vulnerability(cveid=vd.DEFAULT_VULNERABILITY_ID, target='RHEL7', targ
  severity (str): Vulnerability severity.
  published (str): Date when the vulnerability was published.
  updated (str): Contain if the package was updated.
- reference (str): URL referencing the vulnerability
+ reference (str): URL referencing the vulnerability.
  target_v (str): OS target family.
- cvss (str): Common vulnerability scoring system
+ cvss (str): Common vulnerability scoring system.
  cvss_vector (str): Representation of the values used to derive the score.
  rationale (str): Reasons to describe the vulnerability.
- cvss3 (str): Common vulnerability scoring system version 3
- bugzilla_reference (str): URL referencing to bugzilla
- cwe (str): CWE ID
- advisory (str): advisory ID
+ cvss3 (str): Common vulnerability scoring system version 3.
+ bugzilla_reference (str): URL referencing to bugzilla.
+ cwe (str): CWE ID.
+ advisory (str): Advisory ID.
  ref_target (str): OS target ID.
  """
  queries = [
@@ -88,7 +88,7 @@ def get_num_vulnerabilities():
  """Get the number of vulnerabilities inserted in VULNERABILITIES table of CVE DB.
 
  Returns:
- int: total number of vulnerabilities in the VULNERABILITIES table.
+ int: Total number of vulnerabilities in the VULNERABILITIES table.
  """
  query_string = 'SELECT count(*) from VULNERABILITIES'
  query_result = get_sqlite_query_result(vd.CVE_DB_PATH, query_string)

deps/wazuh_testing/wazuh_testing/db_interface/global_db.py

@@ -10,11 +10,11 @@ def modify_system(os_name='CentOS Linux', os_major='7', name='centos7', agent_id
  os_major (str): OS major version.
  name (str): Os name.
  agent_id (str): Agent ID.
- os_minor (str): OS minor version
+ os_minor (str): OS minor version.
  os_arch (str): Host architecture.
  os_version (str): OS version.
- os_platform (str): Os platform e.g (centos, ubuntu, ...)
- version (str): OS version
+ os_platform (str): Os platform e.g (centos, ubuntu, ...).
+ version (str): OS version.
  """
  query_string = f"global sql update AGENT set OS_NAME='{os_name}', OS_VERSION='{os_version}', " \
  f"OS_MAJOR='{os_major}', OS_MINOR='{os_minor}', OS_ARCH='{os_arch}', NAME='{name}', " \
@@ -29,7 +29,34 @@ def create_or_update_agent(agent_id='001', name='centos8-agent', ip='127.0.0.1',
  version='4.2', config_sum='', merged_sum='', manager_host='centos-8', node_name='node01',
  date_add='1612942494', last_keepalive='253402300799', group='', sync_status='synced',
  connection_status='active'):
- """Create an agent or update its info it is already exists (checking agent_id)."""
+ """Create an agent or update its info if it already exists (checking agent_id).
+
+ Args:
+ agent_id (str): Agent ID.
+ name (str): Agent name.
+ ip (str): Agent IP.
+ register_ip (str): IP of the registered agent.
+ internal_key (str): Internal key of the agent.
+ os_name (str): Name of the OS.
+ os_version (str): Version of the OS.
+ os_major (str): Major version of the OS supported.
+ os_minor (str): Minor version of the OS supported.
+ os_codename (str): Codename of the OS.
+ os_build (str): Build id of the OS.
+ os_platform (str): Platform version of the OS.
+ os_uname (str): Version and architecture of the OS.
+ os_arch (str): Architecture of the OS.
+ version (str): Version of the agent.
+ config_sum (str): .
+ merged_sum (str): .
+ manager_host (str): Name of the manager.
+ node_name (str): Name of the node.
+ date_add (str): Date of the added/updated agent.
+ last_keepalive (str): Last keep alive timestamp reported.
+ group (str): Group of the agent.
+ sync_status (str): Status of the syncronization.
+ connection_status (str): Status of the connection.
+ """
 
  query = 'global sql INSERT OR REPLACE INTO AGENT (id, name, ip, register_ip, internal_key, os_name, os_version, ' \
  'os_major, os_minor, os_codename, os_build, os_platform, os_uname, os_arch, version, config_sum, ' \

deps/wazuh_testing/wazuh_testing/fim_module/fim_synchronization.py

@@ -10,10 +10,13 @@
 
 def get_sync_msgs(tout, new_data=True):
  """Look for as many synchronization events as possible.
+
  This function will look for the synchronization messages until a Timeout is raised or 'max_events' is reached.
- Params:
+
+ Args:
  tout (int): Timeout that will be used to get the dbsync_no_data message.
- new_data (bool): Specifies if the test will wait the event `dbsync_no_data`
+ new_data (bool): Specifies if the test will wait the event `dbsync_no_data`.
+
  Returns:
  A list with all the events in json format.
  """
@@ -41,10 +44,12 @@ def get_sync_msgs(tout, new_data=True):
 
 def find_value_in_event_list(key_path, value_name, event_list):
  """Function that looks for a key path and value_name in a list of json events.
- Params:
+
+ Args:
  path (str): Path of the registry key.
- value_name (str): Name of the value
+ value_name (str): Name of the value.
  event_list (list): List containing the events in JSON format.
+
  Returns:
  The event that matches the specified path. None if no event was found.
  """

deps/wazuh_testing/wazuh_testing/mocking/__init__.py

@@ -59,7 +59,37 @@ def create_mocked_agent(name='centos8-agent', ip='127.0.0.1', register_ip='127.0
  manager_host='centos-8', node_name='node01', date_add='1612942494',
  last_keepalive='253402300799', group='', sync_status='synced', connection_status='active',
  client_key_secret=None):
- """Mock a new agent creating a new client keys entry, adding it to the global db and creating a new agent id DB."""
+ """Mock a new agent creating a new client keys entry, adding it to the global db and creating a new agent id DB.
+
+ Args:
+ name (str): Agent name.
+ ip (str): Agent IP.
+ register_ip (str): IP of the registered agent.
+ internal_key (str): Internal key of the agent.
+ os_name (str): Name of the OS.
+ os_version (str): Version of the OS.
+ os_major (str): Major version of the OS supported.
+ os_minor (str): Minor version of the OS supported.
+ os_codename (str): Codename of the OS.
+ os_build (str): Build id of the OS.
+ os_platform (str): Platform version of the OS.
+ os_uname (str): Version and architecture of the OS.
+ os_arch (str): Architecture of the OS.
+ version (str): Version of the agent.
+ config_sum (str): .
+ merged_sum (str): .
+ manager_host (str): Name of the manager.
+ node_name (str): Name of the node.
+ date_add (str): Date of the added/updated agent.
+ last_keepalive (str): Last keep alive timestamp reported.
+ group (str): Group of the agent.
+ sync_status (str): Status of the syncronization.
+ connection_status (str): Status of the connection.
+ client_key_secret (str): Client secret key.
+
+ Return:
+ str: Agent ID.
+ """
 
  # Get new agent_id
  last_id = global_db.get_last_agent_id()

deps/wazuh_testing/wazuh_testing/modules/vulnerability_detector/callbacks.py

@@ -10,10 +10,10 @@ def make_vuln_callback(pattern, prefix=VULNERABILITY_DETECTOR_PREFIX):
 
  Args:
  pattern (str): String to match on the log.
- prefix (str): regular expression used as prefix before the pattern.
+ prefix (str): Regular expression used as prefix before the pattern.
 
  Returns:
- lambda: function that returns if there's a match in the file
+ lambda: Function that returns if there's a match in the file
 
  Examples:
  >>> callback_bionic_update_started = make_vuln_callback("Starting Ubuntu Bionic database update")