updated the pdoc documentation

Author: nikolasfil

docs/pdoc/html/ctfsolver/forensics/index.html

@@ -33,7 +33,7 @@
 <main>
 <article id="content">
 <header>
-<h1 class="title">Namespace <code>ctfsolver.forensics</code></h1>
+<h1 class="title">Module <code>ctfsolver.forensics</code></h1>
 </header>
 <section id="section-intro">
 </section>

docs/pdoc/html/ctfsolver/src/data/index.html

@@ -33,7 +33,7 @@
 <main>
 <article id="content">
 <header>
-<h1 class="title">Namespace <code>ctfsolver.src.data</code></h1>
+<h1 class="title">Module <code>ctfsolver.src.data</code></h1>
 </header>
 <section id="section-intro">
 </section>

docs/pdoc/markdown/ctfsolver/config/global_config.md

@@ -0,0 +1,95 @@
+Module ctfsolver.config.global_config
+=====================================
+Global configuration management for the CTFSolverScript package.
+
+This module provides the `GlobalConfig` class, which handles the creation, initialization,
+and access of a global configuration file stored in the user's home directory. The configuration
+file is used to store persistent settings required by the CTFSolverScript inline tool.
+
+Classes:
+    GlobalConfig: Manages the global configuration file, including creation, initialization,
+                  reading, and attribute/dictionary-style access to configuration values.
+
+Attributes:
+    CONFIG (GlobalConfig): Singleton instance of the GlobalConfig class for global access.
+
+Example:
+    >>> from ctfsolver.config.global_config import CONFIG
+    >>> from ctfsolver.config import CONFIG
+    >>> CONFIG.initializing()  # Initializes the global configuration
+
+Typical usage involves initializing the configuration (creating the file and writing initial
+content if necessary) and accessing configuration values via attribute or dictionary-style access.
+
+Raises:
+    AttributeError: If an attribute is accessed that does not exist in the configuration.
+    KeyError: If a key is accessed that does not exist in the configuration.
+
+Classes
+-------
+
+`GlobalConfig(*args, **kwargs)`
+:   Initializes the global configuration for the CTF solver application.
+    This constructor sets the path to the global configuration file and loads its content.
+    
+    Attributes:
+        global_config_file_path (Path): Path to the global configuration JSON file.
+    
+    Raises:
+        Any exceptions raised by `get_content()` will propagate.
+
+    ### Methods
+
+    `creating(self)`
+    :   Creates a global configuration file in the user's home directory.
+        
+        This method ensures that the required directories and configuration file exist,
+        creating them if necessary. It is typically called during the initial run of the
+        inline tool or when global configuration setup is required.
+        
+        Args:
+            None
+        
+        Returns:
+            None
+        
+        Raises:
+            OSError: If the directory or file cannot be created due to permission issues.
+
+    `get_content(self)`
+    :   Get the content of the global configuration file.
+        This method reads the global configuration file and returns its content
+        as a dictionary.
+        If the file does not exist or is empty, it returns an empty dictionary.
+        It is intended to be used to retrieve the current global configuration
+        settings for use in the inline tool or other parts of the application.
+        
+        
+        Returns:
+            dict: The content of the global configuration file as a dictionary.
+
+    `initial_content(self)`
+    :   Sets the initial content of the global configuration file.
+        
+        This method loads a configuration template from 'config_template.json' and writes it to the global
+        configuration file if the file is empty or does not exist. If the template file is missing, a default
+        initial content is used instead.
+        
+        Args:
+            None
+        
+        Returns:
+            None
+        
+        Raises:
+            FileNotFoundError: If the template file or global configuration file path does not exist.
+            json.JSONDecodeError: If the template file contains invalid JSON.
+        
+        Side Effects:
+            Writes initial configuration content to the global configuration file if it is empty.
+            Prints status messages to the console.
+
+    `initializing(self)`
+    :   Initialize global configuration settings.
+        This method can be used to set up any necessary global configurations
+        required by the inline tool.

docs/pdoc/markdown/ctfsolver/config/index.md

@@ -0,0 +1,6 @@
+Module ctfsolver.config
+=======================
+
+Sub-modules
+-----------
+* ctfsolver.config.global_config

docs/pdoc/markdown/ctfsolver/error/index.md

@@ -0,0 +1,6 @@
+Module ctfsolver.error
+======================
+
+Sub-modules
+-----------
+* ctfsolver.error.manager_error

docs/pdoc/markdown/ctfsolver/error/manager_error.md

