docs: increase docstring coverage to 100% (#4913)

Signed-off-by: Thomas, Hailee <[email protected]>
Signed-off-by: Patel, Narendra <[email protected]>>
Signed-off-by: Menchaca, Jesus <[email protected]>

fixes: #4900

Co-authored-by: Austin Porter <[email protected]>

Author: hai1337

cve_bin_tool/available_fix/redhat_cve_tracker.py

@@ -14,6 +14,16 @@
 
 
 class RedhatCVETracker:
+    """
+    RedhatCVETracker is responsible for tracking CVE
+    information for Red Hat distributions. It retrieves and parses CVE data to provide
+    information about available fixes and affected packages.
+
+    Attributes:
+        distro_name (str): The name of the distribution.
+        distro_codename (str): The codename of the distribution.
+    """
+
     def __init__(self, distro_name: str, distro_codename: str):
         self.distro_name = distro_name
         self.distro_codename = distro_codename

cve_bin_tool/cve_scanner.py

@@ -474,11 +474,28 @@ def metric(self, cve_number, epss_percentile, epss_probability):
         return met
 
     def __enter__(self):
+        """
+        Establishes a connection to the SQLite database and initializes the cursor.
+
+        Returns:
+            CVEScanner: The instance of the CVEScanner with an active database connection.
+        """
         self.connection = sqlite3.connect(self.dbname)
         self.connection.row_factory = sqlite3.Row
         self.cursor = self.connection.cursor()
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
+        """
+        Closes the cursor and the SQLite database connection.
+
+        Args:
+            exc_type (type): The exception type.
+            exc_val (Exception): The exception instance.
+            exc_tb (traceback): The traceback object.
+
+        Returns:
+            None
+        """
         self.cursor.close()
         self.connection.close()

cve_bin_tool/data_sources/nvd_source.py

@@ -186,6 +186,15 @@ def format_data(self, all_cve_entries):
         return cve_data, affects_data
 
     def parse_node(self, node: dict[str, list[dict[str, str]]]) -> list[dict[str, str]]:
+        """
+        Parses a node from the NVD data to extract affected vendor, product, and version information.
+
+        Args:
+            node (dict): A dictionary representing a node in the NVD data.
+
+        Returns:
+            list[dict]: A list of dictionaries containing vendor, product, and version information.
+        """
         affects_list = []
         if "cpe_match" in node:
             vulnerable_matches = (m for m in node["cpe_match"] if m["vulnerable"])
@@ -350,6 +359,15 @@ def format_data_api2(self, all_cve_entries):
     def parse_node_api2(
         self, node: dict[str, list[dict[str, str]]]
     ) -> list[dict[str, str]]:
+        """
+        Parses a node from the NVD API 2.0 data to extract affected vendor, product, and version information.
+
+        Args:
+            node (dict): A dictionary representing a node in the NVD API 2.0 data.
+
+        Returns:
+            list[dict]: A list of dictionaries containing vendor, product, and version information.
+        """
         affects_list = []
         if "cpeMatch" in node:
             vulnerable_matches = (m for m in node["cpeMatch"] if m["vulnerable"])
@@ -462,6 +480,16 @@ async def nist_fetch_using_api(self) -> list:
     async def getmeta(
         self, session: RateLimiter, meta_url: str
     ) -> tuple[str, dict[str, str]]:
+        """
+        Retrieves metadata for a given URL.
+
+        Args:
+            session (RateLimiter): The session used to make HTTP requests.
+            meta_url (str): The URL to fetch metadata from.
+
+        Returns:
+            tuple: A tuple containing the URL for the JSON data and a dictionary of metadata.
+        """
         async with await session.get(meta_url) as response:
             response.raise_for_status()
             return (
@@ -476,6 +504,15 @@ async def getmeta(
             )
 
     async def nist_scrape(self, session: RateLimiter):
+        """
+        Scrapes the NVD feed page to get metadata links for CVE data.
+
+        Args:
+            session (RateLimiter): The session used to make HTTP requests.
+
+        Returns:
+            dict: A dictionary containing metadata links and their corresponding SHA values.
+        """
         async with await session.get(self.feed) as response:
             response.raise_for_status()
             page = await response.text()

cve_bin_tool/error_handler.py

@@ -138,7 +138,7 @@ class InvalidExtensionError(Exception):
 
 
 class SigningError(Exception):
-    """Error while signing or verifing the sign"""
+    """Error while signing or verifying the sign"""
 
 
 class NetworkConnectionError(Exception):
@@ -154,13 +154,32 @@ class VEXError(Exception):
 
 
 class ErrorMode(Enum):
+    """Defines different error handling modes.
+
+    Attributes:
+        Ignore (int): Ignore errors.
+        NoTrace (int): Do not print traceback.
+        TruncTrace (int): Print truncated traceback.
+        FullTrace (int): Print full traceback.
+    """
+
     Ignore = 0
     NoTrace = 1
     TruncTrace = 2
     FullTrace = 3
 
 
 def excepthook(exc_type, exc_val, exc_tb):
+    """Custom exception hook to handle uncaught exceptions.
+
+    Args:
+        exc_type (type): Exception type.
+        exc_val (BaseException): Exception instance.
+        exc_tb (traceback): Traceback object.
+
+    Returns:
+        None
+    """
     trace = Traceback.from_exception(exc_type, exc_val, exc_tb)
     CONSOLE.print(trace)
     if isinstance(exc_val, SystemExit):
@@ -198,9 +217,24 @@ def __init__(
         self.exc_val = None
 
     def __enter__(self):
+        """Enter the runtime context related to this object.
+
+        Returns:
+            ErrorHandler: The error handler instance.
+        """
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
+        """Exit the runtime context related to this object.
+
+        Args:
+            exc_type (type): Exception type.
+            exc_val (BaseException): Exception instance.
+            exc_tb (traceback): Traceback object.
+
+        Returns:
+            bool: True if the exception is handled, False otherwise.
+        """
         if isinstance(exc_val, SystemExit):
             self.exit_code = exc_val.code
             self.exc_val = exc_val

cve_bin_tool/extractor.py

@@ -490,13 +490,39 @@ async def __aexit__(self, exc_type, exc, exc_tb):
             await aio_rmdir(self.tempdir)
 
     def extract(self, filename):
+        """
+        Run the extractor.
+
+        Args:
+            filename (str): The name of the file to extract.
+
+        Returns:
+            str: The path to the extracted files.
+        """
         return run_coroutine(self.aio_extract(filename))
 
     def __enter__(self):
+        """
+        Create a temporary directory to extract files to.
+
+        Returns:
+            TempDirExtractorContext: The current instance with a temporary directory created.
+        """
         self.tempdir = tempfile.mkdtemp(prefix="cve-bin-tool-")
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
+        """
+        Remove all extraction directories that need to be cleaned up.
+
+        Args:
+            exc_type (type): The exception type.
+            exc_val (Exception): The exception instance.
+            exc_tb (traceback): The traceback object.
+
+        Returns:
+            None
+        """
         with ErrorHandler(mode=self.error_mode, logger=self.logger):
             shutil.rmtree(self.tempdir)
 
@@ -515,6 +541,15 @@ def __init__(self):
         super().__init__(mime=Lzma.MIME, extension=Lzma.EXTENSION)
 
     def match(self, buf):
+        """
+        Check if the buffer matches the LZMA file signature.
+
+        Args:
+            buf (bytes): The buffer to check.
+
+        Returns:
+            bool: True if the buffer matches the LZMA file signature, False otherwise.
+        """
         return (
             len(buf) > 3
             and buf[0] == 0x5D

cve_bin_tool/file.py

@@ -28,6 +28,14 @@ async def aio_is_binary(filename: str) -> bool:
 
 
 def is_binary(filename: str) -> bool:
+    """Determine if a file is an executable binary.
+
+    Args:
+        filename (str): The path to the file to check.
+
+    Returns:
+        bool: True if the file is an executable binary, False otherwise.
+    """
     return run_coroutine(aio_is_binary(filename))
 
 

cve_bin_tool/helper_script.py

@@ -376,7 +376,8 @@ def output_single(self) -> None:
                 else:
                     rprint(
                         f'\t\t[bright_green]r"{escape_rich_console_close(filename)}"[/], <--- you could just use "{self.product_name}" to match this file'
-                    )  # to single-handedly match filenames of type varnishd, varnishlog, varnishtop, etc.
+                        # to single-handedly match filenames of type varnishd, varnishlog, varnishtop, etc.
+                    )
             else:
                 rprint(f'\t\t[green]r"{escape_rich_console_close(filename)}"[/],')
         print("\t]")
@@ -468,6 +469,15 @@ def scan_files(args) -> None:
 
 
 def main(argv=None) -> None:
+    """
+    Main function to parse command-line arguments and initiate the scanning process.
+
+    Args:
+        argv (list, optional): List of command-line arguments. Defaults to None.
+
+    Returns:
+        None
+    """
     argv = argv or sys.argv
 
     parser = argparse.ArgumentParser(

cve_bin_tool/merge.py

@@ -33,6 +33,34 @@
 
 
 class MergeReports:
+    """
+    A class to merge multiple intermediate JSON reports generated by cve-bin-tool.
+
+    Attributes:
+        merge_files (list[str]): List of file paths to merge.
+        logger (Logger | None): Logger instance for logging messages.
+        error_mode (ErrorMode): Mode for error handling.
+        cache_dir (str): Directory for caching intermediate files.
+        score (int): Score threshold for filtering CVEs.
+        filter_tag (list[str]): List of tags to filter the reports.
+        intermediate_cve_data (list): List to store intermediate CVE data.
+        all_cve_data (list): List to store all merged CVE data.
+        file_stack (list): Stack to keep track of files being processed.
+        total_inter_files (int): Total number of intermediate files processed.
+        total_files (int): Total number of files processed.
+        products_with_cve (int): Total number of products with CVEs.
+        products_without_cve (int): Total number of products without CVEs.
+        merged_files (list): List to store merged file tags.
+        walker (DirWalk): Directory walker instance for scanning files.
+
+    Methods:
+        recursive_scan(merge_files): Recursively scan all JSON files in the given paths.
+        scan_intermediate_file(filename): Read and verify an intermediate JSON file.
+        merge_intermediate(): Merge valid intermediate dictionaries.
+        remove_intermediate_duplicates() -> list[dict[str, str]]: Remove duplicate CVEs from intermediate data.
+        get_intermediate_cve_scanner(cve_data_list, score) -> list[CVEScanner]: Get CVEScanner objects from CVE data.
+    """
+
     def __init__(
         self,
         merge_files: list[str],

cve_bin_tool/nvd_api.py

@@ -36,6 +36,29 @@
 
 
 class NVD_API:
+    """
+    A class to interact with the National Vulnerability Database (NVD) API.
+
+    This class provides methods to retrieve and process CVE data from the NVD.
+
+    Attributes:
+        logger (Logger): Logger instance for logging messages.
+        feed (str): URL of the NVD feed.
+        session (aiohttp.ClientSession): HTTP session for making requests.
+        page_size (int): Number of results per page.
+        max_fail (int): Maximum number of allowed failures before pausing requests.
+        interval (int): Interval in seconds between successive requests.
+        error_mode (ErrorMode): Error handling mode.
+        incremental_update (bool): Flag to indicate if incremental updates are enabled.
+        api_key (str): API key for accessing the NVD API.
+        api_version (str): Version of the NVD API.
+        max_hosts (int): Number of simultaneous connections.
+        total_results (int): Total number of CVE results.
+        failed_count (int): Count of failed requests.
+        all_cve_entries (list): List to store all CVE entries.
+        invalid_api (bool): Flag to indicate if the API key is invalid.
+    """
+
     def __init__(
         self,
         logger: Logger = LOGGER.getChild("NVD_API"),

cve_bin_tool/package_list_parser.py

@@ -30,6 +30,23 @@
 
 
 class PackageListParser:
+    """
+    A class to parse package lists and retrieve package information.
+
+    This class supports parsing package lists from various Linux distributions
+    and Python package lists. It retrieves package information and checks for
+    vulnerabilities using the CVE database.
+
+    Attributes:
+        input_file (str): The path to the input file containing a list of packages.
+        logger (Logger): Logger object for logging messages.
+        error_mode (ErrorMode): Specifies how errors should be handled.
+        parsed_data_without_vendor (Dict[Any, Any]): Parsed package data without vendor information.
+        parsed_data_with_vendor (Dict[Any, Any]): Parsed package data with vendor information.
+        package_names_with_vendor (List[Any]): List of package names with vendor information.
+        package_names_without_vendor (List[Any]): List of package names without vendor information.
+    """
+
     def __init__(
         self,
         input_file: str,

cve_bin_tool/util.py

@@ -173,12 +173,27 @@ def __identity_members(self):
         return (self.vendor, self.product, self.version)
 
     def __eq__(self, other):
+        """
+        Check if this ProductInfo instance is equal to another instance.
+
+        Args:
+            other (ProductInfo): The other instance to compare with.
+
+        Returns:
+            bool: True if both instances are equal, False otherwise.
+        """
         if type(other) is type(self):
             return self.__identity_members() == other.__identity_members()
         else:
             return False
 
     def __hash__(self):
+        """
+        Compute the hash value for this ProductInfo instance.
+
+        Returns:
+            int: The hash value of the instance.
+        """
         return hash(self.__identity_members())