ctfsolver.forensics.manager_dash ================================ .. py:module:: ctfsolver.forensics.manager_dash .. autoapi-nested-parse:: 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 Attributes ---------- .. autoapisummary:: ctfsolver.forensics.manager_dash.manager Classes ------- .. autoapisummary:: ctfsolver.forensics.manager_dash.ManagerDash Module Contents --------------- .. py:class:: 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. .. attribute:: elements List of elements representing nodes and edges for visualization. :type: list[dict] .. attribute:: title Title of the Dash application. :type: str .. attribute:: app dash.Dash | None # Dash application instance .. method:: 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. .. method:: pcap_to_element_converter_timestamp(packets, save=False) Converts packets into elements including timestamp nodes, representing temporal flow in the network graph. .. method:: elements_checker(elements) Validates the structure and content of a list of element dictionaries for compatibility with Cytoscape. .. method:: example_element_creator() Generates a sample list of elements representing a simple network graph for demonstration purposes. .. method:: setup_dash() Initializes and configures the Dash application layout and callbacks. .. method:: setup_dash_layout() Defines the layout of the Dash application, including the Cytoscape graph and output display. .. method:: setup_dash_functions() Sets up Dash callback functions for interactive node information display. .. method:: run_dash() Validates elements and runs the Dash application for interactive network graph visualization. .. py:attribute:: elements :value: [] .. py:attribute:: title .. py:method:: pcap_to_element_converter(packets, save = False) 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) :param packets: List of scapy Packet objects to process. :type packets: list[scapy.packet.Packet] :param save: If True, returns the generated elements list. If False, assigns it to self.elements. :type save: bool, optional :returns: List of elements representing nodes and edges if save is True; otherwise, None. :rtype: list[dict] .. py:method:: pcap_to_element_converter_timestamp(packets, save = False) 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. :param packets: List of scapy Packet objects to convert. :type packets: list[scapy.packet.Packet] :param save: If True, returns the elements list; otherwise, assigns it to self.elements. Defaults to False. :type save: bool, optional :raises AttributeError: If a packet does not have the expected IP layer attributes. :returns: List of dictionaries representing nodes and edges for visualization (only if save=True). :rtype: list[dict] .. rubric:: Example elements = pcap_to_element_converter_timestamp(packets, save=True) .. py:method:: elements_checker(elements) 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. :param elements: A list of dictionaries to validate. Each dictionary is expected to have a "data" key containing another dictionary. :type elements: list[dict] :returns: Returns True if all dictionaries in the list meet the validation criteria, otherwise False. :rtype: bool .. py:method:: example_element_creator() 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. :param None: :returns: A list of dictionaries where each dictionary represents a node or an edge in the graph. :rtype: list 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"}} ] .. py:method:: setup_dash() 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. :param None: :returns: None .. py:method:: setup_dash_layout() 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 .. py:method:: setup_dash_functions() 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 .. py:method:: run_dash() 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. :raises ValueError: If `self.elements` does not pass the format check. .. py:data:: manager