@@ -0,0 +1,68 @@
+Module ctfsolver.error.manager_error
+====================================
+manager_error.py
+
+Provides the ManagerError class for handling exceptions with colored output and optional verbose tracebacks.
+
+Classes:
+    ManagerError: Handles exceptions by printing colored error messages or full tracebacks, and provides a utility to wrap function execution with error handling.
+
+Usage:
+    Use ManagerError to manage error reporting in CLI applications, with support for verbose output and graceful handling of unexpected exceptions and keyboard interrupts.
+
+Example:
+    error_manager = ManagerError(verbose=True)
+    error_manager.try_function(main_function)
+
+Classes
+-------
+
+`ManagerError(*args, **kwargs)`
+:   Handles exceptions with colored output and optional verbose tracebacks for CLI applications.
+    
+    This class provides methods to manage error reporting, including printing colored error messages,
+    displaying full tracebacks when verbose mode is enabled, and gracefully handling unexpected exceptions
+    and keyboard interrupts.
+    
+    Attributes:
+        verbose (bool): If True, displays full traceback on error; otherwise, shows a colored error message.
+    
+    Methods:
+        handle(exception: Exception, exit_code: int = 1):
+            Handles an exception by printing a colored error message or full traceback, then exits with the given code.
+    
+        try_function(function: callable, *args, **kwargs):
+            Executes a function, catching and handling exceptions and keyboard interrupts gracefully.
+    
+    Args:
+        verbose (bool): If True, show full traceback, otherwise show a colored error.
+
+    ### Descendants
+
+    * ctfsolver.src.ctfsolver.CTFSolver
+
+    ### Methods
+
+    `handle(self, exception: Exception, exit_code: int = 1)`
+    :   Handles exceptions by printing error information in color and exiting the program.
+        
+            exception (Exception): The exception instance to handle.
+            exit_code (int, optional): The exit code to use when exiting the program. Defaults to 1.
+        
+        Returns:
+            None
+        
+        Raises:
+            SystemExit: Exits the program with the specified exit code.
+
+    `try_function(self, function: <built-in function callable>, *args, **kwargs)`
+    :   Executes a given function with provided arguments, handling exceptions.
+        Args:
+            function (callable): The function to execute.
+            *args: Variable length argument list to pass to the function.
+            **kwargs: Arbitrary keyword arguments to pass to the function.
+        Returns:
+            None
+        Raises:
+            Handles all exceptions using the `handle` method.
+            Prints a message if interrupted by the user (KeyboardInterrupt).

docs/pdoc/markdown/ctfsolver/find_usage/index.md

@@ -0,0 +1,2 @@
+Module ctfsolver.find_usage
+===========================

docs/pdoc/markdown/ctfsolver/folders/index.md

@@ -0,0 +1,2 @@
+Module ctfsolver.folders
+========================

docs/pdoc/markdown/ctfsolver/forensics/index.md

@@ -0,0 +1,6 @@
+Module ctfsolver.forensics
+==========================
+
+Sub-modules
+-----------
+* ctfsolver.forensics.manager_dash

docs/pdoc/markdown/ctfsolver/forensics/manager_dash.md

@@ -0,0 +1,181 @@
+Module ctfsolver.forensics.manager_dash
+=======================================
+manager_dash.py
+
+Dash-based visualization manager for network packet flows.
+
+This module provides the ManagerDash class, which facilitates the conversion of network packet data (such as from pcap files using scapy)
+into a format suitable for interactive graph visualization using Dash and Cytoscape. It includes utilities for converting packets to graph elements,
+validating element structure, generating example graphs, and running a Dash web application for visual exploration of network flows.
+
+Classes:
+    ManagerDash: Manages the conversion of packet data to Cytoscape elements and sets up the Dash visualization interface.
+
+Typical Usage Example:
+    manager.elements = manager.example_element_creator()
+
+Dependencies:
+    - dash
+    - dash_cytoscape
+    - scapy
+
+Classes
+-------
+
+`ManagerDash(*args, **kwargs)`
+:   ManagerDash provides functionality for converting network packet data into elements suitable for graph visualization,
+    validating element structure, and displaying interactive network graphs using Dash and Cytoscape.
+    
+    Attributes:
+        elements (list[dict]): List of elements representing nodes and edges for visualization.
+        title (str): Title of the Dash application.
+        app: dash.Dash | None  # Dash application instance
+    
+    
+    Methods:
+        pcap_to_element_converter(packets, save=False):
+            Converts a list of scapy Packet objects into visualization elements (nodes and edges) based on IP layer data.
+    
+        pcap_to_element_converter_timestamp(packets, save=False):
+            Converts packets into elements including timestamp nodes, representing temporal flow in the network graph.
+    
+        elements_checker(elements):
+            Validates the structure and content of a list of element dictionaries for compatibility with Cytoscape.
+    
+        example_element_creator():
+            Generates a sample list of elements representing a simple network graph for demonstration purposes.
+    
+        setup_dash():
+            Initializes and configures the Dash application layout and callbacks.
+    
+        setup_dash_layout():
+            Defines the layout of the Dash application, including the Cytoscape graph and output display.
+    
+        setup_dash_functions():
+            Sets up Dash callback functions for interactive node information display.
+    
+        run_dash():
+            Validates elements and runs the Dash application for interactive network graph visualization.
+    
+    Initializes the manager_dash instance.
+    
+    Args:
+        *args: Variable length argument list.
+        **kwargs: Arbitrary keyword arguments.
+            title (str, optional): The title for the network graph. Defaults to "Interactive Network Graph".
+    
+    Attributes:
+        elements (list): Stores elements related to the manager dashboard.
+        title (str): Title of the interactive network graph.
+
+    ### Methods
+
+    `elements_checker(self, elements: list[dict]) ‑> bool`
+    :   Description:
+            Validates a list of dictionaries to ensure they meet specific structural and content requirements.
+            Each dictionary in the list must contain a "data" key with a dictionary value, and the keys within
+            the "data" dictionary must adhere to a predefined set of allowed keys. Additionally, certain key
+            combinations are required to be present together.
+        Args:
+            elements (list[dict]): A list of dictionaries to validate. Each dictionary is expected to have
+                                   a "data" key containing another dictionary.
+        Returns:
+            bool: Returns True if all dictionaries in the list meet the validation criteria, otherwise False.
+
+    `example_element_creator(self)`
+    :   Generates a list of elements representing a network graph in a format compatible with Cytoscape.
+        Description:
+            This method creates a representation of a network graph based on predefined data.
+            Each node (IP address) and edge (connection between IPs) is converted into a dictionary
+            format suitable for use with Cytoscape visualizations.
+        Args:
+            None
+        Returns:
+            list: A list of dictionaries where each dictionary represents a node or an edge in the graph.
+        Example output:
+            [
+                {"data": {"id": "192.168.0.2", "label": "192.168.0.2"}},
+                {"data": {"id": "8.8.8.8", "label": "8.8.8.8"}},
+                {"data": {"source": "192.168.0.2", "target": "8.8.8.8"}},
+                {"data": {"id": "192.168.0.3", "label": "192.168.0.3"}},
+                {"data": {"source": "192.168.0.2", "target": "192.168.0.3"}},
+                {"data": {"id": "10.0.0.1", "label": "10.0.0.1"}},
+                {"data": {"source": "192.168.0.3", "target": "10.0.0.1"}}
+            ]
+
+    `pcap_to_element_converter(self, packets: list[scapy.packet.Packet], save: bool = False) ‑> list[dict]`
+    :   Converts a list of scapy Packet objects into a list of elements suitable for visualization,
+        extracting source and destination IPs and protocol information.
+        
+        Each packet with an IP layer contributes:
+            - Two node elements (for source and destination IPs)
+            - One edge element (representing the connection and protocol between source and destination)
+        
+        Args:
+            packets (list[scapy.packet.Packet]): List of scapy Packet objects to process.
+            save (bool, optional): If True, returns the generated elements list. If False, assigns it to self.elements.
+        
+        Returns:
+            list[dict]: List of elements representing nodes and edges if save is True; otherwise, None.
+
+    `pcap_to_element_converter_timestamp(self, packets: list[scapy.packet.Packet], save: bool = False) ‑> list[dict]`
+    :   Description:
+            Converts a list of scapy Packet objects from a pcap file into a list of elements suitable for graph visualization.
+            Each packet's timestamp, source IP, destination IP, and protocol are extracted and represented as nodes and edges.
+            Optionally saves the generated elements to the instance.
+        
+        Args:
+            packets (list[scapy.packet.Packet]): List of scapy Packet objects to convert.
+            save (bool, optional): If True, returns the elements list; otherwise, assigns it to self.elements. Defaults to False.
+        
+        Raises:
+            AttributeError: If a packet does not have the expected IP layer attributes.
+        
+        Returns:
+            list[dict]: List of dictionaries representing nodes and edges for visualization (only if save=True).
+        
+        Example:
+            elements = pcap_to_element_converter_timestamp(packets, save=True)
+
+    `run_dash(self)`
+    :   Runs the Dash application after validating and setting up required elements.
+        This method performs the following steps:
+        1. Checks if `self.elements` is not None or empty.
+        2. Validates the format of `self.elements` using `self.elements_checker`.
+        3. Sets up the Dash application by calling `self.setup_dash`.
+        4. Runs the Dash app with debugging enabled.
+        Raises:
+            ValueError: If `self.elements` is None or empty.
+            ValueError: If `self.elements` does not pass the format check.
+
+    `setup_dash(self)`
+    :   Initializes and configures the Dash application.
+        
+        This method creates a Dash app instance, sets its title,
+        and sets up the layout and callback functions required for the dashboard.
+        
+        Args:
+            None
+        
+        Returns:
+            None
+
+    `setup_dash_functions(self)`
+    :   Sets up Dash callback functions for interactive components in the dashboard.
+        This method registers a callback for the Cytoscape graph component to handle node click events.
+        When a node is clicked, its information is displayed in the designated output component.
+        Callback:
+            - Output: Updates the "node-click-output" component's children with node information.
+            - Input: Listens for "tapNodeData" events from the "cytoscape-graph" component.
+        Returns:
+            None
+
+    `setup_dash_layout(self)`
+    :   Sets up the Dash application layout for packet flow visualization.
+        This method configures the main layout of the Dash app, including:
+        - A header displaying "Packet Flow Visualization".
+        - A Cytoscape graph for visualizing packet flows, with nodes and edges styled for clarity.
+        - An output div for displaying information when a node is clicked.
+        The layout uses a force-directed graph ("cose" layout) and applies custom styles for nodes, edges, and background.
+        Returns:
+            None